Real-time Catalog

The Stash v1 WebShop APIs enable game studios to power dynamic, player-personalized web shops with special offers. These protobuf-based APIs provide a robust, type-safe integration path that accelerates development while ensuring reliability at scale.

Getting Started

You can integrate the v1 APIs in two ways. Both produce the same endpoints; pick whichever fits your stack, then follow the Integration Steps below to roll it out.

# Add the public-api repo as a submodule in your backend repo
git submodule add https://github.com/stashgg/public-api.git
# Or just clone it locally
git clone https://github.com/stashgg/public-api.git

# Generate clients using the included script
cd public-api
./gen.sh

Integration Steps

API Overview

The v1 APIs are organized into three services, exposed as REST endpoints. Stash sends requests to your Game Studio's backend servers:

All endpoints use HMAC authentication for secure server-to-server communication.

JSON wire format

Stash reads your responses leniently:

• Field names: camelCase as shown in the API reference (productId) or snake_case (product_id). Both are accepted, also within one response.
• Enum values: the value's name ("CONTENT_ITEM_TYPE_WEB_STORE_BONUS") or its number (1). An enum name Stash does not recognize is ignored, and the field keeps its default value.
• Unknown fields: ignored. Extra fields in your response do not cause an error.

Catalog API

Retrieve dynamic, player-specific product catalogs.

GetCatalog

GET /api/v1/catalog: returns the complete product catalog for a given platform, region, language, and playerId. The response is structured as sections (grids or carousels) containing PurchasableItem, OfferChainItem, or NonPurchasableItem entries.

For the full request parameters and response schema, see the GetCatalog API Reference.

GetOfferDetails

GET /api/v1/catalog/offer: returns detailed offer information including drop rates for loot boxes, required for legal compliance in many jurisdictions.

For the full request parameters and response schema, see the GetOfferDetails API Reference.

Purchase API

Handle the complete purchase lifecycle with three endpoints.

Purchase Flow

For where the player's money is at each step, why ConfirmPayment is the point where your backend can still decline a purchase, and which checks only your backend can enforce, see Payment Flow.

Register and cancel are optional

RegisterPayment and CancelPayment are on or off together. By default Stash calls RegisterPayment before ConfirmPayment, and CancelPayment when a registered web shop cart purchase does not complete.

If your backend does not need a reserve step, ask your Stash engineering partner to turn both off for your shop. Stash then calls neither, and ConfirmPayment is the first request that carries the purchase's transaction ID. Stash can also turn them off only for checkout link purchases (Stash Pay and Buy Now), so web shop carts keep them.

RegisterPayment

POST /api/v1/purchase/register (Step 1): registers a purchase intent. Your backend should reserve inventory for the player and respond with one of the inline status codes (e.g. SUCCESS_REGISTERED, FAILED_INSUFFICIENT_INVENTORY, FAILED_PURCHASE_LIMIT_EXCEEDED, FAILED_INVALID_PRICE).

For the full list of status codes and the complete request/response schema, see the RegisterPayment API Reference.

ConfirmPayment

POST /api/v1/purchase/confirm (Step 2A): confirms and completes the purchase after successful payment. Your backend grants items to the player and acknowledges the transaction.

Declining a confirm. To refuse the purchase, respond with an HTTP 4xx status and a body that carries a decline object naming a PurchaseConfirmationStatus, and omit results. Stash never charges the player for a declined confirm. Where the checkout supports it, Stash uses the status to pick the message the player sees (for example PURCHASE_CONFIRMATION_STATUS_FAILED_INSUFFICIENT_INVENTORY, PURCHASE_CONFIRMATION_STATUS_FAILED_PURCHASE_LIMIT_EXCEEDED, PURCHASE_CONFIRMATION_STATUS_FAILED_INVALID_PRICE); otherwise the player sees a generic failure message. A 4xx without a decline still declines the purchase, but carries no structured reason.

{
  "decline": {
    "status": "PURCHASE_CONFIRMATION_STATUS_FAILED_PURCHASE_LIMIT_EXCEEDED",
    "productId": "gold_1000",
    "message": "player has reached the purchase limit for this item"
  }
}

Use PURCHASE_CONFIRMATION_STATUS_FAILED_PACK_LIMIT_EXCEEDED when the purchase allowance shared by every item of a purchase pack is exhausted, and PURCHASE_CONFIRMATION_STATUS_FAILED_PURCHASE_LIMIT_EXCEEDED when only the item's own limit is. Return exactly one of results or decline; a body carrying both is treated as declined.

