A valid request URL is required to generate request examples{
"id": "<string>",
"object": "invoice",
"number": "<string>",
"customer": "<string>",
"test_clock": "<string>",
"livemode": true,
"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": "CUSTOMER_NOT_FOUND",
"message": "customer not found"
}
}{
"error": {
"code": "CONFLICT",
"message": "invoice was modified concurrently, please retry"
}
}{
"error": {
"code": "NO_PAYMENT_METHOD",
"message": "charge_automatically invoices require an explicit payment_method_id or a customer default payment method"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Create an invoice
Creates a draft invoice for a customer and drains that customer’s pending
items in the given currency onto it. With no pending items the result is
an empty draft. The invoice and the item assignments commit atomically.
For charge_automatically, an explicit payment_method_id is pinned as
the collection target. When omitted, the customer’s default payment
method is resolved and pinned instead.
A valid request URL is required to generate request examples{
"id": "<string>",
"object": "invoice",
"number": "<string>",
"customer": "<string>",
"test_clock": "<string>",
"livemode": true,
"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": "CUSTOMER_NOT_FOUND",
"message": "customer not found"
}
}{
"error": {
"code": "CONFLICT",
"message": "invoice was modified concurrently, please retry"
}
}{
"error": {
"code": "NO_PAYMENT_METHOD",
"message": "charge_automatically invoices require an explicit payment_method_id or a customer default payment method"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Authorizations
A merchant secret key (sk_…) sent as Authorization: Bearer <key>.
Headers
Merchant ID when an authorized Platform acts for a connected Merchant. Omit when authenticating directly as that Merchant.
^mer_[0-9A-Za-z]{14}$A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.
255Body
ID of the customer to bill (cus_…).
Three-letter ISO currency code for the invoice.
One of charge_automatically (charged automatically against the pinned payment method) or send_invoice (the buyer pays through the hosted invoice page).
charge_automatically, send_invoice An active reusable payment method attached to the customer. For
charge_automatically, this overrides the customer's default and is
pinned to the new invoice. When omitted, the customer default is
resolved and pinned. Later changes to the customer default do not
repoint the invoice.
Optional Unix epoch due date for send_invoice. Omit or pass null when the invoice has no due date.
Custom key-value pairs for your use.
Show child attributes
Show child attributes
Response
The created draft 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.
true for live mode, false for test mode.
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.