API Conventions

Patterns and standards that apply across all TTG API v3 endpoints. Read this first — individual endpoint docs assume familiarity with these conventions.

Response Envelope

All responses use a consistent envelope:

Success:

1
{
2
  "data": { ... }
3
}

Success (list):

1
{
2
  "data": [ ... ],
3
  "pagination": { "limit": 50, "offset": 0, "total": 142 }
4
}

Error:

1
{
2
  "error": {
3
    "type": "NOT_FOUND_ERROR",
4
    "code": "RESOURCE_NOT_FOUND",
5
    "message": "The requested resource was not found."
6
  }
7
}

The top-level key is always data or error, never both. Parse the HTTP status code first (2xx vs 4xx/5xx), then read the body.

Money Format

All monetary values use integer minor units with an ISO 4217 currency code. No floating-point, no strings.

1
{
2
  "amount": 18500,
3
  "currency": "USD"
4
}

The number of decimal places depends on the currency:

Use your platform’s i18n library to determine the scale from the currency code — don’t hardcode / 100.

Client examples:

• JavaScript: new Intl.NumberFormat(locale, { style: "currency", currency }).format(amount / 10 ** scale)
• iOS: NumberFormatter with currencyCode set
• Android: Currency.getInstance(currency).defaultFractionDigits for scale

IDs

All IDs are opaque strings. Never parse, construct, or derive meaning from an ID — treat them as tokens you receive from one endpoint and pass to another. The format may change without notice.

Stable IDs — persist across sessions and are safe to store:

• Events, Occurrences, Carts, Orders, Tickets

Ephemeral IDs — valid only for the current session; re-fetch inventory to get fresh ones:

• Inventory Items, Price Options

Pagination

Some list endpoints use limit/offset pagination. Check individual endpoint docs — not all list endpoints are paginated (e.g., occurrences and inventory items return all results in a single response).

The response includes a pagination object:

1
{
2
  "pagination": {
3
    "limit": 50,
4
    "offset": 0,
5
    "total": 142
6
  }
7
}

To iterate all pages: increment offset by limit until offset >= total.

Timezones

Occurrence times (startsAt, endsAt) use the venue’s local timezone with UTC offset:

2026-03-15T19:30:00-05:00

Use the venue.timezone field (IANA identifier, e.g., America/New_York) if you need an IANA timezone for calendar integration (Apple Calendar, Google Calendar). For display, the offset embedded in the timestamp is sufficient — no timezone manipulation required.

System timestamps (createdAt, expiresAt) use UTC:

2026-03-15T19:40:00Z

Nullability

Fields are nullable only when absence carries meaning:

• fromPrice: null — occurrence is sold out or not yet on sale
• endsAt: null — event has no known end time
• listPrice: null — no discount exists (or display is contractually prohibited)
• barcode: null — barcode not yet available (delayed delivery venues)
• totalTaxes: null — taxes not disclosed in this market

When a nullable field is null, handle it explicitly in your UI — don’t display “null” or “$0.00”.

Optional fields that carry no information are omitted entirely rather than sent as null. For example, maxDiscountPercentage is absent (not null) when no discount exists.

Forward Compatibility

The API may add new fields, enum values, or error codes at any time without a version bump. To avoid breaking:

• Ignore unknown fields — don’t fail on unexpected keys in response objects
• Handle unknown enum values — use a default/fallback case for enums like status, _type, and error code
• Don’t switch on error messages — use type and code for programmatic handling; message is for display only and may change