Create an invoice

Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "object": "invoice",
  "number": "<string>",
  "customer": "<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": "CUSTOMER_NOT_FOUND",
    "message": "customer not found"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "invoice was modified concurrently, please retry"
  }
}

{
  "error": {
    "code": "CUSTOMER_ALREADY_DELETED",
    "message": "customer is deleted"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

POST

invoices

Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "object": "invoice",
  "number": "<string>",
  "customer": "<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": "CUSTOMER_NOT_FOUND",
    "message": "customer not found"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "invoice was modified concurrently, please retry"
  }
}

{
  "error": {
    "code": "CUSTOMER_ALREADY_DELETED",
    "message": "customer is deleted"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key

string

A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255

Body

application/json

customer

string

required

currency

string

required

collection_method

enum<string>

required

Available options:

charge_automatically,

send_invoice

due_date

integer | null

Unix epoch seconds; used with send_invoice.

metadata

object

Show child attributes

Response

The created draft invoice.

string

required

The invoice id (inv_…).

object

enum<string>

required

Always invoice.

Available options:

invoice

number

string | null

required

The gapless per-merchant number, assigned at finalize. Null while draft.

customer

string

required

The billed customer (cus_…), set at creation and immutable.

status

enum<string>

required

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

Available options:

draft,

open,

paid,

void,

uncollectible

collection_method

enum<string>

required

One of charge_automatically (charged automatically against the pinned payment method) or send_invoice (the buyer pays the hosted page by due_date).

Available options:

charge_automatically,

send_invoice

allow_save_card

boolean

required

Whether the hosted invoice page offers the buyer the option to save their card for future use.

currency

string

required

Three-letter ISO currency code. USD, EUR, and GBP are supported; all use 2-decimal minor units.

lines

object[]

required

The invoice's line items. Frozen once the invoice leaves draft.

Show child attributes

subtotal

integer

required

The sum of the line amounts, in minor units.

tax

integer

required

The tax amount, in minor units. Zero until finalize supplies a tax amount.

total

integer

required

subtotal plus tax minus discounts, in minor units. Discounts can reduce this to zero but never below it.

amount_paid

integer

required

The cumulative amount paid so far, in minor units.

amount_remaining

integer

required

total minus amount_paid, in minor units.

attempt_count

integer

required

The number of collection attempts recorded against this invoice so far.

metadata

object

required

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

created_at

integer

required

Unix epoch seconds when the invoice was created.

updated_at

integer

required

Unix epoch seconds when the invoice was last updated.

subscription

string | null

The subscription that generated this invoice (sub_…). Absent for one-off invoices created directly against a customer.

collection_payment_method_id

string | null

The payment method (pm_…) pinned for automatic collection. Null when no method is pinned.

due_date

integer | null

Unix epoch seconds by which the buyer must pay. Used with send_invoice; null otherwise.

finalized_at

integer | null

Unix epoch seconds when the invoice was finalized. Null while the invoice is a draft.

paid_at

integer | null

Unix epoch seconds when the invoice became fully paid. Null until then.

voided_at

integer | null

Unix epoch seconds when the invoice was voided. Null unless the invoice is void.

next_payment_attempt_at

integer | null

Unix time of the next scheduled automatic collection retry. Present only while a dunning retry is pending.

payment_intent

string | null

The payment intent created to collect this invoice (pi_…). Present once a collection attempt has created one; links the invoice to its transaction.

max_attempts

integer | null

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.

hosted_invoice_url

string | null

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.

Start here

Checkout

Commerce

Checkout endpoints

Payment link endpoints

Catalog endpoints

Payments

Terminal locations

Terminal management

Terminal testing

Terminal payments

Invoices

Subscriptions

Setup intents

Credit notes

Webhook endpoints

Customer endpoints

API key endpoints

Payment method endpoints

Authorizations

Headers

Body

Response