Skip to main content
GET

List invoices

Scope:sales:invoices.read
https://api.holded.com/api/v2/invoices

Returns 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

limitintegeroptional= 50

Maximum number of invoices to return per page. Defaults to 50, maximum 200.

cursorstringoptional

Pagination cursor returned by the previous response. Omit to start from the first page.

contact_idstringoptional

Filter invoices by contact identifier

statusstringoptional

Filter 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"
start_datestring<date-time>optional

Filter 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)

end_datestring<date-time>optional

Filter 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.

due_date_startstring<date-time>optional

Filter invoices whose DUE date is on or after this date. Accepts ISO 8601 datetime or date only (e.g. 2026-01-01).

due_date_endstring<date-time>optional

Filter 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.

sortstringoptional

Sort order for results. Prefix with - for descending.

"date""-date""dueDate""-dueDate""total""-total"
approval_statusstringoptional

Filter by approval status. Use "draft" for unapproved invoices, "approved" for approved ones.

"draft""approved"
accounting_account_numintegeroptional

Filter 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.

convert_to_account_currencybooleanoptional= false

Internal. `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

python
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

json
{
  "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/json
object
items[]object[]
idstring

Unique identifier of the document

document_numberstring | null

Sequential number assigned to the document

contact_idstring | null

Identifier of the contact associated with this document

contact_namestring | null

Name of the contact associated with this document

descriptionstring | null

Free-text description of the document

datestring<date> | null

Issue date of the document in ISO 8601 format

due_datestring<date> | null

Payment due date in ISO 8601 format

subtotalstring

Sum of all line amounts before tax and discounts, as a decimal string

discountstring

Total discount applied to the document, as a decimal string

totalstring

Final amount including taxes and discounts, as a decimal string

taxstring

Total tax amount, as a decimal string

currencystring

ISO 4217 currency code

currency_changestring

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

statusstring

Current status of the document

Enum:failedcompletedpendingpartialcancelled
tags[]string[]

List of tags attached to the document

lines[]object[]

Line items included in the document

payment_method_idstring | null

Identifier of the default payment method for this invoice

payments_totalstring

Total amount already paid, as a decimal string

payments_pendingstring

Remaining amount to be paid, as a decimal string

has_moreboolean
cursorstring | null

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/json
401Invalid or missing API keyapplication/json
403Insufficient permissionsapplication/json
404No accounting account matches the supplied accounting_account_num.application/json
429Rate limit exceededapplication/json