Gamify API: Loyalty Store Catalog and Purchase Endpoints

Four new endpoints let a custom loyalty widget render a store and complete a purchase against it. All four are documented in the API Reference, and the Custom Widget UI Integration Guide now covers the store in its load and player-action flows.

Catalog

• GET /store/items/brand/{brandId} — active items. Each grants rewardQuantity of one rewardId.
• GET /store/bundles/brand/{brandId} — active bundles. A bundle sells several items for one price and carries items[] for the contents list.

Neither takes a playerId, so both can be fetched in parallel with the rest of your widget data. Each entry carries the display fields a grid needs — priceCurrencyName, priceCurrencyIcon, categoryName, tagName, tagColor, image — so only rewardId needs a lookup against the rewards catalog.

Purchases

• POST /store/items/brand/{brandId}/{itemId}/player/{playerId}/buy
• POST /store/bundles/brand/{brandId}/{bundleId}/player/{playerId}/buy

No request body. Both return the purchase plus newBalance, and both require an Idempotency-Key header.

Two things to get right

• Generate the Idempotency-Key per purchase attempt. A fresh UUID when the player taps Buy, reused only for retries of that tap. A key derived from item and player alone makes the player's next legitimate purchase look like a replay. Retry sequentially, never in parallel.
• Read effectivePrice; never recompute a price client-side. Render basePrice struck through when onSale is true, disable Buy when soldOut is true, and re-fetch the catalog once discountEndsAt passes.

newBalance covers the spent currency only — re-fetch GET /player-rewards/brand/{brandId}/player/{playerId} for the granted reward, and player level too when the reward is a progression reward. purchase.snapshot freezes the title, price and reward at purchase time, so a receipt or purchase-history view still reads correctly after an entry is renamed, repriced or archived.

See Store Item Catalog, Store Bundle Catalog, Buy a Store Item and Buy a Store Bundle for the full request and response reference.