Skip to main content
GET
Get

Authorizations

Authorization
string
header
required

API key authentication

Path Parameters

id
string
required

The unique identifier of the invoice

Query Parameters

expand
string

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.

lineItemsLimit
integer
default:100

Page size for line items when expand=lineItems

Required range: 1 <= x <= 1000
lineItemsPageToken
string

Opaque pagination token for line items when expand=lineItems, taken from a previous response's nextPageToken. Do not construct or parse this value.

provider
string

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)

Maximum string length: 64
Pattern: ^[a-z][a-z0-9_]*$

Response

Invoice details

id
string
required

The invoice ID

object
enum<string>
required

The object type

Available options:
invoice
autoApprove
boolean
required

Whether this invoice auto-approves after calculation

billingAnchor
string<date-time>
required

The billing anchor date used for period calculations

billingCadence
string
required

ISO 8601 duration string for billing frequency

createdAt
string<date-time>
required

When the invoice was created

currency
string
required

ISO 4217 currency code (e.g., USD, EUR)

gracePeriodEnd
string<date-time>
required

The end of the grace period for accepting usage events

grandTotal
string
required

Grand total (subtotal + tax) in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)

itemCount
integer
required

Number of billing items (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)

merchantId
string
required

The merchant organization ID

paidAmount
string
required

Amount already paid via wallet (account_type='main') in decimal dollars

periodEnd
string<date-time>
required

The end of the billing period

periodStart
string<date-time>
required

The start of the billing period

sequenceNumber
integer
required

The sequence number of this invoice period

status
enum<string>
required

The current status of the invoice

Available options:
ACTIVE,
CLOSING,
CLOSED,
CALCULATING,
DRAFT,
ISSUED,
PAYMENT_FAILED,
PAID,
CANCELLED,
WRITTEN_OFF,
FAILED
subscriptionId
string
required

The subscription ID this invoice belongs to

customerId
string
required

The customer ID that owns this invoice

subtotal
string
required

Subtotal in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)

totalTax
string
required

Total tax in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)

unpaidAmount
string
required

Amount accrued as liability (account_type='usage') in decimal dollars

updatedAt
string<date-time>
required

When the invoice was last updated

failureReason
string

Machine-readable reason code for the most recent failure (e.g. CALCULATION_FAILED). Present only when status is FAILED or PAYMENT_FAILED.

paymentInFlight
boolean

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

invoiceNumber
string | null

The invoice number

lineItems
object | null

Line items (only present if expand=lineItems query parameter is provided, or if expand=items is, which implies it)

metadata
object

Additional metadata including transition history

nextActionAt
string<date-time> | null

When the next scheduled action should occur

paidAt
string<date-time> | null

When the invoice was paid (null if not yet paid)

dueAt
string<date-time> | null

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

paymentUrl
string<uri> | null

Payment URL for completing payment (only present when status is ISSUED and unpaidAmount > 0)

pdfUrl
string<uri> | null

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.

pdfSource
enum<string> | null

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.

Available options:
paygentic,
tax_provider,
null

Public URL to view tax invoice

tax
object | null

Tax reconciliation metadata (only present when plan has taxEnabled)