In-game store: storefronts, offers and prices

What the player sees

• Storefronts as tabs. The first section of a storefront is a carousel, the rest are grids of cards.
• A free daily gift that shines until it is claimed.
• Timers on the cards: "refreshes in", "opens in", "sold out".
• A purchase confirmation popup (a bottom sheet on phones).
• The "You got" animation: rewards fly to the balance counters.
• A badge on the store tab when a free offer is waiting.

How the store is built

The store is a tree: storefront → sections → slots → offer.

• Offer - what is sold: price, rewards, limits, ribbons ("best value", "x2"). Offers live in one catalogue.
• Slot - a place on the storefront shelf. An offer can be bought only through a slot: an offer that stands in no slot is not sold at all.
• Rotation: a slot can show an offer from a pool and change it on a schedule, like a daily shop. The server computes the rotation, so a player sees the same store on every device.

Prices

You can show a struck-through "old" price, and the server computes the discount percent. One offer can have several price options, for example coins or gems.

Purchase limits

• Lifetime - for example, a starter pack once.
• Per day - resets at midnight UTC.
• Cooldown - the next purchase after a set time.
• Per rotation window - the slot's limit while this offer stands on the shelf.

The server computes the "first purchase" and "sold out" badges and the timers for each player.

For developers

The store works through client.store in @idosgames/core. Draw the screen from getStorefront(): the storefront already resolved for this player (rotation, limits, timers). getDefinitions() is only the config, the same for everyone.

const res = await client.store.getStorefront()
if (!res.ok) return showError(res.error)

for (const store of res.data.Stores ?? [])
  for (const section of store.Sections ?? [])
    for (const slot of section.Slots ?? []) {
      // An empty slot arrives with Offer === null: draw an empty frame so the shelf does not jump.
      if (!slot.Offer) continue
      drawCard(slot.Offer, slot.RefreshesAtUtc)
    }

const buy = await client.store.purchase(offer.OfferID, 1, {
  selectedOptionID: option.OptionID,
  slot: { storeID: store.StoreID, sectionID: section.SectionID, slotID: slot.SlotID },
})

• If a purchase returns OFFER_NOT_IN_ROTATION, the storefront has changed: reload it without showing an error.
• Disable the "Buy" button while the request is in flight: every purchase call is a separate purchase.
• Count timers down from ServerTimeUtc in the response, not from the device clock.
• null in a remaining limit means "no limit", 0 means "sold out".

Every field is described in the store-system skill, served by the SDK MCP server.