Create an invoice
Generate one-off invoices for custom charges, or understand how subscription invoices are created automatically.
One-off invoices
Create a standalone invoice for a customer that is not tied to a subscription. Use one-off invoices for custom charges, consulting fees, setup fees, or any non-recurring billing.
Dashboard
API
Python SDK
- Go to Billing > Invoices in the sidebar
- Click Create Invoice
- Select a customer
- Set the currency and issued date
- Add line items with descriptions, quantities, and amounts
- Click Create
The invoice is created in Draft state, unless you turn on Finalize Invoice.
Finalized invoices cannot be edited. Finalizing a one-off invoice with Automatic billing (in the form, or with Finalize Invoice on a draft) charges it now to its own payment method, if it is due and has an amount to pay. Only that payment method is charged. If it is declined, PaymentKit does not try the customer’s other payment methods. The message after you finalize says what happened.
- Nothing to pay (customer credit or a 100% coupon covers it): the invoice is marked paid. No payment method is charged. This is also true when the invoice is not due yet, or has no payment method.
- Due date in the future: the invoice is not charged. PaymentKit does not charge it on its due date either: collect it from the invoice on its due date. An invoice is due when it is issued, unless it has payment terms or a later due date.
- Declined charge: the invoice is finalized but not paid. Ask the customer to pay the invoice themselves (for example with its payment link) or to add another card, then use Collect Payment on the invoice. Collect Payment can also charge the customer’s other saved cards.
- No payment method on the invoice: the invoice is only finalized. Collect it from the invoice.
With Manual billing, finalizing opens the invoice for the customer to pay. A subscription invoice is only finalized: its subscription collects it.
Line item fields
Use price_id to reference a catalog price, or provide amount/unit_amount for ad-hoc charges.
Subscription invoices
Subscription invoices are generated automatically by the billing lifecycle. You do not need to create them manually.
PaymentKit generates invoices at these points:
Each invoice contains line items built from the subscription’s active items at the time of generation.
Invoice lifecycle
Every invoice follows this state flow:
Transitions
Finalize an invoice
Finalizing moves a draft invoice to Open state, locks all amounts, and optionally triggers PDF generation and email delivery.
API
Python SDK
The finalize endpoint does not charge. To charge an Automatic invoice, finalize it, then call
the collect endpoint. Send an Idempotency-Key header with each collect
request, so that a retried request does not charge twice.
If another operation is updating the invoice, the finalize endpoint answers 409 Conflict with
"error_code": "invoice_busy" and "retryable": true. Nothing was changed: try again. If you
send an Idempotency-Key, use a new one, because the key stores this answer too.
The collect endpoint is not the same as the dashboard’s Finalize Invoice. The dashboard charges only the invoice’s own payment method, and only for an automatic one-off invoice that is due. The collect endpoint charges when you call it, and after a decline it can try the customer’s other saved payment methods.
Collect payment
Attempt to collect payment on an open invoice:
Send an Idempotency-Key header with each collect request. If you retry the same request (for
example after a timeout), send the same key: PaymentKit returns the first response and does not
charge again. Use a new key for a new attempt, because a reused key returns the first response
for 24 hours.
- If the first request is still in progress, a retry with the same key gets
409 Conflict. This does not mean the payment failed: wait, then retry with the same key. - Keys are not per invoice. Never reuse a key for a different invoice: you get the first invoice’s response, and the second invoice is not charged.
Success response
When payment succeeds, the response includes the payment outcome:
Payment failure (402 response)
When payment fails, the API returns a 402 Payment Required status code and the invoice stays unpaid. An open invoice becomes PAST_DUE once its due date has passed (an invoice without payment terms or a later due date is due when it is issued):
Card declined:
No payment method:
When payment fails, the invoice is NOT marked as paid: it stays open, or becomes past due once its due date has passed. This allows for safe retry without double-charging. Update the payment method and retry collection.
If the invoice is still in Draft state, the collect endpoint finalizes it before attempting payment.
For subscription invoices, payment collection is handled automatically by the lifecycle engine. Use the collect endpoint for manual invoices or to retry a failed payment.
Batch payment collection
Pay multiple invoices at once using confirmed payment intents. This endpoint is designed for checkout flows that create multiple subscriptions simultaneously, where payment intents are collected upfront and then applied to invoices in batch.
Request fields:
Response:
Key behaviors:
- Payment matching: Invoices are matched to payment intents by exact amount first, then by sorted order
- Subscription activation: Incomplete subscriptions linked to paid invoices automatically transition to Active
- Partial failures: Each invoice processes independently — one failure does not block others
- Idempotent: Safe to retry; already-paid invoices are skipped
All payment intents must be in succeeded status and belong to the same customer. The endpoint validates this before processing.