Checkout Integration
Integrate ticket purchase on your site or app using carts and orders.
Two checkout paths
| Path | When to use |
|---|---|
| API checkout | You collect payment yourself; create an order via POST /orders |
| Redirect checkout | Send the buyer to EventCube payment using checkout_url from the cart |
Both paths start with the same cart APIs.
End-to-end flow (API checkout)
1. Discover tickets
From Inventory Management:
GET /api/v1/events?only_listable=1
GET /api/v1/events/{eventId}/tickets
2. Create a cart
POST /api/v1/carts
{
"items": [
{
"ticket_id": 1,
"quantity": 2,
"ticket_holders": [
{ "first_name": "Alice", "last_name": "Smith", "email": "alice@example.com" },
{ "first_name": "Bob", "last_name": "Jones" }
]
}
]
}
Response includes id, token, totals, checkout_url, store seating context (or null), and custom_fields when applicable. Each line may include items[].seating when that ticket requires reserved seating.
3. Reserved seating (when required)
Seat hold and selection routes take the cart numeric ID (not the token).
If items[].seating.required is true:
POST /api/v1/carts/{cartId}/seat-holds
{ "ticket_ids": [1], "refresh": false }
Response items include hold_token, event_key, and category_key for the Seats.io chart.
Then save selected seats (label count must match line quantity; use the hold token as reservation_token):
PATCH /api/v1/carts/{cartId}/seat-selections
{
"items": [
{
"ticket_id": 1,
"seat_labels": ["A-1", "A-2"],
"reservation_token": "hold-token-abc"
}
]
}
Check progress with GET /api/v1/carts/{cartId}/seat-selections (complete: true when done). Release holds with DELETE /api/v1/carts/{cartId}/seat-holds.
POST /orders returns 422 with errors.seat_selections if seating is incomplete.
4. Update the cart
GET and PATCH accept either the cart ID or token. Item and discount-code routes use the token.
PATCH /api/v1/carts/{idOrToken}
Set customer details and custom field answers before checkout:
{
"customer": {
"email": "buyer@example.com",
"first_name": "Buyer",
"last_name": "Test",
"address_1": "123 St",
"city": "London",
"postcode": "E1 1AA",
"country": "GB"
},
"custom_field_values": {
"dietary_requirements": "Vegetarian"
}
}
custom_field_values is keyed by checkout field name. Unknown names are ignored; invalid values for known fields return 422.
You can also replace all line items via items, or extend expiry with expires_in_minutes.
5. Modify individual lines
POST /api/v1/carts/{token}/items/{ticket_id} # add/increment
PATCH /api/v1/carts/{token}/items/{ticket_id} # set quantity/holders
DELETE /api/v1/carts/{token}/items/{ticket_id} # remove line
6. Apply a discount (optional)
Discount definitions are managed under Inventory Management — Discounts. At checkout, apply an existing code on the cart:
POST /api/v1/carts/{token}/discount-code
{ "code": "SAVE10" }
DELETE /api/v1/carts/{token}/discount-code
7. Create an order
POST /api/v1/orders
{
"cart_token": "abc123token",
"customer": {
"email": "buyer@example.com",
"first_name": "Buyer",
"last_name": "Test",
"address_1": "123 St",
"city": "London",
"postcode": "E1 1AA",
"country": "GB"
},
"mark_guests_as_checked_in": false
}
If customer details were already set on the cart, you may omit customer.
Optional mark_guests_as_checked_in: true marks guests as checked in after create (must be a boolean).
A confirmation email is sent unless disabled in store API settings.
Custom checkout answers copied from the cart can be changed after the order exists:
PATCH /api/v1/orders/{idOrReference}
{
"custom_field_values": {
"dietary_requirements": "Vegan"
}
}
The payload matches the cart: keys are field names, unknown names are ignored, and omitted fields keep their current answers. Invalid values return 422.
8. Assign ticket holder names (optional)
After the order exists, set names on individual barcodes:
PUT /api/v1/orders/{idOrReference}/ticket-names
{
"items": [
{ "barcode": "ABC123", "first_name": "Alice", "last_name": "Smith" }
]
}
9. Retrieve orders
GET /api/v1/orders/{idOrReference}
GET /api/v1/order-ticket-items?barcode=...
Order ticket items include ticket_name / ticket_holder, and reserved_seat when seating was used.
Redirect checkout
After creating a cart, redirect the buyer to:
{cart.checkout_url}
EventCube handles payment collection. You do not call POST /orders in this path.
Cart identifiers
| Operation | Identifier |
|---|---|
| Create cart | — |
| GET / PATCH cart | Numeric ID or token |
| Cart items / discount codes | Token |
| Seat holds / selections | Numeric ID only |
| Create order | Cart token (cart_token) |
Error handling
| Status | Typical cause |
|---|---|
400 | Validation, invalid ticket, cart already has order |
409 | Insufficient inventory |
410 | Cart expired (seat holds) |
422 | Cart already converted, inventory gone at order time, incomplete seating, invalid custom field values |