Skip to content

List customers

GET
/stores/{storeRef}/customers
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/customers?limit=20&offset=0&status=active&sort_by=name&sort_order=asc&sort=name&order=asc&filters=%5B%7B%22field%22%3A%22status%22%2C%22operator%22%3A%22is%22%2C%22values%22%3A%5B%22active%22%5D%7D%5D' \
--header 'x-api-key: <x-api-key>'

Returns a page of the store’s customers that are not deleted, newest first by default. Use limit and offset to page, search for free text over name, email and phone, and status to narrow the list. Each customer carries order figures such as total_orders and total_spent. sort_by accepts total_orders, total_spent and last_order_date, but those three order only the rows of the current page. filters takes a JSON array of {field, operator, values} clauses (at most 10 clauses and 50 values each).

Required scopes: read:customers

storeRef
required
string

The store’s ref, as returned by GET /stores.

limit
number
default: 20 >= 1 <= 10000

Example

20

Number of items per page

offset
number
0

Example

0

Number of items to skip

search
string

Search by name/email/phone

status
string
Allowed values: active inactive all

Filter by status

sort_by
string
Allowed values: name created_at total_orders total_spent last_order_date

Sort field

sort_order
string
Allowed values: asc desc

Example

desc

Sort order

sort
deprecated
string
Allowed values: name created_at total_orders total_spent last_order_date

Deprecated. Use sort_by.

order
deprecated
string
Allowed values: asc desc

Deprecated. Use sort_order.

filters
string

Example

[{"field":"status","operator":"is","values":["active"]}]

Admin list-view filters, a JSON array of {field, operator, values}. At most 10 clauses, at most 50 values each.

Media typeapplication/json
object
data
required
Array<object>
object
status
required

Account status set by the store. An inactive customer cannot sign in.

string
Allowed values: active inactive
activity_state

Ordering activity: active for a recent order, inactive for an old one, never_ordered for none. Separate from status.

string
Allowed values: active inactive never_ordered
id
required

Customer ID.

number
email
required

Email address. Empty for a customer created with a phone number only.

string
name
required

Full name.

string
phone

Phone number, or null.

string
nullable
avatar_url

Avatar image URL, or null.

string
nullable
user_id

ID of the sign-in identity linked to the customer, or null for a customer who never signed in.

string
nullable
notes

Internal notes about the customer, or null.

string
nullable
created_at
required

When the customer was created, as an ISO 8601 timestamp.

string
updated_at
required

When the customer was last updated, as an ISO 8601 timestamp.

string
deleted_at

When the customer was deleted, or null while the customer is live.

string
nullable
first_order_date

Date of the first order, as an ISO 8601 timestamp. Absent when the customer has no orders.

string
last_order_date

Date of the latest order, as an ISO 8601 timestamp. Absent when the customer has no orders.

string
days_since_last_order

Days since the latest order. Absent when the customer has no orders.

number
total_orders

Orders placed by the customer.

number
cancelled_orders

Cancelled orders.

number
refunded_orders

Refunded orders.

number
revenue_orders

Orders that count towards revenue: those neither cancelled nor refunded.

number
total_spent

Total spent across revenue orders, in the store currency.

number
avg_order_value

Average value of a revenue order, in the store currency.

number
linked_guest_orders

Orders placed as a guest with the customer’s email and linked to them by it.

number
meta
required
object
total
required

Total number of items matching the request.

number
limit
required

Maximum number of items in this page.

number
offset
required

Number of items skipped before this page.

number
page
required

Current page number, starting at 1.

number
totalPages
required

Total number of pages.

number
hasNext
required

Whether a next page exists.

boolean
hasPrev
required

Whether a previous page exists.

boolean

Example

{
"data": [
{
"status": "active",
"activity_state": "active"
}
]
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}