Skip to navigation

Create an invoice

Generate one-off invoices for custom charges, or understand how subscription invoices are created automatically.

View as Markdown

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.

  1. Go to Billing > Invoices in the sidebar
  2. Click Create Invoice
  3. Select a customer
  4. Set the currency and issued date
  5. Add line items with descriptions, quantities, and amounts
  6. 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

FieldDescription
nameDisplay name for the line item
descriptionDescription displayed on the invoice
quantityNumber of units (default: 1)
unit_amountPrice per unit
amountTotal amount for this line item (alternative to unit_amount * quantity)
price_idLink to an existing price in your product catalog
metadataFree-form metadata for the item

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:

EventBilling reason
Subscription createdsubscription_create
Billing period renewssubscription_cycle
Subscription items changed (with always_invoice proration)subscription_update

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:

StateDescription
DraftInvoice is being prepared. Items and amounts can still be modified.
OpenFinalized and ready for payment. Amounts are locked.
PaidPayment collected in full.
Partially paidSome payment received, balance remaining.
Past duePayment deadline has passed. Dunning retries are active.
VoidInvoice cancelled. No payment expected.
UncollectibleAll collection attempts exhausted.

Transitions

FromToTrigger
DraftOpenInvoice finalized
DraftVoidInvoice voided before finalizing
OpenPaidPayment succeeds in full
OpenPartially paidPartial payment received
OpenPast duePayment deadline passes
OpenVoidInvoice voided
OpenUncollectibleDunning exhausted
Partially paidPaidRemaining balance paid
Partially paidPast duePayment deadline passes
Partially paidVoidInvoice voided
Past duePaidPayment recovered
Past duePartially paidPartial payment received
Past dueUncollectibleDunning exhausted
UncollectibleVoidInvoice voided

Finalize an invoice

Finalizing moves a draft invoice to Open state, locks all amounts, and optionally triggers PDF generation and email delivery.

curl -X POST https://app.paymentkit.com/api/{account_id}/invoices/{invoice_id}/finalize \
-H "Authorization: Bearer sk_live_..."

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:

curl -X POST https://app.paymentkit.com/api/{account_id}/invoices/{invoice_id}/collect \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: collect-in_abc123-attempt-1"

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:

{
"invoice_id": "in_abc123",
"invoice_status": "paid",
"subscription_id": null,
"payment_status": "paid",
"error_message": null
}

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:

{
"error": "Payment failed for invoice collection",
"error_code": "PAYMENT_FAILED",
"payment_status": "failed",
"payment_error": "Your card was declined. Please try a different payment method.",
"orchestrator_summary": "Card declined by issuer (insufficient_funds)",
"invoice_id": "in_abc123",
"invoice_status": "past_due"
}

No payment method:

{
"error": "Cannot collect invoice without a payment method",
"error_code": "PAYMENT_FAILED",
"payment_status": "no_payment_method",
"payment_error": "no_payment_method",
"invoice_id": "in_abc123",
"invoice_status": "open"
}

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.

curl -X POST https://app.paymentkit.com/api/{account_id}/subscriptions/pay-multiple-invoices \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"account_id": "acc_abc123",
"customer_id": "cus_xyz789",
"payment_intent_ids": ["pi_intent1", "pi_intent2"]
}'

Request fields:

FieldTypeRequiredDescription
account_idstringYesAccount external ID
customer_idstringYesCustomer external ID (all payment intents must belong to this customer)
payment_intent_idsarrayYesList of payment intent IDs (must all be in succeeded status)
invoice_idsarrayNoSpecific invoices to pay. If omitted, matches invoices automatically by amount.

Response:

{
"outcomes": [
{
"invoice_id": "inv_abc123",
"invoice_status": "paid",
"subscription_id": "sub_xyz789",
"subscription_state": "active",
"processor_attempt_id": "pa_attempt1",
"processor_attempt_status": "succeeded",
"success": true,
"error_message": null
}
],
"total_processed": 2,
"total_succeeded": 2,
"total_failed": 0,
"overall_success": true
}

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.

Webhook events

EventTrigger
invoice.createdInvoice created
invoice.finalizedDraft finalized to Open
invoice.paidPayment collected in full
invoice.payment_succeededA payment attempt succeeded
invoice.payment_failedA payment attempt failed
invoice.overdueInvoice became past due
invoice.voidedInvoice voided
invoice.marked_uncollectibleInvoice marked uncollectible