Get Customers

Retrieve a list of customers from your store.

Customers are returned newest first. A customer appears in the list only if they have placed at least one order in the requested currency. Narrow the list with the optional filters below — all filters combine with AND.

Request

GET /customers

Query Parameters

Parameter	Type	Required	Default	Description
currency	string	Yes	—	Lowercase ISO currency code (e.g. pln). Scopes the money fields and list membership. See Get Store for valid values.
page	integer	No	1	Page number for pagination
per_page	integer	No	10	Items per page (min: 1, max: 100).
sort	string	No	-first_seen	Sort order: first_seen (when the customer first ordered, in the requested currency) or email. Prefix with - for descending.
created_from	string	No	—	Only customers who ordered on or after this date (inclusive), YYYY-MM-DD.
created_to	string	No	—	Only customers who ordered on or before this date (inclusive), YYYY-MM-DD.
product	string	No	—	Only customers who purchased this product (product UUID).
subscription_status	string	No	—	Only customers holding a subscription with this status. One of active, trialing, past_due, canceled, incomplete, incomplete_expired, unpaid. Store-scoped (ignores currency).
query	string	No	—	Search term. Matched as an exact email when it is a valid email address, otherwise as a partial match on the customer name.

note

The currency parameter is required: a missing or malformed currency returns a 400 error, because lifetime value and order counts are meaningless without it. The other filters are optional, but a non-empty yet unparseable value — an unknown subscription_status, a malformed date, an invalid product UUID, an out-of-range per_page, or an unknown sort field — returns a 400 (see Bad Request). The query search term is free-text and is always accepted.

Ordering: Customers default to first_seen descending (newest first) unless sort is supplied. first_seen sorts on the same date returned in each row.

Counting matches: every response includes the filtered total in pagination.total. To get only a count, request per_page=1 with your filters and read pagination.total.

Example Request

curl -X GET "https://cart.easy.tools/api/v1/customers?currency=pln&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a paginated list of customers.

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Jane Doe",
      "email": "buyer@example.com",
      "avatar": "https://example.com/avatars/jane.png",
      "first_seen": "2026-01-15T10:15:30+00:00",
      "last_order": "2026-05-20T14:02:00+00:00",
      "orders_count": 4,
      "subscriptions_count": 1,
      "lifetime_value": 19600,
      "currency": "pln"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "name": null,
      "email": "another@example.com",
      "avatar": null,
      "first_seen": "2026-03-02T09:00:00+00:00",
      "last_order": "2026-03-02T09:00:00+00:00",
      "orders_count": 1,
      "subscriptions_count": 0,
      "lifetime_value": 3900,
      "currency": "pln"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "per_page": 10,
    "total": 44
  }
}

Response Fields

Field	Type	Nullable	Description
id	string	No	Unique identifier for the customer (UUID)
name	string	Yes	Customer full name. Null when not set.
email	string	No	Customer email
avatar	string	Yes	Avatar URL. Null when not set.
first_seen	string	Yes	When the customer first ordered, in the requested currency (ISO 8601 format)
last_order	string	Yes	When the customer last ordered, in the requested currency (ISO 8601 format)
orders_count	integer	No	Number of completed orders in the requested currency
subscriptions_count	integer	No	Number of active (non-cancelled) subscriptions. Tracked per store, not per currency.
lifetime_value	integer	Yes	Net lifetime value in minor units (payments minus refunds), in the requested currency
currency	string	No	Lowercase ISO currency code the money fields are scoped to

To read a customer's orders, subscriptions, product access, or lifetime-value breakdown, call Get Customer with the include parameter.

Pagination Object

Field	Type	Description
current_page	integer	Current page number
total_pages	integer	Total number of pages
per_page	integer	Effective page size (echoes the per_page request parameter)
total	integer	Total number of customers matching the applied filters, across all pages

Error Responses

Bad Request (400)

Returned when currency is missing or malformed, or when another filter has a non-empty but unparseable value (an unknown subscription_status, a malformed date, or an invalid product UUID). The message describes the problem.

{
  "message": "A valid currency query parameter is required"
}

Unauthorized (401)

{
  "message": "Unauthenticated."
}