Catalog Management

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:

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

The 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:

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.

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>
FieldDescription
v1Protocol 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:

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?

On this page