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.

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

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.

For the full request/response schema (including 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.

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

The catalog supports three item types using protobuf oneof:

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

Localization

All user-facing text supports localization. For each text field you can return either (but not both):

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

Web Store Bonuses

Incentivize web purchases with bonus content:

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 every refresh and expiration timestamp in your response (offer refresh times, offer and item expirations, section display expirations, and scheduled resets such as a midnight-UTC daily offer rollover) and caps the cache at the earliest one. Stash only ever shortens the window from these signals; it never serves a cached response past the point your response indicated.

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

Recommended pattern for timed catalog resets: set the refresh or expiration timestamp 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.

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 refresh/expiration timestamp in your response). Without any timestamp signals 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 the refresh or expiration timestamp in your response. 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?

The window is short, and Stash performs a fresh server-side check before completing any purchase or redemption. Stale attempts are rejected before they reach your server, so players cannot buy something that is no longer available. To minimize the visual window further, include accurate expiration or refresh timestamps in your response.

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

Include the earliest upcoming refresh or expiration timestamp across the catalog. Stash caps the cache lifetime to that value. 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

All API calls use HMAC-SHA256 signatures for authentication:

Header: stash-hmac-signature
Value: HMAC-SHA256(request_body, BASE64(egress_api_key))

Your base64-encoded Egress API key obtained from Stash Studio is the secret used to sign the request body.

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