Free Items and Streaks
How Stash tracks claims of free items in a Real-time Catalog response, and how streaks tracked by Stash work.
A FreeItem is claimable at no cost. When a player claims one, Stash records the redemption and emits a FREE_ITEM_REDEEMED webhook. Two fields govern how claims are tracked: status and claimId.
Claim status
Your response is authoritative for whether the gift is offered: send status as AVAILABLE, CLAIMED or LOCKED. After a recorded claim, Stash overrides AVAILABLE to CLAIMED on catalog reads, so a reload cannot show a consumed gift as claimable. Outside a streak tracked by Stash, that one flip is the only change Stash makes:
| You send | Catalog reads before a recorded claim | Catalog reads after a recorded claim, until the item's refreshAt |
|---|---|---|
AVAILABLE | AVAILABLE | CLAIMED |
CLAIMED | CLAIMED | CLAIMED |
LOCKED | LOCKED | LOCKED |
Stash never produces AVAILABLE. The override ends at the item's refreshAt; from then on your status alone decides the next period.
For items in a streak tracked by Stash, Stash sets AVAILABLE, CLAIMED and LOCKED itself from the player's streak, and ignores the status you send, including when you omit it.
Claim identity
claimId is optional: a stable claim identity, separate from itemId. Free items that share a claimId are the same claim for a claim period: claiming any one of them consumes the claim for all of them. When absent, itemId is the claim identity, so integrations that do not send claimId change nothing.
Use claimId when the item you serve varies per player, for example a daily gift whose itemId differs by loyalty tier. Keep the claimId stable across the variants, and the claim still de-duplicates as one gift per period, whichever variant a player sees.
- One item per
claimId. Return at most one item perclaimIdper response; additional items sharing one may be discarded. A locked preview of a later reward must carry a distinctclaimId, or none at all. - Repeat claims. A repeat claim inside the same window returns an idempotent success: no duplicate
FREE_ITEM_REDEEMEDwebhook, and no second Loyalty XP credit for gifts that grant XP. - Webhook payload. On
FREE_ITEM_REDEEMED,itemIdis the item that was granted.claimIdis the claim it consumed, and appears only when it differs fromitemId.
A free item's refreshAt also ends Stash's cached copy of your catalog at that time, so the next request for the player's catalog after the reset reads your new response. If a free item first appears at a set time that no item, section or trigger in the current response carries, send that time in catalog.refreshAt. See Caching.
Streaks tracked by Stash
A streak is a run of free items that a player claims one per period, such as a daily gift calendar. For a shop where Stash turns on a streak, Stash tracks each player's progress and decides which item is claimable. A shop has 1 such streak. You supply the rewards.
In the web shop, the player sees their current sequence only:
Send the streak in GetCatalog
Put every step in one section
Put all the streak's items in one catalog section as free items: one item per step (or one per tier, see the last step), for every sequence, with the rewards for this player.
Give each item its own itemId, and do not share a claimId between items. Stash keys the streak's claims itself, so the per-variant claimId pattern in Claim identity does not apply.
Number the steps with streakOrder
Start at 1 and continue across sequences: with 7-step sequences, step 1 of the second sequence is 8.
- Set
streakOrderon every free item in the section, or on none. - Set it whenever any item in the section sets
targetTierId. - When no item sets it, Stash numbers the free items that apply to the player (those without
targetTierIdand those for the player's current tier) in the order they appear in the section agreed for your shop or, if none is agreed, in the first section of your catalog that contains only free items.
Keep the layout whole
The numbers run from 1 with no gaps, and they cover a whole number of sequences. The sequence length is set for your shop (7 unless agreed otherwise). Set streakOrder in 1 section only.
| When | Stash |
|---|---|
No item sets streakOrder and no section is agreed for your shop | Only infers the section. A section that breaks these rules is shown as you sent it, with your own status values, and Stash tracks no streak in it. |
| Otherwise, the section's items break these rules | Hides the streak's free items and reports each one in CATALOG_ITEMS_DROPPED, with reason STREAK_LAYOUT_INVALID and a field naming the rule broken. |
More than 1 section sets streakOrder | Hides the free items of each of them and reports them the same way. |
| The section agreed for your shop is missing from a response | Shows no streak for that response. |
Vary rewards by loyalty tier (optional)
For a step whose reward depends on the player's tier, send one item per tier with the same streakOrder and that tier's targetTierId. Optionally, add one item without targetTierId for players with no matching tier.
- Each number has at most one item per tier and one without
targetTierId. - Stash shows the player only the item for their current tier, or else the one without
targetTierId. The claim'sFREE_ITEM_REDEEMEDwebhook carries theitemIdof the item the player claimed. - If you serve only the player's own tier (Stash sends it in the
currentTierIdquery parameter ofGetCatalog), send that tier's items.
Step status
Stash shows the player's current sequence only, and sets each step's status:
| Step | status |
|---|---|
| Earlier steps | CLAIMED |
| The step that is due | AVAILABLE, then CLAIMED once taken |
| Later steps | LOCKED |
Stash also sets maxClaimable: 1 on the step that can be claimed, 0 on every other step. You do not need to send status or maxClaimable on these items; if you do, Stash ignores them, whatever the values. Players who are not signed in do not see the streak's items.
Hidden and highlighted steps (optional)
Two optional booleans on a free item: one keeps a streak step's reward hidden until its day, the other is a display hint. They are independent: send either, both or neither. See GetCatalog for the fields.
| Field | Effect |
|---|---|
rewardHiddenWhileLocked: true | While the step is LOCKED, Stash leaves its name, its contents, the bonus reward from its bonusItems, its textSlots, and the background and infoButton of its attributes out of everything it sends to the player's browser. The step still shows in its place in the streak. Once the step is AVAILABLE or CLAIMED, Stash sends them all. |
featured: true | A display hint: the web shop may show the item prominently, with your shop's featured look, whatever its status. It changes nothing about the claim. |
On a hidden step:
- Send the real reward. Put the step's reward in
contentsandbonusItemsas on any other step. The claim and itsFREE_ITEM_REDEEMEDwebhook work as for any other step. - Keep
itemId,guidandtemplateKeyneutral. Stash always sends all three, so none may name the reward. - Keep its identities unique. No other item in the catalog, of any kind (a free item, a purchasable, an offer chain link or a purchase pack item), may use a hidden step's
itemIdorguid, or claim as it (the sameclaimId, or the free offer it claims as). If one does, Stash hides the streak and reports its items in theCATALOG_ITEMS_DROPPEDwebhook withfield"STREAK_HIDDEN_IDENTITY_SHARED". - Keep it out of offer details. Before the step's day, your
GetOfferDetailsendpoint must not return its reward: Stash passes an offer details request on to you for any item, hidden or not. - It stays hidden when progress is unknown. If Stash cannot read the player's progress, every step is
LOCKED, so a hidden step stays hidden. - Claimed steps hide again after a reset. After a missed period sends the player back to step 1, the steps they claimed earlier are
LOCKEDagain, and a hidden one is hidden again.
Stash applies rewardHiddenWhileLocked only to the items of a streak it tracks for your shop. If that streak's layout is invalid, a hidden step stays hidden and cannot be claimed until the layout is fixed. On any other free item, the item is shown as you sent it.
Periods and resets
- Period. A period is a day or a week, starting at a time of day in a time zone agreed for your shop (00:00 UTC unless agreed otherwise). Weekly periods start on Monday. In a time zone with daylight saving, the reset follows local time.
refreshAt. SendrefreshAton each item, set to the next reset. Stash uses it as the end of the current period and shows a countdown to it. When it is missing, already past, or more than one period ahead, Stash uses the reset agreed for your shop instead.- Your own checks. Send the same time in
refreshAt, and use it for any once-per-period check on your side.
Claims and missed periods
The streak advances only on a claim. A player can claim one step per period, and only the step that is due. Claiming the last step of a sequence moves the player to the next sequence, and claiming the last step of the last sequence wraps the streak to step 1.
A missed period sends the player back to step 1 of the sequence they are in, the one holding the step that was due. A period in which the streak is turned off or its items are missing counts as missed.
| A player who misses a period after claiming | Starts again at |
|---|---|
| A step in the middle of a sequence | Step 1 of that sequence |
| The last step of a sequence | Step 1 of the next sequence |
| The last step of the last sequence | Step 1 |
Granting the reward
Grant the reward when you receive the claim's FREE_ITEM_REDEEMED webhook.
Stash records a claim only once its webhook is queued, so a streak needs an enabled webhook endpoint for your shop. Without one, every claim fails and nothing is recorded.
If a claim fails after its webhook was queued, the player's retry in the same period is the same redemption: its webhook carries the same redemptionId as long as the period's refreshAt has not changed, so de-duplicate on it.
Edge cases
How is this guide?

