Skip to main content

Invoices

An invoice is a commercial document issued by a merchant to a customer for products or services. In PaymentsAI an invoice is generated by an order and tracks the lifecycle of one specific charge — typically a single subscription renewal or a one-time order.

Invoices are panel-first:

PaymentsAI does not dispatch invoice webhook events, and the public API does not expose a list endpoint for invoices. For day-to-day integration, observe the related transaction and subscription events (transaction-processed, transaction-declined, subscription-renewed, subscription-canceled, subscription-churned, order-delinquency-reached) — these reflect the same lifecycle moments as the underlying invoice. The invoice resource itself is mostly useful for the PaymentsAI panel and for fetching a specific invoice by ID (for example, the recentInvoiceId from a subscription creation response).

Where invoices come from​

You do not create invoices directly. They are generated automatically:

  • At subscription creation: the first invoice is created together with the subscription. If the subscription's payment instrument is inactive, the invoice carries the recentInvoicePaymentFormUrl that takes the customer to the hosted payment form to pay it.
  • At each renewal: a new invoice is generated for each billing cycle of an active subscription.
  • At one-time order creation: a one-time order generates a single invoice.

What you can do via the public API​

The invoice endpoints in the public API are intentionally limited:

MethodPathWhat it does
GET/customer-invoices/Fetch invoice data.
POST/customer-invoices/Issue (finalize) an invoice.
GET/customer-invoices/{customerInvoiceId}Download the invoice as PDF.
POST/customer-invoices/{customerInvoiceId}/voidVoid an invoice.

There is no list endpoint — you cannot enumerate all invoices for a customer through the public API. To work with a specific invoice you typically need its ID (for example, the recentInvoiceId returned on a subscription creation response, or the ID looked up in the PaymentsAI panel).

Tracking invoice state​

You do not track invoice state through invoice webhooks or an invoice list endpoint — neither exists in the public API. Drive your integration off the transaction that the invoice was paid by (or attempted on).

The transaction carries:

  • status — completed, refunded, partially-refunded, voided, disputed, waiting, sending, offsite, timeout, not-sent, or suspended.
  • result — approved, declined, canceled, abandoned, or unknown.

See Transaction statuses for the full reference.

What each invoice lifecycle moment looks like on the transaction side:

Invoice momentTransaction-side signal
First payment succeeded (subscription activates)transaction-processed webhook, transaction status: completed, result: approved
Renewal succeededtransaction-processed + subscription-renewed
Renewal payment failedtransaction-declined (one per dunning attempt)
Dunning exhaustedorder-delinquency-reached; then subscription-canceled or subscription-churned
Customer abandoned the offsite stepTransaction result: abandoned
Hosted-form payment completedoffsite-payment-completed
Refund issuedTransaction status: refunded or partially-refunded
Chargeback openedTransaction status: disputed; dispute-created webhook

If you need the underlying invoice itself (for example, to fetch a downloadable copy), use GET /customer-invoices/{customerInvoiceId} with the ID surfaced on the subscription (recentInvoiceId).

How invoices relate to subscriptions​

Each renewal of a subscription generates its own invoice. The renewal charge runs against the subscription's active payment instrument — or against the customer on the hosted payment form when the instrument is inactive. When a renewal payment fails, dunning begins on the transaction side; see Dunning and retries.