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.
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 |