Offer Templates
Send template and slot names with each offer so rewards, buy buttons, and text land in the template slots meant for them.
When your offer templates name their slots, send the slot names with each offer, so each reward, each buy button and each piece of text lands in the slot meant for it. Without them, the web shop fills a template's slots by position: rewards in contents order, and text from the offer's fixed fields such as name. Position breaks when a template has more slots than the fixed fields, or when a new template version orders its slots differently.
All four fields are optional. A response without them stays valid: the web shop shows the offer in your shop's default template for its type and fills the slots by position.
| Field | Where | Value |
|---|---|---|
templateKey | A product, a pack, a free item or an info item. On a pack, set it on the pack; its items have no templateKey. | The template that shows the offer, including its version, for example starter-offer-v2. 1 to 128 characters. |
layoutKey | Each reward: an entry in contents of a product, a pack item, a free item or an info item, and an entry in items of a chain link | The reward slot this reward fills. 1 to 128 characters. |
buyButton.layoutKey | The buyButton in attributes of a product or of a pack item | The buy button slot this offer's or price point's buy button sits in. 1 to 128 characters. |
textSlots | A product, a pack, a pack item, a free item or an info item | An object that maps each text slot name to a LocalizableText, for example Title or RibbonText. Keys up to 128 characters, at most 50 entries. |
Agree your templates, their versions and their slot names with your Stash engineering partner. Stash compares every templateKey, layoutKey, buyButton.layoutKey and textSlots key exactly as sent: case-sensitive, untrimmed, and with no prefix matching. Title and title are different slots, and starter-offer-v2 and starter-offer-v3 are different templates.
{
"product": {
"productId": "starter_bundle",
"price": { "priceId": "starter_bundle_499" },
"name": { "defaultText": "Starter Bundle" },
"templateKey": "starter-offer-v2",
"textSlots": {
"Title": { "defaultText": "Spring Starter Bundle", "localizationKey": "offer.starter.title" },
"RibbonText": { "defaultText": "Best value", "localizationKey": "offer.ribbon.best_value" }
},
"contents": [
{ "name": { "defaultText": "Coins" }, "quantity": "5000", "layoutKey": "TopLeftReward" },
{ "name": { "defaultText": "Gems" }, "quantity": "50", "layoutKey": "BottomReward" }
]
}
}Here the offer shows in version 2 of the starter-offer template. Its Title slot shows "Spring Starter Bundle", not the name, and each reward fills the slot its layoutKey names.
Template choice
| Field | Ignored when |
|---|---|
templateKey | It is missing, empty, longer than 128 characters, or not one of your shop's templates. The offer shows in your shop's default template for its type. |
layoutKey | The template names no reward slots. |
buyButton.layoutKey | The template names no buy button slots. |
textSlots | The template names no text slots. |
Reward slots
A reward whose layoutKey | Result |
|---|---|
| Names a reward slot of the template | Shows in that slot. A slot shows every reward that names it, in contents order. |
| Is missing, or names no slot of the template | Still shows, where the template places rewards without a slot. |
| Is empty, or longer than 128 characters | Counts as no key, so it shows as in the row above. |
Rewards and slots that do not match up. Each template has room for a set number of rewards, in total and in each part of the card. An offer whose rewards do not fit is left out of the web shop and reported as ITEM_NOT_RENDERABLE in CATALOG_ITEMS_DROPPED. With fewer rewards than reward slots, the unfilled slots stay empty.
Buy button slots
A template can give each buy button a slot of its own, separate from the slots its rewards fill, for example one buy button slot per price point of a pack. Name it in the buy button's layoutKey, in attributes.buyButton of the product or the pack item.
- The label stays the price.
textis optional on a buy button. SendbuyButtonwith onlylayoutKeyto name the slot and keep the button's default label, the price. - Buy buttons only.
layoutKeyis read on a buy button. On an info button it is ignored. - Empty or long keys. An empty
layoutKey, or one longer than 128 characters, counts as no key. - Buttons without a matching slot. When a buy button has no
layoutKey, has one that names no buy button slot of the template, or names the same slot as another buy button of the offer, the template decides where that button sits. - Display only. The slot never changes what is bought, charged or sent to
ConfirmPayment.
Text slots
A text slot shows the first of these that has a value:
- Its
textSlotsvalue. - The fixed field the template fills that slot from, for example
namefor a title slot. Stash defines that field for each template.
A slot with no value in either place stays empty, with no placeholder text.
textSlots changes only the offer card. Checkout and receipts show the fixed fields, so always send name (title on an info item).
Slots on purchase packs
Set templateKey and textSlots on the pack, once for the whole offer. A price point (an item in the pack's items) can add its own textSlots:
- For a slot set on both, the price point's value is used for that price point. The pack's entries fill every other slot.
- A price point entry that is ignored, for example an empty text or a key over 128 characters, leaves the pack's entry for that slot.
- Of the combined entries, Stash keeps the first 50 by slot name in byte order.
A pack has no buy button of its own: each price point names its buy button slot in its own attributes.buyButton. Here each price point's rewards fill a Resources_* slot and its buy button sits in a SKU_* slot:
{
"pack": {
"id": "three_price_offer",
"templateKey": "three-price-offer-v1",
"items": [
{
"productId": "offer_tier_1",
"price": { "priceId": "offer_tier_1_499" },
"name": { "defaultText": "Small" },
"contents": [{ "name": { "defaultText": "Coins" }, "quantity": "1000", "layoutKey": "Resources_Left" }],
"attributes": { "buyButton": { "layoutKey": "SKU_Left" } }
},
{
"productId": "offer_tier_2",
"price": { "priceId": "offer_tier_2_999" },
"name": { "defaultText": "Medium" },
"contents": [{ "name": { "defaultText": "Coins" }, "quantity": "2500", "layoutKey": "Resources_Middle" }],
"attributes": { "buyButton": { "layoutKey": "SKU_Center" } }
},
{
"productId": "offer_tier_3",
"price": { "priceId": "offer_tier_3_1999" },
"name": { "defaultText": "Large" },
"contents": [{ "name": { "defaultText": "Coins" }, "quantity": "6000", "layoutKey": "Resources_Right" }],
"attributes": { "buyButton": { "layoutKey": "SKU_Right" } }
}
]
}
}These fields change only how the offer card shows the offer. What Stash sends to ConfirmPayment, and what your backend grants, do not change.
Slot names belong to a template version. When you move an offer to a new version in templateKey, send that version's slot names. A name the version does not have counts as no key: the reward still shows, where the template places rewards without a slot, and the text slot shows its fixed field.
How is this guide?

