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, 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. A set that is not visible to you answers 404 voucher-set-not-found.

The catalog has three resources:

Resource	Operations	Contents
consumer-catalog-provider	List, get, update	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, get, update	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, get	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.

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

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.

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.

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

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.
• 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 to the catalog-* events and refresh the affected entry when one arrives: catalog-voucher-set-available, updated, activation-scheduled, activated, deactivation-scheduled, deactivated, unavailable, stock-low and 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
• Prices and price acceptance
• Pagination, filtering and sorting
• Event catalog