> ## Documentation Index > Fetch the complete documentation index at: https://docs-provider.voucher.allride.io/llms.txt > Use this file to discover all available pages before exploring further. # Get redemptions over time > Returns redemptions, voids and face value per day, ISO week or month, optionally per voucher set. Series are dense; voids count in the bucket of `voidedAt`. **Required permissions:** `view-provider-analytics` · **API keys:** allowed ## OpenAPI ````yaml /openapi/provider.v1.json get /provider/v1/analytics/redemptions openapi: 3.1.1 info: title: AllRide Voucher Provider API version: 1.0.0 description: >- The Provider API (`/provider/v1`) and the shared workspace API (`/partner/v1`) of the AllRide Voucher Platform for Partner Providers. Start with the [quickstart](/quickstart). This reference lists only the sandbox server; production is `https://api.voucher.allride.io`. contact: name: AllRide API support url: https://docs-provider.voucher.allride.io servers: - url: https://api.voucher-staging.allride.io description: Sandbox security: - apiKey: [] tags: - name: Provider profile description: Your consumer-visible general information and general terms. - name: Listing branding description: How you look in consumer catalogs, and the images it uses. - name: Categories description: AllRide-managed categories for voucher sets. - name: Voucher sets description: Voucher sets, their lifecycle, revisions and link templates. - name: Change requests description: Proposed content changes that AllRide approves. - name: Vouchers description: 'Codes and links: batch create, reveal, revoke.' - name: Voucher uploads description: Asynchronous CSV and XLSX imports. - name: Stock alerts description: Threshold alerts on voucher set stock. - name: Redemptions description: Redemptions of your vouchers (provider projection). - name: Analytics description: Statistics without consumer dimension. - name: Partner description: Your partner record, settings, API access and reference values. - name: Members description: People in your partner. - name: Groups description: Groups of members and the permission catalog. - name: API keys description: Credentials for your backend. - name: Webhook endpoints description: Where AllRide sends events. - name: Webhook deliveries description: Delivery log, replays. - name: IP allowlist description: Addresses allowed to call the API. - name: Workspace branding description: Your dashboard theme and its images. - name: Single sign-on description: SAML and OIDC connections. - name: Audit log description: Who changed what. - name: Webhooks description: Events AllRide sends to your endpoints. paths: /provider/v1/analytics/redemptions: get: tags: - Analytics summary: Get redemptions over time description: >- Returns redemptions, voids and face value per day, ISO week or month, optionally per voucher set. Series are dense; voids count in the bucket of `voidedAt`. **Required permissions:** `view-provider-analytics` · **API keys:** allowed operationId: provider.analytics.redemptions parameters: - name: from in: query required: true description: First day (inclusive), in timezone. schema: type: string format: date - name: to in: query required: true description: Last day (exclusive). schema: type: string format: date - name: granularity in: query required: false description: Bucket size; at most 366 days, 260 weeks or 120 months. schema: type: string enum: - day - week - month - name: voucherSetId in: query required: false description: Comma list of up to 50 of your voucher set ids. schema: type: string - name: timezone in: query required: false description: >- IANA zone with whole-hour offsets; defaults to your partner's timezone. schema: type: string - name: groupBy in: query required: false description: Grouping; default none. schema: type: string enum: - none - voucher-set - name: cumulative in: query required: false description: Running totals from from; default false. schema: type: boolean responses: '200': description: Success. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ProviderUsageStatsResponse' examples: example: summary: Example value: data: resource: provider-redemption-stats from: '2026-09-28' to: '2026-10-12' granularity: week timezone: Europe/Berlin groupBy: voucher-set cumulative: false totals: redeemedCount: 812 voidedCount: 3 netCount: 809 faceValue: value: 404500 label: 4.045,00 € series: - voucherSetId: 2030 buckets: - period: 2026-W40 start: '2026-09-28' redeemedCount: 812 voidedCount: 3 netCount: 809 faceValue: value: 404500 label: 4.045,00 € - period: 2026-W41 start: '2026-10-05' redeemedCount: 0 voidedCount: 0 netCount: 0 faceValue: value: 0 label: 0,00 € _links: self: href: >- https://api.voucher-staging.allride.io/provider/v1/analytics/redemptions?from=2026-09-28&to=2026-10-12&granularity=week&groupBy=voucher-set type: application/json '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' components: headers: XRequestId: description: >- Request id: your X-Request-Id (1-100 characters of [A-Za-z0-9._:-]) or a generated UUID. schema: type: string RetryAfter: description: Seconds to wait before the next request or poll. schema: type: integer example: 2 schemas: ProviderUsageStatsResponse: type: object properties: data: $ref: '#/components/schemas/ProviderUsageStats' required: - data description: Single-object envelope around ProviderUsageStats. additionalProperties: false ProviderUsageStats: type: object properties: resource: type: string enum: - provider-redemption-stats description: Always provider-redemption-stats. from: type: string description: Effective start. format: date to: type: string description: Effective end (exclusive). format: date granularity: type: string enum: - day - week - month description: 'Bucket size. Treat as an open set: new values may be added.' timezone: type: string description: Time zone. groupBy: type: string enum: - none - voucher-set description: 'Grouping. Treat as an open set: new values may be added.' cumulative: type: boolean description: Running totals. totals: type: object properties: redeemedCount: type: integer description: Redemptions. voidedCount: type: integer description: Voids. netCount: type: integer description: Net. faceValue: $ref: '#/components/schemas/Money' description: Sum of face values in euros. required: - redeemedCount - voidedCount - netCount - faceValue description: Totals. additionalProperties: false series: type: array items: type: object properties: voucherSetId: oneOf: - $ref: '#/components/schemas/ULong' - type: 'null' description: Voucher set, or null without grouping. buckets: type: array items: $ref: '#/components/schemas/StatsBucket' description: Dense buckets. required: - voucherSetId - buckets description: One series. additionalProperties: false description: Series. _links: type: object description: Links to related resources (self). additionalProperties: $ref: '#/components/schemas/Link' required: - resource - from - to - granularity - timezone - groupBy - cumulative - totals - series - _links description: Redemptions over time. additionalProperties: false ErrorResponse: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorEntry' description: The errors; in v1 always exactly one. minItems: 1 required: - errors description: >- Error body of every 4xx and 5xx response (Content-Type: application/json). additionalProperties: false Money: type: object properties: value: type: integer description: Amount in euro cent. minimum: 0 label: type: string description: >- Formatted amount in the response locale (de 29,00 €, en €29.00). Ignored in requests. readOnly: true required: - value description: An amount in euros (EUR), in cent. additionalProperties: false ULong: type: integer format: uint64 minimum: 0 maximum: 18446744073709552000 x-bigint: true description: >- Unsigned 64-bit integer. May exceed 2^53; parse with a BigInt-safe JSON parser in JavaScript. StatsBucket: type: object properties: period: type: string description: 'Bucket label: YYYY-MM-DD, YYYY-Www or YYYY-MM.' start: type: string description: First day of the bucket. format: date redeemedCount: type: integer description: Redemptions. voidedCount: type: integer description: Voids (by voidedAt). netCount: type: integer description: Redemptions minus voids. faceValue: $ref: '#/components/schemas/Money' description: Sum of face values in euros. required: - period - start - redeemedCount - voidedCount - netCount - faceValue description: One time bucket. additionalProperties: false Link: type: object properties: href: type: string description: Absolute URL. format: uri type: type: string description: Media type of the target. required: - href - type description: A link to a related resource. additionalProperties: false ErrorEntry: type: object properties: message: type: string description: >- Human-readable message. Do not parse it; it can change. For 5xx errors it is always the generic `Something went wrong on our side`. statusCode: type: integer description: The HTTP status. errorCode: type: string description: >- Stable kebab-case error code, listed in the error catalog. Branch on this field. requestId: type: string description: >- 5xx only: the request id (also in the `X-Request-Id` header). Quote it when you contact support. more: type: object additionalProperties: true description: >- Additional details for some codes, for example `validationErrors` (array of `ValidationError`) or `requiredPermissions`. The members per code are listed in the error catalog. properties: validationErrors: type: array items: $ref: '#/components/schemas/ValidationError' description: Invalid properties or parameters. required: - message - statusCode - errorCode description: One error. Branch on `errorCode`; ignore members you do not know. ValidationError: type: object properties: property: type: string description: >- Path of the offending property in your request body (`vouchers[17].value`), or the name of the query parameter, path parameter or header. constraint: type: string description: >- The violated rule as a kebab-case item code, for example `required`, `too-long`, `invalid-id`, `unknown-field`. See the validation item codes in the error catalog. params: type: object additionalProperties: true description: >- Parameters of the violated constraint, for example `{"max": 120}` for `too-long`; absent when the constraint has none. value: type: - number - boolean description: >- The rejected value, only when it is a number or boolean. Strings are never echoed, so secrets, voucher values and personal data never come back in an error. message: type: object description: Explanation per locale. properties: en: type: string description: English message. de: type: string description: German message. required: - en additionalProperties: false required: - property - constraint - message description: >- One invalid property or parameter of a `data-failed-validation` error (also used for item failures of batch operations and content checks). responses: BadRequest: description: >- Bad request: `data-failed-validation`, `malformed-json`, `invalid-header`. x-error-codes: - data-failed-validation - malformed-json - invalid-header headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: data-failed-validation: summary: Data failed validation value: errors: - message: Data failed validation statusCode: 400 errorCode: data-failed-validation more: validationErrors: - property: internalName constraint: too-long params: max: 120 message: en: Must be at most 120 characters. de: Darf höchstens 120 Zeichen lang sein. - property: content.linkTemplate constraint: invalid-link-template message: en: >- Placeholders are allowed only in the path, query or fragment. de: >- Platzhalter sind nur im Pfad, in der Query oder im Fragment erlaubt. malformed-json: summary: Malformed JSON value: errors: - message: The body is not valid UTF-8 JSON. statusCode: 400 errorCode: malformed-json invalid-header: summary: Invalid header value: errors: - message: >- A standard or platform header is malformed; more.validationErrors[].property names the header. statusCode: 400 errorCode: invalid-header Unauthorized: description: >- Unauthorized: `unauthenticated`, `token-invalid`, `api-key-invalid`, `token-expired`, `session-revoked`. x-error-codes: - unauthenticated - token-invalid - api-key-invalid - token-expired - session-revoked headers: X-Request-Id: $ref: '#/components/headers/XRequestId' WWW-Authenticate: description: >- Bearer realm="voucher" (plus error="invalid_token" when a credential was sent). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthenticated: summary: Authentication required value: errors: - message: No credential was sent with the request. statusCode: 401 errorCode: unauthenticated token-invalid: summary: Invalid credential value: errors: - message: >- The credential cannot be verified for this surface, has an unknown scheme, or two Authorization headers were sent. statusCode: 401 errorCode: token-invalid api-key-invalid: summary: Invalid API key value: errors: - message: >- The API key is unknown, revoked, expired, or belongs to the other environment (a vk_test_ key against production or a vk_live_ key against the sandbox). statusCode: 401 errorCode: api-key-invalid token-expired: summary: Credential expired value: errors: - message: The dashboard user's ID token has expired. statusCode: 401 errorCode: token-expired session-revoked: summary: Session revoked value: errors: - message: The dashboard user's session was revoked. statusCode: 401 errorCode: session-revoked Forbidden: description: >- Forbidden: `missing-permission`, `partner-role-missing`, `partner-suspended`, `partner-offboarded`, `api-access-inactive`, `ip-not-allowed`, `mfa-required`, `sso-required`. x-error-codes: - missing-permission - partner-role-missing - partner-suspended - partner-offboarded - api-access-inactive - ip-not-allowed - mfa-required - sso-required headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing-permission: summary: Missing permission value: errors: - message: >- The membership or API key lacks a permission the operation requires; more.requiredPermissions lists them. API keys always get this code on dashboard-only operations. statusCode: 403 errorCode: missing-permission more: requiredPermissions: - manage-provider-voucher-sets partner-role-missing: summary: Partner role missing value: errors: - message: >- The partner lacks the role this surface needs (more.requiredRole names it), for example a consumer-only partner on /provider/v1. statusCode: 403 errorCode: partner-role-missing more: requiredRole: provider partner-suspended: summary: Partner suspended value: errors: - message: The partner is suspended; only reads are allowed. statusCode: 403 errorCode: partner-suspended partner-offboarded: summary: Partner offboarded value: errors: - message: The partner has been offboarded. statusCode: 403 errorCode: partner-offboarded api-access-inactive: summary: API access inactive value: errors: - message: >- API access of the partner is not active, or the partner is not active. API keys work only while both are active; the same code answers key and webhook operations that need active API access. statusCode: 403 errorCode: api-access-inactive ip-not-allowed: summary: IP address not allowed value: errors: - message: >- The request came from an address outside the partner's IP allowlist while enforcement is on. statusCode: 403 errorCode: ip-not-allowed mfa-required: summary: Multi-factor authentication required value: errors: - message: >- The partner requires multi-factor authentication and the session has not satisfied it. statusCode: 403 errorCode: mfa-required sso-required: summary: Single sign-on required value: errors: - message: >- The partner enforces single sign-on for the user's email domain. statusCode: 403 errorCode: sso-required NotFound: description: 'Not found: `route-not-found`, `partner-not-found`.' x-error-codes: - route-not-found - partner-not-found headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: route-not-found: summary: Route not found value: errors: - message: No operation exists for this path. statusCode: 404 errorCode: route-not-found partner-not-found: summary: Partner not found value: errors: - message: >- The token names a partner that does not exist or in which the user has no active membership. statusCode: 404 errorCode: partner-not-found InternalError: description: 'Internal error: `internal-error`.' x-error-codes: - internal-error headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal-error: summary: Internal error value: errors: - message: Something went wrong on our side statusCode: 500 errorCode: internal-error requestId: 0b6f3c1e-9d5a-4c43-a2a8-1f3d2b7c9e10 ServiceUnavailable: description: >- Service unavailable: `service-unavailable`, `db-unavailable`, `query-timeout`. x-error-codes: - service-unavailable - db-unavailable - query-timeout headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: service-unavailable: summary: Service unavailable value: errors: - message: Something went wrong on our side statusCode: 503 errorCode: service-unavailable requestId: 0b6f3c1e-9d5a-4c43-a2a8-1f3d2b7c9e10 db-unavailable: summary: Database unavailable value: errors: - message: Something went wrong on our side statusCode: 503 errorCode: db-unavailable requestId: 0b6f3c1e-9d5a-4c43-a2a8-1f3d2b7c9e10 query-timeout: summary: Query timeout value: errors: - message: Something went wrong on our side statusCode: 503 errorCode: query-timeout requestId: 0b6f3c1e-9d5a-4c43-a2a8-1f3d2b7c9e10 securitySchemes: apiKey: type: http scheme: bearer bearerFormat: vk_live__ description: >- Partner API key: `Authorization: Bearer vk_live_…`. Use `vk_test_…` keys against the sandbox. See [Authentication](/guides/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.