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. See Get Store for valid values.
date	string	No	last7days	Date range. Either a named slug (today, monthToDate, yearToDate, last7days, last30days, last3months, last12months, all) or a custom range as YYYY-MM-DD,YYYY-MM-DD (inclusive).
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.

note

type and currency are required. A missing or invalid currency returns 400; a missing or unknown type, a malformed date, or a non-UUID product_id returns 422.

info

display_value strings are always formatted in English locale (e.g. "125.00 PLN", "28%"). You always get "125.00 PLN", never "125,00 zł".

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": {
    "start": "2026-01-01",
    "end": "2026-01-07"
  },
  "selected_total": {
    "value": 12500,
    "display_value": "125.00 PLN"
  },
  "previous_total": {
    "value": 9800,
    "display_value": "98.00 PLN"
  },
  "change": {
    "absolute": 2700,
    "percentage": 28,
    "direction": "up"
  },
  "data": [
    {
      "selected": {
        "start": "2026-01-01",
        "end": "2026-01-01",
        "value": 1000,
        "display_value": "10.00 PLN"
      },
      "previous": {
        "start": "2025-12-25",
        "end": "2025-12-25",
        "value": 800,
        "display_value": "8.00 PLN"
      }
    },
    {
      "selected": {
        "start": "2026-01-02",
        "end": "2026-01-02",
        "value": 3000,
        "display_value": "30.00 PLN"
      },
      "previous": {
        "start": "2025-12-26",
        "end": "2025-12-26",
        "value": 2200,
        "display_value": "22.00 PLN"
      }
    }
  ]
}

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. See date_range.
selected_total	object	No	Total across all buckets in the selected period. See Total.
previous_total	object	No	Total across all buckets in the matching previous period. See 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
start	string	No	ISO date (YYYY-MM-DD) of the first bucket's start
end	string	No	ISO date (YYYY-MM-DD) of the last bucket's end

Total

Field	Type	Nullable	Description
value	integer	No	Raw integer value. Money stats: minor units (e.g. cents). Count stats: the count. conversion: a rounded percentage 0–100.
display_value	string	No	Pre-formatted English-locale value (e.g. "125.00 PLN", "28%", "42")

change

Field	Type	Nullable	Description
absolute	integer	No	Signed delta selected_total.value - previous_total.value. May be negative.
percentage	integer	No	Rounded percentage change. 0 when the previous total was zero. May be negative.
direction	string	No	up (absolute > 0), down (absolute < 0), or flat (absolute === 0)

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
start	string	No	ISO date (YYYY-MM-DD) of the bucket's start
end	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.value)
display_value	string	No	Pre-formatted English-locale bucket value

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 or not a valid three-letter ISO code.

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

Unauthorized (401)

{
  "message": "Unauthenticated."
}

Validation Error (422)

Returned when type is missing or unknown, date is malformed, or product_id is not a valid UUID.

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