Server-side personalized store and ordering

What's new

The S2S API can now build a player's store and charge the offers in it without going through the Game Hub. Three pieces make it work.

PUT /v1/players/{player_id} registers the player or updates them, and sets the pricing context of their store. country is required. platform is optional and overwrites the platform of the previous upsert. The rest of the body carries the profile fields: name, avatar_url, email, attributes, custom_attributes, and a user_agent used only to derive the device type that promotions are targeted by.

GET /v1/players/{player_id}/store_items returns the store built for that player, the same way the Game Hub builds it. Store promotions, segments, campaigns and the player's own purchase history are all applied, so each offer carries price, price_after_discount, discount_percent, quantity_after_bonus, bonus_percent, the purchase limits (max_purchases, purchases_left, next_purchase_at), an expires_at, and the nested_items of a bundle or a lootbox. Prices come from the country and the platform set by the upsert, so the endpoint takes no pricing parameters of its own.

POST /v1/orders accepts those offers directly. An order item takes a store_item_id, the id of an offer from the store response, which charges the price, discount and bonus the player saw. sku is now optional when store_item_id names the item. An optional expected_price lets you send the price you displayed so that Aghanim can detect a mismatch; the order is still created at the price Aghanim calculates. The create response also returns the currency and the amount the player pays, both required.

Impact

A game server can read a player's offers and order them at prices that match what the Game Hub would have shown, instead of rebuilding promotion, segment and purchase-limit logic on its own side. Returning currency and amount from the create call means the charged price is known at order time, without a follow-up read of the order.

Changes

Resource	Change
upsert_player	New PUT /v1/players/{player_id} endpoint. Registers or updates the player and sets the country and platform their store is priced with. Takes the new PlayerUpsert schema, where only country is required, and returns PlayerRead
get_player_store_items	New GET /v1/players/{player_id}/store_items endpoint, returning the player's personalized offers as a list of the new PlayerStoreItem schema
create_order	Added optional store_item_id and expected_price to order items, and made sku optional. The order item schema no longer requires any field
create_order	Added required currency and amount to the response, naming the currency of the order and the amount the player pays in minor currency units
Components	Added the PlayerUpsert, PlayerStoreItem, and PlayerStoreNestedItem schemas

Upgrade

• Nothing to change for existing callers. sku still works on create_order, and everything else here is an addition.
• To price orders the way the Game Hub does, call upsert_player with the player's country and platform before reading their store for the first time, and again whenever the player changes country or device.
• Pass items[].store_item_id from get_player_store_items rather than sku to charge the offer the player was shown.
• Order items no longer require sku at the schema level, so send either sku or store_item_id. An item with neither names no product.

Need help?
Contact our integration team at [email protected]