Create cart with items | TTG Developer Portal

import requests
url = "https://staging.todaytix.com/api/v3/carts"
payload = { "items": [
        {
            "occurrenceId": "123",
            "inventoryItemId": "eyJwcm92aWRlcklkIjo0NTYsInNlYXRJZCI6IlNUQUxMUy1BLTEifQ",
            "priceOptionId": "eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0",
            "quantity": 1
        },
        {
            "occurrenceId": "123",
            "inventoryItemId": "eyJwcm92aWRlcklkIjo0NTYsInNlYXRJZCI6IkdBLUZMT09SIn0",
            "priceOptionId": "eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0",
            "quantity": 2
        }
    ] }
headers = {
    "X-Client-Platform": "ios",
    "X-Client-Version": "3.1.0",
    "Accept-Language": "es-ES, es;q=0.9, en;q=0.8",
    "X-Request-ID": "req_abc123xyz",
    "X-TT-API-Key": "<apiKey>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "id": "123",
  "items": [
    {
      "id": "001",
      "event": {
        "id": "123",
        "name": "Hamilton",
        "category": "Musical"
      },
      "occurrence": {
        "id": "123",
        "startsAt": "2026-03-15T19:30:00-05:00"
      },
      "venue": {
        "id": "ven_richard_rodgers",
        "name": "Richard Rodgers Theatre",
        "address": {
          "line1": "226 W 46th St",
          "city": "New York",
          "country": "US",
          "line2": "Suite 200",
          "state": "NY",
          "postalCode": "10036",
          "latitude": 40.7589,
          "longitude": -73.9851
        },
        "timezone": "America/New_York"
      },
      "inventoryVariant": {
        "id": "var-seat-orch-a-101",
        "_type": "AssignedSeat",
        "attributes": [
          {
            "category": "NEGATIVE",
            "description": "Seats in this row have reduced legroom due to a safety barrier.",
            "name": "Limited Legroom"
          }
        ],
        "name": "Orchestra A 101",
        "section": "Orchestra",
        "row": "A",
        "seat": "101"
      },
      "priceOption": {
        "id": "po-adult",
        "category": {
          "name": "Adult"
        },
        "sellPrice": {
          "amount": 18500,
          "currency": "USD"
        },
        "listPrice": {
          "amount": 18500,
          "currency": "USD"
        },
        "totalFees": {
          "amount": 18500,
          "currency": "USD"
        }
      },
      "quantity": 1
    }
  ],
  "receiptLines": [
    {
      "_type": "SubtotalLine",
      "label": "string",
      "total": {
        "amount": 18500,
        "currency": "USD"
      },
      "sign": "positive"
    }
  ],
  "total": {
    "amount": 18500,
    "currency": "USD"
  },
  "expiresAt": "2026-03-15T19:40:00Z",
  "protection": {
    "id": "prot_001",
    "perTicketAmount": {
      "amount": 18500,
      "currency": "USD"
    },
    "total": {
      "amount": 18500,
      "currency": "USD"
    },
    "status": "ELIGIBLE"
  },
  "totalTaxes": {
    "amount": 18500,
    "currency": "USD"
  }
}

Creates a new cart and adds inventory items to it in a single request. Holds the inventory for the customer.

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.

Creates a new cart and adds inventory items to it in a single request. Holds the inventory for the customer. - `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.

Authentication

X-TT-API-Keystring

API key for authentication. Pass as X-TT-API-Key header.

Key prefixes:

Production: sk_live_*
Test: sk_test_*

Example: X-TT-API-Key: sk_live_abc123

API key for authentication. Pass as X-TT-API-Key header. Key prefixes: - Production: sk_live_* - Test: sk_test_* Example: X-TT-API-Key: sk_live_abc123

Headers

Request

This endpoint expects an object.

itemslist of objectsRequired

Line items to add to the cart.

Response

Cart created successfully.

idstring

Cart ID

itemslist of objects

Items currently in the cart (held inventory). Does NOT include fees, protection, or credits - see receiptLines for those.

receiptLineslist of objects

Server-ordered display lines for receipt rendering. Iterate in sequence. Always includes SubtotalLine. Conditionally: FeeLine, VoucherLine, ProtectionLine.

totalobject

Total amount to be charged at checkout (locked at cart creation). This value is used for expectedTotal validation in POST /orders.

expiresAtdatetime

UTC timestamp when the cart hold expires and inventory is released. Clients should display a countdown timer and warn users before expiration.

protectionobject or null

Protection covering all items. Null if not added.

totalTaxesobject or null

DISCLOSURE ONLY - taxes already included in total. Omitted when not disclosed (e.g., UK market).

Authentication

Headers

Request

Response

Errors