Quickstart

In about fifteen minutes you create a voucher set in the sandbox, add vouchers, get the content approved, activate the set and receive a webhook when a sandbox consumer redeems one of your vouchers. You need curl, jq and a shell.

Get sandbox access and an API key

Sign in to the sandbox developer dashboard and request API access. AllRide activates it; you get an email. If you have no sandbox sign-in yet, send your AllRide account manager (or AllRide through the Support link at the top of this site) your company name and the email address of your first user.
Open API keys and create a key with these scopes: view-profile, view-provider-voucher-sets, manage-provider-voucher-sets, submit-provider-voucher-sets, activate-provider-voucher-sets, upload-provider-vouchers, view-webhooks, manage-webhooks. Copy the secret: it is shown once.
Export the base URL and the key, then check who you are:

export VOUCHER_API_BASE_URL="https://api.voucher-staging.allride.io"
export VOUCHER_API_KEY="<the vk_test_ secret you copied>"

curl -sS "$VOUCHER_API_BASE_URL/partner/v1/principal" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" | jq '.data | {partnerSlug, environment, effectivePermissions}'

environment is test. A 401 api-key-invalid means the key is wrong or is a production key; a 403 api-access-inactive means API access is not active yet.

Create a voucher set

Pick a category, then create a code set. The content becomes the set’s draft; consumers see nothing yet.

CATEGORY_ID=$(curl -sS "$VOUCHER_API_BASE_URL/provider/v1/categories?perPage=1" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" | jq '.data.data[0].id')

VOUCHER_SET_ID=$(curl -sS -X POST "$VOUCHER_API_BASE_URL/provider/v1/voucher-sets" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "internalName": "Quickstart ride credit",
    "voucherKind": "code",
    "content": {
      "name": {"de": "5 € Fahrguthaben", "en": "€5 ride credit"},
      "termsText": {"de": "Einmal pro Kunde einlösbar.", "en": "One redemption per customer."},
      "faceValue": {"value": 500},
      "categoryId": '"$CATEGORY_ID"'
    }
  }' | jq '.data.id')
echo "$VOUCHER_SET_ID"

The response is 201 with "status": "draft". Your partner’s default locale must be one of the keys of every text (de here).

Add three vouchers

The batch API creates up to 1,000 vouchers in one transaction, all or nothing.

curl -sS -X POST "$VOUCHER_API_BASE_URL/provider/v1/voucher-sets/$VOUCHER_SET_ID/vouchers:batch" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "defaults": {"redemptionType": "single", "validUntil": "2027-12-31T22:59:59Z"},
    "vouchers": [{"value": "QS-0001-AAAA"}, {"value": "QS-0002-BBBB"}, {"value": "QS-0003-CCCC"}]
  }' | jq '.data | {createdCount, items: [.items[] | {id, valueMask}]}'

Values come back masked (QS••••AA); the API never returns them in clear text except through the audited reveal operation.

Submit the content for approval

Consumers only ever see approved content. Create a change request from the draft and submit it:

curl -sS -X POST "$VOUCHER_API_BASE_URL/provider/v1/voucher-sets/$VOUCHER_SET_ID/change-requests" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"providerNote": "Quickstart", "submit": true}' | jq '.data | {id, status, kind}'

The change request goes to scanning while automated checks run. In the sandbox, a change request whose checks pass is approved automatically; in production, AllRide reviews every one. Poll the set until status is inactive and liveRevisionNo is 1:

curl -sS "$VOUCHER_API_BASE_URL/provider/v1/voucher-sets/$VOUCHER_SET_ID" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" | jq '.data | {status, liveRevisionNo, pendingChangeRequestId}'

Activate the set and receive a webhook

Register an endpoint for redemption-created. Use a public HTTPS URL that you control (for example a request inspector); store both secrets from the response.

export WEBHOOK_URL="<your https endpoint>"
curl -sS -X POST "$VOUCHER_API_BASE_URL/partner/v1/webhook-endpoints" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url": "'"$WEBHOOK_URL"'", "eventTypes": ["redemption-created"]}' \
  | jq '.data | {id, status, firstSecret, secondSecret}'

Then activate the set:

curl -sS -X POST "$VOUCHER_API_BASE_URL/provider/v1/voucher-sets/$VOUCHER_SET_ID:activate" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" | jq '.data | {status, availability}'

Within five minutes the sandbox consumer sandbox-transit redeems one voucher of every new active set. Your endpoint receives a redemption-created delivery (event plus the provider view of the redemption in payload), and the stock drops by one. Verify the x-signing-signature header as described in Verifying signatures.

Next steps

Import thousands of vouchers with uploads.
Generate links next to codes with dynamic links.
Configure stock alerts and schedule activations.
Work through the going-live checklist.

Get started

Authentication and security

API conventions

Webhooks

Provider guides

Workspace

​Related

Related