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

Player level

Return the player's level in inGameLevel as a positive integer. The web shop can show it on the player's profile, for example as a power level. Omit it when your game has no player level; the web shop then shows none. Stash treats 0 as an omitted level.

In-game currency balances

Return the player's balances in wallet, one entry per in-game currency. Stash reads the first 100 entries and ignores the rest.

Stash attaches the name and icon of the matching reward type in Studio to each balance. Studio supports one in-game currency reward type per shop today, so a balance for a bonusId that is not a reward type in Studio comes back without a name or icon. An entry whose bonusId names a reward type of another kind, such as loyalty points, is ignored. See Reward types.

{
  "player": {
    "playerId": "player-123",
    "name": "PlayerOne",
    "wallet": [
      { "bonusId": "gold-coins", "bonusType": "WALLET_BONUS_TYPE_IN_GAME_CURRENCY", "balance": "12000000000000000" }
    ]
  }
}

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 an integer in the currency's minor units: 199 in USD is $1.99, and 300 in JPY is ¥300. The number of decimal places per currency follows your shop's minor-unit standard.
• 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.

Minor-unit standard

Each shop has one minor-unit standard. It sets the number of decimal places Stash uses for a currency when it reads cents in your catalog prices and when it writes cents, tax, total and decimalPlaces in RegisterPayment, ConfirmPayment and CancelPayment requests.

The standards disagree for some currencies, for example:

A price of 5,000 COP is cents: 5000 under CLDR release 32 and cents: 500000 under the other two.

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 expiration or refreshAt of its own, so the pack's values govern every item in it. It can have its own maxPurchasable: the player's remaining purchases of that price point. The lower of the item's and the pack's maxPurchasable applies to the item.

• 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. To show a price point as sold out instead, keep it and send maxPurchasable: 0 on it: the player sees it but cannot buy it, and Stash refuses checkout for it.

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.

Formatted text

A LocalizableText can carry values to insert into its text, so one translated sentence serves every player and each language places the values where its grammar needs them.

Stash picks the text for the player's language as described in Localization, inserts the values, and shows the result.

Example. A localization entry shared with Stash:

A content item that uses it as its info tooltip:

{
  "name": { "defaultText": "Card pack" },
  "quantity": "1",
  "infoButton": {
    "tooltip": {
      "text": {
        "defaultText": "Contains guaranteed cards",
        "localizationKey": "TOOLTIP.PACK_GUARANTEE",
        "formatArguments": { "count": "1", "rarity": "3" },
        "formatSyntax": "TEXT_FORMAT_SYNTAX_ICU_MESSAGE_FORMAT"
      }
    }
  }
}

The tooltip text is At least 1 card of 3 stars or more in English and 3つ星以上のカードが1枚以上 in Japanese.

For printf-style text such as At least %1$s card of %2$s stars or more, send "formatArguments": {"1": "1", "2": "3"} with "formatSyntax": "TEXT_FORMAT_SYNTAX_PRINTF".

• Values are literal. Stash inserts each value as sent, with no number, date or plural formatting, so send values already formatted for the player's language.
• Limits. At most 32 entries. Keys match ^[A-Za-z0-9_]{1,64}$ and values are at most 512 bytes. The text before composing is at most 4096 bytes, and the composed text at most 8192 bytes.
• Fallback. If the text cannot be composed, for example because a value it reads is missing, Stash composes defaultText with the same syntax and values instead. If that fails too, the text is left out. Write defaultText without placeholders so the fallback renders, and with printf-style write a literal percent sign as %%.
• Optional. A text with neither field shows as is. formatArguments without a formatSyntax leaves the text out.

For ICU-style quoting, %d, and the other edge cases, see the GetCatalog API Reference.

Shop banner

catalog.banner is an optional banner shown once, above the first section of the shop, for example a message about a bonus for buying on the web. Its text is a LocalizableText, and because the catalog is requested per player, it can differ per player and use formatted text:

{
  "catalog": {
    "banner": {
      "text": {
        "defaultText": "Extra rewards on the web",
        "localizationKey": "BANNER.WEB_BONUS",
        "formatArguments": { "percent": "10" },
        "formatSyntax": "TEXT_FORMAT_SYNTAX_ICU_MESSAGE_FORMAT"
      }
    }
  }
}

With the entry +{percent}% on the web, the banner reads +10% on the web. The banner is display only: it never changes what is granted or charged. Omit it, or send text that resolves to blank, for no banner.

