Inventory Types

Every inventory item contains an inventoryVariant with a _type field that determines what kind of item it represents. This guide explains the three types and how to handle them.

Seats and general admission come from the occurrence’s inventory list. Extras (merchandise, drinks, parking) are offered per cart — they appear under options.extras on the cart response, not in the occurrence inventory.

The Three Types

Discriminator Pattern

All types share a common base (id, _type, name, attributes) and the _type field tells you which one you’re dealing with. Only AssignedSeat adds extra fields.

1
{
2
  "inventoryVariant": {
3
    "_type": "AssignedSeat",
4
    "id": "Orchestra-A-101",
5
    "name": "Orchestra A 101",
6
    "section": "Orchestra",
7
    "row": "A",
8
    "seat": "101",
9
    "attributes": []
10
  }
11
}

1
{
2
  "inventoryVariant": {
3
    "_type": "GeneralAdmission",
4
    "id": "dance-floor",
5
    "name": "Dance Floor",
6
    "attributes": []
7
  }
8
}

1
{
2
  "inventoryVariant": {
3
    "_type": "Extra",
4
    "id": "ICE CREAM",
5
    "name": "Ice Cream",
6
    "attributes": []
7
  }
8
}

Key rule: switch on _type to determine your rendering and quantity logic. Treat unknown _type values gracefully — new types may be added in the future.

AssignedSeat

Represents a specific seat in a venue. Has three additional fields:

Quantity is always 1 — each seat is a separate inventory item. To let a customer buy multiple seats, add multiple items to the cart.

1
{
2
  "items": [
3
    { "inventoryItemId": "seat-a101", "priceOptionId": "po_1", "quantity": 1, "occurrenceId": "occ_1" },
4
    { "inventoryItemId": "seat-a102", "priceOptionId": "po_1", "quantity": 1, "occurrenceId": "occ_1" }
5
  ]
6
}

IDs are shortened here for readability. A real inventoryItemId is an opaque, versioned token (e.g. v1_eyJz…); copy it whole from the inventory response and never build it by hand. See IDs.

GeneralAdmission

Represents entry to a general admission area. No additional fields beyond the base.

Quantity can be 1 to quantityAvailable — a single inventory item covers multiple people. To buy 3 GA tickets, set quantity: 3 on one cart item.

1
{
2
  "items": [
3
    { "inventoryItemId": "ga-dance-floor", "priceOptionId": "po_2", "quantity": 3, "occurrenceId": "occ_1" }
4
  ]
5
}

On the order, you’ll receive one ticket per person (3 tickets in this example), each with its own barcode.

Extra

Represents an add-on sold alongside tickets — merchandise, drinks, parking, and similar. No additional fields beyond the base.

Extras are discovered on the cart, not on the occurrence. After you create a cart, the cart response lists the extras you can add under options.extras, each in the same inventory-item shape as seats and GA. Add one with POST /api/v3/carts/{cartId}/items — see Purchase Flow.

1
{
2
  "id": "v1_eyJwcm92aWRlcklkIjoxLCJzZWF0SWQiOiIxOCJ9",
3
  "inventoryVariant": {
4
    "_type": "Extra",
5
    "id": "ICE CREAM",
6
    "name": "Ice Cream",
7
    "attributes": []
8
  },
9
  "priceOptions": [
10
    { "id": "eyJpc0FkZE9uIjp0cnVlLCJwcmljZVR5cGVJZCI6IjExIn0", "category": { "name": "Adult" }, "sellPrice": { "amount": 4500, "currency": "USD" }, "maxQuantityPerOrder": 4 },
11
    { "id": "eyJpc0FkZE9uIjp0cnVlLCJwcmljZVR5cGVJZCI6IjEyIn0", "category": { "name": "Child" }, "sellPrice": { "amount": 1500, "currency": "USD" }, "maxQuantityPerOrder": 2 }
12
  ],
13
  "quantityAvailable": 20,
14
  "maxQuantityPerOrder": 6
15
}

Quantity can be more than 1, like GA. Three limits apply:

• quantityAvailable — how many are in stock.
• maxQuantityPerOrder on the item — how many of this extra one order may contain, across all its price options. Omitted when there is no item cap.
• maxQuantityPerOrder on a price option — how many units one order may contain at that price option. Omitted when that option has no cap of its own.

The effective limit is the lowest that applies. Extras don’t produce tickets on the order — they appear as order items and on the receipt.

Inventory Attributes

All types can carry attributes[] — tags that describe characteristics of the inventory. Use these for display purposes (badges, filters, icons).

Each attribute has:

Attribute Categories

Example with attributes:

1
{
2
  "inventoryVariant": {
3
    "_type": "AssignedSeat",
4
    "id": "Balcony-B-15",
5
    "name": "Balcony B 15",
6
    "section": "Balcony",
7
    "row": "B",
8
    "seat": "15",
9
    "attributes": [
10
      { "name": "Restricted View", "description": "Pillar may partially obstruct the stage", "category": "NEGATIVE" },
11
      { "name": "Wheelchair Accessible", "description": null, "category": "ACCESSIBILITY" }
12
    ]
13
  }
14
}

Price Options

Each inventory item has one or more priceOptions[] — the available price categories for that item (e.g., Adult, Child, Senior).

When listPrice is present, the customer is getting a deal:

1
{
2
  "priceOptions": [
3
    {
4
      "id": "eyJjIjoiRlVMTCJ9",
5
      "category": { "name": "Adult" },
6
      "listPrice": { "amount": 15000, "currency": "USD" },
7
      "sellPrice": { "amount": 12500, "currency": "USD" }
8
    }
9
  ]
10
}

Display: ~$150.00~ → **$125.00**

When there’s no discount, listPrice is absent — just show sellPrice.

Stable Variant IDs

Inventory variant id values are stable across all occurrences of the same event. The same seat returns the same variant id regardless of which date the customer picks. This is important if you’re building seating charts or caching seat metadata.

Rendering Summary