Real-time Catalog
Learn how to expose REST API endpoints on your game backend to power personalized web shops with real-time offers. This guide covers the Catalog, Player, and Purchase APIs with protobuf-based type-safe integration.
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.
In this guide
This page covers setup, authentication, and configuration. The rest of the guide is split by topic:
Endpoints
The Catalog, Purchase, and Player API endpoints Stash calls on your backend.
Payment Flow
Where the money is at each step, and why ConfirmPayment is required.
Catalog Items and Prices
Item types, prices, purchase packs, and web store bonuses.
Free Items and Streaks
Free item claims and streaks tracked by Stash.
Localization and Text
Localized text, formatted text, and the shop banner.
Offer Templates
Template and slot names for rewards, buy buttons, and text.
Drop Rate Compliance
Info buttons, drop rates tooltips, and the offer details popup.
Caching
How long Stash caches your catalog response, and forcing a refresh.
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.
Clone the proto repository and generate type-safe clients automatically:
# 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.shThe gen.sh script generates clients for Go, TypeScript, and OpenAPI specs. Adapt it for your preferred language (C#, Java, Python, etc.) using standard protobuf tooling.
No documentation required: The generated clients provide full type definitions, so your IDE's autocomplete guides the integration.
Integration Steps
Obtain API credentials
Your Stash engineering partner will generate an Egress API key for you in Stash Studio. Set your Game Backend URL in Stash Studio to match where the APIs will be hosted. Custom API endpoint paths can be configured if needed.
Generate clients or review the API reference
Use the proto repository to generate type-safe clients, or review the API Reference for detailed endpoint documentation.
Implement the required endpoints
At minimum, implement these endpoints on your game backend:
Required:
- GetCatalog: Returns the product catalog
- ConfirmPayment: Powers both WebShop and StashPay
Register and cancel (on by default, optional per shop):
Stash calls these two as a pair. Implement both, or ask your Stash engineering partner to turn them off for your shop. See Register and cancel are optional.
- RegisterPayment: Reserves inventory across all game/shop clients
- CancelPayment: Releases inventory reservation locks
Optional:
- GetOfferDetails: Show extra details like drop rates for legal compliance
- GetPlayer: Show player-specific details like avatar, level, in-game currency balances
Test with test credentials
Test your integration with your studio-test.stash.gg credentials before going live.
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.
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>| Field | Description |
|---|---|
v1 | Protocol version |
<appId> | Your immutable App ID (Studio → Project Settings → General) |
<unixMillisTimestamp> | Request timestamp in Unix milliseconds |
<base64-hmac> | Standard base64-encoded HMAC-SHA256 signature |
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.
New shops (created on or after 2026-08-15) receive only x-stash-hmac-signature. The legacy unversioned stash-hmac-signature header is no longer emitted for them. New integrations should verify x-stash-hmac-signature only.
If you've implemented HMAC authentication and your game backend is still
responding to Stash's API requests with 3xx, 4xx, or 5xx error codes, you may
need to allowlist test-api.stash.gg and api.stash.gg on your cloud network
firewall.
Configuration
To configure your Real-time Catalog endpoint in Stash Studio:
Navigate to game settings
In Stash Studio, navigate to your game settings.
Open App Backend
Go to Project Settings → App Backend
Set endpoint URL
Set your Game Backend URL to match where the Catalog & Purchase APIs will be hosted.
Configure authentication
Your Stash engineering partner can configure custom API endpoint paths if needed.
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
How is this guide?
Managed Catalog
Learn how to create and publish products, configure Free Gift offers, and schedule product availability in the Stash Webshop managed catalog.
Endpoints
The Catalog, Purchase, and Player API endpoints your game backend implements for a Real-time Catalog integration, and how Stash calls them.