Offer templates with named slots

When your offer templates name their slots, send the slot names with each offer, so each reward, each buy button and each piece of text lands in the slot meant for it. Without them, the web shop fills a template's slots by position: rewards in contents order, and text from the offer's fixed fields such as name. Position breaks when a template has more slots than the fixed fields, or when a new template version orders its slots differently.

All four fields are optional. A response without them stays valid: the web shop shows the offer in your shop's default template for its type and fills the slots by position.

Agree your templates, their versions and their slot names with your Stash engineering partner. Stash compares every templateKey, layoutKey, buyButton.layoutKey and textSlots key exactly as sent: case-sensitive, untrimmed, and with no prefix matching. Title and title are different slots, and starter-offer-v2 and starter-offer-v3 are different templates.

{
  "product": {
    "productId": "starter_bundle",
    "price": { "priceId": "starter_bundle_499" },
    "name": { "defaultText": "Starter Bundle" },
    "templateKey": "starter-offer-v2",
    "textSlots": {
      "Title": { "defaultText": "Spring Starter Bundle", "localizationKey": "offer.starter.title" },
      "RibbonText": { "defaultText": "Best value", "localizationKey": "offer.ribbon.best_value" }
    },
    "contents": [
      { "name": { "defaultText": "Coins" }, "quantity": "5000", "layoutKey": "TopLeftReward" },
      { "name": { "defaultText": "Gems" }, "quantity": "50", "layoutKey": "BottomReward" }
    ]
  }
}

Here the offer shows in version 2 of the starter-offer template. Its Title slot shows "Spring Starter Bundle", not the name, and each reward fills the slot its layoutKey names.

Template choice

A templateKey that is missing, empty, longer than 128 characters, or not one of your shop's templates is ignored: the offer shows in your shop's default template for its type. A template that names no reward slots ignores layoutKey, one that names no buy button slots ignores buyButton.layoutKey, and one that names no text slots ignores textSlots.

Reward slots

• Keyed rewards first. A reward whose layoutKey names a reward slot of the template fills that slot. When several rewards name the same slot, the first in contents fills it.
• Then the rest, in order. Every other reward fills the remaining reward slots in contents order: a reward without a layoutKey, one whose layoutKey names no slot of the template, and a later reward that names an already filled slot. Every reward is still shown.
• Empty or long keys. An empty layoutKey, or one longer than 128 characters, counts as no key.
• Rewards and slots that do not match up. With more rewards than reward slots, the template shows the extra rewards as it does for any offer that overflows it. With fewer, the unfilled slots stay empty.

Buy button slots

A template can give each buy button a slot of its own, separate from the slots its rewards fill, for example one buy button slot per price point of a pack. Name it in the buy button's layoutKey, in attributes.buyButton of the product or the pack item.

• The label stays the price. text is optional on a buy button. Send buyButton with only layoutKey to name the slot and keep the button's default label, the price.
• Buy buttons only. layoutKey is read on a buy button. On an info button it is ignored.
• Empty or long keys. An empty layoutKey, or one longer than 128 characters, counts as no key.
• Buttons without a matching slot. When a buy button has no layoutKey, has one that names no buy button slot of the template, or names the same slot as another buy button of the offer, the template decides where that button sits.
• Display only. The slot never changes what is bought, charged or sent to ConfirmPayment.

Text slots

• Slot text wins. A text slot shows its textSlots value. Without one, it shows the fixed field the template fills that slot from, for example name for a title slot. Stash defines that field for each template. A slot with no value in either place stays empty, with no placeholder text.
• Localization. Each textSlots value is a LocalizableText, localized like every other text field (see Localization). When its localizationKey has no translation for the player's language, the slot shows the entry's defaultText. When that is empty too, the slot shows its fixed field.
• Ignored entries. An entry whose key is empty, longer than 128 characters or not a text slot of the template is ignored, and so is an entry whose text is empty or resolves to empty. The offer still shows. Text of only spaces counts as a value.
• Limit. Stash keeps at most 50 entries with text, the first 50 by slot name in byte order.
• Repeated names. Send each slot name once. If a name repeats within one textSlots object, Stash uses its first value and the rest of the catalog still loads.
• The offer card only. textSlots changes only the offer card. Checkout and receipts show the fixed fields, so always send name (title on an info item).

Slots on purchase packs