For the full request/response schema (including the decline object, its status values, and optional fields like extraInGameCurrency, extraLoyaltyPoints, and emailMarketingOptIn), see the ConfirmPayment API Reference.

CancelPayment

POST /api/v1/purchase/cancel (Step 2B, failure path): cancels a pending purchase. Your backend should release reserved inventory so the player can retry.

See the CancelPayment API Reference for the full request/response schema.

Loyalty snapshot on purchase requests

When the shop runs a live loyalty program, the RegisterPayment and ConfirmPayment request bodies carry a loyalty snapshot (type PlayerLoyaltyState): the same object your backend already receives on loyalty webhooks. This gives your backend the player's XP balance, tier, and tier-relative earn multiplier at purchase time, in-band with the register/confirm calls, so it can apply tier-aware logic (for example bonus sizing) without a separate lookup.

"loyalty": {
  "campaignId": "spring_2026",
  "totalPoints": 1250,
  "currentTierId": "silver",
  "pointsMultiplierPermille": 2000,
  "pointsToNextTier": 750,
  "pointsToNextMilestone": 250,
  "nextMilestone": {
    "milestoneId": "milestone_uuid",
    "rewards": [
      { "itemId": "gold-coins", "quantity": 500, "type": "IN_GAME_CURRENCY" }
    ]
  }
}

• The snapshot reflects state as of the request. On RegisterPayment it is pre-purchase; on ConfirmPayment it reflects the XP the confirmed purchase awards.
• It is present only when the shop has a published, enabled loyalty program and a live campaign. Otherwise the field is omitted and the request body is byte-identical to a non-loyalty shop's.
• Treat it as read-only context. It never replaces the authoritative loyalty state your backend receives on the loyalty webhooks; grant XP-linked effects from the webhook, not from this snapshot.

Player API

Retrieve player profile information for personalized experiences.

GetPlayer

GET /api/v1/player: returns player profile data (name, avatar, language, in-game level, in-game currency) for display in the web shop. Stash calls this endpoint with the playerId you supplied to the catalog request.

See the GetPlayer API Reference for the full request/response schema.

Key Data Types

Catalog Items

Each catalog item is exactly one of five types (a protobuf oneof; the JSON key is in parentheses):

For the full field-level structure of each type, including pricing, contents, expiration, attributes, and offer chain link details, see the GetCatalog API Reference.

Stash skips an item whose type it does not recognize and renders the rest of the catalog.

Prices

Each PurchasableItem carries one price, set in one of two ways:

When you send amount:

• cents is in the currency's CLDR minor units: 199 in USD is $1.99, and 300 in JPY is ¥300.
• cents must be greater than 0. To give an item away, use a FreeItem.
• Use one currency for all priced items in a response. Stash shows one currency per shop page and leaves out priced items in any other currency.

Studio price lookup

Stash looks up an imported price in the currency that is primary for the player's region, and takes the first match in this order:

1. The player's region and platform.
2. The player's region, from a file imported for all platforms (Universal in Studio).
3. US in USD, the player's platform.
4. US in USD, Universal.

If none of these exists, the item is left out of the catalog. A missing country therefore shows the US price rather than hiding the item, and a row imported for a country in a currency other than its primary one is never matched. When no platform is resolved, only Universal rows match.

To return a different price per platform or country, choose the price from the request's platform and region:

• platform comes from the Unity SDK session, then from the platform stored on the player's account (the user.platform your backend sends on Approve custom login), then from the browser's user agent (iPhone, iPad and iPod are iOS; Android is Android). A desktop browser has no platform unless the account has one stored, so send user.platform when you link the player if prices differ by platform.
• region is the most recent region your backend sent for the player, as user.regionCode on Approve custom login or Generate authenticated URL when the player signs in. When you send none, it is the country of the player's IP address, or US when that is unknown. It is not the country of the player's app store account.

Purchase packs

Use a pack when one offer is sold at several prices and the player buys one of them, for example the same reward at three price points. Each price point is one entry in the pack's items (a PurchasePackItem).

Declare the values the whole offer shares once, on the pack:

A PurchasePackItem has no maxPurchasable, expiration or refreshAt of its own, so the pack's values govern every item in it.

