Caching
How long Stash caches your Real-time Catalog response, when it clears the cache, and when to force a catalog refresh.
Stash caches the catalog response your server returns. This reduces load on your catalog server and improves shop load times for players.
Caching is on for all Real-time Catalog integrations. If you wish to disable it temporarily for testing purposes, let your engineering partner at Stash know.
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:
expirationon aproduct,chainorpackitemrefreshAton aproduct,packorfreeitemdisplayExpirationon a sectionnextResetAton 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
Most integrations never need this. The cache window is short, and Stash already clears a player's cached catalog automatically after the actions above.
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. List the players to refresh in player_ids, up to 100 per call. When several players need a refresh at the same time, send them in one call rather than one call per player. Leave out both player_ids and player_id only to refresh every player of your shop. player_id, which names a single player, still works but is deprecated: use player_ids instead. The endpoint applies only to shops with a Real-time Catalog integration; for any other integration it is a no-op that still returns success.
This endpoint is optional. Stash checks every Web Shop purchase against the catalog it holds for the player, and that can be a cached response, up to the window in How long are responses cached?. An item's expiration is compared with the current time when the purchase completes, so an expired offer is refused even while a cached view still shows it. A maxPurchasable count is only as current as the cached response, so keep enforcing your purchase limits when you confirm a purchase. Call this endpoint when a change outside the Web Shop, such as an in-game purchase, should reach the catalog view and the counts Stash checks before the cache window ends.
Always name the players in player_ids unless you know exactly what you are doing. A request that names no player refreshes every single player of your shop, which can result in a much slower Web Shop experience for all players across the board and a spike of API calls to your external catalog API server. A signed request with an empty player_ids list is refused, so a job that finds no player to refresh never refreshes everyone; skip the call in that case.
| Scenario | Call ForceRefreshCatalog? |
|---|---|
| A player made a purchase in-game (outside the web shop) that changes what they should see | ✅ Yes (optional); refresh so the catalog view in the Web Shop updates right away |
| Your catalog changed outside a normal player action and you want it visible before the cache expires | ✅ Yes (optional); shortens the visible staleness window |
| A player completed a purchase in the web shop | ❌ No; the cache is cleared automatically |
| A player redeemed a free gift or claimed a loyalty milestone | ❌ No; the cache is cleared automatically |
| You changed prices or bonuses in Stash Studio | ❌ No; Stash-computed data is never cached and updates immediately |
| Your shop does not use a Real-time Catalog integration | ❌ No; the call is a no-op |
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.
How is this guide?
Drop Rate Compliance
Disclose drop rates and rarity for randomized rewards with info buttons, tooltips, and the offer details popup.
Authentication Methods
The three ways players sign in to your Stash webshop: pre-authenticated links your game server generates, Direct Sign-in (SSO) with providers like Google, Apple, or Facebook, and Account Linking through deep links and QR codes.