Set templateKey and textSlots on the pack, once for the whole offer. A price point (an item in the pack's items) can add its own textSlots:

• For a slot set on both, the price point's value is used for that price point. The pack's entries fill every other slot.
• A price point entry that is ignored, for example an empty text or a key over 128 characters, leaves the pack's entry for that slot.
• Of the combined entries, Stash keeps the first 50 by slot name in byte order.

A pack has no buy button of its own: each price point names its buy button slot in its own attributes.buyButton. Here each price point's rewards fill a Resources_* slot and its buy button sits in a SKU_* slot:

{
  "pack": {
    "id": "three_price_offer",
    "templateKey": "three-price-offer-v1",
    "items": [
      {
        "productId": "offer_tier_1",
        "price": { "priceId": "offer_tier_1_499" },
        "name": { "defaultText": "Small" },
        "contents": [{ "name": { "defaultText": "Coins" }, "quantity": "1000", "layoutKey": "Resources_Left" }],
        "attributes": { "buyButton": { "layoutKey": "SKU_Left" } }
      },
      {
        "productId": "offer_tier_2",
        "price": { "priceId": "offer_tier_2_999" },
        "name": { "defaultText": "Medium" },
        "contents": [{ "name": { "defaultText": "Coins" }, "quantity": "2500", "layoutKey": "Resources_Middle" }],
        "attributes": { "buyButton": { "layoutKey": "SKU_Center" } }
      },
      {
        "productId": "offer_tier_3",
        "price": { "priceId": "offer_tier_3_1999" },
        "name": { "defaultText": "Large" },
        "contents": [{ "name": { "defaultText": "Coins" }, "quantity": "6000", "layoutKey": "Resources_Right" }],
        "attributes": { "buyButton": { "layoutKey": "SKU_Right" } }
      }
    ]
  }
}

These fields change only how the offer card shows the offer. What Stash sends to ConfirmPayment, and what your backend grants, do not change.

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.

Info buttons

An info button shows an "i", and tapping it opens its tooltip or a page. It can sit in two places:

Both are the same Button shape, with the same fields and rules whether the button sits on a reward or on a whole offer:

Tapping an info button opens its tooltip when it has one, and otherwise opens linkUrl. A tooltip whose text cannot be shown, and a linkUrl that is not https, count as not sent, and an info button with neither is not shown. Leave the offer's info button out when there is nothing to explain, for example on coins only.

A reward with a guaranteed minimum rarity, like the card pack in the formatted text example, can set "informationType": "INFORMATION_TYPE_RARITY" on its infoButton. A reward whose own contents are drawn at random can set "informationType": "INFORMATION_TYPE_DROP_RATES" with a linkUrl to its drop rates page, or a tooltip with links. A pack whose rewards are drawn at random can explain its drop rates once for the whole offer:

{
  "pack": {
    "id": "sticker-pack-offer",
    "attributes": {
      "infoButton": {
        "informationType": "INFORMATION_TYPE_DROP_RATES",
        "tooltip": {
          "text": {
            "defaultText": "For the odds, see [here](https://example.com/odds)",
            "localizationKey": "TOOLTIP.DROP_RATES"
          }
        }
      }
    },
    "items": [
      {
        "productId": "sticker-pack-small",
        "price": { "priceId": "price-small" },
        "contents": [{ "name": { "defaultText": "Sticker pack" }, "quantity": "1" }]
      }
    ]
  }
}

Links in drop rates tooltips

The tooltip text of an info button with INFORMATION_TYPE_DROP_RATES, on a reward or on a whole offer, can contain links written as [label](url), for example For the odds, see [here](https://example.com/odds).

• Link form. A link is [, the label up to the first ], then immediately (, and the URL up to the first ), with no spaces in the URL. Write a ) inside a URL as %29.
• Only links are read. Every other character shows as typed, including a [ or ( that does not complete a link. No other formatting is applied.
• https only. A link whose URL does not start with https:// followed by a host, or that carries a user name (user@host), shows its label as plain text, so the text is never lost. A link with an empty label shows nothing.
• After formatting. Links are read from the text after formatted text values are inserted. A value you send in formatArguments always shows as typed and never starts or ends a link. A value inside a label shows as part of the label; a link whose URL contains a value shows its label as plain text.
• Special characters in a URL. In a printf-style text, write a % in the URL as %% (so %29 becomes %%29). In an ICU-style text, quote any brace. Otherwise the text cannot be composed.
• Other tooltips are unchanged. In every other tooltip, [ and ( are ordinary characters.

All of these fields are optional, so a response without them stays valid.

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