Skip to content

Get customer statistics

GET
/stores/{storeRef}/customers/statistics
curl --request GET \
--url https://apibase.ecomweb.app/api/v1/stores/example/customers/statistics \
--header 'x-api-key: <x-api-key>'

Returns store-wide customer figures: totals, new customers this month, active and inactive counts, average orders per customer, growth against last month and the five customers who spent the most. Deleted customers are not counted.

Required scopes: read:customers

storeRef
required
string

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

Media typeapplication/json
object
total_customers
required

Customers that are not deleted.

number
new_customers_this_month
required

Customers created since the start of the current month.

number
active_customers
required

Customers with a recent order.

number
inactive_customers
required

Customers without a recent order, including those who never ordered.

number
avg_orders_per_customer
required

Orders per customer, on average.

number
top_customers
required

Up to five customers who spent the most.

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
customers_growth
required

Growth in customer count against the end of last month, as a percentage.

number

Example

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

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