• Buy the whole offer. To sell one item that buys everything in the offer in a single transaction, give it type: PURCHASE_PACK_ITEM_TYPE_WHOLE_PURCHASE_PACK and list the combined rewards in its contents. Use this type on at most one item per pack.
• Remaining count. Compute maxPurchasable per player and send it fresh in every response. Stash keeps no purchase count of its own: it checks each purchase against the value from your catalog.
• Purchase calls. For an item bought from a pack, RegisterPayment, ConfirmPayment and CancelPayment carry the pack's id as purchasePackId on that item. productId still identifies the price point.
• Unavailable offers. To withdraw an offer or a price point, leave it out of the response.

See PurchasePack in the API reference for every field.

Free items and claim identity

A FreeItem is claimable at no cost. When a player claims one, Stash records the redemption and emits a FREE_ITEM_REDEEMED webhook. Two fields govern how claims are tracked:

• status: your response is authoritative for whether the gift is offered (AVAILABLE, CLAIMED, or LOCKED). After a recorded claim, Stash overrides AVAILABLE to CLAIMED on catalog reads so a reload cannot show a consumed gift as claimable. It only ever applies that one flip: a CLAIMED or LOCKED status you send is never changed, and Stash never produces AVAILABLE. The override ends at the item's refreshAt; from then on your status alone decides the next period.
• claimId (optional): a stable claim identity, separate from itemId. Free items that share a claimId are the same claim for a claim period: claiming any one of them consumes the claim for all of them. When absent, itemId is the claim identity, which is the existing behavior; integrations that do not send it change nothing.

Use claimId when the item you serve varies per player, for example a daily gift whose itemId differs by loyalty tier. Keep the claimId stable across the variants and the claim still de-duplicates as one gift per period, whichever variant a player sees.

Rules to follow:

• Return at most one item per claimId per response; additional items sharing one may be discarded. A locked preview of a later reward must carry a distinct claimId, or none at all.
• A repeat claim inside the same window returns an idempotent success: no duplicate FREE_ITEM_REDEEMED webhook, and no second Loyalty XP credit for gifts that grant XP.
• On the FREE_ITEM_REDEEMED payload, itemId is the item that was granted; claimId is the claim it consumed and appears only when it differs from itemId.

Localization

All user-facing text supports localization. Each text field is a LocalizableText. Send defaultText in every one, since it is the fallback, and add at most one of:

• localizationKey: Stash-side lookup in our localization system (requires sharing localization keys with Stash up front).
• localizedText: Pre-resolved text in the player's language, computed by your backend.

Pick whichever fits your localization pipeline; you can mix the two across different fields in the same response.

Stash shows localizedText when you send it. For a localizationKey, it shows the translation for the player's language, or defaultText when the key has no translation. With neither, it shows defaultText.

Web Store Bonuses

Give players extra content for buying on the web:

Grant bonuses from ConfirmPayment. The bonusItems amounts on the ConfirmPayment request are the amounts to grant for the bonus IDs they name. Do not also grant your offer's own bonus for an ID listed there, or the player receives it twice.

Drop Rate Compliance

For loot boxes and randomized rewards, the API supports drop rate disclosure required for legal compliance in many jurisdictions.

Enabling Drop Rate Display

To show drop rates or offer details in a popup:

1. Add a badge with the show details action: Include a badge on the offer with action: BADGE_ACTION_SHOW_OFFER_DETAILS. This signals to the frontend to display an info button that calls the GetOfferDetails API and opens the corresponding modal.

2. Enable per-item details (optional): For individual content items that should show their own reward/drop rate details, include clickAction: CONTENT_ITEM_CLICK_ACTION_SHOW_DETAILS_BY_ID on that ContentItem.

Example Catalog.PurchasableItem Response

{
  "attributes": {
    "badge": {
      "text": { "defaultText": "Loot Box" },
      "action": "BADGE_ACTION_SHOW_OFFER_DETAILS"
    }
  },
  "contents": [
    {
      "name": "Legendary Hero",
      "guid": "xxx",
      "image": "https://...",
      "quantity": "1",
      "dropRate": "2.5%",
      "clickAction": "CONTENT_ITEM_CLICK_ACTION_SHOW_DETAILS_BY_ID"
    },
    {
      "name": "Common Item",
      "quantity": "1",
      "dropRate": "97.5%"
    }
  ]
}

Caching

Stash caches the catalog response your server returns. This reduces load on your catalog server and improves shop load times for players.

How long are responses cached?

The effective cache lifetime is:

min(5 minutes, earliest upcoming timestamp in your response)

Stash inspects these timestamps in your response and caps the cache at the earliest upcoming one:

• expiration on a product, chain or pack item
• refreshAt on a product, pack or free item
• displayExpiration on a section
• nextResetAt on a trigger, for scheduled resets such as a midnight-UTC daily offer rollover

