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 passes a player ID to you, which determines what to show individual players in the webshop.
There are no strict limits on your dynamic catalog payload—just follow the base format detailed below. Add any metadata you need (e.g., item attributes). Stash's dynamic catalog is fully customizable; contact our team if you need advanced features.
Catalog endpoint
Whenever a player visits your webshop, Stash will send 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 step 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 error code (such as 400) Stash webshop will display an configurable error message to the player.
Data structure
This is a base payload structure, you can define the shop's whole layout using rows and assing specific offers to each row. If any game-specific metadata needs to be passed you can leverage attributes field for each item. This object have no set structure and you can pass as much custom medata as needed to be displayed on your webshop.
Stash can also completly customize this payload structure on client-basis using our custom adapters, please 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:
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's performance and troubleshoot any 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?