Dynamic Catalog
Learn how to create a REST API endpoint on your game backend for dynamic catalogs. Understand the request/response structure, data models, configuration steps, and debugging tools to deliver personalized, real-time catalogs to players.
To use dynamic catalogs, you need to create a REST API endpoint on your game backend. Stash calls this endpoint and sends the player ID, which you can use to determine what each player should see in the webshop.
There are no strict limits on your dynamic catalog payload; just follow the base format outlined below. You can add any metadata you need (e.g., item attributes). The dynamic catalog is fully customizable; contact our team if you need advanced features.
Catalog endpoint
Whenever a player visits your webshop, Stash sends a GET request to your game server to retrieve a player-specific catalog.
Request
Stash sends a GET request with the player's ID as a query parameter:
GET /your-catalog-endpoint?player_id={player_id}You can configure the endpoint URL and authentication methods in Stash Studio. The process is detailed in the configuration steps below.
Response
Your endpoint should return a JSON response with the following structure:
{
"rows": [
{
"id": "row-1",
"header": "Featured Items",
"items": [
{
"type": "product",
"guid": "battle_pass",
"product_id": "battle_pass",
"name": "Battle Pass",
"description": "Dominate the battlefield with powerful heroes and essential resources!",
"image": "https://example.com/images/battle_pass.png",
"price": {
"amount": "34.99",
"currency": "USD"
},
"max_purchasable": 1,
"contents": [
{
"name": "Potion",
"description": "A mysterious potion you can drink to get some abilities or health back.",
"image": "https://example.com/images/potion.png",
"quantity": 10
}
],
"attributes": {
"banner": {
"text": "New"
},
"badge": {
"text": "Battle Pass"
}
}
}
]
},
{
"id": "banner-row",
"header": "",
"items": [
{
"type": "banner",
"guid": "promo_banner",
"title": "Earn free coins with every purchase",
"body": "and unlock exclusive rewards only available on the web",
"attributes": {
"background": {
"imageUrl": "https://example.com/images/banner-bg.png"
}
}
}
]
}
]
}If the response is malformed or your endpoint returns an error code (such as 400), Stash Webshop displays a configurable error message to the player.
Data structure
This is the base payload structure. You can define the shop layout using rows and assign specific offers to each row. If you need to pass game-specific metadata, you can use the attributes field on each item. This object has no fixed structure, and you can include as much custom metadata as needed.
Stash can also customize this payload structure on a per-client basis using custom adapters. Contact us for more details.
Root Object
Prop
Type
Row Object
Prop
Type
Item Object (Product)
Prop
Type
Item Object (Banner)
Prop
Type
Price Object
Prop
Type
Content Object
Prop
Type
Attributes Object
The attributes object supports various visual enhancements:
Prop
Type
Attribute Examples
{
"attributes": {
"banner": { "text": "New" },
"badge": { "text": "Limited Time" },
"ribbon": { "text": "Web Exclusive" },
"tooltip": { "text": "This is a special offer" },
"background": { "imageUrl": "https://example.com/bg.png" }
}
}Configuration
To configure your dynamic catalog endpoint, follow these steps:
Navigate to game settings
In Stash Studio, navigate to your game settings.
Open Configuration
Go to Webshop → Configuration
Set endpoint URL
Set your catalog endpoint URL.
Configure authentication
Configure authentication if required.
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
How is this guide?