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.

Why Protobuf-Based APIs?

Getting Started

Step 1: Auto-generate Clients (Recommended)

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.

Step 2: Implement the REST APIs

Implement the REST endpoints that Stash will call. You can either use the API Reference to write your own clients or generate clients automatically from the protobufs.

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

Returns the complete product catalog with purchasable items, offer chains, and display elements.

Endpoint: GET /api/v1/catalog

Query Parameters:

Response Structure:

Catalog
└── Sections[]
    ├── header (LocalizableText)
    ├── displayType (GRID or CAROUSEL)
    └── items[]
        ├── PurchasableItem (products & bundles)
        ├── OfferChainItem (progressive unlocks)
        └── NonPurchasableItem (banners & info)

See the full GetCatalog API Reference for detailed response schema.

GetOfferDetails

Returns detailed offer information including drop rates for loot boxes (required for legal compliance in many jurisdictions).

Endpoint: GET /api/v1/catalog/offer

Query Parameters:

See the full GetOfferDetails API Reference for detailed response schema.

Purchase API

Handle the complete purchase lifecycle with three endpoints.

Purchase Flow

RegisterPayment

Step 1: Registers a purchase intent. Your backend should reserve inventory for the player.

Endpoint: POST /api/v1/purchase/register

Key Fields:

Response Status Codes:

See the full RegisterPayment API Reference for detailed request/response schema.

ConfirmPayment

Step 2A: Confirms and completes the purchase after successful payment.

Endpoint: POST /api/v1/purchase/confirm

Key Fields:

See the full ConfirmPayment API Reference for detailed request/response schema.

CancelPayment

Step 2B: Cancels a pending purchase. Your backend should release reserved inventory.

Endpoint: POST /api/v1/purchase/cancel

See the full CancelPayment API Reference for detailed request/response schema.

Player API

Retrieve player profile information for personalized experiences.

GetPlayer

Returns player profile data for display in the web shop.

Endpoint: GET /api/v1/player

Query Parameters:

Response Example:

{
  "player": {
    "playerId": "abc123",
    "name": "PlayerOne",
    "avatarUrl": "https://...",
    "language": "en",
    "inGameLevel": 42,
    "inGameCurrency": 15000
  }
}

See the full GetPlayer API Reference for detailed response schema.

Coming Soon: Loyalty Data

The Player API will soon include loyalty program data to power rich loyalty experiences:

Key Data Types

Catalog Items

The catalog supports three item types using protobuf oneof:

PurchasableItem Structure

PurchasableItem
├── productId (required) - Your unique SKU
├── guid (optional) - Instance UUID for dynamic offers
├── type - STANDARD_OFFER or BUNDLE_OFFER
├── name/description (LocalizableText)
├── image - Product image URL
├── price
│   ├── amount.currency - ISO currency code
│   └── amount.cents - Price in smallest unit
├── maxPurchasable - Per-player purchase limit
├── expiration - Offer end timestamp
├── contents[] - Items included in purchase
│   ├── name, image, quantity
│   ├── bonusQuantity - Web store bonus amount
│   └── dropRate - For legal compliance
└── attributes
    ├── banner - Promotional banner text
    ├── badge - Corner badge (e.g., "NEW", "50% OFF")
    ├── background - Custom styling
    └── buyButton - CTA customization

Offer Chains

Progressive offers encourage repeat purchases:

OfferChainItem
└── links[]
    ├── status: CLAIMED (purchased)
    ├── status: UNLOCKED (available)
    └── status: LOCKED (requires previous)

Localization

All user-facing text supports localization:

{
  "defaultText": "Special Bundle",
  "localizationKey": "offer.special_bundle.title",
  "localizedText": "Offre Spéciale"
}

Choose between:

• localizationKey: Stash-side lookup in our localization system (requires sharing locKeys)
• localizedText: Pre-resolved server-side text

Integration Considerations

When to Use Each Endpoint

Caching Strategy

Error Handling

• Catalog API: Returns empty sections for unavailable content
• Purchase API: Uses inline status codes (always HTTP 200) for predictable error handling
• Player API: Returns 404 for unknown players

Platform & Region Pricing

Price Resolution

Prices can vary by platform and region. The API resolves the correct price based on:

Platform Values

Price ID vs Price Amount

When returning prices in the catalog, you have two options:

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