Create Invoice | PaymentKit

curl -X POST https://app.paymentkit.com/api/account_id/invoices/ \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "customer_id": "cus_8f3b2a1d9e7c4f2a"
}'

{
  "id": "inv_01f4a2b3c9d8e7f6g5h4",
  "customer_id": "cus_8f3b2a1d9e7c4f2a",
  "status": "draft",
  "currency": "usd",
  "subtotal_amount_atom": 150000,
  "tax_amount_atom": 12000,
  "total_amount_atom": 162000,
  "due_amount_atom": 162000,
  "paid_amount_atom": 0,
  "remaining_amount_atom": 162000,
  "issued_at": "2024-01-15T09:30:00Z",
  "due_date": "2024-02-14T09:30:00Z",
  "description": "Monthly subscription invoice for January 2024",
  "metadata": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "applied_balance_amount_atom": 0,
  "total_discount_amount_atom": 0,
  "period_start": "2024-01-01T00:00:00Z",
  "period_end": "2024-01-31T23:59:59Z",
  "collection_method": "charge_automatically",
  "custom_fields": {},
  "items": [
    {
      "id": "item_9a8b7c6d5e4f3g2h1i0j",
      "invoice_id": "inv_01f4a2b3c9d8e7f6g5h4",
      "description": "Monthly subscription fee for Pro Plan",
      "quantity": 1,
      "amount": 150000,
      "currency": "usd",
      "metadata": {},
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "price": {
        "id": "price_123abc456def789ghi",
        "account_id": "acct_987zyx654wvu321tsr",
        "product_id": "prod_456def789ghi123abc",
        "name": "Monthly Pro Plan",
        "unit_amount_atom": 150000,
        "currency": "usd",
        "is_active": true,
        "unit_label": "month",
        "pricing_type": "recurring",
        "recurring_interval": "month",
        "recurring_interval_count": 1,
        "auto_renew": true,
        "contract_term_multiple": 1,
        "trial_days": 14,
        "usage_type": "licensed",
        "metered_id": "metered_001",
        "billing_scheme": "per_unit",
        "tier_amount_info": {
          "mode": "volume",
          "amount_atoms": [
            {
              "unit_amount_atom": 150000,
              "units_upto": 100,
              "flat_amount_atom": 0
            }
          ]
        },
        "prerequisite_price_ids": [
          "price_abc123xyz789"
        ],
        "exclusive_customer_ids": [
          "cus_exclusive001"
        ],
        "metadata": {},
        "created_at": "2023-12-01T12:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z",
        "product_name": "Pro Plan Subscription",
        "product_description": "Access to all premium features",
        "custom_fields": {},
        "quantity_divisor": 1,
        "quantity_rounding": "ceil"
      },
      "product_name": "Pro Plan Subscription",
      "proration": false,
      "period_start": "2024-01-01T00:00:00Z",
      "period_end": "2024-01-31T23:59:59Z",
      "subscription_id": "sub_1234567890abcdef",
      "subscription_item_id": "si_abcdef1234567890",
      "tier_breakdown": [
        {
          "label": "Standard Rate",
          "quantity": 1,
          "amount_atom": 150000,
          "units_from": 1,
          "unit_amount_atom": 150000,
          "flat_fee": false,
          "units_to": 1
        }
      ]
    }
  ],
  "invoice_number": 1024,
  "billing_reason": "subscription_cycle",
  "subscription_id": "sub_1234567890abcdef",
  "payment_method_id": "pm_0987654321fedcba",
  "invoice_pdf_url": "https://app.paymentkit.com/invoices/inv_01f4a2b3c9d8e7f6g5h4.pdf",
  "receipt_pdf_url": "https://app.paymentkit.com/receipts/rcpt_01f4a2b3c9d8e7f6g5h4.pdf",
  "hosted_invoice_url": "https://app.paymentkit.com/invoices/inv_01f4a2b3c9d8e7f6g5h4",
  "show_payment_link": true
}

Create a new invoice.

Supports two invoice types:

“one_off”: Manual invoice, items must be provided explicitly, no subscription_id allowed
“recurring”: Subscription-attached invoice; items must be provided explicitly (empty items 422s). Floating items are swept in only at subscription renewal, not at create time.

Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Create a new invoice. Supports two invoice types: - "one_off": Manual invoice, items must be provided explicitly, no subscription_id allowed - "recurring": Subscription-attached invoice; items must be provided explicitly (empty items 422s). Floating items are swept in only at subscription renewal, not at create time. Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

account_idstringRequired

Request

This endpoint expects an object.

customer_idstringRequired

invoice_typeenumOptional

statusenumOptional

collection_methodenumOptional

billing_reasonenum or nullOptional

currencyenum or nullOptional

Invoice currency. If not provided, inferred from the first item's price currency.

issued_atdatetime or nullOptional

Invoice issue date. Defaults to the current time if not provided.

due_datedatetime or nullOptional

descriptionstring or nullOptional

metadatamap from strings to any or nullOptional

custom_fieldsmap from strings to any or nullOptional

Custom field values to set on this invoice. Keys must match defined field keys for the invoice entity type. Set a key to null to delete that field's value.

coupon_idstring or nullOptional

ID of a coupon to attach as a discount to this invoice.

net_dinteger or nullOptional

Number of days after issuance that the invoice is due. Overrides due_date if provided.

default_payment_method_idstring or nullOptional

ID of the default payment method for this invoice.

show_payment_linkbooleanOptionalDefaults to false

When true, the ‘Pay online’ link is rendered on the invoice PDF and in-app preview.

itemslist of objects or nullOptional

Response

Successful Response

idstring

customer_idstring

statusenum

currencyenum

ISO 4217 currency codes.

subtotal_amount_atominteger or null

tax_amount_atominteger or null

total_amount_atominteger or null

due_amount_atominteger or null

paid_amount_atominteger or null

remaining_amount_atominteger or null

issued_atdatetime

due_datedatetime or null

descriptionstring or null

metadatamap from strings to any or null

created_atdatetime

updated_atdatetime

applied_balance_amount_atominteger or nullOptional

total_discount_amount_atominteger or nullOptional

period_startdatetime or nullOptional

period_enddatetime or nullOptional

collection_methodenumOptional

custom_fieldsmap from strings to any or nullOptional

Custom field values. Only included when expand=custom_fields is specified.

itemslist of objectsOptional

invoice_numberinteger or nullOptional

billing_reasonenum or nullOptional

subscription_idstring or nullOptional

payment_method_idstring or nullOptional

invoice_pdf_urlstring or nullOptional

receipt_pdf_urlstring or nullOptional

hosted_invoice_urlstring or nullOptional

show_payment_linkbooleanOptionalDefaults to false

Errors

422

Unprocessable Entity Error