Skip to navigation
TIANKII API - API KeyCustomers

List customers

View as Markdown

List customers

Returns a paginated list of customers belonging to the authenticated merchant’s store. Results are always scoped to the caller’s storeId.

Authentication

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

Query params

  • Pagination: page (default 1) and per_page (default 10). Set per_page=0 to return all records (no pagination).
  • name / email: partial, case-insensitive contains filters applied to the respective columns.
  • filter: generic multi-field search across name, email, mobile (Prisma where fragment produced by the @Filter decorator).
  • sort: ordering over createdAt, name, email (Prisma orderBy produced by the @Sort decorator).
  • sorter: JSON-encoded ordering object (allowed keys: createdAt, name, email, each asc or desc). When provided it overrides sort.

Response

Envelope with _metadata (page, per_page, total_page, total_count) and a records array of customer objects.

Notas: Results are always filtered to the authenticated store’s storeId. per_page=0 disables pagination (returns everything; _metadata.per_page then equals total_count). The sorter JSON param, when supplied, takes precedence over sort. start_at/end_at date filters are NOT part of this DTO (FilterCustomerDto extends PaginationDto, not FilterDateDto).

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.
namestringOptional

Case-insensitive partial match on the customer name.

emailstringOptional

Case-insensitive partial match on the customer email.

filterstringOptional

Filter with the query language. Accepts a string expression or a URL-encoded JSON object following Prisma’s where clause.

Allowed fields: name, email, mobile

Allowed operators: equals, not, in, notIn, lt, lte, gt, gte, contains, startsWith, endsWith, like

String format: field:operator:value, comma-separated. The operator defaults to equals (field:value), and | works as a separator. Group with AND(...) or OR(...) — AND is the default.

JSON format: {"OR":[{"name":{"contains":"Jane"}}]}

sortstringOptional

Sort by one or more fields, comma-separated.

Allowed fields: createdAt, name, email

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: createdAt, name, email