Invoices

Paygentic issues an invoice at the end of each billing period for every active subscription. The invoice lists the charges for the period, including usage and tax. Paygentic then collects payment from the customer. You don’t create subscription invoices yourself. You track their status, and act when a payment fails. Invoice 0, the first invoice of a subscription, works differently. Paygentic issues it when you create the subscription. See The first invoice.

Invoice statuses

Status	Description
`ACTIVE`	The billing period is still open. Charges are added as they happen.
`ISSUED`	The invoice was sent to the customer and is waiting for payment. It stays `ISSUED` while Paygentic retries a failed charge.
`PAYMENT_FAILED`	Paygentic stopped retrying a failed charge. The customer can still pay the invoice. See When an automatic charge fails.
`PAID`	The invoice is paid. This status is final.
`CANCELLED`	The invoice was cancelled, and nothing is owed. This status is final.
`WRITTEN_OFF`	The invoice was written off as unpaid. This status is final.

After a billing period ends, Paygentic calculates the final amount before it issues the invoice. During this short time, the API can return CLOSING, CLOSED, CALCULATING, or DRAFT. You don’t need to do anything with these statuses. If Paygentic can’t prepare an invoice, its status is FAILED. Contact support@paygentic.io if you see this status. If an invoice total is zero, Paygentic marks it PAID when it’s issued.

Pay an invoice

How the customer pays depends on the subscription’s autoCharge setting. See How invoices are paid. While an invoice is unpaid, its paymentUrl field links to the invoice payment page. You can use this link in your own app or emails.

Record a payment collected outside Paygentic

If the customer paid you another way, such as by bank transfer, record the payment with POST /v2/invoices/{id}/payment and method: "out_of_band". The invoice must be ISSUED or PAYMENT_FAILED. It changes to PAID immediately. reason is an optional note of up to 500 characters.

cURL

curl -X POST "https://api.sandbox.paygentic.io/v2/invoices/inv_abc123/payment" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "out_of_band",
    "reason": "Wire transfer received 2026-03-25"
  }'

The call is rejected in these cases:

400 Bad Request if the invoice total is zero (Paygentic marks those PAID itself) or the invoice nets to a credit owed to the customer.
409 Conflict while a payment for the invoice is being processed, or when Paygentic can’t confirm that payment’s status with the payment provider. Wait, check the invoice’s status, and call again only if it is still unpaid.
409 Conflict on a second call for the same invoice. Don’t retry it.

Recording Invoice 0 as paid this way activates a subscription that is pending_payment. Paygentic activates it in the background, so the subscription can take a short time to change to active. In the sandbox, this is how you activate a subscription without a payment provider. The same route with method: "hosted_link" creates a new payment link and emails it to the customer. See the API reference.

Track invoices

To list invoices, use GET /v2/invoices. You can filter by subscriptionId, customerId, or status. To get a single invoice, use GET /v2/invoices/{id}, and to download its PDF, use GET /v2/invoices/{id}/pdf.

curl "https://api.sandbox.paygentic.io/v2/invoices?customerId=cus_p1q2r3s4t5u6v7w8&status=ISSUED" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

const response = await fetch(
  'https://api.sandbox.paygentic.io/v2/invoices?customerId=cus_p1q2r3s4t5u6v7w8&status=ISSUED',
  { headers: { 'Authorization': 'Bearer sk_test_YOUR_API_KEY' } }
);

const { data: invoices } = await response.json();

import requests

response = requests.get(
    "https://api.sandbox.paygentic.io/v2/invoices",
    params={"customerId": "cus_p1q2r3s4t5u6v7w8", "status": "ISSUED"},
    headers={"Authorization": "Bearer sk_test_YOUR_API_KEY"},
)

invoices = response.json()["data"]

Paygentic sends the invoice.issued.v0 webhook when an invoice is issued, and invoice.paid.v0 when it’s paid. It doesn’t send a webhook when an invoice changes to PAYMENT_FAILED, CANCELLED, or WRITTEN_OFF. To find those invoices, filter by status. For event payloads and delivery details, see Webhooks.

