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

Parameter	Type	Required	Default	Description
type	string	Yes	—	Which statistic to compute. See the stat types table.
currency	string	Yes	—	Lowercase ISO currency code (e.g. pln). Scopes the figures to a single currency, and must be one your store transacts in. See Get Store for valid values.
date	string	No	last7days	Date range. Either a named slug (today, monthToDate, lastMonth, yearToDate, last7days, 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_id	string	No	—	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=pln" \
  -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=pln&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=pln&date=last30days&product_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns the requested statistic.

{
  "type": "revenue",
  "currency": "pln",
  "date_range": {
    "from": "2026-01-01",
    "to": "2026-01-07",
    "timezone": "Europe/Warsaw"
  },
  "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

Field	Type	Nullable	Description
type	string	No	Echo of the requested stat type slug
currency	string	No	Echo of the requested currency (lowercase ISO)
date_range	object	No	Inclusive date range the figures cover, and the timezone they're bucketed in. See date_range.
selected_total	integer	No	Total 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_total	integer	No	Total across all buckets in the matching previous period. Same units as selected_total.
change	object	No	Server-computed comparison between the two totals. See change.
data	array	No	Per-bucket series, one entry per bucket. May be empty when the date range has no activity. See Item.

date_range

Field	Type	Nullable	Description
from	string	No	ISO date (YYYY-MM-DD) of the first bucket's start
to	string	No	ISO date (YYYY-MM-DD) of the last bucket's end
timezone	string	No	IANA timezone used for the day boundaries (e.g. Europe/Warsaw)

change

Field	Type	Nullable	Description
absolute	integer	No	Signed delta selected_total - previous_total. Negative when the selected period is down.
percentage	integer	No	Rounded percentage change. 0 when the previous total was zero. Negative when the selected period is down.

Item

Field	Type	Nullable	Description
selected	object	No	The bucket value for the selected period. See Period.
previous	object	No	The bucket value for the matching previous period. See Period.

Period

Field	Type	Nullable	Description
from	string	No	ISO date (YYYY-MM-DD) of the bucket's start
to	string	No	ISO date (YYYY-MM-DD) of the bucket's end
value	integer	No	Raw 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 length	Bucket size	Previous period
≤ 14 days	Daily	Same length immediately before the selected range
≤ ~100 days	Weekly	Same length immediately before the selected range
≤ ~2 years	Monthly	Exactly one year back for each selected bucket
longer	Yearly	Exactly 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 (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."
    ]
  }
}