> 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.

# Getting Started

The TTG API lets you browse live entertainment events, check real-time inventory, and complete ticket purchases on behalf of your customers. This guide covers everything you need to make your first successful API call.

> This site documents the **TodayTix Group (TTG) Storefront API v3**. For widget setup and whitelabel checkout, see [developers.todaytixgroup.com](https://developers.todaytixgroup.com). Moving from an older TTG API? Start with [Why Migrate to v3](/migration/why-v3).

## Prerequisites

Before you start, you'll need two things:

- **API key** — `sk_test_*` for staging, `sk_live_*` for production (see [Managing API Keys](#managing-api-keys) below)
- **Retailer ID** — your retailer identifier, used in the `X-TT-Retailer` header (provided during onboarding)

### Managing API Keys

Generate and manage API keys from the **Settings** page in the partner portal:

| Environment | Portal URL |
|---|---|
| Staging | [portal-staging.poweredbytodaytix.com/settings](https://portal-staging.poweredbytodaytix.com/settings) |
| Production | [portal.poweredbytodaytix.com/settings](https://portal.poweredbytodaytix.com/settings) |

1. Log in to the portal.
2. Click your name in the bottom left to open **Settings**.
3. Generate an API key and copy it to a secure location — the full key is only shown once.
4. From Settings you can manage and revoke keys at any time.

> **Start in staging.** Your onboarding contact will create your portal account on staging first. Once your integration is working, request a production account to generate live keys.
>
> Each person who needs portal access requires their own account. Provide a **first name**, **last name**, and **email address** for each user to your onboarding contact.

## Base URLs

| Environment | URL | When to use |
|---|---|---|
| Staging | `https://stg.ttix.io` | Development and testing |
| Production | `https://api.ttix.io` | Live inventory and transactions |

## Authentication & Headers

Every request takes these headers:

| Header | Required | Description |
|---|---|---|
| `X-TT-API-Key` | Yes | Your API key (`sk_test_*` or `sk_live_*`) |
| `X-TT-Retailer` | Yes | Your retailer ID: a retailer your key was issued for. Affects pricing and inventory visibility. |
| `X-TT-Platform` | Yes | One of: `ios`, `android`, `web`, `api`. Send `api` from a server-to-server integration. |
| `X-Correlation-ID` | No | Your own ID for the request (e.g. `req_abc123xyz`). It comes back in the `X-Correlation-ID` response header; without one, the API makes one up and returns it. Quote it when you contact support. |

Send request bodies as JSON, with `Content-Type: application/json`. A body sent any other way returns `400 INVALID_REQUEST`.

`POST /api/v3/orders` also takes two optional headers:

| Header | Description |
|---|---|
| `Idempotency-Key` | A UUID v4 you make for each attempt to buy, so a retry never buys twice. See [Idempotency Keys](/guides/error-handling#idempotency-keys). |
| `X-TT-Device-Data` | The customer's browser or device, as JSON, for card fraud checks. See [Paying](/guides/purchase-flow#paying). |

> **Keep your keys safe.** Store API keys in environment variables or a secrets manager — never commit them to source control or expose them in client-side code.

## Make Your First Request

Confirm your credentials work by listing your available markets — no additional parameters required:

```bash
curl -s https://stg.ttix.io/api/v3/locations \
  -H "X-TT-API-Key: sk_test_YOUR_KEY" \
  -H "X-TT-Retailer: YOUR_RETAILER_ID" \
  -H "X-TT-Platform: api"
```

A successful response looks like:

```json
{
  "data": [
    {"id": "2",  "name": "London",   "country": "GB", "availableCurrencies": ["GBP"]},
    {"id": "1",  "name": "New York", "country": "US", "availableCurrencies": ["USD"]}
  ],
  "pagination": {"limit": 50, "offset": 0, "total": 2}
}
```

## Troubleshooting

| Error | Cause | Fix |
|---|---|---|
| `401 UNAUTHORIZED` | No `X-TT-API-Key` header | Send your API key in `X-TT-API-Key` |
| `401 INVALID_API_KEY` | The API key is wrong or revoked, **or** `X-TT-Retailer` is missing or isn't a retailer your key was issued for | Check both headers. The retailer header is checked as part of the key, so a missing retailer looks like a bad key. |
| `400 MISSING_REQUIRED_HEADER` | No `X-TT-Platform` header | Send `X-TT-Platform` |
| `400 INVALID_FIELD_VALUE` | `X-TT-Platform` has a value the API doesn't recognize | Send one of `ios`, `android`, `web`, `api` |

Every other code is in [Error Handling](/guides/error-handling#common-error-codes).

## Next Steps

- [API Conventions](/guides/api-conventions) — Response envelopes, money format, timezones, IDs, pagination, and forward-compatibility guidance.
- [Purchase Flow](/guides/purchase-flow) — End-to-end walkthrough from browsing events to completing a checkout.
- [Inventory Types](/guides/inventory-types) — Understanding assigned seats, general admission, and pricing.
- [Error Handling](/guides/error-handling) — Error format, common codes, retry strategies, and idempotency.