API Reference: See the List Invoices and Get Invoice endpoints for all fields and filters.

See how a line was calculated

When Paygentic calculates an invoice, it saves a trace of how each line’s amount before tax was reached. To get it, add lineProvenance to the expand parameter. Each line then has a provenance field.

cURL

curl "https://api.sandbox.paygentic.io/v2/invoices/inv_a1b2c3d4e5f6g7h8?expand=lineProvenance" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

For a usage line where a grant covered 1,000 of 1,200 units, priced at €0.05 a unit, provenance looks like this:

Response

{
  "status": "recorded",
  "version": 2,
  "currency": "EUR",
  "precision": { "significantDigits": 20, "rounding": "HALF_UP" },
  "period": { "start": "2026-09-01T00:00:00.000Z", "end": "2026-10-01T00:00:00.000Z" },
  "calculatedAt": "2026-10-01T00:04:12.000Z",
  "subscriptionId": "sub_9f2c",
  "inputs": {
    "kind": "priced",
    "quantity": { "value": "1200", "source": "entitlement" },
    "selector": { "value": "1200", "source": "entitlement" },
    "price": { "fn": { "model": "unit", "rate": "0.05" }, "source": "interval" }
  },
  "sources": {
    "entitlement": {
      "type": "entitlement",
      "ref": { "entitlementId": "ent_7d3e", "billableMetricId": "bm_api_calls", "customerId": "cus_4b1a" },
      "asUsed": {
        "from": "2026-09-01T00:00:00.000Z",
        "to": "2026-10-01T00:00:00.000Z",
        "usage": "1200",
        "overage": "200",
        "softLimit": true,
        "grants": [{ "grantId": "grt_5c8a", "balance": "0" }]
      }
    },
    "interval": {
      "type": "interval",
      "ref": { "intervalId": "spi_2e6b", "priceId": "pri_api_calls", "planVersionId": null },
      "asUsed": { "rate": "0.05", "baseQuantity": "1", "cadence": "P1M", "start": "2026-06-01T00:00:00.000Z", "end": null }
    }
  },
  "steps": [
    { "op": "allow", "on": "quantity", "in": "1200", "out": "200", "params": { "covered": "1000" }, "source": "entitlement" },
    {
      "op": "evaluate",
      "on": "amount",
      "in": null,
      "out": "10",
      "params": { "quantity": "200", "selector": "1200", "fn": { "model": "unit", "rate": "0.05" }, "applied": [] },
      "source": "interval"
    }
  ],
  "notApplied": [],
  "result": { "amount": "10", "quantity": "200", "unitPrice": "0.05" }
}

How to read it:

inputs are the values the calculation started from. selector is the quantity a volume band is chosen on.
Each step changes one value (on) from in to out. A step starts where the previous step on the same value ended, so you can follow quantity, selector, price and amount through the trace.
evaluate is the one step that turns quantity and price into an amount. Steps on quantity, selector and price come before it. Steps on the amount, such as a proration, a cap or a rounding, come after it.
Every source is a key into sources. A source has ref, the ids that link to the resource, and asUsed, the values the calculation read. A price, plan or grant can change after the invoice is issued, but asUsed does not.
result equals the line’s stored amount, quantity and unit price. Tax is not part of the trace.
Grant credit and percentage discount lines have their own trace. A line source in it names the line it reduces.
status is notRecorded for a line calculated before traces were saved. Show “Calculation not recorded” for it.
status is pending while the invoice is not yet calculated.

New ops, source types, price models and reasons can be added without a new version. If your code does not know an op, show the step as “in → out, because source” and keep the rest of the trace.

expand=lineProvenance also works on GET /v2/invoices/{id}/lineItems and GET /v2/invoices/lineItems. If you do not ask for it, the response does not change.

Getting Started

Authentication

Platform

Integrations

Legal

Invoice statuses

Pay an invoice

Record a payment collected outside Paygentic

Track invoices

See how a line was calculated

Next steps