Skip to main content
GET

List purchases

Scope:accounting:purchases.read
https://api.holded.com/api/v2/purchases

Returns a paginated list of purchase 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. Payment status: a purchase with no payment recorded is `pending`, one paid in part is `partial`, and both still owe a balance. `status=outstanding` returns the two together; `status=overdue` narrows that set to purchases 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. `status=overdue` is applied server-side across the whole account and matches pending and partially paid purchases whose due date has passed.

Parameters

Query parameters

limitintegeroptional= 50

Maximum number of purchases 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 by contact identifier

statusstringoptional

Filter by payment status. "pending" matches purchases with no payment recorded and "partial" those paid 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

Return only purchases issued on or after this date. Accepts ISO 8601 datetime or date only (YYYY-MM-DD)

end_datestring<date-time>optional

Return only purchases issued on or before this date. Accepts ISO 8601 datetime or date only (YYYY-MM-DD). 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

Return only purchases whose DUE date is on or after this date. Accepts ISO 8601 datetime or date only (YYYY-MM-DD).

due_date_endstring<date-time>optional

Return only purchases whose DUE date is on or before this date. Combine with status=pending to list overdue purchases (set this to the cut-off date). Accepts ISO 8601 datetime or date only (YYYY-MM-DD). A date without a time (YYYY-MM-DD) includes that whole day; a value with a time is applied exactly as sent.

sortstringoptional

Sort field and direction. Prefix with - for descending order.

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

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

"draft""approved"

Request

python
import requests

url = "https://api.holded.com/api/v2/purchases?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",
      "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",
      "deduction_date": "2026-01-31"
    }
  ],
  "has_more": false,
  "cursor": "string"
}

Success responses

200List of purchasesapplication/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

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 purchase

payments_totalstring

Total amount already paid, as a decimal string

payments_pendingstring

Remaining amount to be paid, as a decimal string

deduction_datestring<date> | null

Accounting date of the purchase ("Fecha contable" in Holded), which drives the tax deduction period. Null when not explicitly set on the document

has_moreboolean
cursorstring | null

Opaque cursor to pass as ?cursor= to fetch the next page. Null on the last page.

Error responses

401Invalid or missing API keyapplication/json
403Insufficient permissionsapplication/json
429Rate limit exceededapplication/json