List invoices
Scope: sales:invoices.read https://api.alladdin.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).
Parameters
Query parameters
limit integer optional = 50
Maximum number of invoices to return per page. Defaults to 50, maximum 200.
cursor string optional
Pagination cursor returned by the previous response. Omit to start from the first page.
contact_id string optional
Filter invoices by contact identifier
status string optional
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_date string<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_date string<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_start string<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_end string<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.
sort string optional
Sort order for results. Prefix with - for descending.
"date" "-date" "dueDate" "-dueDate" "total" "-total" approval_status string optional
Filter by approval status. Use "draft" for unapproved invoices, "approved" for approved ones.
"draft" "approved" accounting_account_num integer optional
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.
Request
import requests
url = "https://api.alladdin.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",
"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
200 List of invoices application/json object items[] object[] id string
Unique identifier of the document
document_number string | null
Sequential number assigned to the document
contact_id string | null
Identifier of the contact associated with this document
contact_name string | null
Name of the contact associated with this document
description string | null
Free-text description of the document
date string<date> | null
Issue date of the document in ISO 8601 format
due_date string<date> | null
Payment due date in ISO 8601 format
subtotal string
Sum of all line amounts before tax and discounts, as a decimal string
discount string
Total discount applied to the document, as a decimal string
total string
Final amount including taxes and discounts, as a decimal string
tax string
Total tax amount, as a decimal string
currency string
ISO 4217 currency code
status string
Current status of the document
Enum: failed completed pending partial cancelled tags[] string[]
List of tags attached to the document
lines[] object[]
Line items included in the document
payment_method_id string | null
Identifier of the default payment method for this invoice
payments_total string
Total amount already paid, as a decimal string
payments_pending string
Remaining amount to be paid, as a decimal string
has_more boolean cursor string | null
Opaque cursor to pass as ?cursor= to fetch the next page. Null on the last page.
Error responses
400 The accounting_account_num query parameter must be a positive integer (PGC code). application/json 401 Invalid or missing API key application/json 403 Insufficient permissions application/json 404 No accounting account matches the supplied accounting_account_num. application/json 429 Rate limit exceeded application/json