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.

GET /v2/invoices/{id}

Get

cURL

curl --request GET \
  --url https://api.paygentic.io/v2/invoices/{id} \
  --header 'Authorization: Bearer <token>'

200

{
  "id": "inv_r1s2t3u4v5w6x7y8",
  "autoApprove": true,
  "billingAnchor": "2024-02-01T00:00:00Z",
  "billingCadence": "P1M",
  "gracePeriodEnd": "2024-03-01T23:59:59Z",
  "grandTotal": "1345.61",
  "invoiceNumber": "INV-2024-02-001",
  "itemCount": 15,
  "lineItems": null,
  "nextActionAt": null,
  "paidAmount": "0.00",
  "paymentUrl": "https://checkout.paygentic.com/invoice/inv_r1s2t3u4v5w6x7y8",
  "pdfUrl": "https://api.paygentic.io/v2/invoices/inv_r1s2t3u4v5w6x7y8/pdf",
  "pdfSource": "paygentic",
  "documentWithheldReason": null,
  "periodEnd": "2024-02-29T23:59:59Z",
  "periodStart": "2024-02-01T00:00:00Z",
  "permalink": "https://quaderno.io/invoices/12345",
  "sequenceNumber": 2,
  "status": "ISSUED",
  "subscriptionId": "sub_z9a0b1c2d3e4f5g6",
  "subtotal": "1234.50",
  "tax": {
    "actualTax": "111110000000",
    "adjustmentNeeded": true,
    "difference": "1110000000",
    "estimatedTax": "110000000000",
    "reconciled": true,
    "reconciledAt": "2024-03-01T10:00:00Z"
  },
  "totalTax": "111.11",
  "unpaidAmount": "1345.61"
}

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

200

application/json

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)

Show child attributes

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

documentWithheldReason · enum<string> | null

Why no Paygentic-rendered document exists for this invoice, or null when none was withheld. A tax-registered merchant's document is a compliance artefact, so it is withheld unless the recorded tax reconciles with the provider exactly and the registered issuer identity is complete. Non-null therefore always accompanies pdfSource tax_provider or null, and never paygentic. Use it to tell a withheld document apart from an invoice the tax provider serves by design — both report pdfSource tax_provider, but only a withheld one can be repaired by POST /v2/invoices/{id}/generate-pdf. tax_unreconciled: the provider's tax figure was never recorded against this invoice. issuer_identity_incomplete: the registered legal name, tax ID or address could not be read. tax_component_unpriceable: a recorded tax component carried no presentable amount. ledger_mismatch: the recorded tax figures and the invoice's own totals disagree. tax_provider_disagrees: the provider re-read its filing and reported a different tax to the one this invoice was charged — terminal, because correcting an issued invoice is a credit note's job, so retrying the repair cannot clear it. New values may be added, so treat an unrecognised one as withheld rather than failing.

Available options: tax_unreconciled, issuer_identity_incomplete, tax_component_unpriceable, ledger_mismatch, tax_provider_disagrees, null

permalink · string<uri> | null

Public URL to view tax invoice

tax · object | null

Tax reconciliation metadata (only present when plan has taxEnabled)

Show child attributes