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' });Catalog: Stores
Section titled “Catalog: Stores”Economy → Stores. One row per store, in the order the client shows them.
| Field | Meaning |
|---|---|
key, name, description, image | The store. |
window | When the store is open. An offer is on sale while both its store and its own window are open. |
rotation | never (all offers), day or week: how often the shown offers change, from the day start of the project. |
show | How 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.
Catalog: Offers
Section titled “Catalog: Offers”On the page of a store, under Offers. An offer belongs to one store.
| Field | Meaning |
|---|---|
key, name, description, image | The offer. |
store | The store it is sold in. |
price | An amount the player pays. Empty for a free offer, a gift. |
oldPrice | Shown struck through next to the price. The player pays price. |
currencies | Amounts of currencies the player gets. |
items | Items of the inventory the player gets, each with a count. |
window | When the offer is on sale. |
limit | How many times one player buys it in a period, 0 for no limit. |
period | never, day, week or month: how often the limit starts again. |
stock | How 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).
Functions
Section titled “Functions”| Function | Kind | Caller | Arguments | Result |
|---|---|---|---|---|
stores | query | client | none | The stores open now, each with offers |
bought | query | client | none | The offers the player bought, the last bought first |
buy | mutation | client | {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,nullfor no limit;left: what is left of its stock,nullfor 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.
Errors
Section titled “Errors”| Code | When |
|---|---|
unknown_offer | There is no such offer. |
not_on_sale | The offer, its store or its rotation does not show it now. |
limit_reached | The player bought it as many times as its limit allows in this period. |
sold_out | The stock is sold out. |
insufficient | The player is short of the price. |
stack_full, unknown_item | An item of the offer does not fit the inventory. |
Events
Section titled “Events”| Event | Payload | When |
|---|---|---|
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.
In the Dashboard
Section titled “In the Dashboard”- 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.
Limits
Section titled “Limits”- 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.