Invoices

An Invoice is a billed line-item document — produced automatically by subscription cycles or created ad-hoc for one-off billing. The Python SDK exposes the full lifecycle: draft, finalize-and-send, pay, remind, void, plus PDF retrieval.

Namespace: client.invoices.

Methods

`create`

invoice = client.invoices.create(
    customer_id="cus_123",
    currency="USD",
    collection_method="send_invoice",       # or "charge_automatically"
    items=[
        {"description": "Onboarding", "amount": 50000, "quantity": 1},
    ],
    due_date="2026-06-01T00:00:00Z",
    metadata={"po": "PO-1234"},
    idempotency_key="inv-cus_123-2026-05-onboarding",
)

Returns: Invoice.

`list`

invoices = client.invoices.list(
    limit=50,
    offset=0,
    status="open",
    collection_method="send_invoice",
    due_date_from="2026-05-01T00:00:00Z",
    due_date_to="2026-06-01T00:00:00Z",
)

Returns list[Invoice]. All filter args are optional.

`retrieve`

invoice = client.invoices.retrieve("inv_123")

`update`

invoice = client.invoices.update(
    "inv_123",
    description="Updated description",
    metadata={"po": "PO-5678"},
)

`send_invoice`

invoice = client.invoices.send_invoice("inv_123")

Sends the invoice email. Named send_invoice (not send) to avoid the coroutine / socket.send association in Python.

`pay`

invoice = client.invoices.pay(
    "inv_123",
    payment_instrument_id="pi_abc",        # optional override
    idempotency_key="pay-inv_123-1",
)

Charges the invoice immediately. With collection_method="charge_automatically" the API runs this on its own at the due date.

`remind`

client.invoices.remind("inv_123")

Sends a reminder email for an overdue invoice.

`void`

client.invoices.void("inv_123")

Cancels the invoice. Use this instead of deleting; deletion isn't exposed for audit reasons.

`pdf_data`

pdf = client.invoices.pdf_data("inv_123")
# pdf is the raw `data` payload from the API — typically a hosted URL.

Object shape

Invoice:

Field	Notes
`id`	Always present.
`status`	`"draft"`, `"open"`, `"paid"`, `"void"`, `"uncollectible"`.
`customer_id`, `subscription_id`	Parent linkage.
`collection_method`	`"send_invoice"` or `"charge_automatically"`.
`currency`	Three-letter ISO.
`amount_due` / `amount_paid` / `amount_remaining`	Integer cents.
`subtotal` / `total`	Integer cents.
`items`	List of line-item dicts.
`custom_fields`, `tax_ids`	Display + tax metadata.
`due_date`	ISO-8601.
`period_start` / `period_end`	Subscription billing window if applicable.
`description`, `metadata`	Free-form.
`hosted_invoice_url`, `invoice_pdf_url`	Public URLs for the hosted view + PDF.
`created_at`, `updated_at`	Standard.

Examples

Manual invoicing — create, finalize, and email

inv = client.invoices.create(
    customer_id="cus_123",
    currency="USD",
    collection_method="send_invoice",
    items=[{"description": "Consulting", "amount": 250000, "quantity": 1}],
    due_date="2026-06-01T00:00:00Z",
    idempotency_key="inv-consult-2026-06",
)
client.invoices.send_invoice(inv.id)

Pay an invoice immediately with a saved card

client.invoices.pay(
    "inv_123",
    payment_instrument_id="pi_abc",
    idempotency_key="pay-inv_123-attempt-1",
)

Nightly chase job

overdue = client.invoices.list(
    status="open",
    due_date_to="2026-05-01T00:00:00Z",
)
for inv in overdue:
    client.invoices.remind(inv.id)

Invoices

On this page