Skip to content

Get the analytics summary

GET
/stores/{storeRef}/analytics/summary
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/analytics/summary?period=day&start_date=2025-01-01&end_date=2025-01-31' \
--header 'x-api-key: <x-api-key>'

Returns key metrics, growth rates, top products, payment methods, geographic distribution and a time series. Pass start_date and end_date together for a custom range, both inclusive and at most 5 years long, and not in the future; growth is then measured against the window of equal length immediately before it. With neither, the period parameter decides the window.

Required scopes: read:analytics

storeRef
required
string

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

period
string
default: day
Allowed values: day week month year

Reporting window when no custom range is given: day covers the last 30 days, week the last 12 weeks, month the last 12 months and year the last 5 years. Growth compares it with the window of equal length before it.

start_date
string

Example

2025-01-01

Start of a custom range. A YYYY-MM-DD calendar date is read as the first instant of that day in the store timezone; a full timestamp is taken as given.

end_date
string

Example

2025-01-31

End of a custom range, inclusive. A YYYY-MM-DD calendar date is read as the LAST instant of that day in the store timezone, so the same date at both ends covers that whole day.

Media typeapplication/json
object
customer_activity_rate
required

Customers on the store’s customer list who ordered in the period, as a percentage of all customers in the store. NOT a conversion rate: no session data is collected, so a true conversion rate is not computable.

number
conversion_rate
required

Misnamed alias of customer_activity_rate. Prefer that field.

number
top_selling_products
required

The best-selling products of the period, at most 10.

Array<object>
object
image_url
required

Image URL of the product, or null.

string
nullable
id
required

Product ID, as a string.

string
name
required

Product name.

string
total_revenue
required

Revenue from the product in the period, in the store currency.

number
total_orders
required

Orders that contain the product.

number
units_sold
required

Sum of line quantities in the period. total_orders counts orders.

number
avg_order_value
required

Average revenue per order that contains the product.

number
payment_methods
required

Revenue split by payment method.

Array<object>
object
method
required

Payment method, as recorded on the orders.

string
count
required

Orders paid with the method.

number
total_revenue
required

Revenue from those orders, in the store currency.

number
percentage
required

Share of the period’s revenue, as a percentage from 0 to 100.

number
geographic_distribution
required

Revenue split by shipping city, at most 15 cities.

Array<object>
object
city
required

Shipping city, or Unknown for orders without one.

string
total_orders
required

Orders shipped to the city.

number
total_revenue
required

Revenue from those orders, in the store currency.

number
percentage
required

Share of the period’s revenue, as a percentage from 0 to 100.

number
time_series_data
required

Orders, revenue and customers over time. It always covers the window of period, even when a custom range is given.

Array<object>
object
date
required

Start of the bucket: YYYY-MM-DD for day, IYYY-IW (ISO year and week) for week, YYYY-MM for month and YYYY for year.

string
revenue
required

Revenue of the bucket, in the store currency.

number
orders
required

Orders placed in the bucket.

number
customers
required

Distinct customers who ordered in the bucket.

number
total_revenue
required

Revenue in the period, in the store currency. Cancelled, refunded and voided orders are excluded.

number
total_orders
required

Orders in the period.

number
total_customers
required

Distinct customers who ordered in the period, guest checkouts included.

number
total_products
required

Active products in the store right now, whatever the period.

number
revenue_growth
required

Change in revenue against the previous window, as a percentage. 100 when the previous window had none and this one has some.

number
orders_growth
required

Change in orders against the previous window, as a percentage.

number
customers_growth
required

Change in customers against the previous window, as a percentage.

number
avg_order_value
required

Average revenue per order in the period.

number

Example generated

{
"customer_activity_rate": 1,
"conversion_rate": 1,
"top_selling_products": [
{
"image_url": "example",
"id": "example",
"name": "example",
"total_revenue": 1,
"total_orders": 1,
"units_sold": 1,
"avg_order_value": 1
}
],
"payment_methods": [
{
"method": "example",
"count": 1,
"total_revenue": 1,
"percentage": 1
}
],
"geographic_distribution": [
{
"city": "example",
"total_orders": 1,
"total_revenue": 1,
"percentage": 1
}
],
"time_series_data": [
{
"date": "example",
"revenue": 1,
"orders": 1,
"customers": 1
}
],
"total_revenue": 1,
"total_orders": 1,
"total_customers": 1,
"total_products": 1,
"revenue_growth": 1,
"orders_growth": 1,
"customers_growth": 1,
"avg_order_value": 1
}

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