Create a redemption link

Creates a Redemption Link. Your Workspace Branding must have landing.privacyUrl and landing.imprintUrl; an email-otp link needs the Email OTP Gate to be ready. Missing Price Acceptances do not block creation; such sets are left out of the landing page. A replay with the same Idempotency-Key returns the same link and token. See Redemption links.

Required permissions: manage-consumer-redemption-links · API keys: allowed

POST /consumer/v1/redemption-links

cURL

entity-bound

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

201

default

{ "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": "[e-mail]" }, "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

201

application/json

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