> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.todaytixgroup.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.todaytixgroup.com/_mcp/server. # Create a cart POST https://stg.ttix.io/api/v3/carts Content-Type: application/json Creates a new cart and adds inventory items to it in a single request. Holds the inventory for the customer. Send the signed-in customer's access token, as `Authorization: Bearer `, to hold the cart for them and price it for them; a cart created with no token is priced for a guest. * `AssignedSeat` variants always require `quantity: 1` (each seat is unique) * `GeneralAdmission` and `Extra` variants support `quantity > 1` * All items must be from the same event + occurrence. * A cart cannot mix general admission and assigned seats. Use a separate cart for each. Send a `currency` in the body to create the cart in that currency: the cart keeps pricing in it on later reads and the order settles in it. Omit it for base-currency prices. Send a `voucherCode` in the body to hold inventory that is hidden behind that code and to apply the code to the new cart in the same request. A well-formed code that does not match a voucher, or that cannot be applied to these items, is ignored rather than reported — the cart is created as if the field were omitted. Send `previousCartId` when the customer re-selects seats: once the new cart is created, the previous cart is released so the customer holds one set of inventory instead of stacking a fresh hold on every selection. The release is best-effort and never fails the create — a cart that cannot be released is left alone. Reference: https://docs.todaytixgroup.com/api-reference/purchase/cart/post-cart ## Authentication - `X-TT-API-Key` header (required) — API Key authentication via header ## Servers - `https://stg.ttix.io` (Staging Environment, default) - `https://api.ttix.io` (Production Environment) ## Request ### Headers - `X-TT-Platform` (enum, required) — Identifies the platform the request comes from. - Allowed values: `android`, `api`, `ios`, `web` - `X-TT-Retailer` (string, required) — Your retailer identifier, provided during onboarding. It must be a retailer your API key was issued for. ### Body (application/json) This endpoint expects a PostCartRequest. - `items` (list of CartItemRequest, required) — One or more items to reserve. All items must share the same occurrence. - `currency` (string, optional, nullable) — ISO 4217 currency to create the cart in: the cart keeps pricing in it on later reads and the order settles in it. Omit for the event base currency. - `voucherCode` (string, optional, nullable) — A promo or access code, as entered by the customer. Some inventory is hidden behind a code; sending the code here is what lets this cart hold those items — applying it after the cart exists is too late to unlock them. The code is also applied to the new cart, as POST /carts/\{cartId}/vouchers would, so the response already shows the discount. Must be 1–15 characters when sent. A well-formed code that does not match a voucher, or that cannot be applied to these items, is ignored: the cart is created as if this field were omitted and no error is returned. To find out why a code does not work, apply it with POST /carts/\{cartId}/vouchers. - `previousCartId` (string, optional, nullable) — The id of the customer's previous cart, from an earlier POST /carts — send it when the customer re-selects seats: once the new cart is created, the previous cart is released and its inventory freed. The release is best-effort and never fails the create: a cart that is unknown, already released, expired, or already turned into an order is simply left alone and the new cart is still created. When the request carries a customer access token, the other carts created with that same token are released too, on the same best-effort terms, and a cart whose order is being placed is left alone; carts the customer made with another token are not touched. Without a customer token, omit it to leave any earlier cart in place until it times out. ## Response ### 201 Cart created successfully. - `data` (CartResponse, required) — Shopping cart containing held inventory cart items. ## Errors ### 400 Bad Request Error Invalid parameters, items span multiple occurrences, the event is not currently available to book (closed, or sold only as an add-on to another event), or a requested currency this event is not sold in - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ### 401 Unauthorized Error `UNAUTHORIZED` — the API key is missing. `INVALID_API_KEY` — the API key is invalid. `INVALID_ACCESS_TOKEN` — the customer access token is invalid or has expired: refresh it and retry, or send none to continue as a guest. - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ### 403 Forbidden Error Insufficient permissions to access this resource. Any request sent from a web page gets `ORIGIN_NOT_ALLOWED` when the page's origin is not one the API key allows. Add the origin to the key, or use a key that allows it. A request with no `Origin` header, such as one from your server, is never refused for this. - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ### 409 Conflict Error Conflict — inventory already held or cart state conflict. `INVENTORY_EXHAUSTED` means the seats or tickets asked for are sold out or held by someone else; choose others. When `details.reason` is `INVENTORY_ITEM_NOT_FOUND`, an item asked for is not in the current inventory, usually because the inventory you read has changed: read inventory again, and if the items are still offered, create the cart once more. `OCCURRENCE_NOT_AVAILABLE` means sales have closed for this occurrence. `ORPHANED_SEATS` means the seats are available but holding them would leave a single seat on its own, which the ticketing system refuses; choose different seats. `PRICE_CHANGED` means the held price changed; refresh inventory, confirm the current price, and create a new cart. - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ### 429 Too Many Requests Error Too many requests. Wait at most the number of seconds in the `Retry-After` header, then send the request again. - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ### 500 Internal Server Error Internal server error - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ### 503 Service Unavailable Error `CURRENCY_TEMPORARILY_UNAVAILABLE` — the requested currency is sold here but cannot be priced right now (no exchange rate). `THIRD_PARTY_OUTAGE` — the venue's ticketing system did not respond. Both can succeed if you retry later. - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ## Types ### CartItemRequest A single inventory item to reserve in the cart - `occurrenceId` (string, required) — ID of the occurrence this item is for. - `inventoryItemId` (string, required) — Opaque inventory item ID from the GET inventory-items response - `priceOptionId` (string, required) — Opaque price option ID from the inventory item priceOptions array - `quantity` (integer, required) — Number of units to reserve. Must be greater than or equal to 1. ### CartResponse Shopping cart containing held inventory cart items. - `id` (string, required) — Cart ID. Keep it on your server: with your API key, it can read the order placed from this cart. - `expiresAt` (datetime, required) — UTC timestamp when the cart hold expires and inventory is released. Clients should display a countdown timer and warn users before expiration. - `expiresInSeconds` (integer, required) — Whole seconds left before the cart expires, as of this response. 0 once it has expired. Count this down for the timer rather than comparing expiresAt with the device clock, which can be minutes out. - `items` (list of CartItemResponse, required) — Items currently in the cart (held inventory). Each item's priceOption carries the itemized fees[] disclosure. Protection and credits are NOT items — see receiptLines. - `receiptLines` (list of ReceiptLineResponse, required) — Lines to show on the receipt, already in display order: render them in the order given. Always includes a subtotal line; the other line types appear only when they apply. A fee charged per item is never a receipt line — it is disclosed per item on priceOption.fees. A fee charged once per order, such as an order fee, is a fee line. - `total` (Money, required) — Amount the order will charge. Worked out again on every read, so it can change while the cart is open: read the cart just before checkout and send this value as expectedTotal on POST /orders. Leave out the currency query parameter on that read: a re-quote in another currency does not change the cart's currency, so its total fails checkout. - `protection` (ProtectionResponse, optional, nullable) — Protection covering all items. Null if not added. - `options` (CartOptionsResponse, optional) — Choices for this cart, such as the currencies it can be priced in, the payment methods it accepts and the extras that can be added. - `voucher` (VoucherResponse, optional, nullable) — Voucher code applied to the cart. Null if none applied. - `totalTaxes` (Money, optional) — DISCLOSURE ONLY — taxes already included in total. Omitted when the cart carries no tax. ### ErrorResponse What went wrong: `type` and `code` for your code to act on, `message` to display. - `type` (enum, required) — High-level error category. - Allowed values: `INVALID_REQUEST_ERROR`, `AUTHENTICATION_ERROR`, `PAYMENT_ERROR`, `PERMISSION_ERROR`, `NOT_FOUND_ERROR`, `METHOD_NOT_ALLOWED_ERROR`, `CONFLICT_ERROR`, `RESOURCE_GONE_ERROR`, `PRECONDITION_FAILED_ERROR`, `UNSUPPORTED_MEDIA_TYPE_ERROR`, `PRECONDITION_REQUIRED_ERROR`, `RATE_LIMIT_ERROR`, `API_ERROR`, `SERVICE_UNAVAILABLE` - `code` (enum, required) — Machine-readable error code. - Allowed values: `METHOD_NOT_ALLOWED`, `UNSUPPORTED_MEDIA_TYPE`, `INVALID_FIELD_VALUE`, `ACCESS_CARD_NOT_VERIFIED`, `ACCESS_CARD_WRONG_SCHEME`, `ACCESS_VERIFICATION_NOT_SUPPORTED`, `ACCESS_VERIFICATION_UNAVAILABLE`, `TICKET_ALERT_SIGNUP_NOT_SUPPORTED`, `MIXED_ITEM_TYPES_NOT_SUPPORTED`, `INVALID_VOUCHER`, `CURRENCY_NOT_SUPPORTED`, `CURRENCY_TEMPORARILY_UNAVAILABLE`, `MISSING_REQUIRED_HEADER`, `MISSING_REQUIRED_FIELD`, `UNAUTHORIZED`, `INVALID_API_KEY`, `INVALID_ACCESS_TOKEN`, `PAYMENT_AUTHENTICATION_REQUIRED`, `PAYMENT_DECLINED`, `RISK_CHECK_FAILED`, `APPLE_PAY_NOT_AVAILABLE`, `APPLE_PAY_SESSION_UNAVAILABLE`, `INVALID_REQUEST`, `RESOURCE_NOT_FOUND`, `INSUFFICIENT_PERMISSIONS`, `ORIGIN_NOT_ALLOWED`, `RATE_LIMITED`, `INTERNAL_SERVER_ERROR`, `SERVICE_UNAVAILABLE`, `PRICE_CHANGED`, `INVENTORY_EXHAUSTED`, `OCCURRENCE_NOT_AVAILABLE`, `OCCURRENCE_NOT_COMPATIBLE`, `ORPHANED_SEATS`, `INVALID_PRICE_OPTION`, `MIXED_OCCURRENCES_NOT_SUPPORTED`, `EVENT_NOT_SELLABLE`, `MIXED_PRODUCT_TYPES_NOT_SUPPORTED`, `MULTIPLE_GIFT_CARDS_NOT_SUPPORTED`, `GIFT_CARD_QUANTITY_NOT_SUPPORTED`, `MINIMUM_QUANTITY_NOT_MET`, `EVENT_MINIMUM_NOT_MET`, `VOUCHER_NOT_APPLICABLE_TO_GIFT_CARD`, `CART_EXPIRED`, `EXPECTED_TOTAL_MISMATCH`, `TICKET_LIMIT_EXCEEDED`, `PAYMENT_METHOD_NOT_AVAILABLE`, `CART_ALREADY_ORDERED`, `CART_CUSTOMER_REQUIRED`, `CART_ALREADY_CLAIMED`, `INVALID_IDEMPOTENCY_KEY`, `IDEMPOTENCY_KEY_ALREADY_PROCESSING`, `IDEMPOTENCY_KEY_CART_MISMATCH`, `IDEMPOTENCY_KEY_FAILED`, `GRANT_NOT_CLAIMABLE`, `GRANT_NOT_CANCELLABLE`, `WALLET_PASS_DOWNLOAD_BLOCKED`, `ACTION_NOT_AVAILABLE`, `WALLET_PASS_CHANGED`, `WALLET_PASS_NOT_ISSUED`, `WALLET_PASS_REPLACEMENT_NOT_SUPPORTED`, `WALLET_PASS_REPLACEMENT_UNFINISHED`, `WALLET_PASS_REPLACEMENT_NEEDS_SUPPORT`, `VERSION_REQUIRED`, `THIRD_PARTY_OUTAGE` - `message` (string, required) — Human-readable description of the error. - `param` (string, optional, nullable) — The request field that caused the error, if applicable. - `details` (map from string to ErrorResponseDetails, optional, nullable) — Additional structured data for client recovery logic. ### CartItemResponse A reserved unit of inventory in the shopping cart - `id` (string, required) — Opaque identifier for this cart item, unique within the cart. Echo it back to change or remove the item. It identifies the line, not the inventory, so it survives a quantity change and two items of the same extra at different price options have different ids. - `event` (EventSimpleResponse, required) — Event the inventory belongs to - `occurrence` (ItemOccurrenceResponse, required) — Occurrence the inventory belongs to - `venue` (VenueResponse, required) — The venue where this occurrence takes place - `inventoryVariant` (InventoryVariantResponse, required) — What was added to the cart: a seat, general admission area, extra or gift card - `priceOption` (PriceOptionResponse, required) — The selected price option - `quantity` (integer, required) — Number of units reserved - `delivery` (DeliveryResponse, optional, nullable) — How tickets for this item will be delivered. Null when delivery details are unavailable. ### ReceiptLineResponse Lines to show on the receipt, already in display order: render them in the order given. Always includes a subtotal line; the other line types appear only when they apply. A fee charged per item is never a receipt line — it is disclosed per item on priceOption.fees. A fee charged once per order, such as an order fee, is a fee line. - `label` (string, required) — Text to display for this line. - `total` (Money, required) — Amount for this line. Never negative; `sign` gives the direction. - `sign` (enum, required) — Display direction (positive = charge, negative = credit/discount). - Allowed values: `positive`, `negative` - `_type` (enum, required) — Discriminator for the line type. - Allowed values: `SubtotalLine`, `FeeLine`, `VoucherLine`, `ProtectionLine`, `CreditLine` ### Money Monetary amount: an integer in minor units (cents for USD) with its currency code. - `amount` (long, required) — Amount in minor units (cents for USD, pence for GBP, etc.) - `currency` (string, required) — ISO 4217 currency code ### ProtectionResponse Protection covering all items. Null if not added. - `id` (string, required) — Unique identifier for this protection. - `pricePerItem` (Money, required) — Per-ticket protection rate. - `total` (Money, required) — Total protection cost (pricePerItem × number of tickets). - `status` (enum, optional, nullable) — Protection redemption status (Order only, omitted in Cart). ELIGIBLE — protection purchased, redemption window open. REDEEMED — user claimed the protection (terminal). EXPIRED — redemption window closed (terminal). - Allowed values: `ELIGIBLE`, `REDEEMED`, `EXPIRED` ### CartOptionsResponse Options that can be applied to this cart. Each key is present only when that option is available. - `currencies` (list of string, optional) — Currencies this cart can be priced in, as ISO 4217 codes. The first entry is the default currency. Re-request the cart with the `currency` query parameter set to one of these values to quote it in that currency, or switch the cart with PATCH to settle in it. - `paymentMethods` (list of PaymentMethodOptionResponse, optional) — Payment methods a customer can select for this cart, in priority order. Render them in the order given. `INVOICE` is listed only when the seller settles on account and the caller may pay on account: a secret key on its own, or a secret key with an on-account access token. A customer token never can. Empty when the seller can't take payment for this cart, so a cart with a balance to pay can't be ordered. `NONE`, for an order with nothing to pay, is never listed. - `extras` (list of InventoryItemResponse, optional) — Extras that can be added to this cart, such as merchandise, drinks, or parking. Each entry is an inventory item — add one to the cart through the cart items endpoint using its id and a price option id. Empty when the event offers no extras. ### VoucherResponse A voucher code applied to a cart. - `code` (string, required) — The voucher code as entered by the customer. - `discount` (Money, required) — Amount this code reduces from the cart total, shown as its own receipt line. Zero when the reduction is already taken off the subtotal instead. ### ErrorResponseDetails Additional structured data for client recovery logic. ### EventSimpleResponse Lightweight event reference - `id` (string, required) — Event ID - `name` (string, required) — Display name of the event ### ItemOccurrenceResponse The occurrence a cart or order item is for, with its doors-open time and notices. - `id` (string, required) — Occurrence ID - `startsAt` (datetime, required) — Start date and time in the venue's local timezone (ISO 8601 with offset). - `doorsOpen` (DoorsOpenResponse, optional, nullable) — When doors open at the venue before the occurrence starts. Omitted when no doors-open time is available. - `notices` (list of NoticeResponse, optional) — Notices about this occurrence, such as cast changes or accessibility services. Omitted when there are none. ### VenueResponse Venue where the occurrence takes place - `id` (string, optional, nullable) — Stable venue identifier. - `name` (string, optional, nullable) — Display name of the venue - `address` (AddressResponse, optional, nullable) — Structured postal address. Omitted when address data is unavailable. - `timezone` (string, optional, nullable) — IANA timezone identifier for the venue. Used for datetime display and calendar integration. ### InventoryVariantResponse A seat, general admission area, extra or gift card. `_type` says which. - `_type`: `AssignedSeat` (AssignedSeat) - `attributes` (list of InventoryAttributeResponse, required) — Attributes describing characteristics of this inventory variant (e.g. legroom, accessibility, VIP perks). - `id` (string, required) — Stable identifier for this inventory variant. The same variant has the same id on every occurrence of the event, so a seat can be matched to the seating chart. A seat or general admission area has the same id in inventory items, carts and orders. - `name` (string, required) — Human-readable label for this inventory variant. Stable across occurrences and safe for display in UI. - `row` (string, required) — Row identifier within the section. - `seat` (string, required) — Seat number within the row. - `section` (string, required) — Section name within the venue. - `description` (string, optional, nullable) — Short plain-text copy about this variant, shown next to the name at seat selection and on the ticket. Omitted when the seller has not written any. - `entrance` (string, optional, nullable) — Where the ticket holder enters the venue, such as a door or gate. Omitted when the venue does not assign one. - `extendedDescription` (string, optional, nullable) — Longer copy about this variant as rich text, which may contain HTML or Markdown markup. Sanitize before rendering it as HTML. Shown in place of description where the client supports rich text. Omitted when the seller has not written any. - `images` (list of ViewFromSeatImage, optional) — Views of the stage from this seat, in the order the venue lists them. Present only on inventory items requested with `include=IMAGES`, and empty for a seat with no images. - `_type`: `GeneralAdmission` (GeneralAdmission) - `attributes` (list of InventoryAttributeResponse, required) — Attributes describing characteristics of this inventory variant (e.g. legroom, accessibility, VIP perks). - `id` (string, required) — Stable identifier for this inventory variant. The same variant has the same id on every occurrence of the event, so a seat can be matched to the seating chart. A seat or general admission area has the same id in inventory items, carts and orders. - `name` (string, required) — Human-readable label for this inventory variant. Stable across occurrences and safe for display in UI. - `description` (string, optional, nullable) — Short plain-text copy about this variant, shown next to the name at seat selection and on the ticket. Omitted when the seller has not written any. - `extendedDescription` (string, optional, nullable) — Longer copy about this variant as rich text, which may contain HTML or Markdown markup. Sanitize before rendering it as HTML. Shown in place of description where the client supports rich text. Omitted when the seller has not written any. - `venueAreaIds` (list of string, optional, nullable) — Ids of the seating-chart areas this variant sells into, matching the area ids on the venue seating chart so a client can highlight them. Omitted when the variant is not tied to chart areas. - `_type`: `Extra` (Extra) - `attributes` (list of InventoryAttributeResponse, required) — Attributes describing characteristics of this inventory variant (e.g. legroom, accessibility, VIP perks). - `id` (string, required) — Stable identifier for this inventory variant. The same variant has the same id on every occurrence of the event, so a seat can be matched to the seating chart. A seat or general admission area has the same id in inventory items, carts and orders. - `name` (string, required) — Human-readable label for this inventory variant. Stable across occurrences and safe for display in UI. - `admissionType` (enum, optional, nullable) — How admission works for this extra when it is its own event with its own schedule. TIMED means entry on a specific day at a specific time. DATED means entry on a specific day, any time between open and close. OPEN means entry on any day at any time. SLOT means entry at any time between the start and end times. Omitted when the extra belongs to the same event as the cart or order. - Allowed values: `TIMED`, `DATED`, `OPEN`, `SLOT`, `TIMED`, `DATED`, `OPEN`, `SLOT` - `caption` (string, optional, nullable) — Short label for this extra, typically a serving size. Omitted when the seller has not written one. - `description` (string, optional, nullable) — Short plain-text copy about this variant, shown next to the name at seat selection and on the ticket. Omitted when the seller has not written any. - `extendedDescription` (string, optional, nullable) — Longer copy about this variant as rich text, which may contain HTML or Markdown markup. Sanitize before rendering it as HTML. Shown in place of description where the client supports rich text. Omitted when the seller has not written any. - `imageUrl` (string, optional, nullable) — Image shown for this extra. Omitted when the seller has not uploaded one. - `_type`: `GiftCard` (GiftCard) - `attributes` (list of InventoryAttributeResponse, required) — Attributes describing characteristics of this inventory variant (e.g. legroom, accessibility, VIP perks). - `id` (string, required) — Stable identifier for this inventory variant. The same variant has the same id on every occurrence of the event, so a seat can be matched to the seating chart. A seat or general admission area has the same id in inventory items, carts and orders. - `name` (string, required) — Human-readable label for this inventory variant. Stable across occurrences and safe for display in UI. - `description` (string, optional, nullable) — Short plain-text copy about this variant, shown next to the name at seat selection and on the ticket. Omitted when the seller has not written any. - `extendedDescription` (string, optional, nullable) — Longer copy about this variant as rich text, which may contain HTML or Markdown markup. Sanitize before rendering it as HTML. Shown in place of description where the client supports rich text. Omitted when the seller has not written any. - `value` (Money, optional, nullable) — The balance the card is issued with. Independent of `priceOptions[].sellPrice`, which is what the customer is charged: a card sold at a discount is worth its full value. Always in the currency the card can be spent in, which is the event's own currency and not the one the shopper is browsing in — a card redeems only in the currency it was issued in. Absent on a listed card whose amount the buyer chooses; in a cart or order it is the amount they chose. ### PriceOptionResponse A single purchasable price option for an inventory item. - `category` (PriceCategoryResponse, required) — Pricing category for this option (e.g., Adult, Child). - `sellPrice` (Money, required) — Per-unit price charged to the customer, including fees and tax. On a listed gift card whose amount the buyer chooses this is the lowest amount they may choose; the card is charged at the amount they choose. - `id` (string, optional, nullable) — Unique identifier for this price option. - `constraints` (PriceOptionConstraintsResponse, optional, nullable) — Selection rules for this option, such as a category it must be bought alongside. Omitted when the option can be bought on its own, and on items that carry no selection rules, such as extras. - `listPrice` (Money, optional) — Original face value before discounts. Omitted when the option is not discounted or the saving may not be shown, and on the price option of a cart or order item. - `discountPercentage` (integer, optional, nullable) — Whole-number percentage saved, for a "Save 30%" style label (30 means 30%). Use it rather than working it out from listPrice and sellPrice, which can be priced on a different fee basis. Omitted when the option is not discounted, when the saving may not be shown, and when the event shows its saving as an amount, which discountAmount then carries. - `discountAmount` (Money, optional, nullable) — Amount saved, for a "Save $20" style label. Sent instead of discountPercentage when the event shows its saving as an amount, so never together with it. Use it rather than working it out from listPrice and sellPrice. Omitted when the option is not discounted or the saving may not be shown, and on the price option of a cart or order item. - `fees` (list of FeeResponse, optional, nullable) — Itemized fee disclosure. Every entry is a component of sellPrice — never add it to a price. Empty when the option carries no fees. Omitted entirely when the retailer or market does not require fee disclosure. - `maxQuantityPerOrder` (integer, optional, nullable) — Maximum number of units allowed in one order at this price option. The effective limit combines this with the item-level cap and quantityAvailable — use the lowest. Omitted when this price option has no cap. - `promotion` (PromotionResponse, optional, nullable) — Active promotion for this price option. Omitted when no promotion applies. - `isDefault` (boolean, optional, nullable) — True for the option a client should pre-select when the item is first shown. Omitted when false. ### DeliveryResponse How tickets for this item are delivered - `method` (DeliveryMethodResponse, required) — The delivery method - `instructions` (string, optional, nullable) — What to tell the customer about getting this item, to show beside it. On a cart item, this is the text shown before purchase, such as when the e-tickets arrive. On an order item, it is specific to that item, for example "Pickup at the bar". An item with nothing specific carries the order's general text, the same as the order's `delivery.instructions`, so the same text can repeat across items. Null when there is none. ### PaymentMethodOptionResponse A payment method a customer can select for this cart. - `method` (enum, required) — The payment method the customer can choose. - Allowed values: `AFTERPAY`, `APPLE_PAY`, `CARD`, `GOOGLE_PAY`, `INVOICE`, `KLARNA` - `gateway` (enum, optional, nullable) — The payment provider that handles this method. Present for card-based methods; omitted for invoice. - Allowed values: `ADYEN` - `merchantAccount` (string, optional, nullable) — The provider account the client needs to start an Apple Pay or Google Pay flow. It is the account the order is charged through, whatever currency the shopper pays in. Present only on wallet methods. ### InventoryItemResponse One thing you can buy for an occurrence — a seat, general admission area, extra or gift card — with the price options it is sold at. - `id` (string, required) — Opaque ID for this inventory item. Pass it whole to the cart; never build or parse it. - `inventoryVariant` (InventoryVariantResponse, required) — What is being sold: a seat, general admission area, extra or gift card (`AssignedSeat`, `GeneralAdmission`, `Extra` or `GiftCard`). - `priceOptions` (list of PriceOptionResponse, required) — Available price options. At least one option whenever `quantityAvailable` is above 0. Empty when `quantityAvailable` is 0: the item is listed for display and has no price to buy at. - `quantityAvailable` (integer, required) — Number of units currently available for purchase. 0 marks a GeneralAdmission area that has sold out but is configured to stay listed: show it as unavailable, and do not add it to a cart. - `maxQuantityPerOrder` (integer, optional, nullable) — Maximum number of units of this item allowed in one order. The effective limit is the lower of this and quantityAvailable. Omitted when there is no per-order cap. - `minQuantityPerOrder` (integer, optional, nullable) — Fewest units of this item one order may hold, counted across all its price options. Present only on an Extra that sets a minimum above 1; omitted otherwise. - `selectionGroup` (SelectionGroupResponse, optional, nullable) — The seats that must be selected together with this one when the customer picks it. The group does not always hold exactly `quantity` seats: add every listed id. Present on an AssignedSeat the party can pick when `quantity` was sent, and on a seat sold only in a fixed group (such as a box of four) whether or not it was. Omitted on GeneralAdmission and Extra items, on a seat carrying `selectionBlocked`, and on a seat that cannot be picked at the requested `quantity`. - `selectionBlocked` (SelectionBlockedResponse, optional, nullable) — Present when the request carried a `quantity` and this seat is in stock but not sold to a party of that size. Show the seat as unavailable at this quantity, keep its price on display, and do not add it to a cart; `chainSize` is the quantity that would make it purchasable. Omitted on every seat a party of the requested `quantity` can buy, and whenever no `quantity` was sent. - `requirements` (RequirementsResponse, optional, nullable) — Present only on a scheduled extra, whose own occurrence still needs picking. Its presence alone is the signal — an item without it needs no such pick. ### DoorsOpenResponse When doors open at the venue for this occurrence. - `at` (datetime, required) — Date and time when doors open, in ISO 8601 with venue timezone offset. - `description` (string, optional, nullable) — Customer-facing copy about doors opening. Omitted when there is none. ### NoticeResponse A notice about this occurrence, such as a cast change or an accessibility service. - `name` (string, required) — Short title of the notice. - `description` (string, optional, nullable) — Longer text with the detail of the notice. Omitted when there is no extra detail. ### AddressResponse Structured postal address for venue display - `line1` (string, optional, nullable) — First line of the street address - `line2` (string, optional, nullable) — Second line of the street address (suite, floor, etc.) - `city` (string, optional, nullable) — City name - `state` (string, optional, nullable) — State, province, or region - `postalCode` (string, optional, nullable) — Postal or ZIP code - `country` (string, optional, nullable) — ISO 3166-1 alpha-2 country code - `latitude` (double, optional, nullable) — Latitude coordinate - `longitude` (double, optional, nullable) — Longitude coordinate ### InventoryAttributeResponse Attributes describing characteristics of this inventory variant (e.g. legroom, accessibility, VIP perks). - `name` (string, required) — Short human-readable label for display in badges or tags. - `category` (enum, required) — Signals how clients should present this attribute: POSITIVE (perk), NEGATIVE (drawback), NEUTRAL (informational), FEATURED (highlight), ACCESSIBILITY (accessibility feature). - Allowed values: `POSITIVE`, `NEGATIVE`, `NEUTRAL`, `FEATURED`, `ACCESSIBILITY` - `description` (string, optional, nullable) — Additional context about the attribute, shown in tooltips or detail views. ### ViewFromSeatImage A view of the stage from a seat. - `url` (string, required) — Absolute URL of the image. ### PriceCategoryResponse Category a price option is sold under (e.g. Adult, Child, Senior). - `name` (string, required) — Display name for the pricing category - `id` (string, optional, nullable) — Identifier for the category. Consistent for every option in the same response, so constraints.requiresCategory always resolves to a sibling option. Stable across occurrences for inventory managed in TodayTix; for inventory sourced from an external ticketing system, treat it as scoped to the response. Omitted when the item has a single, uncategorized price. - `description` (string, optional, nullable) — Longer descriptive text shown alongside the name. Omitted when the category has none. ### PriceOptionConstraintsResponse Selection rules for a price option. Advisory: apply them when the customer builds the order — the server does not guarantee to reject an order that breaks them. - `requiresCategory` (list of string, required) — Category ids, at least one of which must also be in the order for this option to be purchased (e.g. a Child ticket must be bought with an Adult ticket). Each id matches the category.id of another option on the same item. ### FeeResponse One itemized fee included in sellPrice. - `type` (enum, required) — The kind of fee. New fee types may be added over time — treat an unknown value as a new fee type, not an error. - Allowed values: `SERVICE_FEE`, `ORDER_FEE` - `value` (Money, required) — Per-unit fee amount. Already included in sellPrice — never add it to a price. ### PromotionResponse A promotion applied to a price option. - `id` (string, required) — Stable promotion identifier. - `name` (string, required) — Promotion display name. - `description` (string, optional, nullable) — Optional plain-text description of the promotion. ### DeliveryMethodResponse The way tickets are delivered to the customer - `name` (string, required) — Display name of the delivery method ### SelectionGroupResponse The inventory items that must be purchased together with this one. Add every id in the list to the cart when the customer selects this item. - `inventoryItemIds` (list of string, required) — Inventory item ids of every seat in the group, this item included, in seat order. Every member of a group carries the full list, so the group resolves from whichever page of the results the item appeared on. ### SelectionBlockedResponse This seat is in stock but not sold to a party of the requested `quantity`, for example because it would leave a single seat stranded. Show it as unavailable at this quantity and offer `chainSize` as the quantity that works. - `chainSize` (integer, required) — Number of seats in the unbroken run this seat belongs to. Requesting exactly this many always makes the run purchasable, so it is the quantity to offer the customer. ### RequirementsResponse Conditions the buyer must satisfy before this item can be added to a cart. - `occurrence` (OccurrenceRequirementResponse, required) — The occurrence this item belongs to must fall within these bounds. ### OccurrenceRequirementResponse The bounds within which a compatible occurrence for this item may be picked. - `earliestStart` (datetime, optional, nullable) — Earliest compatible occurrence start time, always in UTC. An occurrence starting at this time is compatible. Omitted when there is no lower bound. - `latestStart` (datetime, optional, nullable) — End of the compatible occurrence start times, always in UTC. A compatible occurrence starts before this time. Omitted when there is no upper bound. ## Examples **Request** ```json { "items": [ { "occurrenceId": "123", "inventoryItemId": "v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ", "priceOptionId": "eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0", "quantity": 1 } ] } ``` **Response** ```json { "data": { "id": "6aac14d3-5826-4da8-98b6-9e68c28629d6", "expiresAt": "2026-03-15T19:40:00Z", "expiresInSeconds": 300, "items": [ { "id": "Qm9va2luZ3Mx", "event": { "id": "123", "name": "Hamilton" }, "occurrence": { "id": "456", "startsAt": "2026-03-15T19:30:00-04:00", "doorsOpen": { "at": "2026-03-15T19:00:00-04:00", "description": "Doors open 30 minutes before the performance." }, "notices": [ { "name": "Audio-described performance", "description": "Live audio description for visually impaired patrons." } ] }, "venue": { "id": "UmljaGFyZCBSb2RnZXJzIFRoZWF0cmU", "name": "Richard Rodgers Theatre", "address": { "line1": "226 W 46th St", "line2": "Suite 200", "city": "New York", "state": "NY", "postalCode": "10036", "country": "US", "latitude": 40.759, "longitude": -73.9845 }, "timezone": "America/New_York" }, "inventoryVariant": { "_type": "AssignedSeat", "attributes": [ { "name": "Limited Legroom", "category": "NEGATIVE", "description": "Seats in this row have reduced legroom due to a safety barrier." } ], "id": "ORCHESTRA-A-101", "name": "Orchestra A 101", "row": "A", "seat": "101", "section": "Orchestra", "description": "Closest to the stage", "entrance": "Door 4", "extendedDescription": "Includes a complimentary drink. **Over 18s only.**", "images": [ { "url": "https://example.com/seat-views/orchestra-a-101-center.jpg" } ] }, "priceOption": { "category": { "name": "Adult", "id": "4471", "description": "Ages 3-12" }, "sellPrice": { "amount": 18500, "currency": "USD" }, "id": "eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0", "constraints": { "requiresCategory": [ "string" ] }, "listPrice": { "amount": 18500, "currency": "USD" }, "discountPercentage": 30, "discountAmount": { "amount": 18500, "currency": "USD" }, "fees": [ { "type": "SERVICE_FEE", "value": { "amount": 18500, "currency": "USD" } } ], "maxQuantityPerOrder": 4, "promotion": { "id": "promo-opening-week", "name": "Opening Week Special", "description": "40% off Orchestra seats for opening week performances." }, "isDefault": true }, "quantity": 1, "delivery": { "method": { "name": "E-ticket" }, "instructions": "Your e-tickets will be emailed to you before the performance." } } ], "receiptLines": [ { "label": "Subtotal", "total": { "amount": 18500, "currency": "USD" }, "sign": "positive", "_type": "SubtotalLine" } ], "total": { "amount": 18500, "currency": "USD" }, "protection": { "id": "prot_001", "pricePerItem": { "amount": 18500, "currency": "USD" }, "total": { "amount": 18500, "currency": "USD" }, "status": "ELIGIBLE" }, "options": { "currencies": [ "USD", "GBP", "EUR" ], "paymentMethods": [ { "method": "CARD", "gateway": "ADYEN", "merchantAccount": "EncoreTicketsOwnBrand" } ], "extras": [ { "id": "v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ", "inventoryVariant": { "_type": "AssignedSeat", "attributes": [ { "name": "Limited Legroom", "category": "NEGATIVE", "description": "Seats in this row have reduced legroom due to a safety barrier." } ], "id": "ORCHESTRA-A-101", "name": "Orchestra A 101", "row": "A", "seat": "101", "section": "Orchestra", "description": "Closest to the stage", "entrance": "Door 4", "extendedDescription": "Includes a complimentary drink. **Over 18s only.**", "images": [ { "url": "https://example.com/seat-views/orchestra-a-101-center.jpg" } ] }, "priceOptions": [ { "category": { "name": "Adult", "id": "4471", "description": "Ages 3-12" }, "sellPrice": { "amount": 18500, "currency": "USD" }, "id": "eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0", "constraints": { "requiresCategory": [ "string" ] }, "listPrice": { "amount": 18500, "currency": "USD" }, "discountPercentage": 30, "discountAmount": { "amount": 18500, "currency": "USD" }, "fees": [ { "type": "SERVICE_FEE", "value": { "amount": 18500, "currency": "USD" } } ], "maxQuantityPerOrder": 4, "promotion": { "id": "promo-opening-week", "name": "Opening Week Special", "description": "40% off Orchestra seats for opening week performances." }, "isDefault": true } ], "quantityAvailable": 1, "maxQuantityPerOrder": 6, "minQuantityPerOrder": 4, "selectionGroup": { "inventoryItemIds": [ "v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ", "v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDIifQ" ] }, "selectionBlocked": { "chainSize": 3 }, "requirements": { "occurrence": { "earliestStart": "2026-03-01T15:00:00Z", "latestStart": "2026-03-02T03:00:00Z" } } } ] }, "voucher": { "code": "SUMMER20", "discount": { "amount": 18500, "currency": "USD" } }, "totalTaxes": { "amount": 18500, "currency": "USD" } } } ``` **SDK Code** ```python import requests url = "https://stg.ttix.io/api/v3/carts" payload = { "items": [ { "occurrenceId": "123", "inventoryItemId": "v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ", "priceOptionId": "eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0", "quantity": 1 } ] } headers = { "X-TT-Platform": "android", "X-TT-Retailer": "YOUR_RETAILER_ID", "X-TT-API-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://stg.ttix.io/api/v3/carts'; const options = { method: 'POST', headers: { 'X-TT-Platform': 'android', 'X-TT-Retailer': 'YOUR_RETAILER_ID', 'X-TT-API-Key': '', 'Content-Type': 'application/json' }, body: '{"items":[{"occurrenceId":"123","inventoryItemId":"v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ","priceOptionId":"eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0","quantity":1}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://stg.ttix.io/api/v3/carts" payload := strings.NewReader("{\n \"items\": [\n {\n \"occurrenceId\": \"123\",\n \"inventoryItemId\": \"v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ\",\n \"priceOptionId\": \"eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0\",\n \"quantity\": 1\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-TT-Platform", "android") req.Header.Add("X-TT-Retailer", "YOUR_RETAILER_ID") req.Header.Add("X-TT-API-Key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://stg.ttix.io/api/v3/carts") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-TT-Platform"] = 'android' request["X-TT-Retailer"] = 'YOUR_RETAILER_ID' request["X-TT-API-Key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"items\": [\n {\n \"occurrenceId\": \"123\",\n \"inventoryItemId\": \"v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ\",\n \"priceOptionId\": \"eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0\",\n \"quantity\": 1\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://stg.ttix.io/api/v3/carts") .header("X-TT-Platform", "android") .header("X-TT-Retailer", "YOUR_RETAILER_ID") .header("X-TT-API-Key", "") .header("Content-Type", "application/json") .body("{\n \"items\": [\n {\n \"occurrenceId\": \"123\",\n \"inventoryItemId\": \"v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ\",\n \"priceOptionId\": \"eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0\",\n \"quantity\": 1\n }\n ]\n}") .asString(); ``` ```php request('POST', 'https://stg.ttix.io/api/v3/carts', [ 'body' => '{ "items": [ { "occurrenceId": "123", "inventoryItemId": "v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ", "priceOptionId": "eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0", "quantity": 1 } ] }', 'headers' => [ 'Content-Type' => 'application/json', 'X-TT-API-Key' => '', 'X-TT-Platform' => 'android', 'X-TT-Retailer' => 'YOUR_RETAILER_ID', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://stg.ttix.io/api/v3/carts"); var request = new RestRequest(Method.POST); request.AddHeader("X-TT-Platform", "android"); request.AddHeader("X-TT-Retailer", "YOUR_RETAILER_ID"); request.AddHeader("X-TT-API-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"items\": [\n {\n \"occurrenceId\": \"123\",\n \"inventoryItemId\": \"v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ\",\n \"priceOptionId\": \"eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0\",\n \"quantity\": 1\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-TT-Platform": "android", "X-TT-Retailer": "YOUR_RETAILER_ID", "X-TT-API-Key": "", "Content-Type": "application/json" ] let parameters = ["items": [ [ "occurrenceId": "123", "inventoryItemId": "v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ", "priceOptionId": "eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0", "quantity": 1 ] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://stg.ttix.io/api/v3/carts")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```