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

# Catalog and toggles

> Which providers and voucher sets you can redeem, how availability works, and how Provider and Voucher Set Toggles control what your channels show.

Your catalog is the list of Partner Providers and voucher sets that AllRide makes available to you. You read it with the [catalog operations](https://docs-consumer.voucher.allride.io/api-reference/consumer-catalog-voucher-sets-list.md), decide with Catalog Toggles which entries your apps and landing pages show, and keep your own settings and references next to each entry.

## What your catalog contains

A voucher set appears in your catalog when all of these hold:

* the set has an approved live revision (drafts and pending change requests are never visible to you);
* its effective status is `scheduled`, `active` or `deactivation-scheduled`;
* its provider is active;
* AllRide has granted you access: the provider's Provider Access allows you, and the set's Consumer Access allows you too. Access is managed by AllRide, and a provider is visible to no consumer until AllRide grants access.

A provider is listed when at least one of its voucher sets is visible to you; a provider you have no access to is absent, and asking for it by id answers 404 [`provider-not-found`](https://docs-consumer.voucher.allride.io/errors/catalog#provider-not-found). A set that is not visible to you answers 404 [`voucher-set-not-found`](https://docs-consumer.voucher.allride.io/errors/catalog#voucher-set-not-found).

The catalog has three resources:

| Resource | Operations | Contents |
| - | - | - |
| `consumer-catalog-provider` | [List](https://docs-consumer.voucher.allride.io/api-reference/consumer-catalog-providers-list.md), [get](https://docs-consumer.voucher.allride.io/api-reference/consumer-catalog-providers-get.md), [update](https://docs-consumer.voucher.allride.io/api-reference/consumer-catalog-providers-update.md) | The provider's live profile (name, tagline, terms, app links), its Listing Branding, counts of visible sets per availability, the Provider Toggle and your provider settings |
| `consumer-catalog-entry` | [List](https://docs-consumer.voucher.allride.io/api-reference/consumer-catalog-voucher-sets-list.md), [get](https://docs-consumer.voucher.allride.io/api-reference/consumer-catalog-voucher-sets-get.md), [update](https://docs-consumer.voucher.allride.io/api-reference/consumer-catalog-voucher-sets-update.md) | One voucher set: its approved content (`live`), voucher kind (`code` or `link`), availability and schedule, `stockStatus`, both toggles, `priceAcceptance` and your set settings |
| `category` | [List](https://docs-consumer.voucher.allride.io/api-reference/consumer-catalog-categories-list.md), [get](https://docs-consumer.voucher.allride.io/api-reference/consumer-catalog-categories-get.md) | The active categories AllRide maintains, with localised names and an icon |

Reading the catalog needs the permission `view-consumer-catalog`; changing toggles and settings needs `manage-consumer-catalog`. Both can be granted to API keys.

```bash theme={null}
curl "$VOUCHER_API_BASE_URL/consumer/v1/catalog/voucher-sets?filter%5BproviderToggle%5D=true&filter%5BvoucherSetToggle%5D=true&filter%5Bavailability%5D=active&perPage=50" \
  -H "Authorization: Bearer $VOUCHER_API_KEY"
```

Each entry carries `priceAcceptance` with a `status` and a `nextChangeAt`:

| `priceAcceptance.status` | Meaning | Redeemable |
| - | - | - |
| `accepted` | You accepted the Price Terms in force now | Yes |
| `change-pending` | You accepted the current terms; a price change starts at `nextChangeAt` and is not yet accepted | Yes, until the new terms start |
| `acceptance-required` | You have not accepted the Price Terms in force now | No: redeeming answers 409 [`price-acceptance-required`](https://docs-consumer.voucher.allride.io/errors/catalog#price-acceptance-required) |
| `not-priced` | The set has no price yet | No |
| `exempt` | Your partner is not billed for this set | Yes |

A missing Price Acceptance never hides an entry from the catalog. Accept prices on the Prices page of the consumer dashboard, as described in [Prices and price acceptance](https://docs-consumer.voucher.allride.io/consumer/prices.md). The entry never shows the terms themselves; read them through the pricing operations.

## Availability

`availability` tells you where a set is in its lifecycle as you see it:

| `availability` | Meaning |
| - | - |
| `upcoming` | Approved and scheduled; `activeFrom` says when it becomes redeemable |
| `active` | Redeemable now (subject to your toggles, stock and Price Acceptance) |
| `deactivation-scheduled` | Redeemable now and ends at `deactivateAt` |

Availability is computed from the clock at the moment of your request, so a set whose `activeFrom` has passed is `active` immediately. A provider's `availability` is `active` when any of its visible sets is active, else `deactivation-scheduled` when any is, else `upcoming`. Use `nextActiveFrom` and `earliestDeactivateAt` on the provider to show "coming soon" and "leaving soon" labels.

Stock is shown only as `stockStatus` (`available`, `low` or `depleted`), never as numbers. `available` does not promise more than one voucher; see [batch redemptions](https://docs-consumer.voucher.allride.io/consumer/redeeming.md#batch-redemptions).

## Provider and voucher set toggles

Catalog Toggles let you choose what your channels offer without changing what AllRide makes visible:

* the **Provider Toggle** (`providerToggle`, set through `setting.enabled` on the provider) is **off** by default;
* the **Voucher Set Toggle** (`voucherSetToggle`, set through `setting.enabled` on the entry) defaults to the provider's `setting.autoEnableNewVoucherSets`, which is **on** by default.

A voucher set is redeemable through the API and shown on landing pages only when both toggles are on. Redeeming a set whose provider or set toggle is off answers 409 [`voucher-set-unavailable`](https://docs-consumer.voucher.allride.io/errors/catalog#voucher-set-unavailable).

Toggles never hide entries from the catalog operations: the list always returns every visible entry with its toggle values, so your management screens can show what is switched off. Apps and landing pages filter with `filter[providerToggle]=true&filter[voucherSetToggle]=true`.

```bash theme={null}
curl -X PATCH "$VOUCHER_API_BASE_URL/consumer/v1/catalog/providers/1030" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"setting": {"enabled": true, "autoEnableNewVoucherSets": false}}'
```

`autoEnableNewVoucherSets` is not retroactive. When you change it, every set of that provider that is already visible keeps its current Voucher Set Toggle; only sets that become visible afterwards start with the new value. You can set toggles on `upcoming` sets so they are on when the set activates.

## Your own settings and references

Both the provider and the entry carry a `setting` object that only you see. Update it with a JSON Merge Patch: properties you leave out stay unchanged and `null` clears a value.

| Field | Provider | Voucher set | Notes |
| - | - | - | - |
| `enabled` | Yes | Yes | The toggle |
| `autoEnableNewVoucherSets` | Yes | No | Initial toggle of sets that become visible later |
| `position` | Yes | Yes | Your sort order (0 or more); the entry's effective `position` falls back to the provider's |
| `featured` | Yes | Yes | Highlight flag; an entry is `featured` when the set or its provider is |
| `categoryOverrideId` | Yes | Yes | Show the entry in another active category (`effectiveCategoryId`) |
| `entityLimit` | No | Yes | `{max, period}` with `period` `lifetime` or `calendar-month`: how often one Redemption Entity may redeem this set |
| `settings` | Yes | Yes | Your own JSON object, replaced as a whole |
| `externalRef` | Yes | Yes | Your own reference (1-64 characters), unique among your provider settings and among your set settings |

```bash theme={null}
curl -X PATCH "$VOUCHER_API_BASE_URL/consumer/v1/catalog/voucher-sets/2030" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"setting": {"enabled": true, "entityLimit": {"max": 1, "period": "calendar-month"}, "externalRef": "ride-credit-5"}}'
```

* Look entries up by your reference with `filter[setting.externalRef]=ride-credit-5`. A reference that is already used answers 409 [`external-ref-taken`](https://docs-consumer.voucher.allride.io/errors/catalog#external-ref-taken).
* A PATCH writes only the properties you send, so two systems that change different properties of the same setting both succeed.
* Calendar months of `entityLimit` follow your partner time zone. Changing the `period` starts counting from zero under the new period; lowering `max` below the current count blocks further redemptions in that period.

## Keeping a local copy

Apps that show the catalog to end customers should not call the API on every screen view. A pattern that works:

1. Load the catalog with the toggle filters and cache it for at most 60 seconds.
2. Subscribe a [webhook endpoint](https://docs-consumer.voucher.allride.io/webhooks/overview.md) to the `catalog-*` events and refresh the affected entry when one arrives: [`catalog-voucher-set-available`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-available), [`updated`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-updated), [`activation-scheduled`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-activation-scheduled), [`activated`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-activated), [`deactivation-scheduled`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-deactivation-scheduled), [`deactivated`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-deactivated), [`unavailable`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-unavailable), [`stock-low`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-stock-low) and [`depleted`](https://docs-consumer.voucher.allride.io/webhooks/events/catalog-voucher-set-depleted).
3. Treat a 409 from a redemption as the final word: the cache can be up to a minute old, and redeeming always checks the current state.

`catalog-*` webhooks are sent for every set visible to you, whatever your toggles say, so you also learn about new sets you might want to switch on. `catalog-voucher-set-unavailable` names the reason, for example `access-revoked` or `voucher-set-archived`.

## Related

* [Redeeming vouchers](https://docs-consumer.voucher.allride.io/consumer/redeeming.md)
* [Prices and price acceptance](https://docs-consumer.voucher.allride.io/consumer/prices.md)
* [Pagination, filtering and sorting](https://docs-consumer.voucher.allride.io/guides/pagination.md)
* [Event catalog](https://docs-consumer.voucher.allride.io/webhooks/events.md)


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