> ## Documentation Index
> Fetch the complete documentation index at: https://docs-provider.voucher.allride.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first calls in the sandbox.

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.

**1. Get sandbox access and an API key**

1. Sign in to the [sandbox developer dashboard](https://provider-developers.voucher-staging.allride.io/go/api-access) 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.
2. Open [API keys](https://provider-developers.voucher-staging.allride.io/go/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.
3. Export the base URL and the key, then check who you are:

```bash theme={null}
export VOUCHER_API_BASE_URL="https://api.voucher-staging.allride.io"
export VOUCHER_API_KEY="<the vk_test_ secret you copied>"
```

```bash theme={null}
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.

**2. Create a voucher set**

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

```bash theme={null}
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).

**3. Add three vouchers**

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

```bash theme={null}
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.

**4. Submit the content for approval**

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

```bash theme={null}
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`:

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

**5. 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.

```bash theme={null}
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:

```bash theme={null}
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](https://docs-provider.voucher.allride.io/webhooks/verify-signatures.md).

**6. Next steps**

* Import thousands of vouchers with [uploads](https://docs-provider.voucher.allride.io/provider/vouchers-and-uploads.md#upload-a-file).
* Generate links next to codes with [dynamic links](https://docs-provider.voucher.allride.io/provider/link-templates.md).
* Configure [stock alerts](https://docs-provider.voucher.allride.io/provider/stock-and-alerts.md) and [schedule](https://docs-provider.voucher.allride.io/provider/activation-and-scheduling.md) activations.
* Work through the [going-live checklist](https://docs-provider.voucher.allride.io/guides/going-live.md).

## Related

* [Sandbox and production](https://docs-provider.voucher.allride.io/guides/environments.md)
* [Idempotency](https://docs-provider.voucher.allride.io/guides/idempotency.md)
* [Voucher sets](https://docs-provider.voucher.allride.io/provider/voucher-sets.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.