{"endpoint":"/api/mcp","transport":"streamable-http","authentication":"Bearer token (tpp_live_* / tpp_test_*) — the same per-sub-brand API key as /api/v1/*, forwarded verbatim.","tool_count":57,"tools":[{"name":"adjust_customer_coins","title":"Adjust a customer's coin balance","description":"Adjust a customer's coin balance\n\nCredits (positive `delta`) or debits (negative `delta`) the\ncustomer's virtual-coin wallet. Adjustments on one wallet are\nserialised, so concurrent debits can never take the balance below\nzero.\n\nUse it to debit the coins a redemption costs: `POST /orders` does\nnot move coins.\n\n**Idempotency-Key is required.** A retry with the same key and body\nreturns the original response with `Idempotent-Replay: true` (the\nbalance from the original execution, NOT a fresh read). The same\nkey with a different body, or while the first request is still\nrunning, returns 409 `idempotency_conflict`.\n\nConstraints:\n- `delta` is a signed integer, non-zero, `|delta| <= 1_000_000`.\n- A debit larger than the balance returns 409 `conflict` with\n  `error.field_errors.reason: [\"insufficient_balance\"]`; a credit\n  that would overflow the wallet returns 409 with\n  `reason: [\"balance_overflow\"]`. Nothing is applied in either case.\n\nRequires API key scope: customers:coins.","method":"POST","path":"/api/v1/customers/{id}/coins","scopes":["customers:coins"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"delta":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reason":{"type":"string","maxLength":500},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["id","delta"]}},{"name":"apply_store_template","title":"Apply a template to a storefront's draft","description":"Apply a template to a storefront's draft\n\nReplaces the draft's theme and sections with a template (ids from `GET /api/v1/store-capabilities`). `keep_theme: true` keeps the current colours, fonts and logo. The store logo is always kept. Requires `Idempotency-Key`.\n\nRequires API key scope: stores:update.","method":"POST","path":"/api/v1/stores/{id}/draft/template","scopes":["stores:update"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"template_id":{"type":"string","enum":["clean","luxury","atelier","noir","nocturne","bloom","pulse","streetwear","botanica","vegas","arcade","kickoff","podium","slot","partners-club","betplay"]},"keep_theme":{"description":"Keep the current colours/fonts/logo and only take the template's sections. Default false.","type":"boolean"},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["id","template_id"]}},{"name":"bulk_adjust_customer_coins","title":"Bulk-adjust coins over a customer segment","description":"Bulk-adjust coins over a customer segment\n\nCredits (positive `delta`) or debits (negative `delta`) the coin\nwallet of every customer matching `filter`, scoped to the calling\nkey's sub-brand.\n\nThe filter targets almost any customer attribute: `status`,\n`segment_id`, `country`, registration/creation date windows\n(`created_after`/`before`, `registered_after`/`before`), coin\nbalance range (`min_coins`/`max_coins`) and lifetime order count\n(`min_orders`/`max_orders`), plus free-text `q`.\n\n**Idempotency-Key is required.** The whole batch is one\ntransaction: it applies completely or not at all, so a retry after\na failure re-applies cleanly, and a retry after a success replays\nthe original response (`Idempotent-Replay: true`) without crediting\ntwice.\n\nConstraints:\n- A non-empty filter is required (no accidental credit-everyone).\n- A match set larger than 1000 is rejected — narrow the filter.\n- Debits that would push a wallet negative are skipped and listed\n  in `skipped`.\n- Send `dry_run: true` to preview `matched_count` + a `sample`\n  before committing.\n\nRequires API key scope: customers:coins.","method":"POST","path":"/api/v1/customers/bulk/coins","scopes":["customers:coins"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"filter":{"type":"object","properties":{"q":{"type":"string","minLength":1,"maxLength":120},"status":{"type":"string","enum":["active","watch","restricted","banned"]},"segment_id":{"type":"string","minLength":1,"maxLength":36},"country":{"type":"string","minLength":2,"maxLength":2},"created_after":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"created_before":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"registered_after":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"registered_before":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"min_coins":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max_coins":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"min_orders":{"type":"integer","minimum":0,"maximum":9007199254740991},"max_orders":{"type":"integer","minimum":0,"maximum":9007199254740991}}},"delta":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reason":{"type":"string","maxLength":500},"dry_run":{"default":false,"type":"boolean"},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["filter","delta"]}},{"name":"buy_raffle_tickets","title":"Buy raffle tickets","description":"Buy raffle tickets\n\nBuys tickets for a customer of the calling sub-brand. Same\nsettlement as the storefront: a points store debits the customer's\ncoin wallet, an off-price store sells free raffles only, and a paid\ncard or order-only store is rejected until card capture exists.\n\nThis does not create an order and does not bill the brand. The\nprize, if the customer later wins and claims it, becomes an order\non its own.\n\n**Idempotency-Key is required.** Replay the same key and body to\nread the receipt again; a different body with the same key is\n`409`. The receipt is stored in the same transaction as the charge,\nso within the 24-hour replay window a `201` is final: retrying with\nthe same key never buys twice. Past it, the key is free again.\n\nThe raffle's store, price, sales window and per-customer cap are\nread on the server and checked again under a lock, so parallel\ncalls cannot oversell or exceed the cap. A customer of another\nsub-brand, or a raffle that is not yours, is `404`.\n\nA refusal is `409 conflict` with a machine-readable `error.reason`:\n\n| `error.reason` | Meaning |\n|---|---|\n| `sales_closed` | Not `scheduled`, or outside the sales window. |\n| `purchase_disabled` | The raffle only gives tickets away. |\n| `sold_out` | Fewer tickets left than asked. |\n| `per_customer_limit` | Over `max_tickets_per_customer`. |\n| `insufficient_points` | Points store; the wallet cannot cover it. |\n| `payment_capture_unavailable` | The store's rail cannot collect the price: a paid `card` / `order_only` store, or a priced raffle on an `off_price` store. |\n| `external_wallet_unsupported` | Points store whose balances live in the partner's wallet. |\n| `limit_reached` | A store limit for this customer is spent. |\n| `store_inactive` | The raffle's store is not active. |\n| `customer_blocked` | The customer is restricted or banned. |\n| `not_available_to_customer` | Store rules hide the raffle from this customer. |\n\nNothing is charged and no ticket is issued on any refusal. New\nvalues may be added; treat an unknown one as a generic refusal.\n\nRequires API key scope: raffles:tickets.","method":"POST","path":"/api/v1/raffles/{id}/tickets","scopes":["raffles:tickets"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"customer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Customer who receives the tickets. Must belong to the calling sub-brand."},"quantity":{"description":"Tickets to buy at the unit price. Required unless `package_index` is set, and ignored when it is.","type":"integer","minimum":1,"maximum":1000},"package_index":{"description":"Buy the bundle at this index in the raffle's `packages`. Quantity and price are taken from the raffle, not from this body.","type":"integer","minimum":0,"maximum":9007199254740991},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["id","customer_id"]}},{"name":"buyback_order","title":"Sell an unshipped order back for points","description":"Sell an unshipped order back for points\n\nCancels the order and credits the paying customer's wallet with the\nbrand's buyback share of the points they paid, atomically (the\nbrand's billing balance and the `order.status_changed` webhook\nsettle as for a cancel).\n\nBoth expected_points and expected_rate_bps from the accepted GET quote are required. A changed offer requires fresh customer consent.\n**Idempotency-Key is required.** The same key replays the original\nbody unchanged with `Idempotent-Replay: true`. Calling with a new key\nafter buyback returns `replayed: true`; neither replay moves points.\n\nNot eligible → 409 `conflict` with `error.field_errors.reason[0]` (same values\nas `GET /orders/{id}/buyback`, or `provider_cancel_blocked` when a\nprovider line cannot be cancelled at the provider yet, with\n`error.field_errors.blocked_item_ids`; nothing is credited). Scope: `orders:delete`.\nFor stale consent: `{\"error\":{\"code\":\"conflict\",\"message\":\"Order is not eligible for buyback\",\"field_errors\":{\"reason\":[\"offer_changed\"]},\"request_id\":\"req_6f1c2a9e0b7d4c3fa8e5d2b1c0a9f8e7\"}}`.\nA billing settlement conflict puts its code in `error.field_errors.billing_reason[0]`.\n\nRequires API key scope: orders:delete.","method":"POST","path":"/api/v1/orders/{id}/buyback","scopes":["orders:delete"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"expected_points":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647,"description":"Points offered by the quote the customer accepted; a changed offer returns 409 conflict with error.field_errors.reason: [offer_changed]."},"expected_rate_bps":{"type":"integer","minimum":1,"maximum":10000,"description":"Rate in the accepted quote; a changed rate returns 409 conflict with error.field_errors.reason: [offer_changed]."},"terms_accepted":{"type":"boolean","const":true,"description":"Attests the customer saw the offer and accepted the buyback terms in your UI (the order is cancelled and will not ship; the credit is final)."},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["id","expected_points","expected_rate_bps","terms_accepted"]}},{"name":"cancel_order","title":"Cancel an order","description":"Cancel an order\n\nTransitions the order to `cancelled`. Only valid while the\norder is in `pending` or `processing` — later states return 409\n`conflict` with `error.field_errors.reason: [\"not_cancellable\"]`\nand `error.field_errors.current_status`. When the order's billing\ncan no longer be changed (e.g. its monthly batch is already\ninvoiced), the 409 carries `error.field_errors.billing_reason`\ninstead.\n\nLines fulfilled by a provider are cancelled at the provider first.\nWhen a line cannot be cancelled there yet (already packed, provider\nunreachable, outcome unknown), the order stays active, nothing is\nrefunded and the call returns 409 `conflict` with\n`error.field_errors.reason: [\"provider_cancel_blocked\"]` and\n`error.field_errors.blocked_item_ids` (the blocked lines' item ids).\nRetry later or contact TPP support.\n\nCancellation atomically releases or refunds the brand's billing\nbalance and restores any storefront points the player paid for the\norder. Concurrent requests cannot apply the compensation twice.\nNo `Idempotency-Key` is needed (it is ignored): cancelling an\nalready-cancelled order is a 409, never a second refund.\n\nRequires API key scope: orders:delete.","method":"DELETE","path":"/api/v1/orders/{id}","scopes":["orders:delete"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"confirm_store_media_upload","title":"Confirm an image upload","description":"Confirm an image upload\n\nReturns the public URL and dimensions of an image uploaded through `prepareStoreMediaUpload` (same `sha256` and `store_id`). 404 when the bytes were never PUT. Idempotent: re-uploading identical bytes yields the same URL.\n\nRequires API key scope: media:create.","method":"POST","path":"/api/v1/media/uploads/confirm","scopes":["media:create"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"store_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["sha256"]}},{"name":"create_customer","title":"Create a customer","description":"Create a customer\n\nCreates a customer in the calling key's sub-brand.\n\nOnly an identity is required: send `first_name` + `last_name`, or\njust `external_id` when you hold no personal data (otherwise 400\nwith `field_errors.external_id`). A customer created with only an\n`external_id` returns `first_name` / `last_name` as `null` until the\nplayer submits the hosted shipping form, which fills the empty\nnames from the recipient name. When the store copies the address\nto the customer (the default), the form also writes the address and\nfills an empty `email` / `phone`; names, email and phone you sent\nare never overwritten.\n\nIf `external_id` is already used by a customer of this sub-brand,\nreturns 409 `conflict`.\n\n**Idempotency-Key is required.** A retry with the same key and\nbody returns the original response with `Idempotent-Replay: true`;\nthe same key with a different body, or while the first request is\nstill running, returns 409 `idempotency_conflict`.\n\nRequires API key scope: customers:create.","method":"POST","path":"/api/v1/customers","scopes":["customers:create"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"external_id":{"description":"Caller-supplied identifier (typically your platform's player id). Unique per sub-brand — duplicates return 409 conflict. Required when `first_name` or `last_name` is omitted.","anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"segment_id":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}]},"first_name":{"description":"Given name. Optional when `external_id` is sent: the hosted shipping form fills it from the recipient name.","anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"last_name":{"description":"Family name. Optional when `external_id` is sent: the hosted shipping form fills it from the recipient name.","anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"nickname":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"email":{"anyOf":[{"type":"string","maxLength":255,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"address_line":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}]},"apartment":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"zone":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"locality":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"city":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"state":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"country":{"description":"ISO 3166-1 alpha-2 (`es`, `ES`). Stored and returned lowercase.","anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$"},{"type":"null"}]},"preferred_lang":{"anyOf":[{"type":"string","enum":["en","es","pt","it","fr"]},{"type":"null"}]},"platform_registered_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"status":{"type":"string","enum":["active","watch","restricted","banned"]},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}}}},{"name":"create_embed_session","title":"Create a standalone-games hand-off","description":"Create a standalone-games hand-off\n\nMints a short-lived, single-use hand-off token that logs the given\nplayer into the sub-brand's standalone (embed) games. Resolve order:\n`external_id` then `email`, scoped to the calling key's sub-brand.\nUnknown players are created just-in-time (names and email are used\nonly then).\n\nCall it from your backend, never from the browser. Your page loads\nthe TPP loader (`https://app.thepowerplugin.com/embed/v1/loader.js`,\n`TPPGames.init({ subBrand, getSessionToken })`); `getSessionToken`\nasks your backend for a token and the loader delivers it to the\ngame iframe — there is no URL to open. The token is single use and\nvalid until `expires_at` (`ttl_seconds`, 60–900, default 300); the\nexchange signs the player in to the games for 8 hours. Mint a fresh\ntoken per request. `Idempotency-Key` is ignored.\n\nReturns 404 when embedded games are not enabled for the sub-brand.\n\nRequires API key scope: embed_sessions:create.","method":"POST","path":"/api/v1/embed-sessions","scopes":["embed_sessions:create"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":120,"description":"The operator's identifier for the player, matched against the customer's `external_id` within the sub-brand; the customer is created just-in-time if unknown."},"first_name":{"description":"Used only when JIT-creating the customer.","anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"last_name":{"description":"Used only when JIT-creating the customer.","anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"email":{"description":"Fallback lookup key + used when JIT-creating.","anyOf":[{"type":"string","maxLength":255,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"ttl_seconds":{"description":"Hand-off token lifetime in seconds, 60–900; default 300. A value outside the range is a 400 (not clamped).","type":"integer","minimum":60,"maximum":900}},"required":["external_id"]}},{"name":"create_game","title":"Create a demo arcade game","description":"Create a demo arcade game\n\nCreates a `draft` plinko, tower, mines or deal game on a store of this sub-brand from a preset balanced to at most 90 % RTP, with your colours, logos and images. Pass `prizes` (catalogue products from `search_products`) to put physical prizes in the game: they are resolved server-side to a listing the store can award (`invalid_request` with `prizes.N.product_id` otherwise) and the coin side is rebalanced around them; omit `price_cents` to get the lowest stake they allow. Creation writes no orders or coin movements. The type's feature flag must be enabled for the sub-brand (`forbidden` otherwise). Players can stake only on `points` stores; see `warnings`. Requires `Idempotency-Key`.\n\nRequires API key scope: games:create.","method":"POST","path":"/api/v1/games","scopes":["games:create"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"store_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["plinko","tower","mines","deal"]},"name":{"type":"string","minLength":2,"maxLength":200},"slug":{"type":"string","maxLength":80},"subtitle":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":5000},"price_cents":{"description":"Stake per play. Default 200 (mines 500); with `prizes`, omit it to get the lowest stake the prizes allow at 90 % RTP. An explicit stake that cannot carry the prizes is refused with the minimum in the message.","type":"integer","minimum":100,"maximum":100000},"prizes":{"description":"Physical catalogue prizes (1–6; deal max 4), resolved server-side to a listing this store can award; value = customer price. plinko: outermost bins (12 rows, most valuable at the edges); tower: top floors; mines: hidden prize cells; deal: prize cases. Coins/multipliers are rebalanced so the published RTP stays at or below 90 %. Prizes create orders billed to the brand only when a player wins and claims.","minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Product (family) id from `search_products`."},"variant_id":{"description":"Specific variant; otherwise select across the family using the requested listing policy (cheapest by default).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"listing_selection":{"description":"Opt in to tenant selection. The chosen customer price is converted to EUR, the created game's currency, before valuing the prize and computing RTP. Omit to preserve v1's native-cent cheapest policy. Use the same policy for all prizes in this request.","type":"string","const":"tenant"}},"required":["product_id"],"additionalProperties":false}},"image_url":{"type":"string","maxLength":2000,"description":"https or root-relative image URL (e.g. from `confirm_store_media_upload`)."},"banner_url":{"type":"string","maxLength":2000,"description":"https or root-relative image URL (e.g. from `confirm_store_media_upload`)."},"cover_url":{"type":"string","maxLength":2000,"description":"https or root-relative image URL (e.g. from `confirm_store_media_upload`)."},"branding":{"type":"object","properties":{"colors":{"type":"object","properties":{"brand":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"card_bg":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"tile":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"shelf":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"ball":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"peg":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"additionalProperties":false},"bg_image_url":{"description":"Same-origin upload recommended (WebGL).","type":"string","maxLength":2000},"bg_dim":{"type":"number","minimum":0,"maximum":1},"title_logo_url":{"description":"Transparent brand title logo for the in-game header (~3:1).","type":"string","maxLength":2000},"cover_logo_url":{"description":"Square brand icon on tile/case covers (mines, tower, deal).","type":"string","maxLength":2000},"cover_logo_bg":{"description":"Fill of the chip behind the cover icon (default light).","type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"additionalProperties":false},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["store_id","type","name"]}},{"name":"create_order_shipping_link","title":"Mint a hosted shipping-address window URL for an order","description":"Mint a hosted shipping-address window URL for an order\n\nReturns a signed, expiring URL the brand opens in an **iframe modal**\n(default, `embed=1`) or as a **full store page** (`embed: false`) so the\nplayer can fill in the delivery address. Capturing the address never\nchanges the order `status`; read the derived `address_state` instead.\n\nScope `orders:update`. `Idempotency-Key` is ignored: each call mints a\nfresh token. Re-issuing does not invalidate previous links.\n\nThe window is themed by a store: the order's own (`store_id` on\n`POST /orders`) or the `store_id` you pass here. With neither, the\ncall returns 409 `conflict` with `error.field_errors.reason:\n[\"order_has_no_store\"]`. Other 409 reasons: `order_closed` (order\n`completed` / `cancelled`), `multi_recipient_order` (lines for more\nthan one customer), `store_not_active`.\n\n### What the form collects\n\nThe recipient name and the address (street, postal code, city,\ncountry) are always asked. By default the form also shows **email**\n(required), **phone** (optional), street number, apartment and\nstate/province (optional); an ID **document** field is hidden. Each\nstore sets which fields are shown and required in the store editor\n(shipping page section).\n\nOn submit the address is saved on every line of the order. The\nrecipient name also fills the customer's `first_name` / `last_name`\nwhen they are empty. When the store's \"copy to customer\" option is\non (the default), the address is copied to the customer record and\nan empty customer `email` / `phone` is filled from the form. Values\nalready on the customer other than the address are never overwritten.\n\n### 1. Mint the link\n\n```bash\ncurl -X POST \\\n  -H \"Authorization: Bearer tpp_live_<KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"ttl_seconds\": 86400, \"parent_origin\": \"https://www.yourcasino.com\" }' \\\n  https://api.thepowerplugin.com/api/v1/orders/{id}/shipping-link\n```\n\nPass `parent_origin` (your page's https origin): the window then posts\nits `postMessage` events **only** to that origin, and the API rejects\nit up front if the store's `frame_ancestors` would block the embed.\n\n### 2. Embed it in a modal\n\n```html\n<iframe id=\"tpp-shipping\"\n  src=\"{data.url}\"\n  title=\"Delivery address\"\n  style=\"width:100%;max-width:640px;height:560px;border:0;display:block\"\n  referrerpolicy=\"strict-origin-when-cross-origin\"\n></iframe>\n```\n\nThe window is responsive: give the iframe the full width of your modal\n(phones included) and let the height follow `VIEW_SIZE_UPDATE`.\n\n### 3. Listen to the window\n\n```js\nconst frame = document.getElementById(\"tpp-shipping\")\nconst TPP_ORIGIN = new URL(frame.src).origin\n\nwindow.addEventListener(\"message\", (event) => {\n  // Always validate BOTH the origin and the source frame.\n  if (event.origin !== TPP_ORIGIN) return\n  if (event.source !== frame.contentWindow) return\n  const { type, payload } = event.data ?? {}\n  switch (type) {\n    case \"SHIPPING_VIEW_READY\":\n      // payload.mode: \"form\" | \"locked\" | \"expired\" | \"invalid\"\n      if (payload.mode === \"expired\") remintAndReload()\n      break\n    case \"VIEW_SIZE_UPDATE\":\n      frame.style.height = `${payload.height}px`\n      break\n    case \"SHIPPING_ADDRESS_SUBMITTED\":\n      // { orderId, addressState: \"captured\", country } — never the address itself\n      markOrderAddressed(payload.orderId)\n      closeModal()\n      break\n    case \"SHIPPING_CLOSE_REQUESTED\":\n      closeModal()\n      break\n    case \"SHIPPING_VIEW_ERROR\":\n      // payload.code: \"locked\" | \"consumed\" | \"invalid\" | \"validation\"\n      if (payload.code !== \"validation\") closeModal()\n      break\n  }\n})\n```\n\nPayloads carry no PII. The address itself arrives server-side through\nthe `order.shipping_updated` webhook (`data.source: \"shipping_window\"`)\nor `GET /orders/{id}/shipping`.\n\n### 4. Full page instead of a modal\n\nMint with `{ \"embed\": false }` and redirect the player to `data.url`\n(or open it in a new tab): the form renders as a normal store page with\nthe shared header and footer. Works as an email / push deep link too.\n\n### States and re-issuing\n\n| `address_state` / mode | Meaning | What to do |\n|---|---|---|\n| `missing` | at least one line has no address | show the window |\n| `captured` | address saved, order still editable | optional — the window opens prefilled |\n| `locked` | a line shipped, or order completed/cancelled | nothing to capture; the window shows a read-only notice |\n| `expired` (window) | token past `expires_at` | mint a new link — old links are never revoked, they just expire |\n| `consumed` (window) | `single_use` link already used | mint a new link if the player must edit again |\n\nStores with an access mode other than `free` let this window through\ntheir gate **only** with a valid token — nothing else in the store opens.\n\nRequires API key scope: orders:update.","method":"POST","path":"/api/v1/orders/{id}/shipping-link","scopes":["orders:update"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"ttl_seconds":{"description":"Link lifetime in seconds. Default 604800 (7 days).","type":"integer","minimum":300,"maximum":2592000},"parent_origin":{"description":"https origin of the page that embeds the iframe. Used as postMessage targetOrigin and checked against the store's frame_ancestors.","type":"string","maxLength":255,"format":"uri"},"store_id":{"description":"Store that themes the window. Required only when the order has no store_id. Must belong to the calling sub-brand.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"single_use":{"description":"If true, the link stops working after the first successful submit.","type":"boolean"},"embed":{"description":"If true (default), `url` carries embed=1 (no store chrome).","type":"boolean"}},"required":["id"]}},{"name":"create_raffle","title":"Create a draft raffle","description":"Create a draft raffle\n\nCreates a `draft` raffle on a store of this sub-brand. Each prize is a catalogue product (`product_id` from `search_products`, optional `variant_id`) resolved server-side to a listing the store can award; prize value is the customer price. Nothing is sold or drawn until `publishRaffle`. Raffles must be enabled for the sub-brand. Requires `Idempotency-Key`.\n\nRequires API key scope: raffles:create.","method":"POST","path":"/api/v1/raffles","scopes":["raffles:create"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"store_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":2,"maxLength":200},"slug":{"type":"string","maxLength":80},"subtitle":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":5000},"ticket_price_cents":{"type":"integer","minimum":0,"maximum":1000000,"description":"Ticket price in ISO 4217 minor units of the raffle currency (EUR, the currency API raffles are created in): EUR 2.00 = 200."},"total_tickets":{"type":"integer","minimum":1,"maximum":100000},"min_tickets":{"type":"integer","minimum":0,"maximum":100000},"max_tickets_per_customer":{"type":"integer","minimum":0,"maximum":100000},"sales_open_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"sales_close_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"draw_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"image_url":{"type":"string","maxLength":2000},"banner_url":{"type":"string","maxLength":2000},"about_image_url":{"type":"string","maxLength":2000},"legal_terms":{"type":"string","maxLength":20000},"prizes":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Product (family) id from `search_products`."},"variant_id":{"description":"Specific variant; otherwise select across the family using the requested listing policy (cheapest by default).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"listing_selection":{"description":"Opt in to tenant selection. The chosen customer price is converted to EUR, the created raffle's currency, before valuing the prize. Omit to preserve v1's native-cent cheapest policy. Use the same policy for all prizes in this request.","type":"string","const":"tenant"},"title":{"type":"string","minLength":1,"maxLength":200},"quantity":{"type":"integer","minimum":1,"maximum":1000}},"required":["product_id"],"additionalProperties":false}},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["store_id","name","ticket_price_cents","total_tickets","sales_close_at","draw_at","prizes"]}},{"name":"create_store","title":"Create a draft storefront","description":"Create a draft storefront\n\nCreates a `draft` store (not publicly visible) in the calling key's sub-brand: theme, languages, optional template design and catalog links in one transaction. Edit it with `PATCH /api/v1/stores/{id}/draft`, then publish. Requires `Idempotency-Key`.\n\nRequires API key scope: stores:create.","method":"POST","path":"/api/v1/stores","scopes":["stores:create"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"slug":{"description":"Globally unique. Omit to derive one from the name.","type":"string","minLength":3,"maxLength":50,"pattern":"^[a-z0-9-]+$"},"default_lang":{"type":"string","enum":["en","es","pt","it","fr","de"]},"languages":{"maxItems":13,"type":"array","items":{"type":"string","enum":["en","en-US","es","es-MX","es-CO","es-AR","es-CL","es-PE","pt","pt-BR","it","fr","de"]}},"payment_mode":{"description":"Default `points` (required for arcade games).","type":"string","enum":["card","points","order_only","off_price"]},"points_rate":{"description":"Points per currency unit. Default 10.","type":"integer","minimum":1,"maximum":10000},"template_id":{"type":"string","enum":["clean","luxury","atelier","noir","nocturne","bloom","pulse","streetwear","botanica","vegas","arcade","kickoff","podium","slot","partners-club","betplay"]},"catalog_ids":{"description":"Catalogs visible to this sub-brand to attach (see `list_catalogs`).","maxItems":20,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["name","default_lang"]}},{"name":"create_store_session","title":"Create a storefront hand-off (SSO)","description":"Create a storefront hand-off (SSO)\n\nMints a short-lived, signed hand-off URL that logs the given CRM\nuser into the storefront. Resolve order: `external_id` then\n`email`, scoped to the calling key's sub-brand. Unknown users are\ncreated just-in-time (names and email are used only then).\n\nRedirect the player to `url` or use it as an iframe `src`. The link\nworks once, until `expires_at` (`ttl_seconds`, 60–900, default\n300): the first open signs the player in for 8 hours; opening it\nagain lands on the store without signing in. Mint a new URL for\nevery hand-off. `Idempotency-Key` is ignored — each call mints a\nfresh token.\n\nReturns 404 when `store_id` does not belong to the sub-brand.\n\nRequires API key scope: store_sessions:create.","method":"POST","path":"/api/v1/store-sessions","scopes":["store_sessions:create"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"store_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Storefront to hand the user off to. Must belong to the calling key's sub-brand."},"external_id":{"type":"string","minLength":1,"maxLength":120,"description":"The CRM's identifier for the user, matched against the customer's `external_id` within the sub-brand; the customer is created just-in-time if unknown."},"first_name":{"description":"Used only when JIT-creating the customer.","anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"last_name":{"description":"Used only when JIT-creating the customer.","anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"email":{"description":"Fallback lookup key + used when JIT-creating.","anyOf":[{"type":"string","maxLength":255,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"ttl_seconds":{"description":"Hand-off URL lifetime in seconds, 60–900; default 300. A value outside the range is a 400 (not clamped).","type":"integer","minimum":60,"maximum":900}},"required":["store_id","external_id"]}},{"name":"delete_customer","title":"Delete a customer","description":"Delete a customer\n\nDeletes the customer. This cannot be undone:\n- Their personal data and `external_id` are erased. The customer no\n  longer appears in lists and every call with its id returns 404. The\n  same `external_id` can be used for a new customer.\n- Their orders, coin movement history and game history are kept\n  without personal data.\n- A remaining coin balance is cancelled with a `customer_deleted`\n  movement. Later refunds for their orders are not credited.\n\nReturns `{ id, deleted: true }` on success. A repeated call returns\n404. `Idempotency-Key` is not used by this endpoint.\n\nRequires API key scope: customers:delete.","method":"DELETE","path":"/api/v1/customers/{id}","scopes":["customers:delete"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"discard_store_draft","title":"Discard a storefront's draft design","description":"Discard a storefront's draft design\n\nDeletes the staged draft and returns the published design. Does not change the live storefront.\n\nRequires API key scope: stores:update.","method":"DELETE","path":"/api/v1/stores/{id}/draft","scopes":["stores:update"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"get_brand_sub_brand","title":"Get brand and sub-brand metadata","description":"Get brand and sub-brand metadata\n\nReturns the calling API key's sub-brand together with its parent brand. Both path ids must match the key scope.\n\nRequires API key scope: brands:read.","method":"GET","path":"/api/v1/brands/{brandId}/sub-brands/{subBrandId}","scopes":["brands:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"brandId":{"type":"string","description":"Path parameter `brandId` (identifier or slug)."},"subBrandId":{"type":"string","description":"Path parameter `subBrandId` (identifier or slug)."}},"required":["brandId","subBrandId"]}},{"name":"get_catalog","title":"Fetch a catalog by id","description":"Fetch a catalog by id\n\nReturns the catalog if it is visible to the calling sub-brand (own or accepted brand-level). 404 otherwise — pending/rejected brand-level catalogs return 404 to prevent enumeration.\n\nRequires API key scope: catalogs:read.","method":"GET","path":"/api/v1/catalogs/{id}","scopes":["catalogs:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"get_customer","title":"Fetch a customer by id","description":"Fetch a customer by id\n\nReturns the customer if it belongs to the calling key's sub-brand.\n\n404 is intentionally returned for both unknown ids and ids in\nother sub-brands — distinguishing them would leak existence.\n\nRequires API key scope: customers:read.","method":"GET","path":"/api/v1/customers/{id}","scopes":["customers:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"get_customer_coins","title":"Get a customer's coin wallet snapshot","description":"Get a customer's coin wallet snapshot\n\nReturns the cached balance plus the 10 most recent movements\nfor the customer. Convenient for an activity-feed UI that\nshows running history without a separate paginated call.\n\nReturns `balance: 0` with an empty `recent_movements` array\nwhen the customer's wallet has never been touched.\n\nFor the full history, page through\n`GET /customers/{id}/coins/movements`.\n\nRequires API key scope: customers:read.","method":"GET","path":"/api/v1/customers/{id}/coins","scopes":["customers:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"get_game","title":"Fetch an arcade game","description":"Fetch an arcade game\n\nReturns the game when it belongs to the calling key's sub-brand.\n\nRequires API key scope: games:read.","method":"GET","path":"/api/v1/games/{id}","scopes":["games:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"get_health","title":"Liveness probe and key sanity check","description":"Liveness probe and key sanity check\n\nVerifies the calling key authenticates, has at least the `customers:read` scope, and counts against its rate-limit bucket. Returns the environment and sub-brand id encoded in the key so clients can confirm they are talking to the right tenant/mode.\n\nRequires API key scope: customers:read.","method":"GET","path":"/api/v1/health","scopes":["customers:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}},{"name":"get_order","title":"Fetch an order + its line items","description":"Fetch an order + its line items\n\nReturns the order header with its line items. Shipping details are also available via `GET /api/v1/orders/{id}/shipping` if you only need addresses + carrier info.\n\nRequires API key scope: orders:read.","method":"GET","path":"/api/v1/orders/{id}","scopes":["orders:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"get_order_buyback","title":"Get the buyback offer for an order","description":"Get the buyback offer for an order\n\nWhat the paying customer would receive for selling this order back\nfor points, or why they can't. Eligible while the order is `pending`\nor `processing`, no item has shipped, it was paid from a single TPP\nwallet and the brand has buyback on (brand rate, e.g. 9000 bps = 90%).\n\nShow `points_offered` to the customer and collect their acceptance of\nthe buyback terms before calling `POST`.\n\nRequires API key scope: orders:read.","method":"GET","path":"/api/v1/orders/{id}/buyback","scopes":["orders:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"get_order_reservation_request","title":"Get an asynchronous order reservation","description":"Get an asynchronous order reservation\n\nReturns the durable status of a reservation accepted with HTTP 202\nby `POST /api/v1/orders`. The id is scoped to the calling key's\nsub-brand. When status becomes `completed`, use `order_id` with\n`GET /api/v1/orders/{id}`. `failed` is terminal and includes a\nsafe failure code/message.\n\nRequires API key scope: orders:read.","method":"GET","path":"/api/v1/order-reservations/{id}","scopes":["orders:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"get_order_shipping","title":"Fetch per-item shipping details for an order","description":"Fetch per-item shipping details for an order\n\nReturns one entry per line item with the recipient + carrier\nfields, without the financial / billing fields. Convenient for\nlabel-printing flows and courier polling.\n\nRequires API key scope: orders:read.","method":"GET","path":"/api/v1/orders/{id}/shipping","scopes":["orders:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"get_product","title":"Fetch a product family + its variants","description":"Fetch a product family + its variants\n\nReturns the product family with its variants array. The path accepts\neither the UUIDv7 or the id the product had on the previous TPP platform.\n404 when the product is not visible to the calling sub-brand.\n\nThe top-level product fields include the final price\n(`price_cents`, `currency`, `price_country`); the raw provider cost\nis never exposed. Each variant carries `listing_market_id` — the id to\nsend to `POST /orders` — plus that listing's own `price_cents`,\n`currency` and `price_country`; all four are null when the variant\nhas no orderable listing for the calling sub-brand.\nBy default selection preserves v1's cheapest raw listing in the first effective market.\nPass `listing_selection=tenant` to opt in to the effective sub-brand/brand selection mode.\n\nOnly `active` products are returned; any other status, or a\nmalformed id, is a 404. Brand-level custom products are visible to\nevery sub-brand of their owning brand; sub-brand-owned custom products\nare visible only to their owner. A sibling or foreign sub-brand gets\nthe same 404 even when it knows the id.\n\nRequires API key scope: products:read.","method":"GET","path":"/api/v1/products/{id}","scopes":["products:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"listing_selection":{"description":"Opt in to the effective sub-brand/brand provider-selection mode, with currency-normalized costs and stable provider/listing tie-breaks. Omit to preserve v1: cheapest raw listing in the first effective market, ties by listing id. Use the same option on every page and sync; switching requires a new full listing.","type":"string","const":"tenant"}},"required":["id"]}},{"name":"get_raffle","title":"Get a raffle","description":"Get a raffle\n\nOne raffle in the calling sub-brand: price, how many tickets are\nleft, prizes, bundles, and — once drawn — `winner_count`. List the\nwinners with `GET /raffles/{id}/winners` (cursor-paginated).\n\nEmails, shipping addresses and the encrypted seed are never returned.\n\nAnother sub-brand's raffle, a draft, and a raffle while the module\nis off all answer `404`.\n\nRequires API key scope: raffles:read.","method":"GET","path":"/api/v1/raffles/{id}","scopes":["raffles:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"get_store","title":"Fetch a store by id or slug","description":"Fetch a store by id or slug\n\nThe `{id}` path parameter accepts either a UUID or the store's slug.\nSlugs are globally unique so disambiguation by shape is safe.\n\nReturns 404 if the store doesn't exist OR belongs to a different sub-brand.\n\nRequires API key scope: stores:read.","method":"GET","path":"/api/v1/stores/{id}","scopes":["stores:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"get_store_capabilities","title":"List store templates and composable sections","description":"List store templates and composable sections\n\nTemplates (with their theme), section types an API caller may add (with each field's key, type, options and whether it holds media), pages, languages, payment modes and the limits enforced by `PATCH /api/v1/stores/{id}/draft`.\n\nRequires API key scope: stores:read.","method":"GET","path":"/api/v1/store-capabilities","scopes":["stores:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}},{"name":"get_store_draft","title":"Get a storefront's draft design","description":"Get a storefront's draft design\n\nTheme and sections of the staged draft, or of the published design when no draft exists (`source`). Section `config` keys follow the section registry (see `GET /api/v1/store-capabilities`).\n\nRequires API key scope: stores:read.","method":"GET","path":"/api/v1/stores/{id}/draft","scopes":["stores:read"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"ingest_engine_event","title":"Deliver an event to the Engine","description":"Deliver an event to the Engine\n\nExecutes the event definition identified by `event_code` for the\nplayer referenced in `data`: the payload key named by the\ndefinition's `player_id_field` (see `GET /engine/definitions`;\ndefault payload key `externalUserId`) is matched against the\ncustomer's `external_id` within your sub-brand.\n`occurred_at` may carry the RFC 3339 business event time; it defaults\nto ingestion time and is accepted only from 24 hours in the past to 5\nminutes in the future. It is used by bounded event-time consumers such\nas leaderboards. It never controls audit ordering, retention, rate\nlimits, billing, or Engine active-window evaluation.\n\nA delivery that passes pre-flight always returns **200 with an\n`EngineEventResult`** — check `status`, don't assume `completed`:\n- `completed` — the points were applied to the wallet.\n- `skipped` — rules declined, nothing applied. `error_code`:\n  `outside_active_window`; `max_daily_reached` (per-player daily\n  cap); `cooldown_active` (per-player minimum interval);\n  `budget_limit_reached` (a budget cap; see `limit_context`);\n  `budget_misconfigured`; `invalid_amount` / `calculated_points_below_minimum`\n  (runtime points calculation from the payload); `invalid_constraints`\n  (the definition's rules are misconfigured — ask TPP).\n- `failed` — recorded but not applied. `error_code`:\n  `player_id_missing`, `player_not_found`, `insufficient_balance`,\n  `balance_overflow`, `invalid_points` (the definition's points are\n  misconfigured), or `internal_error` (transient, see below).\n\n**Idempotency-Key header is REQUIRED** (this endpoint moves money).\nThe same value is also the business idempotency key, so a\nredelivery through the webhook channel with the same id can never\ndouble-credit. A retry with the SAME key and body is normally\nanswered by the HTTP idempotency layer: the original response body\nverbatim (so `replayed` reads `false`) plus the\n`Idempotent-Replay: true` response header — key off the header.\n`replayed: true` in the body marks a business-layer replay (e.g.\nthe same id already arrived via webhook). Same key + a DIFFERENT\nbody, or a retry while the first is still running → 409\n`idempotency_conflict`.\n\nRetry semantics: a `failed` with `error_code: internal_error`\nreturns **500** and IS retryable with the same key; business\n`failed`/`skipped` are terminal and replay their frozen verdict.\n\n`points_override` (a non-zero integer) is accepted only when the\ndefinition's `override_mode` is `external_bounded`, the key holds\nthe `engine:overrides` scope, and the value lies within the\ndefinition's `min_points`/`max_points`. A key with only\n`engine:events` keeps working for events that use default points.\n\nPre-flight rejections (error envelope, nothing executed; the\nreason is in `error.message`):\n- 400 `invalid_request` — `points_override` not allowed (definition\n  forbids it, or the key lacks `engine:overrides`) or out of bounds;\n  payload too large; `occurred_at` outside its accepted window; a\n  wallet-moving event without a stable event id.\n- 403 `forbidden` — the Engine is not enabled for this brand.\n- 404 `not_found` — unknown `event_code`.\n- 409 `conflict` — the definition is not `active`; it is `internal`\n  (cannot be delivered through the API); deliveries are paused by a\n  budget policy; or a delivery with the same key is still being\n  processed (retry shortly).\n\nEvery delivery — completed, skipped, failed, replay, rejection —\nlands in the immutable Engine audit trail.\n\nRequires API key scope: engine:events.","method":"POST","path":"/api/v1/engine/events","scopes":["engine:events"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"event_code":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,79}$","description":"Code of the event definition to execute (unique per sub-brand)."},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The event payload, stored verbatim on the execution and audit records. The player is resolved from the payload key named by the definition's `player_id_field` (default payload key `externalUserId`), matched against the customer's `external_id`."},"occurred_at":{"description":"Optional RFC 3339 business occurrence time. Defaults to server ingestion time and must be no more than 24 hours old or 5 minutes in the future. Used by event-time consumers such as leaderboards; it never controls audit ordering, retention, rate limits, billing, or the Engine definition's own active-window evaluation.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"points_override":{"description":"Optional per-event points value: a signed non-zero integer, |points| <= 1,000,000, within the definition's `min_points` / `max_points`. Accepted only when the definition's `override_mode` is `external_bounded` AND the API key holds the `engine:overrides` scope; otherwise the delivery is rejected 400 `invalid_request` before anything is executed.","type":["number","null"]},"correlation_id":{"description":"Optional caller tracing id (echoed back). Generated when absent.","anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["event_code","data"]}},{"name":"ingest_engine_webhook","title":"Deliver an event to the Engine via webhook","description":"Deliver an event to the Engine via webhook\n\nWebhook-style ingestion: POST the provider payload verbatim; the\nevent definition code travels in the path. Runs the exact same\npipeline as `POST /engine/events` (same ledger, same audit trail,\nsame velocity caps).\n\nRedeliveries dedupe on the payload key named by the definition's\n`idempotency_key_field` (see `GET /engine/definitions`; when null,\nthe payload's `event_id`, then `id`)\n— a stable provider id is strongly recommended. Ids longer than\n64 chars are hashed deterministically, so dedup always holds.\n\n**FAIL-CLOSED anti-replay:** a wallet-moving delivery with NO\nusable id (no matching payload key AND no `Idempotency-Key`\nheader) is **rejected 400 `invalid_request`** rather than executed —\nwithout a key an attacker could replay the same body to farm\npoints. Always send a stable event id.\n\nResponds 200 with an `EngineEventResult` for every delivery that\npasses pre-flight — check `status` (`completed` / `skipped` /\n`failed`, same `error_code` values as `POST /engine/events`), don't\nassume `completed`. `replayed: true` marks a redelivery answered\nwith the FROZEN first result. The same pre-flight rejections as\n`/engine/events` apply (400 / 403 / 404 / 409; 500 for a transient\n`internal_error` — retry with the same id).\n\nRequires API key scope: engine:events.","method":"POST","path":"/api/v1/engine/webhooks/{code}","scopes":["engine:events"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string","description":"Path parameter `code` (identifier or slug)."}},"required":["code"]}},{"name":"list_catalogs","title":"List catalogs visible to the sub-brand","description":"List catalogs visible to the sub-brand\n\nReturns catalogs the calling sub-brand can use:\n1. Catalogs owned exclusively by this sub-brand (`scope: \"sub_brand\"`).\n2. Brand-level catalogs the sub-brand has ACCEPTED (`scope: \"brand\"`).\n\nPending or rejected brand-level catalogs are filtered out — clients\nsee them as if they didn't exist.\n\nRequires API key scope: catalogs:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"GET","path":"/api/v1/catalogs","scopes":["catalogs:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{}}},{"name":"list_categories","title":"List product categories","description":"List product categories\n\nReturns the global canonical category list. The default is `active`; pass `status=inactive` to inspect disabled categories.\n\nRequires API key scope: categories:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"GET","path":"/api/v1/categories","scopes":["categories:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string","enum":["active","inactive"]}}}},{"name":"list_customer_coin_movements","title":"List a customer's full coin-movement history","description":"List a customer's full coin-movement history\n\nReturns every movement for the customer's wallet in reverse\nchronological order, cursor-paginated. Movements are append-\nonly — corrections appear as NEW rows with their own `delta`\nand `balance_after`, so the running history is reconstructable\nfrom this endpoint alone.\n\n404 if the customer doesn't exist or belongs to a different\nsub-brand.\n\nRequires API key scope: customers:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"GET","path":"/api/v1/customers/{id}/coins/movements","scopes":["customers:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"limit":{"description":"Page size — default 25, max 100. Smaller pages are cheaper; large pages save round-trips when backfilling history.","type":"integer","minimum":1,"maximum":100},"cursor":{"description":"Opaque cursor from the previous page's `page.next_cursor`. Omit on the first page.","type":"string"}},"required":["id"]}},{"name":"list_customers","title":"List customers","description":"List customers\n\nReturns the calling key's sub-brand customers in reverse\nchronological order. Pagination is cursor-based — call again with\n`?cursor=<page.next_cursor>` until `page.has_more` is false.\n\nAll filters combine with AND. Filter by status, segment, country,\ncreation/registration date windows, coin-balance range and\nlifetime order-count range — the same targeting the bulk-coins\nendpoint uses.\n\nRequires API key scope: customers:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"GET","path":"/api/v1/customers","scopes":["customers:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"q":{"description":"Substring match across `first_name`, `last_name`, `email`, `external_id`. Case-insensitive.","type":"string","minLength":1,"maxLength":200},"status":{"description":"Filter by moderation status.","type":"string","enum":["active","watch","restricted","banned"]},"segment_id":{"description":"Exact match on the casino-side segment/cohort tag.","type":"string","minLength":1,"maxLength":36},"country":{"description":"ISO-3166-1 alpha-2 country.","type":"string","minLength":2,"maxLength":2},"created_after":{"description":"Only customers created at/after this ISO-8601 UTC instant.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"created_before":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"registered_after":{"description":"Only customers whose casino `platform_registered_at` is at/after this instant.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"registered_before":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"min_coins":{"description":"Only customers whose coin balance is >= this value (0 default).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max_coins":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"min_orders":{"description":"Only customers with at least this many lifetime orders.","type":"integer","minimum":0,"maximum":9007199254740991},"max_orders":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Default 25, max 100.","type":"integer","minimum":1,"maximum":100},"cursor":{"description":"Opaque cursor returned by the previous page's `page.next_cursor`. Omit on the first page.","type":"string"}}}},{"name":"list_engine_definitions","title":"List the sub-brand's Engine event definitions","description":"List the sub-brand's Engine event definitions\n\nRead-only catalogue of the event definitions the operator configured\nfor the calling key's sub-brand: the `code` to send as `event_code`,\nwho may deliver it (`kind`), the payload fields carrying the player\n(`player_id_field`) and the idempotency id (`idempotency_key_field`),\nthe points envelope and the per-player constraints.\n\nImport this before wiring emitters — never invent an event code.\nAnswers `403` when the Engine is not enabled for the brand, the same\nsignal a delivery would get. Definitions are authored in the TPP\nbackoffice; ask TPP for a missing one.\n\nRequires API key scope: engine:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"GET","path":"/api/v1/engine/definitions","scopes":["engine:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"description":"Default `active` (the only status that executes). `all` lists draft and disabled too.","type":"string","enum":["active","disabled","draft","all"]},"kind":{"description":"Filter by who may deliver the event. Integrators usually want `external`.","type":"string","enum":["internal","external"]}}}},{"name":"list_games","title":"List arcade games","description":"List arcade games\n\nCursor-paginated arcade games of the calling key's sub-brand, newest first. Filter by `store_id`.\n\nRequires API key scope: games:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"GET","path":"/api/v1/games","scopes":["games:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"store_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"limit":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string"}}}},{"name":"list_orders","title":"List orders","description":"List orders\n\nCursor-paginated list of orders for the calling sub-brand. Newest\nfirst. Filter by status, store id, or a creation-time window.\n\nBilling-layer fields (billing batch references, payment references)\nare not exposed by the public API.\n\nRequires API key scope: orders:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"GET","path":"/api/v1/orders","scopes":["orders:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string","enum":["pending","processing","shipped","completed","failed","cancelled"]},"store_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"customer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"q":{"type":"string","minLength":1},"created_from":{"description":"Inclusive lower bound on `created_at` (ISO-8601).","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"created_to":{"description":"Inclusive upper bound on `created_at` (ISO-8601).","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"limit":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string"},"address_state":{"description":"Filter by derived shipping-address state: missing, captured, or locked.","type":"string","enum":["missing","captured","locked"]}}}},{"name":"list_product_ids","title":"List the ids of every product visible to the sub-brand","description":"List the ids of every product visible to the sub-brand\n\nIds of all products `GET /products` would return, ascending, without\nprices or variants. Like the list, only products you can order now are\nincluded (at least one in-stock listing). An incremental sync\n(`GET /products?updated_since=`) does not return products that stopped\nbeing visible or sold out; delete local products whose id is missing\nfrom this list.\n\nRequires API key scope: products:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"GET","path":"/api/v1/product-ids","scopes":["products:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"catalog_id":{"description":"Restrict to a specific catalog visible to the calling sub-brand.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"limit":{"description":"Page size, 1–1000. Default 500.","type":"integer","minimum":1,"maximum":1000},"cursor":{"type":"string"}}}},{"name":"list_raffle_winners","title":"List a raffle's winners","description":"List a raffle's winners\n\nWinners of a drawn raffle, cursor-paginated in draw order. A large\nraffle can have tens of thousands of winners, so they are not part of\n`GET /raffles/{id}` (which returns `winner_count`).\n\nA winner is `{ position, prize_title, ticket_number, customer_id }`.\n`customer_id` is a customer of this sub-brand, or null. Emails and\nshipping addresses are never returned.\n\nEmpty until the raffle is `drawn`. Another sub-brand's raffle, a\ndraft, and a raffle while the module is off all answer `404`.\n\nRequires API key scope: raffles:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"GET","path":"/api/v1/raffles/{id}/winners","scopes":["raffles:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"limit":{"description":"Page size — default 25, max 100.","type":"integer","minimum":1,"maximum":100},"cursor":{"description":"Opaque cursor from the previous page's `page.next_cursor`. Omit on the first page.","type":"string"}},"required":["id"]}},{"name":"list_raffles","title":"List raffles","description":"List raffles\n\nCursor-paginated raffles of the calling sub-brand, newest first.\nA raffle is what you buy a ticket for — it is not a catalog product\nand it does not appear in `GET /products`.\n\nDrafts and archived raffles are omitted. When raffles are not\nenabled for the sub-brand the list is empty.\n\nRequires API key scope: raffles:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"GET","path":"/api/v1/raffles","scopes":["raffles:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"store_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["scheduled","sales_closed","drawing","drawn","cancelled"]},"limit":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string"}}}},{"name":"list_stores","title":"List storefronts","description":"List storefronts\n\nCursor-paginated list of storefronts belonging to the calling key's sub-brand. Filter by status or name/slug substring.\n\nRequires API key scope: stores:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"GET","path":"/api/v1/stores","scopes":["stores:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"q":{"type":"string","minLength":1,"maxLength":200},"status":{"type":"string","enum":["draft","active","inactive"]},"limit":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string"}}}},{"name":"prepare_store_media_upload","title":"Prepare an image upload","description":"Prepare an image upload\n\nSigns a 10-minute upload URL bound to this sub-brand (and optional store), the MIME type, size and SHA-256 you declare. PUT the exact bytes to `upload_url` without an Authorization header, then call `POST /api/v1/media/uploads/confirm`. PNG, JPEG or WebP up to 5 MB; stored as WebP.\n\nRequires API key scope: media:create.","method":"POST","path":"/api/v1/media/uploads","scopes":["media:create"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"mime_type":{"type":"string","enum":["image/png","image/jpeg","image/webp"]},"size_bytes":{"type":"integer","minimum":1,"maximum":5242880},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 of the exact bytes you will PUT."},"store_id":{"description":"Store the image belongs to; omit for sub-brand-wide assets.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["mime_type","size_bytes","sha256"]}},{"name":"publish_game","title":"Publish an arcade game","description":"Publish an arcade game\n\nRuns the same publish gate as the backoffice (RTP within target, prize listings, commit-reveal seed) and makes the game `active`. Already-active games are returned unchanged. No economic override is available through the API. Requires `Idempotency-Key`.\n\nRequires API key scope: games:update.","method":"POST","path":"/api/v1/games/{id}/publish","scopes":["games:update"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["id"]}},{"name":"publish_raffle","title":"Publish a draft raffle","description":"Publish a draft raffle\n\nRuns the backoffice publish gate (prizes within capacity, every prize awardable by the store, draw after sales close), seals the commit-reveal seed and moves the raffle to `scheduled`. Tickets go on sale and the draw runs automatically at `draw_at`; a claimed prize becomes an order billed to the brand. Already-scheduled raffles are returned unchanged. Requires `Idempotency-Key`.\n\nRequires API key scope: raffles:update.","method":"POST","path":"/api/v1/raffles/{id}/publish","scopes":["raffles:update"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["id"]}},{"name":"publish_store","title":"Publish a storefront's draft design","description":"Publish a storefront's draft design\n\nCopies the staged draft (or re-publishes the current design) to the live storefront and clears the draft — the editor's Publish button. `activate: true` also moves a `draft` store to `active`, making it publicly visible. Requires `Idempotency-Key`.\n\nRequires API key scope: stores:update.","method":"POST","path":"/api/v1/stores/{id}/publish","scopes":["stores:update"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"activate":{"description":"Also move a `draft` store to `active` (publicly visible). Default false.","type":"boolean"},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["id"]}},{"name":"reserve_order","title":"Reserve a new order","description":"Reserve a new order\n\nCreates an order in the calling key's sub-brand from one or more\ncatalog listings. Each line item references a `listing_market_id`\n(from `variants[]` of `GET /products` or `GET /products/{id}`) and\nan existing customer of the same sub-brand. Only catalog listings\ncan be ordered. A customer whose `status` is `restricted` or\n`banned` cannot receive an order (403 `forbidden`).\n\nOwned custom products use the same visibility rule as `GET /products`:\nbrand-level products are available to every sub-brand of their brand,\nwhile a sub-brand-owned product is available only to that sub-brand.\nA sibling or foreign `listing_market_id` is returned as the same opaque\nunknown-market error. The internal custom provider has no reservation\nintegration, so TPP Operations coordinates fulfilment manually today;\nagree the long-term owner and process with TPP during onboarding.\n\nCoins are not debited by this call: debit the player's wallet\nyourself with `POST /customers/{id}/coins` (negative `delta`), or\nlet TPP do it through your inbound webhooks integration.\n\n**Idempotency-Key is required.** A retry with the same key and\nbody returns the original response with `Idempotent-Replay: true`\n(the order was created once). The same key with a different body\nor while the first request is still running returns 409\n`idempotency_conflict`.\n\n**Shipping window.** The response carries `shipping_url`: the hosted\naddress form (`embed=1`, ready for an iframe/modal), minted once here\nso you do not need a second call. Null when the order has no store\n(pass `store_id`) or the platform cannot sign the link — never a\nfallback to `status_url`, which is a different, read-only page.\nOrder reads omit the field; use `POST /orders/{id}/shipping-link`\nfor a fresh link, a full-page (non-embedded) one, a custom TTL,\n`parent_origin` or `single_use`.\n\n**Pricing.** Each line's `unit_price_cents` is the per-unit price\n(TPP's commission and price rounding included, before the brand\ndiscount), snapshotted at creation so later configuration changes\nnever move historical totals. `total_amount_cents` is authoritative:\nthe lines' `line_total_after_discount_cents` add up to it exactly.\n\n**Billing.**\n- `prepaid_balance` brands: the brand balance is reserved\n  atomically. If it is insufficient and the brand does not allow a\n  negative balance, the order is created with\n  `billing_status='blocked_balance'` — fulfilment cannot proceed\n  until the brand tops up. Watch the field on the response.\n- `monthly_billing` brands: the order is attached to the current\n  open billing batch (created lazily for the period).\n- `pay_per_order` brands: the order is born with\n  `payment_status='pending_payment'` — fulfilment is gated until\n  the admin marks it paid in the backoffice.\n\n**Market gate.** Every listing must be available in one of the\nsub-brand's markets; otherwise 403 `forbidden`. An inactive or\nout-of-stock listing returns 409 `conflict`.\n\n**Transient-failure fallback.** A validated request that encounters\nan explicitly retryable database/infrastructure failure is durably\naccepted with HTTP 202. The response carries a\n`reservation_request_id`; poll\n`GET /api/v1/order-reservations/{id}` for completion. Validation,\nauthorization, catalog, stock, billing, and all unknown/non-retryable\nerrors remain ordinary 4xx/5xx errors and are never queued.\n\nRequires API key scope: orders:create.","method":"POST","path":"/api/v1/orders","scopes":["orders:create"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"listing_market_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"UUID of the listing to purchase. Take it from `variants[].listing_market_id` of `GET /products` or `GET /products/{id}` (null there means the variant cannot be ordered)."},"quantity":{"type":"integer","minimum":1,"maximum":1000,"description":"Units to purchase. Brand-level cart limit caps the total across items."},"customer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Customer who receives this line. MUST belong to the calling sub-brand. The customer's address snapshot fills the line's `shipping_address` and `recipient_*` fields."}},"required":["listing_market_id","quantity","customer_id"]},"description":"Line items. At least one; brand-level cart limit applies."},"store_id":{"description":"Store the order is attributed to; must belong to the calling sub-brand (404 otherwise). Pass it whenever the player should use the hosted pages: without a store the order has no `status_url` or `shipping_url`, and `POST /orders/{id}/shipping-link` answers 409 `order_has_no_store`.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"currency":{"description":"Optional ISO-4217 billing-currency echo. Must match the sub-brand's configured billing currency and have a server-configured FX rate (EUR is the base); defaults to that billing currency.","type":"string","minLength":3,"maxLength":3},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["items"]}},{"name":"resolve_store_code","title":"Products a promotional code applies to","description":"Products a promotional code applies to\n\nResolves a store's promotional code — a shared coupon (`code`) or a single-use code (`free_code` / `assigned`) — to its public terms, its scope and one page of the store's products in that scope, priced as the storefront shows them. Call it from your backend: the API key is a server secret.\n\n`{id}` accepts the store UUID or slug; the store must belong to the key's sub-brand.\n\n- `code.scope` is always the rule's target (`store` = the whole store), whether or not the store restricts visibility by code (`code.store_filters_by_code`).\n- `code.purchasable` is `false` for a single-use code that was already redeemed (browse only).\n- `price_cents` already includes automatic promotions but NOT this code's discount, which the cart applies (and where `min_order_cents` is checked).\n\nThe code goes in the body and is never written to logs. Read-only: no `Idempotency-Key`.\n\n**Errors.** An unknown, inactive, expired, not-yet-started or disabled code, a store of another sub-brand and a code of another store all return the same `404 not_found`. Failed attempts are limited to 10 per 5 minutes per API key and store; past that every attempt returns `429 rate_limited` with `Retry-After` until the window ends. Successful resolutions do not count.\n\nRequires API key scope: stores:read, products:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"POST","path":"/api/v1/stores/{id}/codes/resolve","scopes":["stores:read","products:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"code":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$","description":"The promotional code exactly as the customer received it: a shared coupon (`SUMMER20`) or a single-use code (`7K3M-9QXP-R4TW`). Trimmed and upper-cased before lookup."},"cursor":{"description":"`page.next_cursor` of the previous response, verbatim. Omit for the first page.","type":"string","minLength":1,"maxLength":512},"limit":{"description":"Products per page, 1–100. Default 50.","type":"integer","minimum":1,"maximum":100},"lang":{"description":"Language for product descriptions (`es`, `es-CO`). A language the store does not offer falls back like the storefront does (regional → base → store default).","type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$"}},"required":["id","code"]}},{"name":"search_products","title":"Search products visible to the sub-brand","description":"Search products visible to the sub-brand\n\nReturns product families reachable via any catalog the sub-brand owns\nor has accepted. Product ids are UUIDv7 values (`GET /products/{id}`\nalso accepts the id a product had on the previous TPP platform).\n\nEach product includes `price_cents` / `currency` / `price_country`:\nthe final price (TPP's commission included) resolved from active\nlistings in the sub-brand's markets. The raw provider cost is never\nexposed.\nBy default selection preserves v1's cheapest raw listing in the first effective market.\nPass `listing_selection=tenant` to opt in to the effective sub-brand/brand selection mode.\n\nEach product also lists its `variants`; every variant carries the\n`listing_market_id` to send to `POST /orders` and that listing's final price\n(null when the variant cannot be ordered). Products reachable only\nthrough a disabled catalog are not returned.\n\nCustom products follow the same active-family, active-catalog and\nmarket gates. A brand-level custom product is visible to every\nsub-brand of its owning brand; a sub-brand-owned custom product is\nvisible only to that sub-brand. A sibling or foreign sub-brand sees\nnothing, even when it knows the product id. A valid default provider\nnever hides custom products the calling sub-brand owns.\n\nWith `updated_since` the list becomes an incremental sync, ordered by\nchange time, and `page.sync` carries the value for the next sync.\n\nRequires API key scope: products:read.\n\nPaginated: pass `cursor` from the previous response's `page.next_cursor` to fetch more.","method":"GET","path":"/api/v1/products","scopes":["products:read"],"idempotent":false,"paginated":true,"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"listing_selection":{"description":"Opt in to the effective sub-brand/brand provider-selection mode, with currency-normalized costs and stable provider/listing tie-breaks. Omit to preserve v1: cheapest raw listing in the first effective market, ties by listing id. Use the same option on every page and sync; switching requires a new full listing.","type":"string","const":"tenant"},"q":{"description":"Substring match across `name` and `slug` (case-insensitive).","type":"string","minLength":1,"maxLength":200},"category_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"catalog_id":{"description":"Restrict the search to a specific catalog. The catalog must already be visible to the calling sub-brand.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"updated_since":{"description":"Incremental sync: return only products whose representation may have changed at or after this ISO-8601 instant, oldest change first. Start with a full listing; then pass `page.sync.next_updated_since` from the previous sync (read every page first). A product can be returned again without a visible change. When pricing or catalog settings changed in between, `page.sync.full_sync` is `true` and every visible product is returned. A product going out of or back in stock, or switching to another in-stock listing, counts as a change; a restocked product is returned, but one that stopped being visible or sold out is not (only orderable products are listed): reconcile removals with `GET /product-ids`. Send the same value with each `cursor`.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"limit":{"description":"Page size, 1–100. Default 25.","type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string"}}}},{"name":"set_store_languages","title":"Set a storefront's languages","description":"Set a storefront's languages\n\nSets the languages the storefront offers (applied now) and its base language. Section configs hold the base language's copy and other languages in `config.i18n`; changing the base stages the change in the draft and moves each section's copy, so the live storefront switches on publish and no visitor's text changes. Requires `Idempotency-Key`.\n\nRequires API key scope: stores:update.","method":"PUT","path":"/api/v1/stores/{id}/languages","scopes":["stores:update"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"default_lang":{"type":"string","enum":["en","es","pt","it","fr","de"],"description":"Base language: section configs hold its copy. A change is staged in the draft (live after publish) and moves each section's copy so no visitor's text changes."},"languages":{"minItems":1,"maxItems":13,"type":"array","items":{"type":"string","enum":["en","en-US","es","es-MX","es-CO","es-AR","es-CL","es-PE","pt","pt-BR","it","fr","de"]},"description":"Every language the storefront offers (the language switcher). Must include `default_lang`; applied immediately."},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["id","default_lang","languages"]}},{"name":"update_customer","title":"Partial-update a customer","description":"Partial-update a customer\n\nUpdates the fields present in the body. Omitted fields are NOT\nchanged. To unset a nullable field, send it explicitly as `null`\n(this is PATCH semantics, NOT JSON-merge-patch).\n\n`status` transitions stamp `status_changed_at` automatically.\nAny status can be set here; `restricted` / `banned` block orders,\nnot profile updates or coin adjustments (see `Customer.status`).\nAn empty body returns 400.\n\nRequires API key scope: customers:update.","method":"PATCH","path":"/api/v1/customers/{id}","scopes":["customers:update"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"external_id":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"segment_id":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}]},"first_name":{"type":"string","minLength":1,"maxLength":120},"last_name":{"type":"string","minLength":1,"maxLength":120},"nickname":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"email":{"anyOf":[{"type":"string","maxLength":255,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"address_line":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}]},"street_number":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}]},"apartment":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"zone":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"locality":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"city":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"state":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"country":{"description":"ISO 3166-1 alpha-2 (`es`, `ES`). Stored and returned lowercase.","anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$"},{"type":"null"}]},"preferred_lang":{"anyOf":[{"type":"string","enum":["en","es","pt","it","fr"]},{"type":"null"}]},"platform_registered_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"status":{"type":"string","enum":["active","watch","restricted","banned"]},"status_note":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"required":["id"]}},{"name":"update_game","title":"Update an arcade game's name, copy, art or branding","description":"Update an arcade game's name, copy, art or branding\n\nPresentation only: `name`, `subtitle`, `description`, `image_url` (card and info-modal art), `banner_url`, `cover_url`, and `branding` (colours, stage background and dim, title/cover logos, CTA colours), merged over the current branding and validated like on create; `null` clears a field. Works on draft, active and paused games (archived games are read-only). The board, stake and prizes are not editable here. Requires `Idempotency-Key`.\n\nRequires API key scope: games:update.","method":"PATCH","path":"/api/v1/games/{id}","scopes":["games:update"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"name":{"type":"string","minLength":2,"maxLength":200},"subtitle":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"image_url":{"description":"Card and info-modal art (branded key art that explains the game).","anyOf":[{"type":"string","maxLength":2000,"description":"https or root-relative image URL (e.g. from `confirm_store_media_upload`)."},{"type":"null"}]},"banner_url":{"anyOf":[{"type":"string","maxLength":2000,"description":"https or root-relative image URL (e.g. from `confirm_store_media_upload`)."},{"type":"null"}]},"cover_url":{"anyOf":[{"type":"string","maxLength":2000,"description":"https or root-relative image URL (e.g. from `confirm_store_media_upload`)."},{"type":"null"}]},"branding":{"description":"Look and feel only — editable even while the game is active.","type":"object","properties":{"colors":{"type":"object","properties":{"brand":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"card_bg":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"tile":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"shelf":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"ball":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"peg":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"additionalProperties":false},"bg_image_url":{"description":"Stage background (see the Store Studio game-art guide).","anyOf":[{"type":"string","maxLength":2000,"description":"https or root-relative image URL (e.g. from `confirm_store_media_upload`)."},{"type":"null"}]},"bg_dim":{"description":"plinko and deal only.","type":"number","minimum":0,"maximum":1},"title_logo_url":{"description":"Transparent brand title logo for the in-game header (~3:1).","anyOf":[{"type":"string","maxLength":2000,"description":"https or root-relative image URL (e.g. from `confirm_store_media_upload`)."},{"type":"null"}]},"cover_logo_url":{"description":"Square brand icon on tile/case covers (mines, tower, deal).","anyOf":[{"type":"string","maxLength":2000,"description":"https or root-relative image URL (e.g. from `confirm_store_media_upload`)."},{"type":"null"}]},"cover_logo_bg":{"description":"Fill of the chip behind the cover icon (default light).","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"cta_color":{"description":"Primary button gradient start (mines, plinko).","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"cta_color_dark":{"description":"Primary button gradient end (mines, plinko).","type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"additionalProperties":false},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["id"]}},{"name":"update_order_shipping","title":"Add or update an order's delivery details","description":"Add or update an order's delivery details\n\nSet the delivery details for an order. Two modes:\n\n**Grouped** — send `shipping_address` (+ optional recipient\nfields) at the top level and the SAME address is written to\nevery line item. The order's `shipping_mode` becomes `grouped`.\n\n```json\n{ \"shipping_address\": \"Calle Mayor 1\\n28013 Madrid\\nES\",\n  \"recipient_name\": \"Ana Pérez\" }\n```\n\n**Split** — send an `items` array, one entry per line item\n(addressed independently by `item_id`). The order's\n`shipping_mode` becomes `split`. Every `item_id` must belong\nto the order.\n\n```json\n{ \"items\": [\n  { \"item_id\": \"01933b1c-2100-7000-8000-000000000061\",\n    \"shipping_address\": \"Calle Mayor 1\\n28013 Madrid\\nES\", \"recipient_name\": \"Ana Pérez\" },\n  { \"item_id\": \"01933b1c-2100-7000-8000-000000000062\",\n    \"shipping_address\": \"Carrer de Balmes 20\\n08007 Barcelona\\nES\", \"recipient_name\": \"Luis García\" }\n] }\n```\n\n**Delivery requirements** — each line carries `fulfillment_type`\nand `delivery_requirements` (see `GET /orders/{id}/shipping` or the\n`POST /orders` response). A `digital` line (gift card, code) is\ncomplete with just `recipient_email`:\n\n```json\n{ \"recipient_email\": \"ana@example.com\" }\n```\n\nStructured fields (`address_line1`, `address_line2`, `city`, `state`,\n`postal_code`, `country`) may replace the free-text\n`shipping_address`; the server builds the block from them.\nWhen the sub-brand has saved delivery requirements, every targeted\nline is validated against its map: a missing `required` field\nreturns **422 `validation_failed`** with the fields in\n`field_errors` (prefixed `items[<index>].` in split mode), and\n`hidden` fields are ignored. Without saved requirements the\nvalidation is unchanged.\n\nOnly recipient, address and notes fields are touched — carrier and\ntracking stay fulfilment-side. Rejected with 409 `conflict` once\nthe order is `completed` or `cancelled`. `Idempotency-Key` is\nignored (the update is a plain overwrite). Returns the full per-item\nshipping projection after the update.\n\nRequires API key scope: orders:update.","method":"PATCH","path":"/api/v1/orders/{id}/shipping","scopes":["orders:update"],"idempotent":false,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."}},"required":["id"]}},{"name":"update_raffle","title":"Update a raffle's name, copy or art","description":"Update a raffle's name, copy or art\n\nPresentation only: `name`, `subtitle`, `description`, `image_url`, `banner_url` (landing hero background), `about_image_url`; `null` clears a field. Allowed while the raffle is `draft` or `scheduled`, also after tickets are sold. Ticket price, quantities, dates and prizes are not editable here. Requires `Idempotency-Key`.\n\nRequires API key scope: raffles:update.","method":"PATCH","path":"/api/v1/raffles/{id}","scopes":["raffles:update"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"name":{"type":"string","minLength":2,"maxLength":200},"subtitle":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"image_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"banner_url":{"description":"Landing hero background (full-bleed, under a dark overlay).","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"about_image_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["id"]}},{"name":"update_store_draft","title":"Edit a storefront's draft design","description":"Edit a storefront's draft design\n\nApplies an optional theme patch and up to 25 section operations (`add_section`, `update_section`, `remove_section`, `move_section`) to the staged draft. Configs are validated against the section registry; nothing is saved if any operation is invalid. The live storefront does not change until publish. Requires `Idempotency-Key`.\n\nRequires API key scope: stores:update.","method":"PATCH","path":"/api/v1/stores/{id}/draft","scopes":["stores:update"],"idempotent":true,"paginated":false,"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Path parameter `id` (identifier or slug)."},"name":{"type":"string","minLength":1,"maxLength":100},"theme":{"type":"object","properties":{"primary_color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"secondary_color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accent_color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"background_color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"text_color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"muted_text_color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"border_color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"card_background_color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"price_color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"font_family":{"type":"string","minLength":1,"maxLength":80},"heading_font":{"type":"string","minLength":1,"maxLength":80},"border_radius":{"type":"integer","minimum":0,"maximum":32},"card_border_width":{"type":"integer","minimum":0,"maximum":4},"card_shadow":{"type":"string","enum":["none","sm","md","lg","xl"]},"button_style":{"type":"string","enum":["rounded","pill","sharp"]},"content_width":{"type":"string","enum":["boxed","full"]},"logo_url":{"type":"string","maxLength":2000,"description":"https or root-relative image URL (e.g. from `confirm_store_media_upload`); empty clears it."}},"additionalProperties":false},"ops":{"maxItems":25,"type":"array","items":{"oneOf":[{"type":"object","properties":{"op":{"type":"string","const":"add_section"},"type":{"type":"string","maxLength":60},"page":{"description":"Default `home`.","type":"string","enum":["home","listing","product","cart","checkout","shipping","account","order","confirmation","access","games","broadcast","mystery-box","arcade"]},"position":{"description":"0-based position among the page's sections; default appends before the footer.","type":"integer","minimum":0,"maximum":80},"after_id":{"type":"string","maxLength":120},"visible":{"type":"boolean"},"config":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Field values keyed by section registry field key (the store's default-language copy). Optional `i18n`: `{ \"<lang>\": { \"<fieldKey>\": value } }` with copy for other store languages, translatable fields only (see `GET /api/v1/store-capabilities`)."}},"required":["op","type"],"additionalProperties":false},{"type":"object","properties":{"op":{"type":"string","const":"update_section"},"id":{"type":"string","maxLength":120},"visible":{"type":"boolean"},"config":{"description":"Shallow-merged into the existing config. `i18n` merges per language: a language sent replaces its overlay, `{}` removes it, omitted languages are kept.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["op","id"],"additionalProperties":false},{"type":"object","properties":{"op":{"type":"string","const":"remove_section"},"id":{"type":"string","maxLength":120}},"required":["op","id"],"additionalProperties":false},{"type":"object","properties":{"op":{"type":"string","const":"move_section"},"id":{"type":"string","maxLength":120},"position":{"type":"integer","minimum":0,"maximum":80}},"required":["op","id","position"],"additionalProperties":false}]}},"idempotency_key":{"description":"Optional. Reuse the same value to safely retry this exact call without duplicating its effect. Auto-generated when omitted.","type":"string","minLength":1,"maxLength":64}},"required":["id"]}}]}