Skip to content

In-game store backend

Stores a designer opens for a time, each with its offers. An offer has a price (or none, for a gift), what the player gets, a sale window, a limit per player and period, and a stock all players buy from together. A store may rotate: show some of its offers and change them every day or week, the same for every player. Requires Inventory.

await rudder.stores.buy({ offer: 'gold-bag' });

Economy → Stores. One row per store, in the order the client shows them.

FieldMeaning
key, name, description, imageThe store.
windowWhen the store is open. An offer is on sale while both its store and its own window are open.
rotationnever (all offers), day or week: how often the shown offers change, from the day start of the project.
showHow many of its offers on sale the rotation shows, 0 for all.

A rotation picks the same offers for every player in a period. An offer whose window opens or closes changes one place of the pick, not the others.

On the page of a store, under Offers. An offer belongs to one store.

FieldMeaning
key, name, description, imageThe offer.
storeThe store it is sold in.
priceAn amount the player pays. Empty for a free offer, a gift.
oldPriceShown struck through next to the price. The player pays price.
currenciesAmounts of currencies the player gets.
itemsItems of the inventory the player gets, each with a count.
windowWhen the offer is on sale.
limitHow many times one player buys it in a period, 0 for no limit.
periodnever, day, week or month: how often the limit starts again.
stockHow many all players together buy, 0 for no stock.

The purchases of an offer are counted in every period at once, so a limit whose period a designer changes counts the purchases already made in the new period. A stock counts what was sold, not what is left: raising stock sells more at once. A sale that comes back with a fresh stock is a copy of the offer under a new key (Duplicate on its page).

FunctionKindCallerArgumentsResult
storesqueryclientnoneThe stores open now, each with offers
boughtqueryclientnoneThe offers the player bought, the last bought first
buymutationclient{offer}The offer with remaining and left after the purchase

stores returns the stores open now in their order. Each has its fields and offers: the offers on sale now that its rotation shows, in the order of the catalog. Each offer has its fields and:

  • remaining: how many more times the player may buy it in this period, null for no limit;
  • left: what is left of its stock, null for no stock.

bought returns each offer the player has bought with its offer key, name, image, lastBought, bought (how many times ever), limit ({done, of, name}: the purchases in the period of its limit against the limit, named ever, today, this week or this month), resetsAt (when the limit starts again) and stock ({done, of, name: "left"}: what is left of its stock against the stock); each is null where the offer has none.

buy checks that the offer is on sale and within the limit, pays the price, takes one from the stock, grants the currencies and the items, and emits purchased. If any step fails, the whole purchase is refused and nothing changed: a player short of the price, a sold out stock or an item that does not fit the inventory leaves the player with the gems it had.

CodeWhen
unknown_offerThere is no such offer.
not_on_saleThe offer, its store or its rotation does not show it now.
limit_reachedThe player bought it as many times as its limit allows in this period.
sold_outThe stock is sold out.
insufficientThe player is short of the price.
stack_full, unknown_itemAn item of the offer does not fit the inventory.
EventPayloadWhen
purchased{offer, store, price}After every purchase.

Anything else an offer gives (a premium pass, experience, a reward of your own module) is granted by your module: it requires stores, handles stores.purchased and names the offer in a catalog of its own.

  • Economy → Stores: the stores as cards. The page of a store lists its offers, adds one with New offer, and shows “Sold N of M” for each offer with a stock, in the environment chosen in the header.
  • Engagement → Calendar: store windows, offer windows, rotations and limit resets.
  • Player card, Overview: the offers the player bought, when last, the limit used, when it resets and the stock left.
  • No real-money offers: no store product ids, no receipt validation. Validate a receipt on your game server, then grant the items to the player.
  • No prices per player or segments, and no percent discounts.
  • A window does not repeat by itself; a repeat is a copy of the row.
  • The purchases of one offer with a stock all count against one shared number. An offer every player buys at the same second (a flash sale to the whole game) may answer some calls with 503 try_again, which the SDK sends again.