Skip to navigation
TIANKII API - API KeyCustomers

List customer invoices

View as Markdown

Customer invoice history

Returns the paginated list of invoices (payment requests of type INVOICE) that have been issued to the customer :id. Use it to render a customer’s invoice history without filtering the global payment-requests list by hand.

Internally it validates that the customer belongs to the caller’s store and then calls the payment-requests finder with CustomerId forced to the path id and the type pinned to INVOICE.

Authentication

  • Send the merchant API key in the x-api-key header (alias x-account-api-key).
  • Requires the scope: Merchant.payment_link.read (note: the payment_link scope, not customer).
  • Optionally scope the key with x-application-account-id (alias x-account-id) or the application_account_id / account_id query param.

Path params

  • id: the customer UUID. If it does not belong to the caller’s store the request fails with 404 Not Found.

Query params (FilterPaymentRequestsDto)

  • Pagination: page (default 1), per_page (default 10).
  • Date range: start_at / end_at (ISO date-time, validated as a pair) over the Created date.
  • Status: numeric payment request status (0 = PENDING, 1 = COMPLETED, 2 = EXPIRED, 3 = ACTIVE, 4 = DEACTIVATED).
  • sort (allowed fields Status, Created, Archived) or sorter (JSON string, e.g. {"Created":"desc"}).

There is no request body.

Notas: Handler: customersService.findBillingInvoices -> paymentRequestsService.findMany with CustomerId injected and type pinned to INVOICE. The type and CustomerId query params are ignored/overridden. Uses the payment_link.read scope even though it lives under /customers.

Authentication

x-api-keystring
API Key authentication via header

Path parameters

idstringRequired

The customer’s unique identifier (UUID). Must belong to the authenticated store.

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.

StatusintegerOptional

Filter by payment request status: 0 PENDING, 1 COMPLETED, 2 EXPIRED, 3 ACTIVE, 4 DEACTIVATED.

sortstringOptional

Sort by one or more fields, comma-separated.

Allowed fields: Status, Created, Archived

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

sorterstringOptional

Alternative to sort: a JSON string mapping a field to a direction (asc / desc).

Allowed fields: Status, Archived, Created