> ## 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. # List Price Terms of visible voucher sets > Lists your resolved Price Terms for every voucher set visible to you now: the current and up to 5 upcoming periods with their acceptance status. A visible set is redeemable only after you accept the terms in force. See [Prices and price acceptance](/consumer/prices). **Required permissions:** `view-consumer-pricing` · **API keys:** allowed ## OpenAPI ````yaml /openapi/consumer.v1.json get /consumer/v1/pricing/voucher-sets openapi: 3.1.1 info: title: AllRide Voucher Consumer API version: 1.0.0 description: >- The Consumer API (`/consumer/v1`) and the shared Workspace API (`/partner/v1`) of the AllRide Voucher Platform for Partner Consumers: browse your catalog, redeem vouchers, manage redemption entities and Redemption Links, configure email OTP, read analytics and billing, and administer your workspace. Start with the [quickstart](https://docs-consumer.voucher.allride.io/quickstart). This document lists the sandbox server; production uses `https://api.voucher.allride.io`. contact: name: AllRide url: https://allride.io servers: - url: https://api.voucher-staging.allride.io description: Sandbox security: - apiKey: [] tags: - name: Catalog description: >- Browse the providers, voucher sets and categories AllRide makes available to you. - name: Catalog settings description: >- Turn providers and voucher sets on or off for your channels and keep your own settings and references. - name: Redemptions description: >- Redeem vouchers (single or batch), read issued codes and links, and void redemptions. - name: Redemption entities description: Your end customers or accounts, identified by your own opaque `refId`. - name: Redemption links description: >- Shareable links that let an end customer redeem on an AllRide-hosted landing page. - name: Email (SMTP and templates) description: >- Email OTP Gate settings, your SMTP configuration and the OTP email templates. - name: Analytics description: Redemption, entity and link statistics in your partner time zone. - name: Billing description: >- Billing account, contacts, payment methods, invoices (including Stornorechnungen), payments, usage and balance. - name: Pricing description: Your resolved Price Terms per voucher set and your Price Acceptances. - name: Partner description: >- Your partner record, settings, principal introspection, API access and the developer reference. - name: Members description: Users of your partner and their invitations. - name: Groups description: Groups, their permissions and the permission catalog. - name: API keys description: API keys of your partner (dashboard only). - name: Webhook endpoints description: Webhook endpoints, their secrets and the event types you can subscribe to. - name: Webhook deliveries description: The webhook delivery log and replays. - name: IP allowlist description: Source address ranges allowed to call the API. - name: Custom domains description: Your own host names for Redemption Link landing pages. - name: Workspace branding description: Workspace Branding (dashboards and landing pages) and brand assets. - name: Single sign-on description: SAML and OIDC connections for your users. - name: Audit log description: Every change made in your partner, by whom and when. paths: /consumer/v1/pricing/voucher-sets: get: tags: - Pricing summary: List Price Terms of visible voucher sets description: >- Lists your resolved Price Terms for every voucher set visible to you now: the current and up to 5 upcoming periods with their acceptance status. A visible set is redeemable only after you accept the terms in force. See [Prices and price acceptance](/consumer/prices). **Required permissions:** `view-consumer-pricing` · **API keys:** allowed operationId: consumer.pricing-voucher-sets.list parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - name: sort in: query required: false description: >- One sort field; prefix `-` for descending (`sort=field` or `sort=-field`). Allowed: `voucherSetName`, `nextChangeAt`. Default `voucherSetName`. The server appends `id` as a tie-breaker. schema: type: string example: voucherSetName x-sort-fields: - voucherSetName - nextChangeAt - name: search in: query required: false description: >- Case-insensitive search (at most 255 characters) over `voucherSetName`, `providerName`. schema: type: string maxLength: 255 x-search-fields: - voucherSetName - providerName - name: filter[providerPartnerId] in: query required: false description: Provider id (equals). schema: type: integer minimum: 0 x-filter-operators: - eq - in - name: filter[providerPartnerId][in] in: query required: false description: Provider id (one of (comma-separated)). schema: type: string description: Comma-separated values. x-filter-operators: - eq - in - name: filter[voucherSetId] in: query required: false description: Voucher set id (equals). schema: type: integer minimum: 0 x-filter-operators: - eq - in - name: filter[voucherSetId][in] in: query required: false description: Voucher set id (one of (comma-separated)). schema: type: string description: Comma-separated values. x-filter-operators: - eq - in - name: filter[status] in: query required: false description: Price acceptance status (equals). schema: type: string enum: - accepted - change-pending - acceptance-required - not-priced - exempt x-filter-operators: - eq - in - name: filter[status][in] in: query required: false description: Price acceptance status (one of (comma-separated)). schema: type: string description: Comma-separated values. x-filter-operators: - eq - in - name: filter[hasUpcomingChange] in: query required: false description: Has an upcoming period (equals). schema: type: boolean x-filter-operators: - eq responses: '200': description: OK headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Idempotency-Key-Ignored: $ref: '#/components/headers/IdempotencyKeyIgnored' content: application/json: schema: $ref: '#/components/schemas/VoucherSetPriceTermsPage' examples: default: summary: OK value: data: data: - id: 2030 resource: voucher-set-price-terms voucherSetId: 2030 providerPartnerId: 1030 provider: id: 1030 resource: partner name: Acme Scooters _links: self: href: >- https://api.voucher.allride.io/consumer/v1/catalog/providers/1030 type: application/json voucherSetName: de: Acme Starter Pass en: Acme Starter Pass status: change-pending nextChangeAt: '2026-11-30T23:00:00Z' current: startsAt: '2025-12-31T23:00:00Z' endsAt: '2026-11-30T23:00:00Z' terms: pricingModel: per-unit unitPrice: value: 800 scale: 4 label: €0.08 tiers: null termsDigest: >- 4f0c2a9e7b13d5c8e1f6a0b2c4d6e8f0a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9d1 acceptBy: '2025-12-31T23:00:00Z' acceptance: status: accepted priceAcceptanceId: 61017 acceptedAt: '2026-01-03T09:12:00Z' acceptedBy: type: partner-user id: 4069 label: finance@example.com upcoming: - startsAt: '2026-11-30T23:00:00Z' endsAt: null terms: pricingModel: per-unit unitPrice: value: 1000 scale: 4 label: €0.10 tiers: null termsDigest: >- 9a17e3c5b7d9f1a3c5e7a9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1 acceptBy: '2026-11-30T23:00:00Z' acceptance: status: pending _links: self: href: >- https://api.voucher.allride.io/consumer/v1/pricing/voucher-sets/2030 type: application/json voucherSet: href: >- https://api.voucher.allride.io/consumer/v1/catalog/voucher-sets/2030 type: application/json page: 1 perPage: 25 totalPages: 1 total: 1 '400': description: Bad Request x-error-codes: - data-failed-validation 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: One or more properties or parameters are invalid. statusCode: 400 errorCode: data-failed-validation more: validationErrors: - property: sort constraint: invalid-sort message: en: Sort by one of the allowed fields. params: allowed: - voucherSetName - nextChangeAt '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: parameters: Page: name: page in: query required: false description: >- Page number, 1-100,000 (default 1). Outside the range: `400 data-failed-validation` with the constraint `invalid-page`. schema: type: integer minimum: 1 maximum: 100000 default: 1 PerPage: name: perPage in: query required: false description: >- Items per page, 1-100 (default 25). Outside the range: `400 data-failed-validation` with the constraint `invalid-page`. schema: type: integer minimum: 1 maximum: 100 default: 25 headers: XRequestId: description: Request id (yours if you sent a valid `X-Request-Id`, else generated). schema: type: string IdempotencyKeyIgnored: description: '`true` when you sent `Idempotency-Key` on a method that ignores it.' schema: type: string enum: - 'true' RetryAfter: description: Seconds to wait before retrying or polling. schema: type: integer schemas: VoucherSetPriceTermsPage: type: object description: Page envelope of `VoucherSetPriceTerms` items. properties: data: type: object description: The page. properties: data: type: array items: $ref: '#/components/schemas/VoucherSetPriceTerms' description: The items of this page. page: type: integer minimum: 1 description: Effective page number (1-based). perPage: type: integer minimum: 1 maximum: 100 description: Effective page size. totalPages: type: integer minimum: 0 description: ceil(total / perPage); 0 when total is 0. total: type: integer minimum: 0 description: Exact number of matching items. required: - data - page - perPage - totalPages - total additionalProperties: false required: - data additionalProperties: false ErrorResponse: type: object description: >- Error body of every 4xx and 5xx response (`Content-Type: application/json`). properties: errors: type: array minItems: 1 items: $ref: '#/components/schemas/ErrorEntry' description: The errors; in v1 always exactly one. required: - errors additionalProperties: false VoucherSetPriceTerms: type: object description: >- Your resolved Price Terms for one visible voucher set: current and up to 5 upcoming periods. `id` is the voucher set id. Never contains price rules. properties: id: $ref: '#/components/schemas/ULong' description: Numeric id of the resource, unique per resource type. resource: type: string enum: - voucher-set-price-terms description: Always `voucher-set-price-terms`. voucherSetId: $ref: '#/components/schemas/ULong' description: The voucher set (equal to `id`). providerPartnerId: $ref: '#/components/schemas/ULong' description: Provider of the voucher set. provider: type: object properties: id: $ref: '#/components/schemas/ULong' description: Provider id. resource: type: string enum: - partner description: Always `partner`. name: type: string description: Provider name. _links: type: object properties: self: $ref: '#/components/schemas/Link' description: The catalog provider. required: - self additionalProperties: false required: - id - resource - name - _links additionalProperties: false description: The provider. voucherSetName: $ref: '#/components/schemas/I18nText' description: Name of the live revision. status: type: string enum: - accepted - change-pending - acceptance-required - not-priced - exempt description: >- Your price acceptance status now: `accepted`, `change-pending` (redeemable; upcoming terms not yet accepted), `acceptance-required` (not redeemable until you accept), `not-priced` (not redeemable), `exempt`. Treat as an open set: new values may be added. nextChangeAt: anyOf: - $ref: '#/components/schemas/Instant' - type: 'null' description: >- Start of the next period, or the end of the current one; `null` when nothing changes. current: anyOf: - $ref: '#/components/schemas/PriceTermsPeriod' - type: 'null' description: The period in force now; `null` when the set is not priced now. upcoming: type: array items: $ref: '#/components/schemas/PriceTermsPeriod' maxItems: 5 description: Up to 5 following periods in order. _links: type: object description: >- Related resources you may follow (HAL style). A link is present only when you hold the target's permissions. properties: self: $ref: '#/components/schemas/Link' description: This resource. voucherSet: $ref: '#/components/schemas/Link' description: The catalog voucher set. required: - self additionalProperties: false required: - id - resource - voucherSetId - providerPartnerId - provider - voucherSetName - status - nextChangeAt - current - upcoming - _links additionalProperties: false ErrorEntry: type: object description: One error. Branch on `errorCode`; ignore members you do not know. properties: message: type: string description: >- Human-readable message. 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. 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 additionalProperties: true ULong: type: integer format: uint64 minimum: 0 maximum: 18446744073709552000 x-bigint: true description: >- Unsigned 64-bit integer (ids and large counters). May exceed 2^53; parse with a BigInt-safe JSON parser in JavaScript. Link: type: object description: A link to a related resource. properties: href: type: string format: uri description: Absolute URL. type: type: string description: Media type of the target, usually `application/json`. required: - href - type additionalProperties: false I18nText: type: object description: >- Localised text: an object keyed by locale (`de`, `en`). Responses always return the full map; pick the locale on your side. Requests must include your partner's default locale. properties: de: type: string description: German text. en: type: string description: English text. additionalProperties: false example: de: 5 € Fahrguthaben en: €5 ride credit Instant: type: string format: date-time description: >- RFC 3339 timestamp in UTC with `Z`, millisecond precision, truncated: no fraction when the milliseconds are zero (`2026-11-01T00:00:00Z`), otherwise exactly three digits (`2026-10-21T17:42:10.120Z`). Inputs must carry an offset and are normalised to UTC. example: '2026-11-01T00:00:00Z' PriceTermsPeriod: type: object properties: startsAt: $ref: '#/components/schemas/Instant' description: Start of the period (UTC). endsAt: anyOf: - $ref: '#/components/schemas/Instant' - type: 'null' description: End of the period (exclusive); `null` when open-ended. terms: $ref: '#/components/schemas/PriceTerms' description: The resolved Price Terms of the period. termsDigest: type: string pattern: ^[0-9a-f]{64}$ description: >- Lower-case hex SHA-256 of the canonical terms; send it back when you accept. acceptBy: $ref: '#/components/schemas/Instant' description: >- Accept before this instant to keep redeeming without a pause (= `startsAt`). acceptance: type: object properties: status: type: string enum: - accepted - pending - not-required description: >- Whether you accepted these terms. Treat as an open set: new values may be added. priceAcceptanceId: $ref: '#/components/schemas/ULong' description: The acceptance (when accepted). acceptedAt: $ref: '#/components/schemas/Instant' description: When accepted. acceptedBy: $ref: '#/components/schemas/Actor' description: Who accepted. required: - status additionalProperties: false description: Your acceptance of this period. required: - startsAt - endsAt - terms - termsDigest - acceptBy - acceptance additionalProperties: false description: A period during which your resolved Price Terms are constant. ValidationError: type: object description: >- One invalid property or parameter of a `data-failed-validation` error (also used for item failures of batch operations and content checks). properties: property: type: string description: >- Path of the offending property in your request body (`items[2].quantity`), 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 constraint, for example `min` and `max` for `invalid-page` or `allowed` for `invalid-sort`. value: description: The rejected value, when it is safe to return. 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 additionalProperties: true PriceTerms: type: object description: >- Resolved Price Terms of a voucher set for you: the pricing model and price. Validity dates are not part of the terms. properties: pricingModel: type: string enum: - per-unit - graduated description: >- `per-unit`: one unit price; `graduated`: tiers by the n-th redemption of the month. Treat as an open set: new values may be added. unitPrice: anyOf: - $ref: '#/components/schemas/UnitPrice' - type: 'null' description: Price per redemption (`per-unit`); `null` for `graduated`. tiers: type: - array - 'null' items: type: object properties: upTo: anyOf: - $ref: '#/components/schemas/ULong' - type: 'null' description: >- Last redemption number (in the month) this tier covers; `null` on the last tier. unitPrice: $ref: '#/components/schemas/UnitPrice' description: Price per redemption in this tier. required: - upTo - unitPrice additionalProperties: false description: Tiers in order (`graduated`, 2-10 tiers); `null` for `per-unit`. required: - pricingModel - unitPrice - tiers additionalProperties: false Actor: type: object description: >- Who performed an action. AllRide staff appear as `{"type": "admin-user", "id": null, "label": "AllRide"}`. properties: type: type: string enum: - partner-user - api-key - admin-user - system - end-customer description: 'Kind of actor. Treat as an open set: new values may be added.' id: anyOf: - $ref: '#/components/schemas/ULong' - type: 'null' description: Id of the user or API key; `null` for AllRide staff and the system. label: type: string description: >- Display label (email of the user, API key name, `AllRide`, `System`). required: - type - id - label additionalProperties: false example: type: api-key id: 12017 label: Production integration UnitPrice: type: object description: >- A per-redemption price in ten-thousandths of a euro (`value` 1250 = €0.1250). Used only for unit prices; totals are `Money`. properties: value: type: integer minimum: 0 maximum: 100000000 description: Price in 1/10,000 euro. scale: type: integer const: 4 description: Always 4. label: type: string readOnly: true description: >- Server-formatted price: 2 fraction digits when the last two digits of `value` are 0, else 4 (`€0.10`, `€0.1250`). required: - value - scale - label additionalProperties: false example: value: 1250 scale: 4 label: 0,1250 € responses: Unauthorized: description: 'Unauthorized: the credential is missing or invalid.' x-error-codes: - unauthenticated - token-invalid - token-expired - api-key-invalid headers: X-Request-Id: $ref: '#/components/headers/XRequestId' 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 (wrong scheme, signature or credential kind). statusCode: 401 errorCode: token-invalid token-expired: summary: Credential expired value: errors: - message: The dashboard ID token has expired. statusCode: 401 errorCode: token-expired api-key-invalid: summary: Invalid API key value: errors: - message: >- The API key is unknown, revoked, expired, past its roll grace period or belongs to the other environment (`vk_test_` against production or `vk_live_` against the sandbox). statusCode: 401 errorCode: api-key-invalid Forbidden: description: 'Forbidden: an access gate refused the request.' x-error-codes: - partner-role-missing - partner-suspended - partner-offboarded - api-access-inactive - ip-not-allowed - mfa-required - sso-required - missing-permission - reauthentication-required headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: partner-role-missing: summary: Partner role missing value: errors: - message: >- Your partner lacks the role (provider or consumer) this surface needs. statusCode: 403 errorCode: partner-role-missing more: requiredRole: consumer partner-suspended: summary: Partner suspended value: errors: - message: >- Your partner is suspended: writes are refused (billing writes from the dashboard excepted). statusCode: 403 errorCode: partner-suspended partner-offboarded: summary: Partner offboarded value: errors: - message: Your partner has been offboarded; every route is refused. statusCode: 403 errorCode: partner-offboarded api-access-inactive: summary: API access inactive value: errors: - message: >- API access of your partner is not active (not yet granted, revoked, or the partner is suspended), so API keys are refused. statusCode: 403 errorCode: api-access-inactive ip-not-allowed: summary: IP address not allowed value: errors: - message: >- The request's source address is not in your IP allowlist while enforcement is on. statusCode: 403 errorCode: ip-not-allowed mfa-required: summary: Multi-factor authentication required value: errors: - message: >- Your partner requires multi-factor authentication for dashboard users. statusCode: 403 errorCode: mfa-required sso-required: summary: Single sign-on required value: errors: - message: >- Your partner enforces single sign-on for this user's email domain. statusCode: 403 errorCode: sso-required missing-permission: summary: Missing permission value: errors: - message: >- The membership or API key lacks a permission the operation requires, including non-delegable permissions called with an API key. statusCode: 403 errorCode: missing-permission more: requiredPermissions: - create-consumer-redemptions reauthentication-required: summary: Recent sign-in required value: errors: - message: >- The operation needs a sign-in within the last 15 minutes (dashboard users only). statusCode: 403 errorCode: reauthentication-required NotFound: description: Not found. x-error-codes: - route-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 InternalError: description: Unexpected failure; quote the `requestId`. 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: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad ServiceUnavailable: description: Temporarily unavailable; retry after `Retry-After`. 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: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad db-unavailable: summary: Database unavailable value: errors: - message: Something went wrong on our side statusCode: 503 errorCode: db-unavailable requestId: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad query-timeout: summary: Query timeout value: errors: - message: Something went wrong on our side statusCode: 503 errorCode: query-timeout requestId: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad securitySchemes: apiKey: type: http scheme: bearer bearerFormat: vk_live__ description: >- Your API key in `Authorization: Bearer `. Use `vk_test_…` keys against the sandbox and `vk_live_…` keys against production. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.