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 token, totals, and checkout_url.
3. Update the cart
Use the cart token (not numeric ID):
PATCH /api/v1/carts/{token}
Set customer details before checkout:
{
"customer": {
"email": "buyer@example.com",
"first_name": "Buyer",
"last_name": "Test",
"address_1": "123 St",
"city": "London",
"postcode": "E1 1AA",
"country": "GB"
}
}
You can also replace all line items via items, or extend expiry with expires_in_minutes.
4. 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
5. 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
6. 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"
}
}
If customer details were already set on the cart, you may omit customer.
A confirmation email is sent unless disabled in store API settings.
7. Retrieve orders
GET /api/v1/orders/{idOrReference}
GET /api/v1/order-ticket-items?barcode=...
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.
Error handling
| Status | Typical cause |
|---|---|
400 | Validation, invalid ticket, cart already has order |
409 | Insufficient inventory |
422 | Cart already converted, inventory gone at order time |