# 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

```bash
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

```json
{
  "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.