Redeem a voucher

Allocates one voucher (first expiring first, never the same single-use voucher twice) from a voucher set (voucherSetId) or from the provider’s best redeemable set (providerId) and returns the issued code or link. Optionally attaches a redemption entity by id or inline by refId, and stores your metadata. The response is sent only after the redemption is committed. Always send an Idempotency-Key: a replay returns the identical 201 including issued; a stored 409 is final for its key. Errors are checked in this order: unknown set (404), not redeemable (409 voucher-set-unavailable), no Price Acceptance (409 price-acceptance-required), entity problems, entity limit, stock. Sends the redemption-created webhook. See Redeeming vouchers.

Required permissions: create-consumer-redemptions · API keys: allowed

POST /consumer/v1/redemptions

cURL

by-set

curl --request POST \
  --url https://api.voucher-staging.allride.io/consumer/v1/redemptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

201

default

{
  "data": {
    "id": 6017,
    "resource": "redemption",
    "status": "completed",
    "channel": "api",
    "providerPartnerId": 1030,
    "voucherSetId": 2030,
    "voucherSetRevisionNo": 2,
    "voucherId": 5017,
    "voucherSet": {
      "id": 2030,
      "name": {
        "de": "5 € Fahrguthaben",
        "en": "€5 ride credit"
      },
      "providerDisplayName": {
        "de": "Acme Scooters",
        "en": "Acme Scooters"
      }
    },
    "issued": {
      "kind": "code",
      "code": "ACME5-7KQ2-M9XA",
      "link": "https://acme-scooters.example.com/r?c=ACME5-7KQ2-M9XA"
    },
    "validFrom": null,
    "validUntil": "2026-12-31T22:59:59Z",
    "redemptionEntity": {
      "id": 9017,
      "resource": "redemption-entity",
      "refId": "customer:48213",
      "_links": {
        "self": {
          "href": "https://api.voucher.allride.io/consumer/v1/redemption-entities/9017",
          "type": "application/json"
        }
      }
    },
    "redemptionLink": null,
    "batchId": null,
    "metadata": {
      "redemptionReason": "standard",
      "forMonth": "2026-10"
    },
    "actor": {
      "type": "api-key",
      "id": 12017,
      "label": "Production integration"
    },
    "idempotencyKey": "order-8812:line-1",
    "legacyRef": null,
    "redeemedAt": "2026-10-21T17:42:10.120Z",
    "voidedAt": null,
    "voidedBy": null,
    "voidReason": null,
    "_links": {
      "self": {
        "href": "https://api.voucher.allride.io/consumer/v1/redemptions/6017",
        "type": "application/json"
      },
      "voucherSet": {
        "href": "https://api.voucher.allride.io/consumer/v1/catalog/voucher-sets/2030",
        "type": "application/json"
      },
      "redemptionEntity": {
        "href": "https://api.voucher.allride.io/consumer/v1/redemption-entities/9017",
        "type": "application/json"
      }
    }
  }
}

Authorizations

Authorization · string · header · required

Your API key in Authorization: Bearer <key>. Use vk_test_… keys against the sandbox and vk_live_… keys against production.

Headers

Idempotency-Key · string

Optional key (1-255 printable ASCII characters, no spaces; a UUID is ideal) that makes this POST safe to retry: the same key with the same request replays the stored response for 24 hours. See Idempotency.

Required string length: 1 - 255

Pattern: ^[\x21-\x7E]{1,255}$

Body

application/json

Exactly one of voucherSetId and providerId; at most one of redemptionEntityId and redemptionEntity.

voucherSetId · integer<uint64>

Redeem from this voucher set.

Required range: 0 <= x <= 18446744073709552000

providerId · integer<uint64>

Redeem from the provider's best redeemable set (by your position, then activation).

Required range: 0 <= x <= 18446744073709552000

redemptionEntityId · integer<uint64>

An existing redemption entity.

Required range: 0 <= x <= 18446744073709552000

redemptionEntity · object

Inline entity, upserted by refId.

Show child attributes

metadata · object | null

Stored on the redemption and forwarded in the redemption-created webhook. Never put personal data here.

Example:

{ "orderId": "8812", "channel": "app" }

Response

201

application/json

Created

Single-object envelope around a Redemption.

data · object · required

A redemption (consumer view). Append-only. Also the payload of the redemption-created and redemption-voided webhooks.

Show child attributes