Create a redemption link

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

{
  "data": {
    "id": 8017,
    "resource": "redemption-link",
    "token": "ExampleLinkToken000001",
    "url": "https://vouchers.example-transit.example.com/r/ExampleLinkToken000001",
    "name": "Jobticket November - employee 42",
    "mode": "entity-bound",
    "redemptionEntity": {
      "id": 9030,
      "resource": "redemption-entity",
      "refId": "emp-42",
      "_links": {
        "self": {
          "href": "https://api.voucher.allride.io/consumer/v1/redemption-entities/9030",
          "type": "application/json"
        }
      }
    },
    "requireEmailOtp": false,
    "allowedProviderIds": [
      1030,
      1056
    ],
    "allowedVoucherSetIds": [],
    "maxRedemptions": 1,
    "maxTotalRedemptions": null,
    "redemptionCount": 0,
    "metadata": {
      "campaign": "jobticket-nov"
    },
    "expiresAt": "2026-11-30T22:59:59Z",
    "customDomainId": 20030,
    "defaultLocale": "de",
    "status": "active",
    "lastRedeemedAt": null,
    "revokedAt": null,
    "createdBy": {
      "type": "partner-user",
      "id": 4069,
      "label": "[email protected]"
    },
    "createdAt": "2026-10-22T09:00:00Z",
    "updatedAt": "2026-10-22T09:00:00Z",
    "_links": {
      "self": {
        "href": "https://api.voucher.allride.io/consumer/v1/redemption-links/8017",
        "type": "application/json"
      },
      "catalog": {
        "href": "https://api.voucher.allride.io/consumer/v1/redemption-links/8017/catalog",
        "type": "application/json"
      },
      "redemptionEntity": {
        "href": "https://api.voucher.allride.io/consumer/v1/redemption-entities/9030",
        "type": "application/json"
      }
    }
  }
}

POST

consumer

redemption-links

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

{
  "data": {
    "id": 8017,
    "resource": "redemption-link",
    "token": "ExampleLinkToken000001",
    "url": "https://vouchers.example-transit.example.com/r/ExampleLinkToken000001",
    "name": "Jobticket November - employee 42",
    "mode": "entity-bound",
    "redemptionEntity": {
      "id": 9030,
      "resource": "redemption-entity",
      "refId": "emp-42",
      "_links": {
        "self": {
          "href": "https://api.voucher.allride.io/consumer/v1/redemption-entities/9030",
          "type": "application/json"
        }
      }
    },
    "requireEmailOtp": false,
    "allowedProviderIds": [
      1030,
      1056
    ],
    "allowedVoucherSetIds": [],
    "maxRedemptions": 1,
    "maxTotalRedemptions": null,
    "redemptionCount": 0,
    "metadata": {
      "campaign": "jobticket-nov"
    },
    "expiresAt": "2026-11-30T22:59:59Z",
    "customDomainId": 20030,
    "defaultLocale": "de",
    "status": "active",
    "lastRedeemedAt": null,
    "revokedAt": null,
    "createdBy": {
      "type": "partner-user",
      "id": 4069,
      "label": "[email protected]"
    },
    "createdAt": "2026-10-22T09:00:00Z",
    "updatedAt": "2026-10-22T09:00:00Z",
    "_links": {
      "self": {
        "href": "https://api.voucher.allride.io/consumer/v1/redemption-links/8017",
        "type": "application/json"
      },
      "catalog": {
        "href": "https://api.voucher.allride.io/consumer/v1/redemption-links/8017/catalog",
        "type": "application/json"
      },
      "redemptionEntity": {
        "href": "https://api.voucher.allride.io/consumer/v1/redemption-entities/9030",
        "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

Create a Redemption Link. The mode follows from the fields: an entity → entity-bound; requireEmailOtp → email-otp; neither → anonymous.

name

string | null

1-120 characters.

Required string length: 1 - 120

redemptionEntityId

integer<uint64> | null

Bind to an existing entity (mode entity-bound).

Required range: 0 <= x <= 18446744073709552000

redemptionEntity

object | null

Bind to an entity upserted by refId.

Show child attributes

requireEmailOtp

boolean

default:false

Require the email OTP gate (mode email-otp); not allowed with an entity.

allowedProviderIds

integer<uint64>[]

At most 50 providers, each with a visible and enabled set; empty = all.

Maximum array length: 50

Unsigned 64-bit integer (ids and large counters). May exceed 2^53; parse with a BigInt-safe JSON parser in JavaScript.

Required range: 0 <= x <= 18446744073709552000

allowedVoucherSetIds

integer<uint64>[]

At most 200 sets, each visible with both toggles on; empty = all.

Maximum array length: 200

Unsigned 64-bit integer (ids and large counters). May exceed 2^53; parse with a BigInt-safe JSON parser in JavaScript.

Required range: 0 <= x <= 18446744073709552000

maxRedemptions

integer<uint64>

At least 1; null = unlimited.

Required range: 1 <= x <= 18446744073709552000

maxTotalRedemptions

integer<uint64>

At least 1; only for email-otp links.

Required range: 1 <= x <= 18446744073709552000

metadata

object | null

Forwarded in redemption-created webhooks. Never put personal data here.

Example:

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

expiresAt

string<date-time> | null

Must be in the future.

Example:

"2026-11-01T00:00:00Z"

customDomainId

integer<uint64> | null

One of your active custom domains.

Required range: 0 <= x <= 18446744073709552000

defaultLocale

enum<string> | null

de or en.

Available options:

de,

en

Response

Created

Single-object envelope around a RedemptionLink.

data

object

required

A shareable link to an AllRide-hosted landing page where an end customer redeems.

Show child attributes

Consumer API

Workspace API

Authorizations

Headers

Body

Response