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

## 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

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"}}]}

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

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

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.

$	curl -G https://api.md.tiankii.com/v1/customers \
>	-H "x-application-account-id: acct_3f9a21c7" \
>	-H "x-api-key: <apiKey>" \
>	--data-urlencode email=jane@example.com \
>	--data-urlencode filter=AND(name:contains:jane,email:endsWith:@example.com) \
>	-d name=jane \
>	-d sort=-createdAt \
>	--data-urlencode sorter={"createdAt":"desc"}

List customers

Authentication

Query params

Response

Authentication

Headers

Query parameters

List customers

Authentication

Query params

Response