A valid request URL is required to generate request examples{
"id": "<string>",
"object": "invoice",
"number": "<string>",
"customer": "<string>",
"test_clock": "<string>",
"status": "draft",
"collection_method": "charge_automatically",
"allow_save_card": true,
"currency": "<string>",
"lines": [
{
"id": "<string>",
"description": "<string>",
"quantity": 123,
"unit_amount": 123,
"amount": 123,
"currency": "<string>",
"invoice_item": "<string>",
"price": "<string>"
}
],
"subtotal": 123,
"tax": 123,
"total": 123,
"amount_paid": 123,
"amount_remaining": 123,
"attempt_count": 123,
"metadata": {},
"created_at": 123,
"updated_at": 123,
"subscription": "<string>",
"collection_payment_method_id": "<string>",
"due_date": 123,
"finalized_at": 123,
"paid_at": 123,
"voided_at": 123,
"next_payment_attempt_at": 123,
"payment_intent": "<string>",
"max_attempts": 123,
"hosted_invoice_url": "<string>"
}{
"error": {
"code": "INVALID_DATA",
"message": "invalid currency"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "INVOICE_NOT_FOUND",
"message": "invoice not found"
}
}{
"error": {
"code": "CONFLICT",
"message": "invoice was modified concurrently, please retry"
}
}{
"error": {
"code": "INVALID_INVOICE_STATE",
"message": "invalid invoice state for this operation"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Update an invoice's payment method
Sets or replaces the payment method pinned for collection on an open
invoice, including a card replacement during dunning. The payment
method must be active and attached to the invoice’s customer. This
endpoint requires a direct Account secret key and does not accept
Ionic-Account.
A valid request URL is required to generate request examples{
"id": "<string>",
"object": "invoice",
"number": "<string>",
"customer": "<string>",
"test_clock": "<string>",
"status": "draft",
"collection_method": "charge_automatically",
"allow_save_card": true,
"currency": "<string>",
"lines": [
{
"id": "<string>",
"description": "<string>",
"quantity": 123,
"unit_amount": 123,
"amount": 123,
"currency": "<string>",
"invoice_item": "<string>",
"price": "<string>"
}
],
"subtotal": 123,
"tax": 123,
"total": 123,
"amount_paid": 123,
"amount_remaining": 123,
"attempt_count": 123,
"metadata": {},
"created_at": 123,
"updated_at": 123,
"subscription": "<string>",
"collection_payment_method_id": "<string>",
"due_date": 123,
"finalized_at": 123,
"paid_at": 123,
"voided_at": 123,
"next_payment_attempt_at": 123,
"payment_intent": "<string>",
"max_attempts": 123,
"hosted_invoice_url": "<string>"
}{
"error": {
"code": "INVALID_DATA",
"message": "invalid currency"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "INVOICE_NOT_FOUND",
"message": "invoice not found"
}
}{
"error": {
"code": "CONFLICT",
"message": "invoice was modified concurrently, please retry"
}
}{
"error": {
"code": "INVALID_INVOICE_STATE",
"message": "invalid invoice state for this operation"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Authorizations
A merchant secret key (sk_…) sent as Authorization: Bearer <key>.
Headers
A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.
255Path Parameters
The invoice id (inv_…).
Body
Active payment method attached to the invoice's customer (pm_…).
Response
The updated invoice.
The invoice id (inv_…).
Always invoice.
invoice The gapless per-merchant number, assigned at finalize. Null while draft.
The billed customer (cus_…), set at creation and immutable.
The logical billing clock inherited from the customer; null when the invoice uses wall-clock time.
One of draft (being built, lines mutable, never customer-visible), open (finalized, lines frozen, awaiting payment), paid (terminal; reachable from open, from uncollectible via a late payment, or directly at finalize when the total is zero), void (terminal; requires amount_paid of zero), or uncollectible (written off; not terminal, since a late payment can still move it to paid).
draft, open, paid, void, uncollectible One of charge_automatically (charged automatically against the pinned payment method) or send_invoice (the buyer pays through the hosted invoice page, with an optional due_date).
charge_automatically, send_invoice Whether the hosted invoice page offers the buyer the option to save their card for future use.
Three-letter ISO currency code. USD, EUR, and GBP are supported; all use 2-decimal minor units.
The invoice's line items. Frozen once the invoice leaves draft.
Show child attributes
Show child attributes
The sum of the line amounts, in minor units.
The tax amount, in minor units. Zero until finalize supplies a tax amount.
subtotal plus tax minus discounts, in minor units. Discounts can reduce this to zero but never below it.
The cumulative amount paid so far, in minor units.
total minus amount_paid, in minor units.
The number of collection attempts recorded against this invoice so far.
A string key-value map for storing your own structured data. Up to 50 keys; each key at most 40 characters and each value at most 500 characters.
Show child attributes
Show child attributes
Unix epoch seconds when the invoice was created.
Unix epoch seconds when the invoice was last updated.
The subscription that generated this invoice (sub_…). Absent for one-off invoices created directly against a customer.
The payment method (pm_…) pinned for automatic collection. Null when no method is pinned.
Optional Unix epoch due date for send_invoice. When null, customer-facing invoice surfaces omit due-date copy.
Unix epoch seconds when the invoice was finalized. Null while the invoice is a draft.
Unix epoch seconds when the invoice became fully paid. Null until then.
Unix epoch seconds when the invoice was voided. Null unless the invoice is void.
Unix time of the next scheduled automatic collection retry. Present only while a dunning retry is pending.
The payment intent created to collect this invoice (pi_…). Present once a collection attempt has created one; links the invoice to its transaction.
The dunning policy's total attempt allowance, for rendering progress like "attempt N of max_attempts". Present only on subscription charge_automatically invoices when the dunning schedule is enabled for the deployment; null otherwise.
The buyer-facing hosted invoice page URL. Present once the invoice has been finalized and hosted invoicing is enabled for the deployment; null on drafts or when hosted invoicing is not configured.