Skip to navigation
TIANKII API - API KeyCheckout Invoice

List invoices

View as Markdown

List invoices

Returns a paginated list of invoices for the authenticated merchant, filterable by status, date range, app and payment/LNURL request ids.

Auth

x-api-key header with Merchant.invoice.read. Also accepts JWT user and limited JWT user tokens.

Filtering conventions

  • Status uses enum-filter syntax: a bare value (new) or an operator form such as in:new,complete.
  • start_at / end_at must be supplied together (each requires the other) and are parsed as date-times.
  • include selects extra attributes to embed in each invoice (repeatable / array).
  • sort accepts one or more of the allowed order fields.
  • Pagination via page (default 1) and per_page (default 10).

Notas: FilterInvoiceDto extends FilterDateDto (which extends PaginationDto), so date-range and pagination params are inherited. Field names are PascalCase to match the Prisma Invoices model.

Authentication

x-api-keystring
API Key authentication via header

Headers

x-application-account-idstringOptional

Scope the request to a specific store / account instead of the one resolved from the API key. Aliases: the x-account-id header, or the application_account_id / account_id query parameter.

Query parameters

pageintegerOptionalDefaults to 1
Page number to return.
per_pageintegerOptionalDefaults to 10
Number of records per page.
start_atdatetimeOptional

Start of the Created date range (ISO 8601). Must be sent together with end_at — supplying only one is a validation error.

end_atdatetimeOptional

End of the Created date range (ISO 8601). Must be sent together with start_at.

StatusstringOptional

Filter by checkout invoice status.

Allowed values: new, invalid, expired, complete, paid

Allowed operators: equals, in, not, notIn

Formats: value (defaults to equals), operator:value, operator|value, a comma-separated list for in / notIn (in:a,b), or a JSON object ({"in":["a","b"]}).

ArchivedbooleanOptional

Return only archived (true) or unarchived (false) charges.

AppIdstringOptional

Return only charges belonging to this app / terminal.

PaymentRequestIdstringOptional
Return only charges generated by this payment request.
LnurlpRequestIdstringOptional

Return only charges generated by this LNURL-pay request.

sortstringOptional

Sort by one or more fields, comma-separated.

Allowed fields: Status, Created, AppId, PaymentRequestId, Archived

Formats: field (ascending by default), +field, -field, field:asc, field:desc (| also works as the separator).

includeenumOptional

Extra attributes to embed in each charge. Repeat the parameter to request several.

Allowed values: buyer.all, buyer.contact, pos_data, pos_data.json, summary, app, refund