Dynamic 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%"
    }
  ]
}

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 dynamic catalog endpoint in Stash Studio:

Debugging & Logs

Stash Studio provides comprehensive logging and debugging tools for your dynamic 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