Migration: Baskets to Carts

Guide for migrating from the legacy PATCH /api/v1/baskets flow to the new POST /api/v3/carts flow.

For the full v1 basket reference, see Baskets on the legacy portal.

Endpoint Comparison

What Changed

The server owns the cart ID

In v1 you supplied a unique reference and a checksum password, then PATCHed the same basket to build it up. In v3 you POST the items you want and the server returns a cartId. There’s no reference to invent and no checksum to manage — the API key authenticates you.

# Legacy — you pick the reference, PATCH to upsert
PATCH /api/v1/baskets
{ "reference": "1010101", "channelId": "...", "checksum": "...", "reservations": [ ... ] }
# New — POST items, server returns the cart
POST /api/v3/carts
{ "items": [ ... ] }

From reservations to items

Legacy grouped tickets into reservations, each with a productId, a quantity, and opaque aggregateReference item tokens that bundled the price inside them. v3 takes a flat items list. Each item names the occurrence, the inventory item, and the price option separately.

{
  "items": [
    {
      "occurrenceId": "123",
      "inventoryItemId": "v1_eyJzIjoiT1JDSC1BLTEwMSJ9",
      "priceOptionId": "eyJjIjoiRlVMTCJ9",
      "quantity": 1
    }
  ]
}

Get inventoryItemId and priceOptionId from the inventory step (see Areas → Inventory Items). All items must belong to the same occurrence.

The hold timer is explicit

Legacy baskets held inventory, but the expiry wasn’t part of the response. v3 returns expiresAt (UTC) on the cart — show a countdown. When it passes, the hold is released and GET /api/v3/carts/{cartId} returns 404. Create a new cart to continue. To release a hold early, DELETE /api/v3/carts/{cartId} (idempotent, returns 204).

Discounts move to a voucher endpoint

Legacy applied a coupon inline on the basket or through applyPromotion. v3 has a dedicated pair:

POST   /api/v3/carts/{cartId}/vouchers        { "code": "SAVE20" }
DELETE /api/v3/carts/{cartId}/vouchers/{code}

The discount shows up in the cart’s receiptLines[] and total.

Changing seats means a new cart; changing extras does not

In v3 a cart’s admission items are fixed once created — to change them, create a new cart and pass the old cart’s id as previousCartId: once the new cart is created, the same request attempts to release the old hold so the customer isn’t left holding two sets of inventory. The release is best-effort and never fails the create — an old cart that is unknown, expired, or already turned into an order is left alone, and the old hold then simply times out on its own.

Extras are changed in place on a live cart, addressed by the id of the line they came back as:

POST   /api/v3/carts/{cartId}/items                { "items": [...] } # add one or more
PATCH  /api/v3/carts/{cartId}/items/{itemId}       { "quantity": 2 }  # hold more or fewer
DELETE /api/v3/carts/{cartId}/items/{itemId}                          # drop

All three return the repriced cart. DELETE is idempotent: an itemId the cart does not hold returns the current cart; PATCH on one returns 404. To drop an item send DELETE, not PATCH with a quantity of 0. An itemId naming an admission item is refused with a 400 — see Purchase Flow.

Money format

// Legacy basket money
{ "value": 8500, "currency": "USD", "decimalPlaces": 2 }
// New cart total
{ "amount": 8500, "currency": "USD" }

Both are minor units; v3 drops decimalPlaces — derive the scale from the currency. A cart owns its currency: it’s set at creation (base, or the body’s currency when supported) and switched with PATCH /api/v3/carts/{cartId} { "currency": "EUR" }. See Currency.

Totals come from the server

Don’t compute the total yourself. Read total and render receiptLines[] in order — each line has a sign (positive = charge, negative = credit). You’ll pass total straight through as expectedTotal at checkout.

Response Shape

New (v3)

{
  "data": {
    "id": "6aac14d3-5826-4da8-98b6-9e68c28629d6",
    "expiresAt": "2026-03-15T19:40:00Z",
    "total": { "amount": 18500, "currency": "USD" },
    "items": [ ... ],
    "receiptLines": [ ... ],
    "options": {
      "currencies": ["USD", "EUR"],
      "extras": [ ... ]
    }
  }
}

Key differences:

• id is the server-generated cart ID — stable, safe to store (see IDs)
• expiresAt is the hold deadline in UTC — drive a countdown from it
• options.extras lists add-ons you can attach; the key is absent when the event offers none
• options.currencies lists the currencies the cart can be priced in

Migration Checklist

1. Replace PATCH /api/v1/baskets with POST /api/v3/carts; let the server return the cartId
2. Drop the self-assigned reference and checksum; authenticate with the API key
3. Convert reservations to a flat items list keyed by occurrenceId, inventoryItemId, and priceOptionId
4. Keep all items in one cart to a single occurrence
5. Read expiresAt and show a countdown; handle the 404 on expiry by creating a new cart
6. Move promo codes to POST /api/v3/carts/{cartId}/vouchers
7. Replace single-reservation removal with “create a new cart with previousCartId”, which makes a best-effort release of the old hold in the same request; use DELETE to release a hold without creating a new cart
8. Read total and receiptLines[] from the server — don’t recompute; drop decimalPlaces

Next Steps

With a cart held, continue the Purchase Flow:

1. Add Extras (optional) — POST /api/v3/carts/{cartId}/items
2. Checkout — POST /api/v3/orders (see Checkout → Orders)