Operator shop

In a rewards shop, players earn bonus coins in their player account and spend them on gifts. Your rewards store holds the gifts and their coin prices. Your site shows them, takes the player’s address, and places the order. Luxorr delivers the gift.

Requires: a key with the REWARD_STORES scope, and a webhook URL.

Find the store

Ask your team or your Luxorr contact to set up a rewards store for your brand, with its bonus currency and rate, and to select Rewards Stores on your key. To find the store’s ID, call GET /reward-stores?brandId=…, and then store the ID.

Show the shop

When a player opens the shop, read the store for the player’s brand and country, in the player’s language:

GET /v1/reward-stores/4b3a2918-0716-4f5e-8d4c-3b2a19080716?brandId=0a6f2e1c-3b5d-4e7f-8a9b-0c1d2e3f4a5b&country=DE&locale=de-DE

Show its sections and gifts, each with its coinPrice and the store’s currency.symbol. For a gift with options, offer only the combinations it lists. Read the store again on each visit, because prices can change.

Take the order

Your form asks for the delivery address. Use the store’s country as the address country, or read the store again for the country that the player enters.

POST /v1/reward-store-orders
Idempotency-Key: shop-order-58213

{
  "storeId": "4b3a2918-0716-4f5e-8d4c-3b2a19080716",
  "brandId": "0a6f2e1c-3b5d-4e7f-8a9b-0c1d2e3f4a5b",
  "productId": "2f1e0d9c-8b7a-4695-a483-72615f4e3d2c",
  "variations": { "Size": "L", "Color": "Black" },
  "coinPrice": "450",
  "locale": "de-DE",
  "recipient": {
    "name": "Wendy Player",
    "phone": "+4915112345678",
    "address": { "street": "Beispielstraße 12", "city": "Berlin", "postalCode": "10115", "country": "DE" }
  },
  "customFields": [
    { "fieldId": "5c4b3a29-1807-4f6e-8d5c-4b3a29180746", "textValue": "player-77" }
  ]
}

The following table shows what your shop does with each response:

Response	Your shop
201	Deduct coinPrice from the player’s balance, and store the order id.
409 price_changed	Show the current coinPrice from the response, and ask the player to confirm.
422 gift_not_available, 409 out_of_stock	Tell the player that the gift isn’t available, and read the store again.
422 reward_store_not_live	Show that the shop is closed.
400 invalid_request	Show the fields that errors[] names.
Timeout or 5xx	Retry with the same Idempotency-Key and body. Deduct when the 201 arrives.

If the API refuses the order, deduct nothing, because no order was created. If approval is required, the order stays REQUESTED until your team approves it. Send the player’s locale, because Luxorr writes the player’s status emails and the order’s productName in it.

Follow the gift

The following table shows what your shop does with each event:

Event	Your shop
order.approved	Show the gift as being prepared.
order.cancelled	Refund coinPrice to the player, once per orderId.
order.sent	Show the tracking from shipment.
order.completed	Show the gift as delivered.

Refund on order.cancelled only, and never twice for one order: store the refunded order IDs and the processed event ids. Reconcile from the event feed every few minutes. Your key receives the events of the orders it placed, and no others.

To show the player’s order history, read GET /reward-store-orders/{orderId} for the orders you stored. Your key reads only the orders it placed. Orders never return the address, so match them to the player by the order id or your player ID field.

You can’t cancel a store order through the API. To cancel one, ask your team. You then receive order.cancelled and refund the coins.

For every field and error, see Rewards stores.