Skip to main content

Get a Statistic

Retrieve a single statistic from your store — totals, per-bucket series, and a server-computed comparison against the previous period.

One call returns one stat type, selected with the type parameter. To assemble a dashboard view from several statistics, call this endpoint in parallel with different type values.

Request​

GET /statistics

Query Parameters​

ParameterTypeRequiredDefaultDescription
typestringYes—Which statistic to compute. See the stat types table.
currencystringYes—Lowercase ISO currency code (e.g. usd). Scopes the figures to a single currency, and must be one your store transacts in. See Get Store for valid values.
datestringNolast7daysDate range. Either a named slug (today, monthToDate, lastMonth, yearToDate, last7days, last14days, last30days, last3months, last12months, all) or a custom range as YYYY-MM-DD,YYYY-MM-DD (inclusive, valid calendar dates, start on or before end).
product_idstringNo—Restrict the statistic to a single product (product UUID). Ignored for stat types whose underlying query does not scope by product.

type and currency are required. A missing, malformed, or unrecognised currency (one your store doesn't transact in) returns 400 - the endpoint does not fall back to a zero-filled response. A missing or unknown type, a date that isn't a valid calendar range (bad month/day, or start after end), or a non-UUID product_id returns 422.

Figures are bucketed by day in your store's timezone, echoed back as date_range.timezone. This endpoint does not accept a timezone parameter.

Example Request — revenue, last 7 days​

curl -X GET "https://cart.easy.tools/api/v1/statistics?type=revenue&currency=usd" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Example Request — sales for a custom month​

curl -X GET "https://cart.easy.tools/api/v1/statistics?type=sales&currency=usd&date=2026-03-01,2026-03-31" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Example Request — revenue for a single product​

curl -X GET "https://cart.easy.tools/api/v1/statistics?type=revenue&currency=usd&date=last30days&product_id=0632bef5-c308-42cd-9cba-89a7a4f722bb" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Response​

Success Response (200)​

Returns the requested statistic.

{
"type": "revenue",
"currency": "usd",
"date_range": {
"from": "2026-01-01",
"to": "2026-01-07",
"timezone": "America/New_York"
},
"selected_total": 12500,
"previous_total": 9800,
"change": {
"absolute": 2700,
"percentage": 28
},
"data": [
{
"selected": {
"from": "2026-01-01",
"to": "2026-01-01",
"value": 1000
},
"previous": {
"from": "2025-12-25",
"to": "2025-12-25",
"value": 800
}
},
{
"selected": {
"from": "2026-01-02",
"to": "2026-01-02",
"value": 3000
},
"previous": {
"from": "2025-12-26",
"to": "2025-12-26",
"value": 2200
}
}
]
}

Response Fields​

FieldTypeNullableDescription
typestringNoEcho of the requested stat type slug
currencystringNoEcho of the requested currency (lowercase ISO)
date_rangeobjectNoInclusive date range the figures cover, and the timezone they're bucketed in. See date_range.
selected_totalintegerNoTotal across all buckets in the selected period. Money stats: minor units (e.g. cents). Count stats: the count. conversion: the period ratio (orders / checkout sessions), a percentage that can exceed 100 - not the sum of the daily rates.
previous_totalintegerNoTotal across all buckets in the matching previous period. Same units as selected_total.
changeobjectNoServer-computed comparison between the two totals. See change.
dataarrayNoPer-bucket series, one entry per bucket. May be empty when the date range has no activity. See Item.

date_range​

FieldTypeNullableDescription
fromstringNoISO date (YYYY-MM-DD) of the first bucket's start
tostringNoISO date (YYYY-MM-DD) of the last bucket's end
timezonestringNoIANA timezone used for the day boundaries (e.g. America/New_York)

change​

FieldTypeNullableDescription
absoluteintegerNoSigned delta selected_total - previous_total. Negative when the selected period is down.
percentageintegerNoRounded percentage change. 0 when the previous total was zero. Negative when the selected period is down.

Item​

FieldTypeNullableDescription
selectedobjectNoThe bucket value for the selected period. See Period.
previousobjectNoThe bucket value for the matching previous period. See Period.

Period​

FieldTypeNullableDescription
fromstringNoISO date (YYYY-MM-DD) of the bucket's start
tostringNoISO date (YYYY-MM-DD) of the bucket's end
valueintegerNoRaw integer value for this bucket (same units as selected_total)

Bucket size​

The bucket size is auto-derived from the requested date range length:

Range lengthBucket sizePrevious period
≤ 14 daysDailySame length immediately before the selected range
≤ ~100 daysWeeklySame length immediately before the selected range
≤ ~2 yearsMonthlyExactly one year back for each selected bucket
longerYearlyExactly one year back for each selected bucket

Caching​

Each unique combination of statistic type and filters is cached for 120 seconds. Rapid repeat calls within that window return the same result.

Error Responses​

Bad Request (400)​

Returned when currency is missing, not a valid three-letter ISO code, or not one your store transacts in.

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

Unauthorized Error (401)​

{
"message": "Unauthenticated."
}

Validation Error (422 Unprocessable Entity)​

Returned when type is missing or unknown, date is not a valid calendar range (bad month/day, or start after end), or product_id is not a valid UUID.

{
"message": "The selected type is invalid.",
"errors": {
"type": [
"The selected type is invalid."
]
}
}