Migration: Availability to Occurrences

Guide for migrating from the legacy GET /api/v4/availability/products/{productId}/... endpoint to the new GET /api/v3/events/{eventId}/occurrences endpoint.

For the full v4 inventory reference, see Inventory API on the legacy portal.

Endpoint Comparison

What Changed

Simplified URL

The v4 endpoint encoded filters (quantity, date range) in the URL path. The v3 endpoint moves these to optional query parameters.

# Legacy
GET /api/v4/availability/products/123/quantity/2/from/2026-03-15/to/2026-03-31
# New (all filters optional)
GET /api/v3/events/123/occurrences?quantity=2&startDate=2026-03-15&endDate=2026-03-31
# New (no filters — returns all upcoming occurrences)
GET /api/v3/events/123/occurrences

Terminology

Quantity and Date Range Are Now Optional Query Parameters

In v4, quantity, from, and to were required path segments. In v3, they are optional query parameters:

All parameters can be combined freely or omitted entirely:

# Equivalent to v4 call with all filters
GET /api/v3/events/123/occurrences?quantity=2&startDate=2026-03-15&endDate=2026-03-31
# Only filter by date range
GET /api/v3/events/123/occurrences?startDate=2026-03-15&endDate=2026-03-31
# Only filter by quantity
GET /api/v3/events/123/occurrences?quantity=2
# No filters — all upcoming occurrences
GET /api/v3/events/123/occurrences

Money Format

Prices changed from decimal (major units) to integer (minor units) with explicit currency.

Legacy (v4):

1
{ "price": 85.00 }

New (v3):

1
{ "fromPrice": { "amount": 8500, "currency": "USD" } }

All monetary values in v3 use minor units (cents for USD, pence for GBP). Divide by 100 for display.

Availability Status

Each occurrence also carries availabilityLevel: LOW (tickets are running out), SOLD_OUT, or null (no signal — display the occurrence normally). New values may be added over time; treat any unrecognized value as no signal.

Discount Information

The v3 endpoint adds discount data not available in v4:

• maxDiscountPercentage — Best available % discount (e.g., 29 = “Up to 29% off”)
• maxDiscountAmount — Best available amount discount (e.g., { amount: 5000, currency: "USD" } = “Save up to $50”)

These fields are optional — omitted when no discount exists.

Response Shape

Legacy (v4)

1
{
2
  "data": [
3
    {
4
      "date": "2026-03-15",
5
      "time": "19:30",
6
      "price": 85.00,
7
      "currencyCode": "USD",
8
      "available": true
9
    }
10
  ]
11
}

New (v3)

1
{
2
  "data": [
3
    {
4
      "availabilityLevel": null,
5
      "id": "123",
6
      "startsAt": "2026-03-15T19:30:00-04:00",
7
      "endsAt": "2026-03-15T22:30:00-04:00",
8
      "fromPrice": {
9
        "amount": 8500,
10
        "currency": "USD"
11
      },
12
      "maxDiscountPercentage": 29
13
    },
14
    {
15
      "availabilityLevel": "SOLD_OUT",
16
      "id": "124",
17
      "startsAt": "2026-03-16T19:30:00-04:00",
18
      "endsAt": "2026-03-16T22:30:00-04:00",
19
      "fromPrice": null
20
    }
21
  ]
22
}

Key differences:

• Each occurrence has an id you’ll need for subsequent calls (inventory, cart)
• startsAt includes timezone offset — no separate date/time fields
• endsAt is nullable (some events have no fixed end time)
• fromPrice is null instead of available: false
• availabilityLevel says why nothing is buyable (SOLD_OUT) or that stock is running out (LOW)

Migration Checklist

1. Replace productId with eventId in your integration
2. Update the endpoint URL from v4 path to GET /api/v3/events/{eventId}/occurrences
3. Move quantity from URL path to ?quantity= query parameter (now optional)
4. Move date range from URL path to ?startDate= and ?endDate= query parameters (now optional)
5. Update price parsing: divide fromPrice.amount by 100 for display (or appropriate factor for the currency)
6. Store the occurrence id — you need it for inventory browsing and cart creation
7. Decide how to present unavailable occurrences — any date with nothing to buy comes back with availabilityLevel: "SOLD_OUT" and fromPrice: null. To match the legacy behavior (which excluded those dates), filter out occurrences where fromPrice is null
8. Optionally display discount badges using maxDiscountPercentage or maxDiscountAmount

Next Steps

After migrating the browse step, continue with the full Purchase Flow:

1. Browse Inventory — GET /api/v3/events/{eventId}/occurrences/{occurrenceId}/inventory-items
2. Create Cart — POST /api/v3/carts
3. Checkout — POST /api/v3/orders