Retrieve an invoice
Return one invoice by id, including line items, balances and the current collection stage.
API v3 · Last updated 12 August 2026.
Use this operation when you already know the invoice id and need its current state. List and search are separate endpoints; this one never filters.
Signature #
GET
/v3/invoices/{id}
Authentication
Requires a secret API key in the Authorization header
as Bearer <key>. Publishable keys are rejected
with 401.
Parameters #
Path parameters are required. Query parameters are optional and never change which invoice is returned; they only shape the payload.
| Name | Type | Description |
|---|---|---|
id |
string | The invoice id returned by create or list. Format: inv_ followed by 24 hex characters. |
| Name | Type | Description |
|---|---|---|
expand |
string | Comma-separated related objects to inline. Supported: customer, line_items. |
idempotency_key |
string | Optional. Retrieve is safe to retry without it; include one only when your client retries every request uniformly. |
Request #
No request body. The examples below fetch the same invoice with
line_items expanded.
curl https://api.northwind.example/v3/invoices/inv_a1b2c3d4e5f678901234abcd \
-H 'Authorization: Bearer sk_live_...' \
-G --data-urlencode 'expand=line_items'
import northwind
client = northwind.Client(api_key='sk_live_...')
invoice = client.invoices.retrieve(
'inv_a1b2c3d4e5f678901234abcd',
expand=['line_items'],
)
Response #
A successful response returns the invoice object. Amounts are minor units of the invoice currency; never floating-point major units.
{
"id": "inv_a1b2c3d4e5f678901234abcd",
"object": "invoice",
"currency": "gbp",
"balance_due": 12500,
"collection_stage": "overdue",
"line_items": [
{"description": "Monthly plan", "amount": 12500}
]
}
Before you cache this
balance_due and collection_stage change as
payments and reminders land. Cache the id and the static fields;
re-fetch before any chase or write-off decision.
Status codes #
| Code | Meaning |
|---|---|
200 |
Invoice found and returned. |
401 |
Missing or invalid API key, or a publishable key was used. |
404 |
No invoice with that id exists in this account. |
429 |
Rate limited. Retry after the Retry-After header. |
Further reading: List invoices and Authenticating requests with an API key.