Catalog ManagementReal-time Catalog

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 sendCatalog reads before a recorded claimCatalog reads after a recorded claim, until the item's refreshAt
AVAILABLEAVAILABLECLAIMED
CLAIMEDCLAIMEDCLAIMED
LOCKEDLOCKEDLOCKED

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 per claimId per response; additional items sharing one may be discarded. A locked preview of a later reward must carry a distinct claimId, or none at all.
  • Repeat claims. A repeat claim inside the same window returns an idempotent success: no duplicate FREE_ITEM_REDEEMED webhook, and no second Loyalty XP credit for gifts that grant XP.
  • Webhook payload. On FREE_ITEM_REDEEMED, itemId is the item that was granted. claimId is the claim it consumed, and appears only when it differs from itemId.

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.

Example 7-step daily streak: steps 1 to 3 claimed, step 4 available with a countdown to the next reset, steps 5 to 7 locked.

In the web shop, the player sees their current sequence only:

Example web shop with a daily streak: the player's current sequence (week 2), days 1 to 3 claimed, day 4 ready to claim, days 5 to 7 locked, and a countdown to the next gift.

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 streakOrder on 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 targetTierId and 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.

WhenStash
No item sets streakOrder and no section is agreed for your shopOnly 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 rulesHides 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 streakOrderHides the free items of each of them and reports them the same way.
The section agreed for your shop is missing from a responseShows 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's FREE_ITEM_REDEEMED webhook carries the itemId of the item the player claimed.
  • If you serve only the player's own tier (Stash sends it in the currentTierId query parameter of GetCatalog), send that tier's items.

Step status

Stash shows the player's current sequence only, and sets each step's status:

Stepstatus
Earlier stepsCLAIMED
The step that is dueAVAILABLE, then CLAIMED once taken
Later stepsLOCKED

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.

FieldEffect
rewardHiddenWhileLocked: trueWhile 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: trueA 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 contents and bonusItems as on any other step. The claim and its FREE_ITEM_REDEEMED webhook work as for any other step.
  • Keep itemId, guid and templateKey neutral. 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 itemId or guid, or claim as it (the same claimId, or the free offer it claims as). If one does, Stash hides the streak and reports its items in the CATALOG_ITEMS_DROPPED webhook with field "STREAK_HIDDEN_IDENTITY_SHARED".
  • Keep it out of offer details. Before the step's day, your GetOfferDetails endpoint 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 LOCKED again, 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. Send refreshAt on 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 claimingStarts again at
A step in the middle of a sequenceStep 1 of that sequence
The last step of a sequenceStep 1 of the next sequence
The last step of the last sequenceStep 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?

On this page