> ## 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.

# Concepts

> Partners, roles and the core resources of the platform.

## Partners and roles

| Term | Meaning |
| - | - |
| **Partner** | A company that contracts with AllRide. Every API call acts for exactly one partner: the partner of the API key, or the partner the dashboard user signed in to. |
| **Partner Provider** | A partner that owns voucher sets and vouchers. This site is for providers. |
| **Partner Consumer** | A partner that offers voucher sets to its customers and redeems vouchers. Providers never see which consumer redeemed. |
| **User** and **Partner Membership** | A person (one per email) and their membership in a partner. One person can belong to several partners. |
| **Group** and **Permission** | Groups carry permissions such as `manage-provider-voucher-sets`; a member's effective permissions are their direct permissions plus those of their groups. |
| **API Key** | A credential for your backend with a subset of your permissions, its **scopes**. |
| **API Access** | A partner-level switch that AllRide activates before API keys work. |

A partner can be both provider and consumer; it then also uses the Consumer API, documented on the consumer docs site.

## Core resources

| Term | Meaning | API |
| - | - | - |
| **Provider Profile** | Your consumer-visible general information and general terms. Changes only through approved change requests. | `/provider/v1/provider-profile` |
| **Listing Branding** | How you look inside consumer catalogs and landing pages (colours, logo, hero image). Approval required. | `/provider/v1/listing-branding` |
| **Workspace Branding** | The theme of your own dashboards. No approval. | `/partner/v1/branding/workspace` |
| **Category** | AllRide-managed grouping shown to consumers. | `/provider/v1/categories` |
| **Voucher Set** | A collection of vouchers sharing content, terms, kind, link format and schedule. | `/provider/v1/voucher-sets` |
| **Voucher Set Revision** | An immutable, approved snapshot of a set's content. Consumers only see the **live revision**. | `…/revisions` |
| **Change Request** | A proposed create or update of consumer-visible content that AllRide approves. | `…/change-requests` |
| **Voucher** | One redeemable item: a **code** or a **link** (the **Voucher Kind** of its set). | `…/vouchers` |
| **Redemption Type** and **Max Redemptions** | `single` (once) or `multiple` (up to `maxRedemptions`; `null` means unlimited). | voucher fields |
| **Validity Window** | `validFrom` (earliest redemption) and `validUntil` (expiry) of a voucher. | voucher fields |
| **Link Template** | A URL with `{{placeholders}}` rendered at redemption ("dynamic links"). | voucher set content |
| **Voucher Upload** | An asynchronous CSV or XLSX import of vouchers. | `…/uploads` |
| **Stock** and **Stock Alert Rule** | Remaining and used capacity of a set, and the thresholds (50, 75, 90, 100 % used) that trigger alerts. | `stock`, `…/stock-alert-rule` |
| **Content Scan** | Automated checks of a change request's content; AllRide reviews the outcome. | change request status |
| **Availability** | How consumers see an active set: `upcoming`, `active` or `deactivation-scheduled`. | `availability` |
| **Redemption** | One use of one of your vouchers by a consumer. You see when and which voucher, never who. | `/provider/v1/redemptions` |
| **Redemption Channel** and **Void** | How a redemption was made (not shown to providers) and its cancellation by the consumer (`voidedAt`). A void never returns the voucher to stock. | `status: voided` |
| **Webhook Endpoint** and **Webhook Delivery** | Your HTTPS URL that receives signed events, and the log of every delivery attempt. | `/partner/v1/webhook-endpoints` |
| **Idempotency Key** | Optional header on every POST that makes retries safe. | `Idempotency-Key` |

Which consumers can see and redeem your active sets is decided by AllRide: access is granted per provider and consumer and is denied by default, and each consumer must have agreed its prices with AllRide before it can redeem. Consumer prices are agreed between AllRide and each consumer; you never see them, and you never see which consumers have access. Ask your AllRide account manager about distribution.

## Lifecycle at a glance

```mermaid theme={null}
stateDiagram-v2
  [*] --> draft: create voucher set
  draft --> pending_approval: submit create change request
  pending_approval --> draft: rejected or withdrawn
  pending_approval --> inactive: AllRide approves (live revision 1)
  inactive --> active: activate
  inactive --> scheduled: schedule activation
  scheduled --> active: activeFrom reached
  scheduled --> inactive: cancel schedule
  active --> deactivation_scheduled: schedule deactivation
  deactivation_scheduled --> active: cancel schedule
  active --> inactive: deactivate
  deactivation_scheduled --> inactive: deactivate or deactivateAt reached
  inactive --> suspended: AllRide suspends
  active --> suspended: AllRide suspends
  suspended --> inactive: AllRide unsuspends
  draft --> archived: archive
  inactive --> archived: archive
  archived --> [*]
```

Vouchers can be added in every status except `suspended` and `archived`. Content changes of a live set go through update change requests and never change the status; consumers keep seeing the previous revision until the new one is approved.

## Related

* [Voucher sets](https://docs-provider.voucher.allride.io/provider/voucher-sets.md)
* [Change requests and approval](https://docs-provider.voucher.allride.io/provider/change-requests.md)
* [Permissions and scopes](https://docs-provider.voucher.allride.io/guides/permissions.md)


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