Preview Invoice | PaymentKit

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

{
  "id": "inv_4a7c9e2b1d5f4e3a",
  "customer_id": "cus_8f3b2d1a9e7c4b6d",
  "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": 5000,
  "period_start": "2024-01-01T00:00:00Z",
  "period_end": "2024-01-31T23:59:59Z",
  "collection_method": "charge_automatically",
  "custom_fields": {},
  "items": [
    {
      "id": "item_9d8f7a6b5c4e3d2f",
      "invoice_id": "inv_4a7c9e2b1d5f4e3a",
      "description": "Monthly subscription fee for Pro Plan",
      "quantity": 1,
      "amount": 150000,
      "currency": "usd",
      "metadata": {},
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "price": {
        "id": "price_1a2b3c4d5e6f7g8h",
        "account_id": "acct_1234567890abcdef",
        "product_id": "prod_0987654321fedcba",
        "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": "meter_123abc",
        "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_0a1b2c3d4e5f6g7h"
        ],
        "exclusive_customer_ids": [
          "cus_8f3b2d1a9e7c4b6d"
        ],
        "metadata": {},
        "created_at": "2023-12-01T12:00:00Z",
        "updated_at": "2024-01-10T08: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_7e6d5c4b3a2f1e0d",
      "subscription_item_id": "si_1234567890abcdef",
      "tier_breakdown": [
        {
          "label": "Base 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_7e6d5c4b3a2f1e0d",
  "payment_method_id": "pm_1a2b3c4d5e6f7g8h",
  "invoice_pdf_url": "https://app.paymentkit.com/invoices/inv_4a7c9e2b1d5f4e3a.pdf",
  "receipt_pdf_url": "https://app.paymentkit.com/receipts/rcpt_4a7c9e2b1d5f4e3a.pdf",
  "hosted_invoice_url": "https://app.paymentkit.com/invoices/inv_4a7c9e2b1d5f4e3a",
  "show_payment_link": true
}

Preview an invoice without persisting it.

Resolves prices and computes totals using pure computation — no rows are created, no invoice numbers claimed, no row locks acquired. Returns the same Invoice response with server-computed totals.

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