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

# Concepts

> Partners, roles and the core resources of the AllRide Voucher Platform, and how a voucher set moves through your catalog.

These are the names used everywhere in the API, the dashboards and these docs. Each concept has exactly one name.

## Partners and roles

* **Partner**: a company that has a contract with AllRide. A partner is a provider, a consumer, or both, and is the owner of everything it creates. Every API key and every dashboard user acts for exactly one partner.
* **Partner Provider** ("provider"): a partner that owns voucher sets and vouchers, for example a scooter or bike operator.
* **Partner Consumer** ("consumer"): a partner that offers voucher sets to its own end customers and redeems them. You are a consumer. Consumers are the only partners AllRide bills.
* **End Customer**: the person your app or landing page serves. End customers do not have accounts on the platform; you represent them as redemption entities if you want to.
* **User** and **Partner Membership**: a person with a login, and the link that makes them a member of your partner. One person can be a member of several partners.
* **Group** and **Permission**: permissions are capabilities with kebab-case names such as `create-consumer-redemptions`; groups carry permissions, and members get the union of their groups' permissions and their own direct permissions ([Members and groups](https://docs-consumer.voucher.allride.io/workspace/members-and-groups.md)).
* **API Access**: a partner-level switch that AllRide activates before API keys work.
* **API Key**: a secret credential of your partner whose **scopes** are a subset of the delegable permissions ([API keys](https://docs-consumer.voucher.allride.io/guides/api-keys.md)).

## Core resources

**Provider content**

* **Voucher Set**: a provider's collection of vouchers that share content, terms, kind, link format and schedule.
* **Voucher Set Revision**: an approved, unchangeable snapshot of a voucher set's content. You only ever see the **live revision**; providers change content through a **Change Request** that AllRide approves before it reaches you.
* **Voucher**: one redeemable item of a set, either a **code** or a **link**. The **Voucher Kind** (`code` or `link`) is declared per voucher set.
* **Redemption Type**: `single` (a voucher can be redeemed once) or `multiple` (it can be redeemed up to **Max Redemptions** times; `null` means unlimited).
* **Validity Window**: `validFrom` and `validUntil` of a voucher.
* **Availability**: how a visible voucher set looks to you: `upcoming`, `active` or `deactivation-scheduled`.

**Your side**

* **Consumer Catalog**: the providers and voucher sets AllRide makes available to you, with their live content ([Catalog and toggles](https://docs-consumer.voucher.allride.io/consumer/catalog.md)).
* **Catalog Toggle**: your on/off switch per provider (**Provider Toggle**) and per voucher set (**Voucher Set Toggle**).
* **Price Terms** and **Price Acceptance**: the price you pay per redemption of a voucher set, and a user's recorded agreement to it. A set is redeemable only with an accepted price ([Prices and price acceptance](https://docs-consumer.voucher.allride.io/consumer/prices.md)).
* **Redemption**: the assignment of one voucher use to you (and optionally to a redemption entity), recorded in the ledger. Its **Redemption Channel** says how it was created: `api`, `dashboard`, `redemption-link` or `import`.
* **Void**: marking a redemption as cancelled for reporting and limits. A void never returns the voucher to stock ([Voiding redemptions](https://docs-consumer.voucher.allride.io/consumer/voiding.md)).
* **Redemption Entity**: your record of who or what redeems (a customer, a device, an employee), with an optional opaque `refId` and `metadata` ([Redemption entities](https://docs-consumer.voucher.allride.io/consumer/redemption-entities.md)).
* **Redemption Link**: a URL you create that lets an end customer redeem on an AllRide-hosted landing page ([Redemption links](https://docs-consumer.voucher.allride.io/consumer/redemption-links.md)).
* **Email OTP Gate**: a Redemption Link option that asks the visitor to confirm an email address with a one-time code before redeeming ([Email OTP links](https://docs-consumer.voucher.allride.io/consumer/email-otp-links.md)).
* **Landing Page**: the page, in your Workspace Branding, that serves a Redemption Link, on AllRide's host or your own **Custom Domain** ([Landing pages and custom domains](https://docs-consumer.voucher.allride.io/consumer/landing-pages.md)).

**Integration**

* **Webhook Endpoint**: an HTTPS URL of yours that receives signed events; each attempt to send one is a **Webhook Delivery** ([Webhooks](https://docs-consumer.voucher.allride.io/webhooks/overview.md)).
* **Idempotency Key**: the optional `Idempotency-Key` header that makes a POST safe to retry ([Idempotency](https://docs-consumer.voucher.allride.io/guides/idempotency.md)).
* **Audit Event**: an append-only record of a change in your partner ([Audit log](https://docs-consumer.voucher.allride.io/workspace/audit-log.md)).

## Lifecycle at a glance

Providers create and schedule voucher sets; AllRide approves their content and decides which consumers may see them. From your side, a voucher set appears in your catalog, becomes redeemable, and eventually leaves it:

```mermaid theme={null}
stateDiagram-v2
  direction LR
  [*] --> upcoming: available to you (scheduled)
  [*] --> active: available to you (already active)
  upcoming --> active: activation time reached
  active --> deactivation_scheduled: provider schedules the end
  deactivation_scheduled --> active: schedule cancelled
  deactivation_scheduled --> [*]: deactivated
  active --> [*]: deactivated, suspended or access removed
  upcoming --> [*]: activation cancelled or access removed
```

* A set enters your catalog with the webhook [`catalog-voucher-set-available`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-available) and leaves it with [`catalog-voucher-set-deactivated`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-deactivated) or [`catalog-voucher-set-unavailable`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-unavailable).
* Content changes arrive as a new live revision with [`catalog-voucher-set-updated`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-updated).
* You can redeem a set when its `availability` is `active` or `deactivation-scheduled`, your Provider Toggle and Voucher Set Toggle are on, its Price Terms are accepted and it has stock.
* Every redemption sends [`redemption-created`](https://docs-consumer.voucher.allride.io/webhooks/events/redemption-created); a void sends [`redemption-voided`](https://docs-consumer.voucher.allride.io/webhooks/events/redemption-voided).

## Related

* [Catalog and toggles](https://docs-consumer.voucher.allride.io/consumer/catalog.md)
* [Redeeming vouchers](https://docs-consumer.voucher.allride.io/consumer/redeeming.md)
* [Permissions and scopes](https://docs-consumer.voucher.allride.io/guides/permissions.md)


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