> ## 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 catalog voucher sets

> Lists the voucher sets visible to you: an approved live revision, effective status scheduled, active or deactivation-scheduled, an active provider, and access granted by AllRide. Entries are returned whatever your toggles say; apps and landing pages use `filter[providerToggle]=true&filter[voucherSetToggle]=true` and show only entries whose `priceAcceptance.status` is `accepted`, `change-pending` or `exempt`. Stock is shown only as `stockStatus`. Cache for at most 60 seconds and refresh on `catalog-*` webhooks. See [Catalog and toggles](/consumer/catalog).

**Required permissions:** `view-consumer-catalog` · **API keys:** allowed



## OpenAPI

````yaml /openapi/consumer.v1.json get /consumer/v1/catalog/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/catalog/voucher-sets:
    get:
      tags:
        - Catalog
      summary: List catalog voucher sets
      description: >-
        Lists the voucher sets visible to you: an approved live revision,
        effective status scheduled, active or deactivation-scheduled, an active
        provider, and access granted by AllRide. Entries are returned whatever
        your toggles say; apps and landing pages use
        `filter[providerToggle]=true&filter[voucherSetToggle]=true` and show
        only entries whose `priceAcceptance.status` is `accepted`,
        `change-pending` or `exempt`. Stock is shown only as `stockStatus`.
        Cache for at most 60 seconds and refresh on `catalog-*` webhooks. See
        [Catalog and toggles](/consumer/catalog).


        **Required permissions:** `view-consumer-catalog` · **API keys:**
        allowed
      operationId: consumer.catalog-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: `position`, `activeFrom`, `deactivateAt`,
            `revisionApprovedAt`. Default `position`. The server appends `id` as
            a tie-breaker.
          schema:
            type: string
            example: position
          x-sort-fields:
            - position
            - activeFrom
            - deactivateAt
            - revisionApprovedAt
        - name: search
          in: query
          required: false
          description: >-
            Case-insensitive search (at most 255 characters) over `live.name`,
            `live.summary`, `live.valueLabel`.
          schema:
            type: string
            maxLength: 255
          x-search-fields:
            - live.name
            - live.summary
            - live.valueLabel
        - 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[availability]
          in: query
          required: false
          description: Availability (equals).
          schema:
            type: string
            enum:
              - upcoming
              - active
              - deactivation-scheduled
          x-filter-operators:
            - eq
            - in
        - name: filter[availability][in]
          in: query
          required: false
          description: Availability (one of (comma-separated)).
          schema:
            type: string
            description: Comma-separated values.
          x-filter-operators:
            - eq
            - in
        - name: filter[voucherKind]
          in: query
          required: false
          description: Voucher kind (equals).
          schema:
            type: string
            enum:
              - code
              - link
          x-filter-operators:
            - eq
        - name: filter[effectiveCategoryId]
          in: query
          required: false
          description: Effective category id (equals).
          schema:
            type: integer
            minimum: 0
          x-filter-operators:
            - eq
            - in
        - name: filter[effectiveCategoryId][in]
          in: query
          required: false
          description: Effective category id (one of (comma-separated)).
          schema:
            type: string
            description: Comma-separated values.
          x-filter-operators:
            - eq
            - in
        - name: filter[stockStatus]
          in: query
          required: false
          description: Stock status (equals).
          schema:
            type: string
            enum:
              - available
              - low
              - depleted
          x-filter-operators:
            - eq
            - in
        - name: filter[stockStatus][in]
          in: query
          required: false
          description: Stock status (one of (comma-separated)).
          schema:
            type: string
            description: Comma-separated values.
          x-filter-operators:
            - eq
            - in
        - name: filter[providerToggle]
          in: query
          required: false
          description: Your Provider Toggle (equals).
          schema:
            type: boolean
          x-filter-operators:
            - eq
        - name: filter[voucherSetToggle]
          in: query
          required: false
          description: Your Voucher Set Toggle (equals).
          schema:
            type: boolean
          x-filter-operators:
            - eq
        - name: filter[featured]
          in: query
          required: false
          description: Featured (equals).
          schema:
            type: boolean
          x-filter-operators:
            - eq
        - name: filter[setting.externalRef]
          in: query
          required: false
          description: Your external reference (equals).
          schema:
            type: string
          x-filter-operators:
            - eq
            - in
        - name: filter[setting.externalRef][in]
          in: query
          required: false
          description: Your external reference (one of (comma-separated)).
          schema:
            type: string
            description: Comma-separated values.
          x-filter-operators:
            - eq
            - in
        - name: filter[activeFrom][gte]
          in: query
          required: false
          description: Activation time (greater than or equal).
          schema:
            type: string
            format: date-time
          x-filter-operators:
            - gte
            - lt
            - isNull
        - name: filter[activeFrom][lt]
          in: query
          required: false
          description: Activation time (less than).
          schema:
            type: string
            format: date-time
          x-filter-operators:
            - gte
            - lt
            - isNull
        - name: filter[activeFrom][isNull]
          in: query
          required: false
          description: Activation time (is null (`true`/`false`)).
          schema:
            type: boolean
          x-filter-operators:
            - gte
            - lt
            - isNull
        - name: filter[deactivateAt][gte]
          in: query
          required: false
          description: Deactivation time (greater than or equal).
          schema:
            type: string
            format: date-time
          x-filter-operators:
            - gte
            - lt
            - isNull
        - name: filter[deactivateAt][lt]
          in: query
          required: false
          description: Deactivation time (less than).
          schema:
            type: string
            format: date-time
          x-filter-operators:
            - gte
            - lt
            - isNull
        - name: filter[deactivateAt][isNull]
          in: query
          required: false
          description: Deactivation time (is null (`true`/`false`)).
          schema:
            type: boolean
          x-filter-operators:
            - gte
            - lt
            - isNull
      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/ConsumerCatalogEntryPage'
              examples:
                default:
                  summary: OK
                  value:
                    data:
                      data:
                        - id: 2030
                          resource: consumer-catalog-entry
                          providerPartnerId: 1030
                          provider:
                            id: 1030
                            resource: consumer-catalog-provider
                            slug: acme-scooters
                            displayName:
                              de: Acme Scooters
                              en: Acme Scooters
                            logoUrl: >-
                              https://assets.voucher.allride.io/acme-scooters/3095.png
                            _links:
                              self:
                                href: >-
                                  https://api.voucher.allride.io/consumer/v1/catalog/providers/1030
                                type: application/json
                          voucherKind: code
                          availability: active
                          activeFrom: '2026-10-01T00:00:00Z'
                          deactivateAt: null
                          revisionNo: 2
                          revisionApprovedAt: '2026-09-28T09:40:11Z'
                          live:
                            name:
                              de: 5 € Fahrguthaben
                              en: €5 ride credit
                            summary:
                              de: Für alle E-Scooter
                              en: For all e-scooters
                            bullets:
                              - de: Einmal einlösbar
                                en: Single use
                            description: null
                            howToRedeem:
                              - de: App öffnen und Code unter Wallet eingeben
                                en: Open the app and enter the code under Wallet
                            termsText:
                              de: Einmal pro Konto einlösbar.
                              en: Redeemable once per account.
                            valueLabel:
                              de: 5 € Rabatt
                              en: €5 off
                            faceValue:
                              value: 500
                              label: €5.00
                            categoryId: 7017
                            linkTemplate: https://acme-scooters.example.com/r?c={{code}}
                            allowedLinkHosts:
                              - acme-scooters.example.com
                            allowedLinkSchemes: []
                            brandingOverride: null
                            countries:
                              - DE
                            extensions: null
                            metadata: null
                          brandingOverrideAssetUrls: null
                          stockStatus: available
                          providerToggle: true
                          voucherSetToggle: true
                          position: 1
                          featured: true
                          effectiveCategoryId: 7017
                          priceAcceptance:
                            status: accepted
                            nextChangeAt: null
                          setting:
                            enabled: true
                            position: null
                            featured: false
                            categoryOverrideId: null
                            entityLimit:
                              max: 1
                              period: calendar-month
                            settings: null
                            externalRef: '3'
                            updatedAt: '2026-10-20T10:02:00Z'
                          _links:
                            self:
                              href: >-
                                https://api.voucher.allride.io/consumer/v1/catalog/voucher-sets/2030
                              type: application/json
                            provider:
                              href: >-
                                https://api.voucher.allride.io/consumer/v1/catalog/providers/1030
                              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:
                                  - position
                                  - activeFrom
                                  - deactivateAt
                                  - revisionApprovedAt
        '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:
    ConsumerCatalogEntryPage:
      type: object
      description: Page envelope of `ConsumerCatalogEntry` items.
      properties:
        data:
          type: object
          description: The page.
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/ConsumerCatalogEntry'
              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
    ConsumerCatalogEntry:
      type: object
      description: >-
        A voucher set visible to you (approved live revision, scheduled or
        active, AllRide grants you access), with your setting.
      properties:
        id:
          $ref: '#/components/schemas/ULong'
          description: Numeric id of the resource, unique per resource type.
        resource:
          type: string
          enum:
            - consumer-catalog-entry
          description: Always `consumer-catalog-entry`.
        providerPartnerId:
          $ref: '#/components/schemas/ULong'
          description: The provider.
        provider:
          $ref: '#/components/schemas/CatalogProviderSummary'
          description: Provider summary.
        voucherKind:
          type: string
          enum:
            - code
            - link
          description: >-
            What a redemption issues. Treat as an open set: new values may be
            added.
        availability:
          type: string
          enum:
            - upcoming
            - active
            - deactivation-scheduled
          description: >-
            Effective availability. Treat as an open set: new values may be
            added.
        activeFrom:
          anyOf:
            - $ref: '#/components/schemas/Instant'
            - type: 'null'
          description: Scheduled or actual activation.
        deactivateAt:
          anyOf:
            - $ref: '#/components/schemas/Instant'
            - type: 'null'
          description: Scheduled deactivation.
        revisionNo:
          type: integer
          description: Live revision number.
        revisionApprovedAt:
          $ref: '#/components/schemas/Instant'
          description: When the live revision was approved.
        live:
          $ref: '#/components/schemas/VoucherSetContent'
          description: Approved content of the live revision.
        brandingOverrideAssetUrls:
          type:
            - object
            - 'null'
          properties:
            logo:
              anyOf:
                - $ref: '#/components/schemas/AssetView'
                - type: 'null'
              description: Logo.
            hero:
              anyOf:
                - $ref: '#/components/schemas/AssetView'
                - type: 'null'
              description: Hero image.
          required:
            - logo
            - hero
          additionalProperties: false
          description: Rendered assets of `live.brandingOverride`.
        stockStatus:
          type: string
          enum:
            - available
            - low
            - depleted
          description: >-
            Stock status; stock numbers are never shown. `available` does not
            promise more than one voucher. Treat as an open set: new values may
            be added.
        providerToggle:
          type: boolean
          description: Your Provider Toggle.
        voucherSetToggle:
          type: boolean
          description: Your Voucher Set Toggle.
        position:
          type:
            - integer
            - 'null'
          description: Effective position (set setting, else provider setting).
        featured:
          type: boolean
          description: Set or provider setting is featured.
        effectiveCategoryId:
          $ref: '#/components/schemas/ULong'
          description: Set override, else provider override, else `live.categoryId`.
        priceAcceptance:
          $ref: '#/components/schemas/CatalogPriceAcceptance'
          description: Price gate at the request instant.
        setting:
          $ref: '#/components/schemas/ConsumerVoucherSetSettingView'
          description: Your setting for this voucher set.
        _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.
            provider:
              $ref: '#/components/schemas/Link'
              description: The catalog provider.
          required:
            - self
          additionalProperties: false
      required:
        - id
        - resource
        - providerPartnerId
        - provider
        - voucherKind
        - availability
        - activeFrom
        - deactivateAt
        - revisionNo
        - revisionApprovedAt
        - live
        - brandingOverrideAssetUrls
        - stockStatus
        - providerToggle
        - voucherSetToggle
        - position
        - featured
        - effectiveCategoryId
        - priceAcceptance
        - setting
        - _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.
    CatalogProviderSummary:
      type: object
      description: Summary of a catalog provider.
      properties:
        id:
          $ref: '#/components/schemas/ULong'
          description: Numeric id of the resource, unique per resource type.
        resource:
          type: string
          enum:
            - consumer-catalog-provider
          description: Always `consumer-catalog-provider`.
        slug:
          type: string
          description: Provider slug.
        displayName:
          $ref: '#/components/schemas/I18nText'
          description: Provider name.
        logoUrl:
          type:
            - string
            - 'null'
          format: uri
          pattern: ^https://
          description: Provider logo URL.
        _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.
          required:
            - self
          additionalProperties: false
      required:
        - id
        - resource
        - slug
        - displayName
        - logoUrl
        - _links
      additionalProperties: false
    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'
    VoucherSetContent:
      type: object
      description: >-
        The approved (live) content of a voucher set. Render Markdown fields
        with a sanitising renderer. A voucher set has no terms URL and no app
        links of its own: App Store and Google Play links and the terms and
        privacy URLs belong to the provider (`profile` of the catalog provider).
      properties:
        name:
          $ref: '#/components/schemas/I18nText'
          description: Card title (at most 80 characters per locale).
        summary:
          anyOf:
            - $ref: '#/components/schemas/I18nText'
            - type: 'null'
          description: One-liner (at most 160 characters).
        bullets:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/I18nText'
          description: Short lines on the card (at most 5).
        description:
          anyOf:
            - $ref: '#/components/schemas/I18nMarkdown'
            - type: 'null'
          description: Description in restricted Markdown (at most 5,000 characters).
        howToRedeem:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/I18nText'
          description: Redemption steps (at most 8).
        termsText:
          anyOf:
            - $ref: '#/components/schemas/I18nMarkdown'
            - type: 'null'
          description: >-
            The voucher set's own voucher terms in restricted Markdown (present
            on every approved set). The provider's terms and privacy pages are
            `termsUrl` / `privacyUrl` of the provider profile.
        valueLabel:
          anyOf:
            - $ref: '#/components/schemas/I18nText'
            - type: 'null'
          description: Value label such as "€5 off" (at most 30 characters).
        faceValue:
          anyOf:
            - $ref: '#/components/schemas/Money'
            - type: 'null'
          description: Nominal value of one voucher, used for statistics.
        categoryId:
          $ref: '#/components/schemas/ULong'
          description: Category of the set.
        linkTemplate:
          type:
            - string
            - 'null'
          description: >-
            Dynamic link template rendered alongside a code (placeholders such
            as `{{code}}`).
        allowedLinkHosts:
          type: array
          items:
            type: string
          description: Hosts that issued `https` links may use.
        allowedLinkSchemes:
          type: array
          items:
            type: string
          description: Custom app schemes issued links may use.
        brandingOverride:
          anyOf:
            - $ref: '#/components/schemas/VoucherSetBrandingOverride'
            - type: 'null'
          description: Per-set look.
        countries:
          type: array
          items:
            type: string
            pattern: ^[A-Z]{2}$
          description: ISO 3166-1 alpha-2 countries; empty means all.
        extensions:
          anyOf:
            - $ref: '#/components/schemas/JsonMetadata'
            - type: 'null'
          description: Namespaced display hints for consumers.
        metadata:
          anyOf:
            - $ref: '#/components/schemas/JsonMetadata'
            - type: 'null'
          description: Provider metadata visible to consumers.
      required:
        - name
        - summary
        - bullets
        - description
        - howToRedeem
        - termsText
        - valueLabel
        - faceValue
        - categoryId
        - linkTemplate
        - allowedLinkHosts
        - allowedLinkSchemes
        - brandingOverride
        - countries
        - extensions
        - metadata
      additionalProperties: false
    AssetView:
      type: object
      description: A rendered brand asset with its dimensions.
      properties:
        assetId:
          $ref: '#/components/schemas/ULong'
          description: Brand asset id.
        url:
          type: string
          format: uri
          pattern: ^https://
          description: Immutable public URL of the asset.
        width:
          type: integer
          description: Width in pixels.
        height:
          type: integer
          description: Height in pixels.
        variants:
          type:
            - array
            - 'null'
          items:
            type: object
            properties:
              width:
                type: integer
                description: Width in pixels.
              url:
                type: string
                format: uri
                pattern: ^https://
                description: URL of the variant.
              format:
                type: string
                enum:
                  - webp
                  - png
                  - jpeg
                description: 'Image format. Treat as an open set: new values may be added.'
            required:
              - width
              - url
              - format
            additionalProperties: false
          description: Resized variants; `null` until generated.
      required:
        - assetId
        - url
        - width
        - height
        - variants
      additionalProperties: false
    CatalogPriceAcceptance:
      type: object
      description: >-
        Whether you can redeem the set with respect to its Price Terms. Carries
        no prices; see the Pricing operations.
      properties:
        status:
          type: string
          enum:
            - accepted
            - change-pending
            - acceptance-required
            - not-priced
            - exempt
          description: >-
            Redeemable only when `accepted`, `change-pending` or `exempt`. Treat
            as an open set: new values may be added.
        nextChangeAt:
          anyOf:
            - $ref: '#/components/schemas/Instant'
            - type: 'null'
          description: Start of the next upcoming Price Terms period with different terms.
      required:
        - status
        - nextChangeAt
      additionalProperties: false
    ConsumerVoucherSetSettingView:
      type: object
      description: Your setting for a voucher set.
      properties:
        enabled:
          type: boolean
          description: >-
            Voucher Set Toggle. When never saved: the provider setting's
            `autoEnableNewVoucherSets` at the time the set became visible.
        position:
          type:
            - integer
            - 'null'
          minimum: 0
          description: Your sort position (0 or more).
        featured:
          type: boolean
          description: Featured flag.
        categoryOverrideId:
          anyOf:
            - $ref: '#/components/schemas/ULong'
            - type: 'null'
          description: Your category override.
        entityLimit:
          anyOf:
            - $ref: '#/components/schemas/EntityLimit'
            - type: 'null'
          description: Per-entity limit; `null` for none.
        settings:
          anyOf:
            - $ref: '#/components/schemas/JsonMetadata'
            - type: 'null'
          description: Your own opaque JSON for this voucher set.
        externalRef:
          type:
            - string
            - 'null'
          maxLength: 64
          description: >-
            Your own reference, unique among your voucher set settings (1-64
            characters).
        updatedAt:
          anyOf:
            - $ref: '#/components/schemas/Instant'
            - type: 'null'
          description: Last save; `null` when never saved.
      required:
        - enabled
        - position
        - featured
        - categoryOverrideId
        - entityLimit
        - settings
        - externalRef
        - updatedAt
      additionalProperties: false
    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
    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
    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
    I18nMarkdown:
      type: object
      description: >-
        Localised restricted Markdown (paragraphs, line breaks, bold, italic,
        lists, headings level 3-4, https links). Render with a sanitising
        Markdown renderer, never as raw HTML.
      properties:
        de:
          type: string
          description: German Markdown.
        en:
          type: string
          description: English Markdown.
      additionalProperties: false
      example:
        de: Gültig für **alle** E-Scooter.
        en: Valid for **all** e-scooters.
    Money:
      type: object
      description: >-
        An amount in euros: `value` in cent (2900 = €29.00). All amounts are in
        euros (EUR). In requests send `value`; a `label` you send is ignored.
      properties:
        value:
          type: integer
          minimum: 0
          description: Amount in cent (2900 = €29.00).
        label:
          type: string
          readOnly: true
          description: >-
            Server-formatted amount in the response locale (`€5.00` in English,
            `5,00 €` in German).
      required:
        - value
        - label
      additionalProperties: false
      example:
        value: 2900
        label: 29,00 €
    VoucherSetBrandingOverride:
      type: object
      description: Per-voucher-set look (colours, logo and hero image).
      properties:
        primaryColor:
          type:
            - string
            - 'null'
          pattern: ^#[0-9a-f]{6}$
          description: '`primaryColor` as `#rrggbb`.'
        secondaryColor:
          type:
            - string
            - 'null'
          pattern: ^#[0-9a-f]{6}$
          description: '`secondaryColor` as `#rrggbb`.'
        backgroundColor:
          type:
            - string
            - 'null'
          pattern: ^#[0-9a-f]{6}$
          description: '`backgroundColor` as `#rrggbb`.'
        surfaceColor:
          type:
            - string
            - 'null'
          pattern: ^#[0-9a-f]{6}$
          description: '`surfaceColor` as `#rrggbb`.'
        textColor:
          type:
            - string
            - 'null'
          pattern: ^#[0-9a-f]{6}$
          description: '`textColor` as `#rrggbb`.'
        accentColor:
          type:
            - string
            - 'null'
          pattern: ^#[0-9a-f]{6}$
          description: '`accentColor` as `#rrggbb`.'
        buttonColor:
          type:
            - string
            - 'null'
          pattern: ^#[0-9a-f]{6}$
          description: '`buttonColor` as `#rrggbb`.'
        buttonTextColor:
          type:
            - string
            - 'null'
          pattern: ^#[0-9a-f]{6}$
          description: '`buttonTextColor` as `#rrggbb`.'
        buttonBorderColor:
          type:
            - string
            - 'null'
          pattern: ^#[0-9a-f]{6}$
          description: '`buttonBorderColor` as `#rrggbb`.'
        logoAssetId:
          anyOf:
            - $ref: '#/components/schemas/ULong'
            - type: 'null'
          description: Logo asset id.
        heroImageAssetId:
          anyOf:
            - $ref: '#/components/schemas/ULong'
            - type: 'null'
          description: Hero image asset id.
      required:
        - primaryColor
        - secondaryColor
        - backgroundColor
        - surfaceColor
        - textColor
        - accentColor
        - buttonColor
        - buttonTextColor
        - buttonBorderColor
        - logoAssetId
        - heroImageAssetId
      additionalProperties: false
    JsonMetadata:
      type: object
      additionalProperties: true
      description: >-
        Free-form JSON object (at most 16 KiB, depth 5, 100 keys per object).
        The platform stores it as sent and never interprets it. Key order is not
        preserved.
      example:
        orderId: '8812'
        channel: app
    EntityLimit:
      type: object
      description: Per-entity redemption limit of a voucher set.
      properties:
        max:
          $ref: '#/components/schemas/ULong'
          description: >-
            Maximum redemptions per redemption entity in the period (at least
            1).
        period:
          type: string
          enum:
            - lifetime
            - calendar-month
          description: >-
            Counting period; calendar months use your partner time zone. Treat
            as an open set: new values may be added.
      required:
        - max
        - period
      additionalProperties: false
  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_<keyId>_<secret>
      description: >-
        Your API key in `Authorization: Bearer <key>`. 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.