{ "openapi": "3.0.3", "info": { "title": "Ticketlayer Live API", "version": "0.1.0", "description": "Live-only superset endpoints (`/session` and `/queue`). The `/sales/*` surface is mirrored from Backstage and is not described here." }, "paths": { "/session": { "post": { "operationId": "createLiveSession", "x-sdk-method": "start", "summary": "Bootstrap a Live session", "description": "Resolves the channel and mints a session that holds the channel’s publishable key server-side. Hosted callers (channel resolved from the Host header or an explicit `domain`) receive an httpOnly cookie; embed callers (providing a `channelKey`) receive the session id in the body.", "tags": [ "Session" ], "x-tl-surface": "live", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionBody" } } } }, "responses": { "201": { "description": "Session created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/CreateSessionData" }, "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } }, "required": [ "status", "data", "metadata" ] } } } }, "400": { "description": "The channel could not be resolved (no host)." }, "404": { "description": "No channel is configured for this site." } } }, "get": { "operationId": "getLiveSession", "x-sdk-method": "current", "summary": "Get the current session", "description": "Returns the current session’s customer and cart state.", "tags": [ "Session" ], "x-tl-surface": "live", "responses": { "200": { "description": "The current session state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/GetSessionData" }, "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } }, "required": [ "status", "data", "metadata" ] } } } }, "401": { "description": "No valid session." } } }, "delete": { "operationId": "deleteLiveSession", "x-sdk-method": "end", "summary": "Destroy the current session", "description": "Signs out and drops the current session.", "tags": [ "Session" ], "x-tl-surface": "live", "responses": { "204": { "description": "Session destroyed." }, "401": { "description": "No valid session." } } } }, "/session/order-access": { "post": { "operationId": "attachLiveOrderAccess", "x-sdk-method": "attachOrderAccess", "summary": "Attach an order access token to the session", "description": "Proves possession of an order by reading it upstream with the emailed order access token, then holds the token in the session so `GET /sales/orders/{orderId}` (and ticket downloads) work without the browser keeping it. Creates the session on a cold open, exactly like `POST /session`.", "tags": [ "Session" ], "x-tl-surface": "live", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachOrderAccessBody" } } } }, "responses": { "200": { "description": "Token attached to the existing session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/AttachOrderAccessData" }, "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } }, "required": [ "status", "data", "metadata" ] } } } }, "201": { "description": "Token attached to a session created by this call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/AttachOrderAccessData" }, "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } }, "required": [ "status", "data", "metadata" ] } } } }, "400": { "description": "Missing fields, or the token does not open that order (INVALID_ORDER_ACCESS)." }, "404": { "description": "No session and no channel is configured for this site." } } } }, "/queue/status": { "get": { "operationId": "getLiveQueueStatus", "x-sdk-method": "status", "summary": "Get waiting-room status", "description": "Returns the waiting-room status for the current session. The waiting room lives only in Live; when disabled the queue is transparent and every session is admitted.", "tags": [ "Queue" ], "x-tl-surface": "live", "responses": { "200": { "description": "The current queue status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/QueueStatusData" }, "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } }, "required": [ "status", "data", "metadata" ] } } } }, "401": { "description": "No valid session." } } } }, "/queue/join": { "post": { "operationId": "joinLiveQueue", "x-sdk-method": "join", "summary": "Join the waiting room", "description": "Joins the current session to the waiting room. While the queue is disabled this is a no-op that reports immediate admission.", "tags": [ "Queue" ], "x-tl-surface": "live", "responses": { "200": { "description": "The session’s queue state after joining.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/QueueJoinData" }, "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } }, "required": [ "status", "data", "metadata" ] } } } }, "401": { "description": "No valid session." } } } }, "/sales/listings": { "get": { "summary": "List active listings", "operationId": "listSalesListings", "description": "What is on sale through this channel right now. The channel is resolved from the key, never from a parameter.", "tags": [ "Sales Listings" ], "x-sdk-method": "list", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "responses": { "200": { "description": "Listings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSalesListingsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/customer-auth/magic-link": { "post": { "summary": "Request magic link", "operationId": "requestSalesMagicLink", "description": "Start a magic-link sign-in for a customer. Always reports success - account existence is never revealed.", "tags": [ "Sales Customer Auth" ], "x-sdk-method": "magicLink", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "minLength": 5, "maxLength": 50 } } } } } }, "responses": { "200": { "description": "Magic link request accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesMagicLinkResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/customer-tokens": { "post": { "summary": "Exchange identity proof for customer token", "operationId": "createSalesCustomerToken", "description": "Exchange an identity proof (magic-link code or partner assertion) for a short-lived customer token bound to this channel. Identity is exchanged, never asserted.", "tags": [ "Sales Customer Tokens" ], "x-sdk-method": "create", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "proof": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "magic_link" ] }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "code" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "partner_assertion" ] }, "assertion": { "type": "string", "minLength": 1 } }, "required": [ "type", "assertion" ] } ] } }, "required": [ "proof" ] } } } }, "responses": { "200": { "description": "Customer token issued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCustomerTokenResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/carts": { "post": { "summary": "Create cart", "operationId": "createSalesCart", "description": "Create a cart on this channel. Customer identity comes only from a verified customer token, never from the body.", "tags": [ "Sales Carts" ], "x-sdk-method": "create", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": {} } } } } } }, "responses": { "201": { "description": "Cart created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCartResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/carts/{cartId}": { "get": { "summary": "Get cart", "operationId": "getSalesCart", "description": "Get a cart with its items", "tags": [ "Sales Carts" ], "x-sdk-method": "get", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "cartId", "in": "path" } ], "responses": { "200": { "description": "Cart retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCartResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/carts/{cartId}/items": { "post": { "summary": "Add cart item", "operationId": "addSalesCartItem", "description": "Add an item to the cart, taking a real inventory reservation with the channel's TTL", "tags": [ "Sales Carts" ], "x-sdk-method": "addItem", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "cartId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eventOccurrenceId": { "type": "string", "minLength": 1 }, "categoryId": { "type": "string", "minLength": 1 }, "ticketTypeId": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 50 }, "eventLayoutAreaId": { "type": "string", "minLength": 1 }, "eventLayoutSeatIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50 } }, "required": [ "eventOccurrenceId", "categoryId", "ticketTypeId" ] } } } }, "responses": { "201": { "description": "Item added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCartResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/carts/{cartId}/items/{itemId}": { "delete": { "summary": "Remove cart item", "operationId": "removeSalesCartItem", "description": "Remove an item from the cart, releasing its reservation", "tags": [ "Sales Carts" ], "x-sdk-method": "removeItem", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "cartId", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "itemId", "in": "path" } ], "responses": { "200": { "description": "Item removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCartResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/carts/{cartId}/checkout": { "post": { "summary": "Checkout cart", "operationId": "checkoutSalesCart", "description": "Convert the cart into an order. Returns an order access token for possession-based guest access (confirmation page, payment status polling).", "tags": [ "Sales Carts" ], "x-sdk-method": "checkout", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "cartId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerNotes": { "type": "string", "maxLength": 2000 }, "metadata": { "type": "object", "additionalProperties": {} }, "customer": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "maxLength": 100 }, "lastName": { "type": "string", "maxLength": 100 }, "phone": { "type": "string", "minLength": 5, "maxLength": 50 }, "marketingConsent": { "type": "boolean" } }, "required": [ "email" ] } } } } } }, "responses": { "200": { "description": "Cart checked out successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCheckoutResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/my-orders": { "get": { "summary": "List my orders", "operationId": "listMySalesOrders", "description": "The verified customer's own orders. Requires a customer token - orders cannot be listed with key or possession credentials alone.", "tags": [ "Sales My Orders" ], "x-sdk-method": "list", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "responses": { "200": { "description": "Orders retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMySalesOrdersResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/orders/{orderId}": { "get": { "summary": "Get order", "operationId": "getSalesOrder", "description": "Get an order on this channel. Access requires a secret key (own channel), an X-Order-Access-Token header (guest possession) or a customer token (own orders).", "tags": [ "Sales Orders" ], "x-sdk-method": "get", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "orderId", "in": "path" } ], "responses": { "200": { "description": "Order retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSalesOrderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/orders/{orderId}/passes/{passId}/ticket.pdf": { "get": { "summary": "Download a ticket PDF", "operationId": "getSalesOrderTicketPdf", "description": "Render and stream a pass as a PDF ticket (application/pdf) for the holder. Order-access gated. Browsers fetch this directly rather than through the typed SDK.", "tags": [ "Sales Orders" ], "x-sdk-method": "ticketPdf", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "example": "ord_abc123xyz789" }, "required": true, "name": "orderId", "in": "path" }, { "schema": { "type": "string", "example": "pas_7D6SYiF0oExsH1aYwtsv" }, "required": true, "name": "passId", "in": "path" } ], "responses": { "200": { "description": "PDF ticket (application/pdf)" }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/orders/{orderId}/payments": { "post": { "summary": "Create order payment", "operationId": "createSalesOrderPayment", "description": "Initiate payment for the order's outstanding balance through the channel's payment provider", "tags": [ "Sales Order Payments" ], "x-sdk-method": "create", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "orderId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "online_card", "online_bank_transfer", "online_wallet" ] }, "returnUrl": { "type": "string", "format": "uri" } } } } } }, "responses": { "201": { "description": "Payment initiated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSalesOrderPaymentResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/orders/{orderId}/refund-requests": { "post": { "summary": "Request refund or exchange", "operationId": "createSalesOrderRefundRequest", "description": "File a refund or exchange request for the order within the resolved refund policy. Requester identity is derived from the credential, never from the body.", "tags": [ "Sales Refund Requests" ], "x-sdk-method": "create", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "orderId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refund", "exchange" ] }, "reason": { "type": "string", "maxLength": 2000 } }, "required": [ "type" ] } } } }, "responses": { "201": { "description": "Refund request created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSalesRefundRequestResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/customers": { "post": { "summary": "Create customer", "operationId": "createSalesCustomer", "description": "Provenance-scoped channel CRM (secret keys only). Reuses the org's existing record for the email and grants the channel access; there is no list or search.", "tags": [ "Sales Customers" ], "x-sdk-method": "create", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "maxLength": 255 }, "lastName": { "type": "string", "maxLength": 255 }, "phone": { "type": "string", "maxLength": 50 }, "marketingConsent": { "type": "boolean" } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "Customer created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCustomerResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/customers/{customerId}": { "get": { "summary": "Get customer", "operationId": "getSalesCustomer", "description": "Get a customer the channel holds an access grant for (created through it, or who bought through it)", "tags": [ "Sales Customers" ], "x-sdk-method": "get", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "customerId", "in": "path" } ], "responses": { "200": { "description": "Customer retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCustomerResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update customer", "operationId": "updateSalesCustomer", "description": "Update a customer the channel holds an access grant for. The update surface is deliberately small - email changes go through the org's staff.", "tags": [ "Sales Customers" ], "x-sdk-method": "update", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "customerId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 255 }, "lastName": { "type": "string", "maxLength": 255 }, "phone": { "type": "string", "maxLength": 50 } } } } } }, "responses": { "200": { "description": "Customer updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCustomerResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/presale-codes/redeem": { "post": { "summary": "Redeem presale code", "operationId": "redeemSalesPresaleCode", "description": "A verified customer redeems a presale code for its benefit; gated pricing unlocks immediately. Requires a customer token.", "tags": [ "Sales Presale Codes" ], "x-sdk-method": "redeem", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Presale code redeemed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemSalesPresaleCodeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/customer-tokens/refresh": { "post": { "summary": "Refresh a customer token", "operationId": "refreshSalesCustomerToken", "description": "Re-signs a still-valid customer token (presented via X-Customer-Token) for a fresh 30 minutes, carrying the original 24-hour absolute ceiling forward. Once the ceiling passes the customer must re-authenticate.", "tags": [ "Sales Customer Tokens" ], "x-sdk-method": "refresh", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "responses": { "200": { "description": "Customer token refreshed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCustomerTokenResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/channel": { "get": { "summary": "Resolve a channel by domain", "operationId": "resolveSalesChannel", "description": "Public tenant resolution for hosted surfaces: maps a hostname (the channel's configured subdomain or custom domain) to its channel summary and publishable key. No authentication; rate-limited.", "tags": [ "Sales" ], "x-sdk-method": "resolveChannel", "x-tl-surface": "sales", "parameters": [ { "schema": { "type": "string", "example": "tickets.acmevenue.com", "description": "The hostname to resolve" }, "required": true, "description": "The hostname to resolve", "name": "domain", "in": "query" } ], "responses": { "200": { "description": "Channel resolved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesResolveChannelResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/events/{eventId}": { "get": { "summary": "Get event catalogue detail", "operationId": "getSalesEvent", "description": "Catalogue detail for an event listed on this channel: occurrences with their priced ticket-type offers. Benefit-gated types are included only when the request carries a customer token holding the benefit. Returns 404 if the event is not listed on this channel.", "tags": [ "Sales" ], "x-sdk-method": "get", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "The event ID" }, "required": true, "description": "The event ID", "name": "eventId", "in": "path" } ], "responses": { "200": { "description": "Event detail retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesEventDetailResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/theme": { "get": { "summary": "Get channel theme", "operationId": "getSalesTheme", "description": "The channel's resolved (inheritance-merged) theme for SSR injection. Returns 404 if the channel has neither its own theme nor an organisation base theme.", "tags": [ "Sales" ], "x-sdk-method": "getTheme", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "responses": { "200": { "description": "Theme retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesThemeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } } }, "components": { "schemas": { "SessionCustomer": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_123" }, "email": { "type": "string", "format": "email", "example": "visitor@example.com" }, "firstName": { "type": "string", "nullable": true, "example": "Ada" }, "lastName": { "type": "string", "nullable": true, "example": "Lovelace" } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "A minimal customer view mirrored from the sales surface." }, "CreateSessionData": { "type": "object", "properties": { "sessionToken": { "type": "string", "description": "Present for embed callers only. Hosted callers receive the session in an httpOnly cookie and may ignore this. Send it back as the X-Live-Session header." }, "channel": { "type": "object", "properties": { "id": { "type": "string", "example": "sch_123" }, "name": { "type": "string", "example": "Main Box Office" }, "slug": { "type": "string", "example": "main-box-office" } }, "required": [ "id" ] }, "customer": { "allOf": [ { "$ref": "#/components/schemas/SessionCustomer" }, { "nullable": true } ] } }, "required": [ "channel", "customer" ] }, "ResponseMetadata": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Correlation id for this request." } }, "required": [ "requestId" ] }, "CreateSessionBody": { "type": "object", "properties": { "channelKey": { "type": "string", "description": "Embed mode: the channel publishable key (tlpk_…). When omitted, the channel is resolved from the Host header (hosted mode).", "example": "tlpk_live_abc123" }, "domain": { "type": "string", "description": "Hosted mode: an explicit domain to resolve the channel from, overriding the Host header.", "example": "tickets.example.com" } } }, "GetSessionData": { "type": "object", "properties": { "channel": { "type": "object", "properties": { "id": { "type": "string", "example": "sch_123" } }, "required": [ "id" ] }, "customer": { "allOf": [ { "$ref": "#/components/schemas/SessionCustomer" }, { "nullable": true } ] }, "authenticated": { "type": "boolean", "description": "True once the visitor has authenticated." }, "cartId": { "type": "string", "nullable": true, "description": "The active cart, if any." } }, "required": [ "channel", "customer", "authenticated", "cartId" ] }, "AttachOrderAccessData": { "type": "object", "properties": { "orderId": { "type": "string", "example": "ord_123" }, "sessionToken": { "type": "string", "description": "Present only when the call created the session (a cold open). Hosted browser callers receive the cookie instead and can ignore it.", "example": "7f0c2c1e-2d7e-4f2a-9a5e-2d2d8f7c9b1a" } }, "required": [ "orderId" ] }, "AttachOrderAccessBody": { "type": "object", "properties": { "orderId": { "type": "string", "description": "The order the token grants access to.", "example": "ord_123" }, "token": { "type": "string", "description": "The order access token from the \"view your tickets\" email link. Held server-side from then on; never echoed back.", "example": "oat_…" }, "channelKey": { "type": "string", "description": "Embed mode, when no session exists yet: the channel publishable key (tlpk_…). Otherwise the channel is resolved from the Host header.", "example": "tlpk_live_abc123" }, "domain": { "type": "string", "description": "Hosted mode, when no session exists yet: an explicit domain to resolve the channel from, overriding the Host header.", "example": "tickets.example.com" } }, "required": [ "orderId", "token" ] }, "QueueStatusData": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the waiting room is armed." }, "admitted": { "type": "boolean", "description": "Whether this session is admitted. While the queue is disabled everyone is transparently admitted." }, "position": { "type": "number", "nullable": true, "description": "Position in the queue, when waiting." }, "estimatedWaitSeconds": { "type": "number", "nullable": true, "description": "Estimated wait in seconds, when waiting." } }, "required": [ "enabled", "admitted", "position", "estimatedWaitSeconds" ] }, "QueueJoinData": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the waiting room is armed." }, "admitted": { "type": "boolean", "description": "Whether this session is admitted." }, "position": { "type": "number", "nullable": true, "description": "Position in the queue, when waiting." } }, "required": [ "enabled", "admitted", "position" ] }, "GetSalesListingsResponse": { "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/SalesChannelSummary" }, "listings": { "type": "array", "items": { "$ref": "#/components/schemas/SalesListing" } } }, "required": [ "channel", "listings" ] }, "SalesMagicLinkResponse": { "type": "object", "properties": { "sent": { "type": "boolean", "example": true, "description": "Always true - success is reported regardless of whether the contact exists (no account enumeration)" } }, "required": [ "sent" ] }, "SalesCustomerTokenResponse": { "type": "object", "properties": { "customerToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIs..." }, "expiresIn": { "type": "number", "example": 1800, "description": "Token lifetime in seconds" }, "customer": { "$ref": "#/components/schemas/SalesCustomer" } }, "required": [ "customerToken", "expiresIn", "customer" ] }, "SalesCartResponse": { "type": "object", "properties": { "cart": { "$ref": "#/components/schemas/SalesCart" } }, "required": [ "cart" ] }, "SalesCheckoutResponse": { "type": "object", "properties": { "cart": { "$ref": "#/components/schemas/SalesCart" }, "order": { "$ref": "#/components/schemas/SalesOrder" }, "orderAccessToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIs...", "description": "Possession-based guest access token for reading/paying this order without a customer login" } }, "required": [ "cart", "order", "orderAccessToken" ] }, "ListMySalesOrdersResponse": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/SalesOrder" } } }, "required": [ "orders" ] }, "GetSalesOrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/SalesOrder" } }, "required": [ "order" ] }, "CreateSalesOrderPaymentResponse": { "type": "object", "properties": { "payment": { "$ref": "#/components/schemas/SalesPayment" } }, "required": [ "payment" ] }, "CreateSalesRefundRequestResponse": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/SalesRefundRequest" } }, "required": [ "request" ] }, "SalesCustomerResponse": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/SalesCustomer" } }, "required": [ "customer" ] }, "RedeemSalesPresaleCodeResponse": { "type": "object", "properties": { "benefit": { "type": "string", "example": "presale.summer-gala" }, "alreadyHeld": { "type": "boolean", "example": false, "description": "True if the customer already held this benefit" } }, "required": [ "benefit", "alreadyHeld" ] }, "SalesResolveChannelResponse": { "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/SalesChannelSummary" }, "publishableKey": { "type": [ "string", "null" ], "example": "tlpk_abc123", "description": "The channel's active publishable key (public by design), or null if none is issued" } }, "required": [ "channel", "publishableKey" ] }, "SalesEventDetailResponse": { "type": "object", "properties": { "event": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "subtitle": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "heroImageUrl": { "type": [ "string", "null" ] }, "presentation": { "type": [ "object", "null" ], "properties": { "heroLayout": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hero", "cinema" ] }, "size": { "type": "string", "enum": [ "small", "medium", "large" ] } }, "required": [ "type", "size" ], "additionalProperties": false }, "cinemaGradient": { "type": "object", "properties": { "strength": { "anyOf": [ { "type": "number", "enum": [ 20 ] }, { "type": "number", "enum": [ 50 ] }, { "type": "number", "enum": [ 70 ] } ] }, "position": { "type": "string", "enum": [ "bottom", "center" ] } }, "required": [ "strength", "position" ], "additionalProperties": false }, "twoColumnSplit": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ] }, "navbar": { "type": "object", "properties": { "transparent": { "type": "boolean" } }, "additionalProperties": false }, "buttonSize": { "type": "string", "enum": [ "small", "medium", "large" ] } }, "additionalProperties": false }, "venueId": { "type": [ "string", "null" ] }, "venueName": { "type": [ "string", "null" ] }, "venueCity": { "type": [ "string", "null" ] }, "priceFrom": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "occurrences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "startsAt": { "type": [ "string", "null" ] }, "endsAt": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "startDate": { "type": "string" }, "startTime": { "type": "string" }, "endDate": { "type": "string" }, "endTime": { "type": "string" }, "status": { "type": "string" }, "ticketTypes": { "type": "array", "items": { "type": "object", "properties": { "ticketTypeId": { "type": "string" }, "ticketTypeName": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "categoryId": { "type": "string" }, "categoryName": { "type": "string" }, "unitPrice": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "ticketTypeId", "ticketTypeName", "description", "categoryId", "categoryName", "unitPrice", "currency" ], "additionalProperties": false } } }, "required": [ "id", "startsAt", "endsAt", "timezone", "startDate", "startTime", "endDate", "endTime", "status", "ticketTypes" ], "additionalProperties": false } } }, "required": [ "id", "name", "subtitle", "description", "shortDescription", "status", "imageUrl", "heroImageUrl", "presentation", "venueId", "venueName", "venueCity", "priceFrom", "currency", "timezone", "occurrences" ], "additionalProperties": false } }, "required": [ "event" ] }, "SalesThemeResponse": { "type": "object", "properties": { "theme": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "object", "additionalProperties": {} }, "colors": { "type": "object", "additionalProperties": {} }, "typography": { "type": "object", "additionalProperties": {} }, "shape": { "type": "object", "additionalProperties": {} }, "design": { "type": [ "object", "null" ], "additionalProperties": {} } }, "required": [ "id", "name", "brand", "colors", "typography", "shape" ], "additionalProperties": false } }, "required": [ "theme" ] }, "SalesChannelSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, "SalesCustomer": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "firstName", "lastName" ], "additionalProperties": false }, "SalesCart": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "example": "2026-01-15T10:45:00Z" }, "orderId": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SalesCartItem" } }, "itemsSubtotal": { "type": "number" } }, "required": [ "id", "status", "currency", "expiresAt", "orderId", "items", "itemsSubtotal" ], "additionalProperties": false }, "SalesOrder": { "type": "object", "properties": { "id": { "type": "string" }, "orderNumber": { "type": "string" }, "status": { "type": "string" }, "paymentStatus": { "type": "string" }, "currency": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SalesOrderItem" } }, "subtotal": { "type": "number" }, "totalFees": { "type": "number" }, "totalTax": { "type": "number" }, "total": { "type": "number" }, "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/SalesTicket" } }, "expiresAt": { "type": [ "string", "null" ], "example": "2026-01-15T10:45:00Z" }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "orderNumber", "status", "paymentStatus", "currency", "items", "subtotal", "totalFees", "totalTax", "total", "tickets", "expiresAt", "createdAt" ], "additionalProperties": false }, "SalesPayment": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "status": { "type": "string" }, "paymentType": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "providerClientSecret": { "type": [ "string", "null" ] }, "externalPaymentUrl": { "type": [ "string", "null" ] }, "publishableKey": { "type": [ "string", "null" ] }, "connectedAccountId": { "type": [ "string", "null" ] }, "providerType": { "type": [ "string", "null" ] } }, "required": [ "id", "orderId", "status", "paymentType", "amount", "currency", "providerClientSecret", "externalPaymentUrl", "publishableKey", "connectedAccountId", "providerType" ], "additionalProperties": false }, "SalesRefundRequest": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "orderId", "type", "status", "reason", "createdAt" ], "additionalProperties": false }, "SalesListing": { "type": "object", "properties": { "id": { "type": "string" }, "eventId": { "type": "string" }, "saleStartsAt": { "type": [ "string", "null" ], "example": "2026-02-01T09:00:00Z" }, "saleEndsAt": { "type": [ "string", "null" ], "example": null }, "name": { "type": [ "string", "null" ] }, "subtitle": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "venueName": { "type": [ "string", "null" ] }, "venueCity": { "type": [ "string", "null" ] }, "priceFrom": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "nextOccurrenceAt": { "type": [ "string", "null" ] } }, "required": [ "id", "eventId", "saleStartsAt", "saleEndsAt", "name", "subtitle", "shortDescription", "imageUrl", "venueName", "venueCity", "priceFrom", "currency", "nextOccurrenceAt" ], "additionalProperties": false }, "SalesCartItem": { "type": "object", "properties": { "id": { "type": "string" }, "eventOccurrenceId": { "type": "string" }, "eventName": { "type": "string" }, "categoryName": { "type": "string" }, "ticketTypeName": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "currency": { "type": "string" }, "subtotal": { "type": "number" } }, "required": [ "id", "eventOccurrenceId", "eventName", "categoryName", "ticketTypeName", "quantity", "unitPrice", "currency", "subtotal" ], "additionalProperties": false }, "SalesOrderItem": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "subtotal": { "type": "number" } }, "required": [ "name", "description", "type", "quantity", "unitPrice", "subtotal" ], "additionalProperties": false }, "SalesTicket": { "type": "object", "properties": { "id": { "type": "string" }, "barcode": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "holderName": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "admissionStatus": { "type": "string" }, "eventOccurrenceId": { "type": [ "string", "null" ] }, "seatLabel": { "type": [ "string", "null" ] } }, "required": [ "id", "barcode", "type", "status", "holderName", "name", "admissionStatus", "eventOccurrenceId", "seatLabel" ], "additionalProperties": false } }, "parameters": {} } }