Operator shop

An operator shows gifts in its own shop or VIP area. A player redeems a gift, the shop places an order, and Luxorr delivers it.

Requires: a key with CATALOG and ORDERS, and a webhook URL.

1. Keep a catalog copy per country

For each delivery country, load the catalog once, then sync it every few minutes:

curl -s "$LUXORR_API/catalog/products?country=DE&locale=de-DE&limit=100" -H "Authorization: Bearer $LUXORR_KEY"
curl -s "$LUXORR_API/catalog/products?country=DE&locale=de-DE&updatedSince=2026-10-06T08:55:00Z&limit=100" -H "Authorization: Bearer $LUXORR_KEY"

• Send the same country and locale on the load and on the sync. locale is optional; an unsupported locale answers 400 with the supported list.
• Follow nextCursor until it is null. For the next sync, pass the newest updatedAt you hold, minus five minutes. See catalog sync.
• Show only gifts where listed and available are both true.
• estimate (your currency) and estimateEur are estimates, not prices. You may show points instead.
• Use images[].url directly. Image URLs need no key.

Campaign instead of the full catalog: read GET /campaigns/{campaignId}?locale=de-DE. Each offering has the gift name, images and stockRemaining, but no price.

2. Place the order on redemption

Use your redemption ID as externalOrderId and the player ID as externalRecipientId. Send the order from your server, with a new Idempotency-Key stored with the redemption.

{
  "externalOrderId": "SHOP-77120",
  "externalRecipientId": "player-77",
  "brandId": "0a6f2e1c-3b5d-4e7f-8a9b-0c1d2e3f4a5b",
  "items": [{ "productId": "9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "variations": { "Colour": "Black" } }],
  "client": { "name": "Wendy Player" },
  "recipient": {
    "name": "Wendy Player",
    "phone": "+4930123456",
    "address": { "street": "Unter den Linden 1", "city": "Berlin", "postalCode": "10117", "country": "DE" }
  }
}

• Deduct points only after 201.
• On a timeout, retry with the same Idempotency-Key and body. The response is the same order, never a second one.
• On out_of_stock or not_deliverable_to_country, no order was placed. Refresh the gift and let the player choose again.

3. Show the status

Listen for order.status_changed:

Status	Player sees
REQUESTED	Being confirmed
PROCESSING	Being prepared
SENT	On its way, with shipments[0].trackingUrl
COMPLETED	Delivered
CANCELLED	Cancelled; return the points

Reconcile from the event feed every few minutes.

4. Address corrections

While the order is PROCESSING, call POST /orders/{orderId}:update-delivery with the order version as expectedVersion and only the changed fields, for example {"recipient": {"phone": "+4930987654"}}. Fields you omit keep their values. The country cannot change; cancel and place a new order instead.

5. Exceptions

For a cancellation after dispatch or a damaged gift, post a message with POST /orders/{orderId}/messages. Replies arrive as order.message_posted.