BillingInvoices

Customize an invoice

Configure payment terms, collection methods, metadata, and custom fields on invoices.
View as Markdown

Collection method

Control how payment is collected on an invoice:

MethodBehavior
charge_automaticallyPaymentKit charges the customer’s payment method on file when the invoice is finalized.
send_invoiceThe invoice is sent to the customer and they pay manually through the hosted invoice page.
$curl -X POST https://api.paymentkit.com/api/{account_id}/invoices \
>-H "Authorization: Bearer sk_live_..." \
>-H "Content-Type: application/json" \
>-d '{
>  "customer_id": "cus_abc123",
>  "currency": "USD",
>  "issued_at": "2026-02-01T00:00:00Z",
>  "collection_method": "send_invoice",
>  "items": [
>    {"description": "Consulting - January", "quantity": 1, "amount": 2000.00}
>  ]
>}'

Payment terms

Set due_date to specify when payment is due. For subscription invoices, the net_d field on the subscription controls due dates automatically.

$curl -X POST https://api.paymentkit.com/api/{account_id}/invoices \
>-H "Authorization: Bearer sk_live_..." \
>-H "Content-Type: application/json" \
>-d '{
>  "customer_id": "cus_abc123",
>  "currency": "USD",
>  "issued_at": "2026-02-01T00:00:00Z",
>  "due_date": "2026-03-01T00:00:00Z",
>  "collection_method": "send_invoice",
>  "items": [
>    {"description": "Consulting - January", "quantity": 1, "amount": 2000.00}
>  ]
>}'

Custom fields

Attach structured custom data to invoices. Custom field keys must match field definitions configured for the invoice entity type in your account.

Set custom fields at creation

$curl -X POST https://api.paymentkit.com/api/{account_id}/invoices \
>-H "Authorization: Bearer sk_live_..." \
>-H "Content-Type: application/json" \
>-d '{
>  "customer_id": "cus_abc123",
>  "currency": "USD",
>  "issued_at": "2026-02-01T00:00:00Z",
>  "custom_fields": {
>    "purchase_order": "PO-2026-0042",
>    "department": "Engineering"
>  },
>  "items": [
>    {"description": "Monthly platform fee", "quantity": 1, "amount": 999.00}
>  ]
>}'

Retrieve custom fields

Include expand=custom_fields when fetching an invoice:

$curl -X GET "https://api.paymentkit.com/api/{account_id}/invoices/{invoice_id}?expand=custom_fields" \
>-H "Authorization: Bearer sk_live_..."

Delete a custom field value

Set a field key to null to remove it:

1{
2  "custom_fields": {
3    "department": null
4  }
5}

Metadata

Attach free-form key-value data to an invoice using the metadata field. Unlike custom fields, metadata does not require predefined field definitions.

$curl -X POST https://api.paymentkit.com/api/{account_id}/invoices \
>-H "Authorization: Bearer sk_live_..." \
>-H "Content-Type: application/json" \
>-d '{
>  "customer_id": "cus_abc123",
>  "currency": "USD",
>  "issued_at": "2026-02-01T00:00:00Z",
>  "metadata": {
>    "internal_ref": "INV-2026-Q1-042",
>    "sales_rep": "jsmith"
>  },
>  "items": [
>    {"description": "Quarterly license", "quantity": 1, "amount": 4500.00}
>  ]
>}'

Invoice documents

PaymentKit automatically generates PDF documents for finalized invoices.

DocumentGenerated when
Invoice PDFInvoice is finalized (Draft to Open)
Receipt PDFInvoice is fully paid

PDF URLs are available on the invoice object via invoice_pdf_url and receipt_pdf_url.

Hosted invoice page

Every invoice has a public hosted URL that customers can access without authentication. The hosted invoice URL is included automatically in customer-facing emails sent by PaymentKit.

PaymentKit automatically includes the hosted invoice URL in customer-facing emails to provide a self-service payment experience.