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

# Rate Codes

Rate codes let you retrieve different configured pricing tiers — full price, a campaign offer, a special commission rate — through a single integration. One retailer ID, one API key, any number of tiers.

In the API the rate code travels as the `providerCode` query parameter. Your TTG contact configures the tiers and shares the codes with you during setup; there is no endpoint to list them.

## Requesting a Tier

Add `providerCode` to the inventory call:

```http
GET /api/v3/events/{eventId}/occurrences/{occurrenceId}/inventory-items?providerCode=campaign-may
```

The calendar (`GET /api/v3/events/{eventId}/occurrences`) always shows default-tier prices, so its `fromPrice` can differ from the tier's seat prices. Label it as a starting price rather than the tier's price.

Everything else — endpoint, auth, response shape — is identical to a standard inventory call. Only the prices change. Same call, one extra parameter:

```bash
curl "https://stg.ttix.io/api/v3/events/123/occurrences/456/inventory-items?providerCode=campaign-may" \
  -H "X-TT-API-Key: $API_KEY" -H "X-TT-Retailer: $RETAILER_ID" -H "X-TT-Platform: api"
```

| Request | Behavior |
|---|---|
| No `providerCode` | Default tier — the prices you get without a rate code. Existing integrations need no changes (treat `priceOptionId` as opaque; its value may differ between calls). |
| Recognized code | Prices reflect that tier's configuration. |
| Unrecognized code | `404 RESOURCE_NOT_FOUND` naming the rejected code, but only when the occurrence has something on sale. With nothing on sale, you get a list with nothing to buy instead: empty, or only sold-out areas. |
| Blank code, or longer than 255 characters | `400 INVALID_FIELD_VALUE`. |

A code counts as recognized only when it is configured for your retailer on that event — a typo, an expired code, or a code from another event or retailer is treated the same way.

The 404 carries `error.details.resourceType: "providerCode"` and `error.details.resourceId` set to the rejected code, so you can tell it apart from an event or occurrence that doesn't exist.

To show multiple tiers concurrently, make one inventory call per code. Each response stands alone.

## Purchasing at a Tier

Create the cart with the `inventoryItemId` and `priceOptionId` values returned by the tier-priced inventory call, exactly as in the standard [Purchase Flow](/guides/purchase-flow). The requested rate rides along inside the returned `priceOptionId`, so the tier's configured effect — price, commission, or both, depending on how the tier was set up for you — carries through to the resulting order automatically. No extra parameters are needed at cart or checkout.

One cart can mix items from different tiers: each item keeps the rate of the inventory call it came from.

## FAQ

**Can one call return all tiers at once?**
No — one tier per call is the contract. Request each code separately.

**Do rate codes affect which seats I see?**
A tier can be configured to apply only to part of the inventory (for example, specific sections). Seats outside that scope still appear, priced at the default tier.

**How do I get codes for a new offer?**
Ask your TTG contact. Tiers are configured on TTG's side; no integration changes are needed for a new code.

**Are codes case-sensitive?**
Yes. Send them exactly as provided.