Gift wheel analytics

GET /analytics/wheel-games

Returns the gift wheel analytics of one shop (shop_id) or all your shops over a period: total participations, validated participations, gifts claimed, CTA clicks and marketing opt-ins with their respective rates, a breakdown of the gifts won, the evolution over time at the requested granularity, and the comparison with the previous period of identical duration.

Requires the wheel_games:read scope.

Returns a single object (no pagination). The gift_breakdown lists at most the 20 most won gifts; gift_breakdown_truncated is true when less frequent gifts were omitted (summing the breakdown then does not equal total_participations). All figures are zero when the period holds no participation.

Example request


curl "https://api.dokaa.app/v1/analytics/wheel-games?from=FROM&to=TO" \
  -H "Authorization: Bearer dk_live_..."

Query parameters

shop_id (string) – Restrict to a single shop (omit to query all your shops)
from (string, required) (format: date) – First day of the period (UTC)
to (string, required) (format: date) – Last day of the period (UTC)
granularity (string) (default: day; one of: hour, day, week, month) – Bucket size of the evolution series. The allowed span depends on the granularity: 31 days for hour, 366 for day, 1095 for week, 3660 for month; larger ranges answer a 422 problem.

Responses

200 – Gift wheel aggregates, evolution and previous-period comparison


{
  "period": {
    "from": "2026-07-01",
    "to": "2026-08-05"
  },
  "granularity": "day",
  "total_participations": 100,
  "validated": 80,
  "validation_rate": 80,
  "gifts_claimed": 40,
  "claim_rate": 40,
  "cta_clicks": 25,
  "cta_click_rate": 25,
  "marketing_optins": 60,
  "marketing_optin_rate": 60,
  "previous_participations": 50,
  "previous_validated": 30,
  "previous_gifts_claimed": 10,
  "participations_delta": 50,
  "validated_delta": 50,
  "gifts_claimed_delta": 30,
  "participations_evolution": 100,
  "validated_evolution": 167,
  "gifts_claimed_evolution": 300,
  "gift_breakdown": [
    {
      "gift": "Dessert offert",
      "count": 30,
      "claimed": 12
    }
  ],
  "gift_breakdown_truncated": false,
  "evolution": [
    {
      "date": "2026-07-01",
      "participations": 4,
      "validated": 3,
      "gifts_claimed": 1
    }
  ]
}

401 – Missing, invalid, or revoked API key

403 – The API key does not grant access to this resource

422 – Invalid request parameters

Errors are application/problem+json (RFC 9457) with type, title, status and detail fields.