Stash only ever shortens the window from these signals; it never serves a cached response past the point they indicate.

The default cap is 5 minutes when your response contains no timestamp signals.

Recommended pattern for timed catalog resets: set one of the timestamps above equal to your planned reset time. Stash re-fetches exactly at that boundary, so there is no perceptible delay when the catalog changes.

Immediate invalidation after player actions

Stash clears a player's cached catalog immediately after every non-read action:

• Purchases
• Free-gift redemptions
• Loyalty-milestone claims (where integrated)

The next shop load re-fetches live from your server. No special annotation or forced reload is needed. This is automatic.

Always-fresh Stash-side data

Only the raw response from your catalog API is cached. Data that Stash computes (prices, bonuses, offer-chain and purchase-progression state, injected free offers) is recomputed on every request and is never cached. Changes you make to prices or bonuses in Stash Studio are reflected immediately regardless of the cache window.

Force a catalog refresh

If something changes outside the web shop and you want the catalog view in the Web Shop to reflect it right away, call Force refresh catalog from your backend. Pass a player_id to refresh a single player, or omit it to refresh every player of your shop. It applies only to shops with a Real-time Catalog integration; for any other integration it is a no-op that still returns success.

Frequently asked questions

Does Stash cache the response my server returns?

Yes. Stash caches your catalog/offer response for a short, bounded window. This reduces load on your catalog server and speeds up the shop for players.

What is the worst-case staleness? How long is my data cached?

min(5 minutes, earliest upcoming timestamp in your response), counting only the timestamps listed in How long are responses cached?. Without any of those timestamps in your response, responses may be served for up to 5 minutes.

How do I make a catalog change appear at a known time, such as a daily reset?

Include the planned reset time as one of the timestamps that shorten the cache, for example a trigger's nextResetAt or an item's expiration. Stash re-fetches exactly at that boundary with no delay.

What happens after a player makes a purchase?

The player's cached catalog is cleared immediately on every purchase, free-gift redemption, and loyalty-milestone claim. The next shop visit re-fetches live from your server. This is automatic. No special annotation is needed.

Do I need to send Cache-Control HTTP headers?

No. Stash does not use HTTP Cache-Control headers for this. Control freshness via refresh and expiration timestamps in your catalog payload instead.

Can the cache show a player an offer they already purchased?

Not after a Web Shop purchase: Stash clears the player's cached catalog as soon as it completes. A purchase made outside the Web Shop, such as in-game, shows when the cache window ends or after you force a catalog refresh. Until then Stash still refuses an offer whose expiration has passed, but it checks the quantity against the cached maxPurchasable, so enforce your purchase limits when you confirm a purchase. Accurate expiration and refresh timestamps in your response shorten the window.

My catalog has offers with different refresh times. How should I structure the timestamps?

Stash caps the cache lifetime at the earliest upcoming timestamp among those that shorten the cache, so send accurate values on every item and section. Ideally align all refreshes to a single consistent reset time so the whole catalog expires together.

Can caching be turned off while I test catalog changes?

Yes. Contact your Stash engineering partner and they will disable caching for your test shop, so every request hits your server live.

What are the benefits of caching?

Faster shop loads for players, fewer requests to your catalog server, and improved reliability if your server is briefly slow or unavailable.

Authentication

Stash authenticates outgoing requests to your game backend using a versioned HMAC-SHA256 signature in the x-stash-hmac-signature header:

x-stash-hmac-signature: v1;<appId>;<unixMillisTimestamp>;<base64-hmac>

The signature covers "<unixMillisTimestamp>." + <body>, where <body> is the exact bytes Stash transmits: empty string for GET requests, raw request body for POST requests. The HMAC key is your egress secret base64-decoded: the value shown in Studio → Project Settings → API Keys is base64-encoded; decode it before computing the HMAC (e.g. Buffer.from(secret, 'base64')). Reject requests where <unixMillisTimestamp> is more than 5 minutes from your server clock.

Verifying the signature

For Node.js, Python, and Go implementation code, see API Keys → HMAC Verification.

Configuration

To configure your Real-time Catalog endpoint in Stash Studio:

Debugging & Logs

Stash Studio provides comprehensive logging and debugging tools for your Real-time Catalog. Use these tools to monitor your catalog endpoint and troubleshoot issues:

• Check Stash Studio logs for endpoint response times
• Verify your endpoint returns valid JSON
• Ensure all required fields are present
• Test with your studio-test credentials before going live