> ## Documentation Index
> Fetch the complete documentation index at: https://docs-consumer.voucher.allride.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Redemption, entity and link statistics in your time zone, and how they differ from billing quantities.

The Analytics endpoints answer "how many vouchers did we redeem, from whom, through which channel, and how well do our links convert". They need `view-consumer-analytics`, which you can delegate to an API key.

## Statistics

| Operation | What it returns |
| - | - |
| [Analytics overview](https://docs-consumer.voucher.allride.io/api-reference/consumer-analytics-overview.md) `GET /consumer/v1/analytics/overview` | One summary for a date range (`from`, `to`, at most 366 days; default: this month so far): redeemed, voided and net counts with the void rate, the same figures for the previous period of equal length, unique and new redemption entities, face value issued in euros, redemptions per channel, your top 5 providers, the Redemption Link funnel and your catalog coverage (visible versus enabled providers and voucher sets, upcoming and leaving sets, enabled sets that are low or depleted) |
| [Redemption statistics](https://docs-consumer.voucher.allride.io/api-reference/consumer-analytics-redemption-stats.md) `GET /consumer/v1/analytics/redemption-stats` | Rows per period (`granularity=month` or `day`), grouped by `provider` (default), `voucher-set`, `channel`, `redemption-link` (comma-separated) or `none` |
| [Entity statistics](https://docs-consumer.voucher.allride.io/api-reference/consumer-analytics-entity-stats.md) `GET /consumer/v1/analytics/entity-stats` | Per period: unique redemption entities that redeemed, new entities, and redemptions without an entity |
| [Link funnel statistics](https://docs-consumer.voucher.allride.io/api-reference/consumer-analytics-link-stats.md) `GET /consumer/v1/analytics/link-stats` | Per period, optionally per link: landing visits, OTP emails requested, OTPs verified, redemptions and the conversion rate |

Redemptions per provider per month, the headline figure, is the default of the redemption statistics:

```bash theme={null}
curl -G "$VOUCHER_API_BASE_URL/consumer/v1/analytics/redemption-stats" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  --data-urlencode "granularity=month" \
  --data-urlencode "groupBy=provider" \
  --data-urlencode "filter[period][gte]=2026-09" \
  --data-urlencode "filter[period][lte]=2026-10"
```

```json theme={null}
{
  "data": {
    "data": [
      {
        "resource": "redemption-stats-row",
        "period": "2026-10",
        "periodStart": "2026-09-30T22:00:00Z",
        "periodEnd": "2026-10-31T23:00:00Z",
        "providerPartnerId": 1030,
        "providerDisplayName": { "de": "Acme Scooters", "en": "Acme Scooters" },
        "voucherSetId": null,
        "voucherSetName": null,
        "channel": null,
        "redemptionLinkId": null,
        "redeemedCount": 30117,
        "voidedCount": 70,
        "netCount": 30047,
        "faceValue": { "value": 15058500, "label": "€150,585.00" }
      }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "total": 1
  }
}
```

How to read the rows:

* Statistics rows are values, not resources: they have `resource` but no `id` or `_links`. Dimensions you did not group by are `null`.
* A void counts in the period of its `voidedAt`, not of the original redemption. `netCount` = redeemed − voided, so a period can have a negative `netCount`.
* With `groupBy=none` every period of the range is returned, zero-filled; with a grouping, only combinations that have data. Entity statistics are always zero-filled.
* Filter with `filter[period][gte]`, `filter[period][lte]` (months `YYYY-MM` or days `YYYY-MM-DD`), `filter[providerPartnerId]`, `filter[voucherSetId]`, `filter[channel]` and `filter[redemptionLinkId]`. The default range is the last 12 months, or the last 30 days for daily rows. Ranges are limited (redemption and link statistics: 36 months or 92 days; entity statistics: 12 months or 31 days); a longer range fails with `400 data-failed-validation`: the item has `property` `filter[period][gte]`, the constraint [`invalid-filter`](https://docs-consumer.voucher.allride.io/errors/catalog#invalid-filter) and `params.maxMonths` (36, or 12 for entity statistics) or `params.maxDays` (92, or 31 for entity statistics).
* `faceValue` sums the face value of the redeemed vouchers in euros; sets without a face value contribute nothing.
* The conversion rate of the link funnel is redemptions ÷ visits × 100, `null` when there were no visits.

Statistics are eventually consistent: a redemption appears within about 2 minutes. The authoritative record of every single redemption is [List redemptions](https://docs-consumer.voucher.allride.io/api-reference/consumer-redemptions-list.md).

## Time zones

Periods are calendar months and days in **your partner time zone** (`timezone` of your partner, for example `Europe/Berlin`). Each row carries `periodStart` and `periodEnd`, the period's half-open bounds in UTC, and the overview echoes the `timezone` it used. Internally AllRide counts in hourly UTC buckets and rolls them up into your time zone when you query, so changing your time zone changes how existing data is grouped.

> [!WARNING]
>
> Monthly statistics are not your invoice quantities. Billing months always follow Berlin time (`Europe/Berlin`), whatever your partner time zone; billing excludes imported legacy redemptions, and a void after invoicing does not change the issued invoice. A redemption at `2026-10-31T23:30:00Z` counts in October for a partner in `Europe/London`, but in the November billing month. For billing quantities use the [usage estimate](https://docs-consumer.voucher.allride.io/consumer/billing.md#usage-and-pricing).

For raw rows rather than statistics, page through [List redemptions](https://docs-consumer.voucher.allride.io/api-reference/consumer-redemptions-list.md) as described in [Downloading large lists](https://docs-consumer.voucher.allride.io/guides/pagination.md#downloading-large-lists).

## Related

* [Pagination, filtering and sorting](https://docs-consumer.voucher.allride.io/guides/pagination.md)
* [Billing](https://docs-consumer.voucher.allride.io/consumer/billing.md)
* [Redemption links](https://docs-consumer.voucher.allride.io/consumer/redemption-links.md)
* [Pagination, filtering and sorting](https://docs-consumer.voucher.allride.io/guides/pagination.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.