Get
Retrieve a single invoice with real-time aggregates (for ACTIVE/CLOSING/CLOSED) or cached aggregates (for finalized invoices). Optionally include line items with expand=lineItems.
Authorizations
API key authentication
Path Parameters
The unique identifier of the invoice
Query Parameters
Comma-separated list of fields to expand. Supports: lineItems, items. items resolves each returned line's item and its external accounting codes into an items collection inside the lineItems block; because those ids come from the lines, requesting items also expands lineItems on its default paging.
Page size for line items when expand=lineItems
1 <= x <= 1000Opaque pagination token for line items when expand=lineItems, taken from a previous response's nextPageToken. Do not construct or parse this value.
Narrows which external references are returned per item when expand=items. Matched exactly against the provider stored on the reference (e.g. accountsiq); there is no allowlist of known providers, but the value must satisfy the same format every stored provider does, so a malformed one is rejected rather than answered with an empty result that reads as "nothing is mapped". It never removes lines or items: an item with no reference for this provider comes back with an empty list, so unmapped SKUs stay visible. Ignored when the items expansion is not requested.
Lowercase snake_case provider identifier (e.g. salesforce, netsuite)
64^[a-z][a-z0-9_]*$Response
Invoice details
The invoice ID
The object type
invoice Whether this invoice auto-approves after calculation
The billing anchor date used for period calculations
ISO 8601 duration string for billing frequency
When the invoice was created
ISO 4217 currency code (e.g., USD, EUR)
The end of the grace period for accepting usage events
Grand total (subtotal + tax) in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)
Number of billing items (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)
The merchant organization ID
Amount already paid via wallet (account_type='main') in decimal dollars
The end of the billing period
The start of the billing period
The sequence number of this invoice period
The current status of the invoice
ACTIVE, CLOSING, CLOSED, CALCULATING, DRAFT, ISSUED, PAYMENT_FAILED, PAID, CANCELLED, WRITTEN_OFF, FAILED The subscription ID this invoice belongs to
The customer ID that owns this invoice
Subtotal in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)
Total tax in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)
Amount accrued as liability (account_type='usage') in decimal dollars
When the invoice was last updated
Machine-readable reason code for the most recent failure (e.g. CALCULATION_FAILED). Present only when status is FAILED or PAYMENT_FAILED.
Whether a payment for this invoice is currently being processed (the payment session is in the 'processing' state). Clients should not offer manual 'mark as paid' while true. Only populated by GET /invoices/{id}.
The invoice number
Line items (only present if expand=lineItems query parameter is provided, or if expand=items is, which implies it)
Additional metadata including transition history
When the next scheduled action should occur
When the invoice was paid (null if not yet paid)
Payment due date snapshotted at invoice-create time as the issue date + subscription.paymentTermDays, anchored to midnight UTC. Null only for invoices created before this feature shipped (no backfill).
Payment URL for completing payment (only present when status is ISSUED and unpaidAmount > 0)
Link to the invoice document, or null when there is none. For Paygentic-rendered documents this is GET /v2/invoices/{id}/pdf, which requires authentication; for documents supplied by the tax provider it is the provider's own direct link. The URL is stable and does not expire. Branch on pdfSource rather than on the shape of this URL.
Who produced the document at pdfUrl, or null when there is none. paygentic means pdfUrl is this API's download endpoint and the request must carry your API key; tax_provider means it is the provider's own link, which opens directly in a browser.
paygentic, tax_provider, null Public URL to view tax invoice
Tax reconciliation metadata (only present when plan has taxEnabled)