Invoices

Create an invoice

A single route creates invoices of every type — there is no per-type endpoint. type is the discriminator that decides which of the remaining fields apply.

The 201 body is the minimal envelope — it carries no amount. Read the invoice by id for the full card. Validation is strict: an unknown field in the body or an unknown type is a 400. Creation writes a single row — no payment currency is chosen and no payment provider is called, and the merchant settings in force at that moment are frozen into the invoice. A server-to-server caller signs this request with an API key instead of a session JWT: see Authentication and API keys.

List invoices

Lists your invoices with filters, search and keyset pagination. Soft-deleted invoices never appear, whatever the filters.

The set of displayStatus values is not published in this reference yet — it belongs with the invoice status reference, which this section does not cover. An empty value (?type=) means no filter at all; an unknown one is a 400, as is an unknown query parameter. Filter groups combine with AND, values inside a group with IN. Paging is keyset: the sort is always createdAt then id as a tiebreak, both in the same direction, and the cursor is an opaque token carrying a fingerprint of the filters and of sortOrder — change either and paging restarts. limit is not part of that fingerprint and may change between pages. totalCount is the size of the whole filtered set, not of what is left after the cursor. For the fixed types totalAmount is the invoice's own base amount; for an open donation it is null until money arrives, and then the sum of all receipts converted to your base currency. The JSON shape of a money value is not pinned by this version of the reference — read it from the response rather than assuming a decimal string.

Get an invoice

Returns the full invoice card: header fields, the type-specific data envelope, the payment currencies frozen at creation, and the first page of payments.

The example above is abridged. It leaves out the merchant object — the merchant's first and last name — because this reference does not pin the field names inside it. Every money value on the card, including unitPrice and totalPrice on each line item, is a placeholder: the JSON shape of a money value is not pinned by this version of the reference either, so read it from the response rather than assuming a decimal string. So is allowedCurrencies, the snapshot of the currencies this invoice may be paid in. data is polymorphic and is the only part of the read path that knows about the type: for PAYME, SUBSCRIPTION and DONATION it is { amount, description, title } (amount is null for a donation, and title is only ever set there); for GOODS_SERVICES it is { items[], totalAmount, orderId }, where each item adds totalPrice and an imageUrl that is null when no image was attached. The order of the ownership checks is deliberate: an invalid id is a 400, a missing one a 404, someone else's a 403, and only then a soft-deleted one a 404 again — so a 403 does confirm that the id exists.

List invoice payments

Pages through the invoice’s successful receipts. One row is one actual transfer, including partial ones. The invoice card already carries the first page.

Sorting is fixed — paidAt descending with id as a tiebreak; there are no filters and no sortOrder. A row is one receipt, so attempts in PARTIALLY_PAID, PAID_LATE and BLOCKED appear here too — that list is illustrative, not exhaustive. status is the status of the parent attempt and amount is that single transaction in the currency it was paid in, which is not your base currency: baseCurrency belongs to totalBaseAmount, the sum of every row converted for you. payerEmail is null on older attempts, and totalCount covers every receipt on the invoice, not just this page. The JSON shape of a money value is not pinned by this version of the reference — read it from the response rather than assuming a decimal string.

Cancel an invoice

Moves the invoice to CANCELED. Answers 200 with the same detail card as Get an invoice, not a new resource — which is why the status is 200 and not 201.

Two checks run in order. The type's state machine allows the transition from ACTIVE but not from EXPIRED. On top of that, PAYME and GOODS_SERVICES refuse cancellation once a payment has started — an attempt in PROCESSING, PARTIALLY_PAID, BLOCKED, PAID, PAID_LATE or REFUNDED. A DONATION can be cancelled regardless of what it has received. Both refusals come back as VALIDATION_ERROR, not as a dedicated code. A SUBSCRIPTION plan follows its own rules: it can be cancelled from ACTIVE or PAUSED whatever its subscribers have paid, its subscribers are cancelled with it and unpaid period invoices are closed without a refund. A plan in any other state answers 409 BUSINESS_INVOICE_CANNOT_CANCEL, and a cancelled plan cannot be reactivated.

Reactivate an invoice

Takes a cancelled invoice back to ACTIVE, provided its expiresAt is still in the future or null. Answers 200 with the same detail card as Get an invoice, not a new resource — which is why the status is 200 and not 201.

The deadline is checked separately from the state machine: the machine is a pure function of statuses and knows nothing about time, so without that extra check an expired invoice would come back to life pointing at a payment form that is already dead. An expired invoice is refused with VALIDATION_ERROR, like any other forbidden transition.

Delete an invoice

Soft-deletes the invoice: the row stays in the database with a deletion timestamp, but disappears from the list and from the payment form. Answers 200 with the same detail card as Get an invoice, not an empty 204.

Two guards, and they fail with different codes. A type that forbids deletion is a plain VALIDATION_ERROR; payment activity gets the dedicated BUSINESS_INVOICE_CANNOT_DELETE. The payment check uses the same attempt statuses as cancellation, but here there is no per-type bypass — the rule holds for donations too. A SUBSCRIPTION plan is stricter: it must be CANCELED first, otherwise the answer is 409 SUBSCRIPTION_PLAN_NOT_CANCELED, and none of its period invoices may carry a payment attempt or receipt — even an attempt that never received any money blocks deletion with BUSINESS_INVOICE_CANNOT_DELETE. Deleting a plan removes its subscribers and period invoices along with it. Repeat deletes are idempotent as far as the caller can tell: the second one answers 404 BUSINESS_INVOICE_NOT_FOUND.