Invoices

An invoice is the bill: the immutable record of what a customer owes you for a period of service or a one-off purchase.

States

draft ──► open ──► partially_paid ──► paid
   │        │           │
   ▼        ▼           ▼
  void   uncollectible  …

State	Meaning
`draft`	Mutable. Lines can be added, removed, edited.
`open`	Finalised. Immutable. Awaiting payment.
`partially_paid`	Some payment received; balance remains.
`paid`	Balance is zero or below.
`void`	Cancelled before payment. Cannot be reopened.
`uncollectible`	Marked as bad debt. Does not affect AR going forward.

paid, void, and uncollectible are terminal.

How an invoice gets created

Source	When
Subscription period close	The most common path. The billing engine computes line items and finalises automatically.
Subscription change with `proration_behavior: always_invoice`	Immediate proration invoice.
`POST /v1/invoices`	One-off invoice for ad-hoc charges.
Commitment with `billing: upfront`	One invoice for the full commitment term.

Anatomy

{
  "id": "inv_…",
  "number": "INV-2026-000123",
  "customer_id": "cus_…",
  "subscription_id": "sub_…",
  "currency": "USD",
  "status": "open",
  "issued_at": "2026-05-06T00:00:00Z",
  "due_at": "2026-05-13T00:00:00Z",
  "lines": [
    { "code": "base", "description": "Pro – May 2026", "quantity": "1", "unit_amount": "49.00", "amount": "49.00" },
    { "code": "seats", "description": "Active seats × 7", "quantity": "7", "unit_amount": "10.00", "amount": "70.00" }
  ],
  "subtotal":  "119.00",
  "discount":  "11.90",
  "tax":       "8.57",
  "total":     "115.67",
  "amount_paid": "0.00",
  "amount_due":  "115.67"
}

Invariants enforced at finalisation:

total = subtotal − discount + tax
amount_paid ≤ total
currency = upper(currency) and ISO-4217
All money columns are NUMERIC(20,8); rounding is per-line.

Draft → open

Open invoices are immutable. Before finalisation, you can add ad-hoc items:

POST /v1/invoices/{id}/lines
{ "description": "One-time setup", "quantity": "1", "unit_amount": "250.00" }

Then:

POST /v1/invoices/{id}/finalize

Finalisation locks the line items, computes tax, assigns the invoice number, and transitions to open.

Payment

Once open, Paylera attempts payment using the customer’s default_payment_method_id (or the subscription’s, if set). The payment flow is documented in Payments and Charge an invoice.

You can also pay an open invoice manually:

POST /v1/invoices/{id}/pay
{ "payment_method_id": "pm_…" }

Or apply a wallet balance:

POST /v1/invoices/{id}/pay
{ "source": "wallet" }

See Wallets.

Finalisation lock

Once open, you cannot:

Edit line items, amounts, descriptions, or tax.
Change the customer, currency, or due date.
Delete the invoice.

You can:

Apply a payment.
Mark it uncollectible.
Void it (if not paid).
Issue a credit note against it.

This is non-negotiable: customer-facing invoices are accounting documents. If something needs to change after issuance, the only correct mechanism is a credit note.

PDFs

Every invoice has a stable PDF URL:

GET /v1/invoices/{id}/pdf

Returns application/pdf. The URL is signed and short-lived; for customer-facing portals, generate a new URL on each view.

Webhook events

Event	When
`invoice.created`	A draft invoice is created.
`invoice.finalized`	Transition to `open`. The customer can be billed.
`invoice.paid`	Transition to `paid`.
`invoice.payment_failed`	A payment attempt failed.
`invoice.voided`	Transition to `void`.
`invoice.marked_uncollectible`	Transition to `uncollectible`.

The most useful one to listen for is invoice.finalized — that’s when you should email the customer or update your dashboard.