Creates a new cart and adds inventory items to it in a single request. Holds the inventory for the customer.
- `AssignedSeat` variants always require `quantity: 1` (each seat is unique)
- `GeneralAdmission` and `Extra` variants support `quantity > 1`
- All items must be from the same event + occurrence.
- A cart cannot currently mix general admission and assigned seats. Use a separate cart for each. This is a limitation of how inventory is held today, not of the request format, and is expected to lift.
Send a `currency` in the body to create the cart in that currency: the cart keeps pricing in it on later reads and the order settles in it. Omit it for base-currency prices. A currency this event is not sold in returns `400`; one it is sold in but that cannot be priced right now (no exchange rate) returns `503`.
Send a `voucherCode` in the body to hold inventory that is hidden behind that code and to apply the code to the new cart in the same request. A well-formed code that does not match a voucher, or that cannot be applied to these items, is ignored rather than reported — the cart is created as if the field were omitted. A blank or over-length value is malformed and returns `400` like any other field.
Send `previousCartId` when the customer re-selects seats: once the new cart is created, the previous cart is released so the customer holds one set of inventory instead of stacking a fresh hold on every selection. The release is best-effort and never fails the create — a cart that cannot be released is left alone.
Request
This endpoint expects an object.
itemslist of objectsRequired
currencystring or nullOptionalformat: "^[A-Z]{3}$"
ISO 4217 currency to create the cart in: the cart keeps pricing in it on later reads and the order settles in it. Omit for the event base currency. A currency this event is not sold in returns 400; one it is sold in but that cannot be priced right now returns 503.
voucherCodestring or nullOptionalformat: ".*\S.*"0-15 characters
A promo or access code, as entered by the customer. Some inventory is hidden behind a code; sending the code here is what lets this cart hold those items — applying it after the cart exists is too late to unlock them. The code is also applied to the new cart, exactly as POST /carts/{cartId}/vouchers would, so the response already shows the discount. When sent, the value must be 1–15 characters — blank or longer returns 400, like any malformed field. A well-formed code that does not match a voucher, or that cannot be applied to these items, is ignored: the cart is created as if this field were omitted and no error is returned. To find out why a code does not work, apply it with POST /carts/{cartId}/vouchers.
previousCartIdstring or nullOptionalformat: "(?i)^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
The id of the customer’s previous cart, from an earlier POST /carts — send it when the customer re-selects seats: once the new cart is created, the previous cart is released and its inventory freed. The release is best-effort and never fails the create: a cart that is unknown, already released, expired, or already turned into an order is simply left alone and the new cart is still created. Omit it to leave any earlier cart in place until it times out.
Response
Cart created successfully.
expiresAtstring
UTC timestamp when the cart hold expires and inventory is released. Clients should display a countdown timer and warn users before expiration.
itemslist of objects
Items currently in the cart (held inventory). Each item’s priceOption carries the itemized fees[] disclosure. Protection and credits are NOT items — see receiptLines.
receiptLineslist of objects
Server-ordered display lines for receipt rendering. Iterate in sequence. Always includes SubtotalLine. Conditionally: VoucherLine, ProtectionLine, CreditLine. Fees are never a receipt line — they are disclosed per item on priceOption.fees.
totalobject
Monetary amount in minor units (cents for USD). Never uses floating point to avoid precision errors.
protectionobjectOptional
Protection covering all items. Null if not added.
optionsobjectOptional
Options that can be applied to this cart. Each key is present only when that option is available.
voucherobjectOptional
A promo code applied to a cart.
totalTaxesobjectOptional
Monetary amount in minor units (cents for USD). Never uses floating point to avoid precision errors.