List invoices
sales:invoices.readhttps://api.holded.com/api/v2/invoicesReturns a paginated list of invoices in your account. Results are cursor-paginated: the response includes a `cursor` value and a `has_more` boolean. Pass the `cursor` to the next request to fetch the following page. The list includes payment summary fields (`payments_total`, `payments_pending`) so you can display outstanding balances without fetching each invoice individually. Payment status: an invoice with no payment recorded is `pending`, one collected in part is `partial`, and both still owe a balance. `status=outstanding` returns the two together; `status=overdue` narrows that set to invoices whose due date has passed. Date parameters (`start_date`, `end_date`) filter by ISSUE date; `due_date_start`/`due_date_end` filter by DUE date; all are optional and unfiltered means the whole account. Use `status=overdue` to list all unpaid invoices (pending or partial) whose due date has passed. All date parameters accept RFC 3339 (e.g. `2026-01-01T00:00:00+00:00`) or date-only (`2026-01-01`). A signed-in user with limited access to invoices gets only the invoices assigned to them. API keys still need the scope of this endpoint.
Parameters
Query parameters
integeroptional= 50Maximum number of invoices to return per page. Defaults to 50, maximum 200.
stringoptionalPagination cursor returned by the previous response. Omit to start from the first page.
stringoptionalFilter invoices by contact identifier
stringoptionalFilter invoices by payment status. "pending" matches invoices with no payment recorded and "partial" those collected in part; both still owe a balance. "outstanding" returns the two together, "overdue" narrows that set to a due date already past, and "completed" returns the settled ones.
"pending""completed""partial""cancelled""failed""overdue""outstanding"string<date-time>optionalFilter invoices from this date. Accepts ISO 8601 datetime (e.g. 2026-01-01T00:00:00+00:00) or date only (e.g. 2026-01-01)
string<date-time>optionalFilter invoices up to this date. Accepts ISO 8601 datetime (e.g. 2026-12-31T23:59:59+00:00) or date only (e.g. 2026-12-31). A date without a time (YYYY-MM-DD) includes that whole day; a value with a time is applied exactly as sent.
string<date-time>optionalFilter invoices whose DUE date is on or after this date. Accepts ISO 8601 datetime or date only (e.g. 2026-01-01).
string<date-time>optionalFilter invoices whose DUE date is on or before this date. Accepts ISO 8601 datetime or date only (e.g. 2026-03-12). A date without a time (YYYY-MM-DD) includes that whole day; a value with a time is applied exactly as sent.
stringoptionalSort order for results. Prefix with - for descending.
"date""-date""dueDate""-dueDate""total""-total"stringoptionalFilter by approval status. Use "draft" for unapproved invoices, "approved" for approved ones.
"draft""approved"integeroptionalFilter invoices that have at least one line booked to this accounting account, identified by its numeric PGC code (e.g. 70000000 for "Ventas de mercaderias"). Only the numeric code is accepted; a non-numeric value returns 400. Returns 404 if no accounting account with that number exists in the tenant. When called through the AI assistant, an account name is resolved to its code automatically before the request reaches this endpoint.
booleanoptional= falseInternal. `true` answers every amount as stored, in the account base currency, instead of in each document's own currency (aggregates then return ONE bucket under the account currency). Default `false`.
Request
import requests
url = "https://api.holded.com/api/v2/invoices?limit=50&cursor=value&contact_id=value"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json",
}
response = requests.get(url, headers=headers)
print(response.json())Responses
Response
{
"items": [
{
"id": "507f1f77bcf86cd799439011",
"document_number": "INV-0001",
"contact_id": "507f1f77bcf86cd799439011",
"contact_name": "Acme Corp",
"description": "string",
"date": "2024-01-15",
"due_date": "2024-02-15",
"subtotal": "100.00",
"discount": "0",
"total": "121.00",
"tax": "21.00",
"currency": "EUR",
"currency_change": "1.25",
"status": "pending",
"tags": [
"string"
],
"lines": [
{
"line_id": "...",
"name": "...",
"description": "...",
"price": "...",
"units": "...",
"discount": "...",
"tax": "...",
"taxes": "...",
"tags": "...",
"product_id": "...",
"variant_id": "...",
"service_id": "...",
"sku": "...",
"weight": "...",
"cost_price": "...",
"account": "...",
"project_id": "...",
"retention": "...",
"unit_type": "...",
"supplied": "..."
}
],
"payment_method_id": "string",
"payments_total": "0",
"payments_pending": "121.00"
}
],
"has_more": false,
"cursor": "string"
}Success responses
200List of invoicesapplication/jsonUnique identifier of the document
Sequential number assigned to the document
Identifier of the contact associated with this document
Name of the contact associated with this document
Free-text description of the document
Issue date of the document in ISO 8601 format
Payment due date in ISO 8601 format
Sum of all line amounts before tax and discounts, as a decimal string
Total discount applied to the document, as a decimal string
Final amount including taxes and discounts, as a decimal string
Total tax amount, as a decimal string
ISO 4217 currency code
Exchange rate between the document currency and the account currency. The amounts are written in the document currency: divide one by this rate to get it in the account currency. 1 when both are the same or no rate was stored
Current status of the document
failedcompletedpendingpartialcancelledList of tags attached to the document
Line items included in the document
Identifier of the default payment method for this invoice
Total amount already paid, as a decimal string
Remaining amount to be paid, as a decimal string
Opaque cursor to pass as ?cursor= to fetch the next page. Null on the last page.
Error responses
400The accounting_account_num query parameter must be a positive integer (PGC code).application/json401Invalid or missing API keyapplication/json403Insufficient permissionsapplication/json404No accounting account matches the supplied accounting_account_num.application/json429Rate limit exceededapplication/json