A cart is the starting point for any booking. It holds items, customer information, and optional discount codes until an order is created.
The recommended flow is to create an empty cart, then add items and other details in separate steps. This approach provides more flexibility and better error handling for each item.
- Create an empty cart (see basic cart creation below)
- Add items to the cart using the add items endpoint
- Add customer details and other information as needed
To create an empty cart, make the following request:
curl -X POST '{baseUrl}/carts' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
--data-raw '{}'The response returns an empty cart:
{
"uuid": "cc6fcf36-2ec6-41b8-b715-1072d4e441e4",
"items": [],
"full_price": {
"currency": "EUR",
"value": 0,
"formatted_value": "€ 0.00"
},
"discount": {
"currency": "EUR",
"value": 0,
"formatted_value": "€ 0.00"
}
}Hold onto the cart's uuid property. You'll need it whenever you add products, update customer details, or create an order.
It is also possible to provide initial data when creating a cart. The sections below show the available options.
You can create a cart with products already included by providing a tickets array:
curl -X POST '{baseUrl}/carts' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
--data-raw '{
"tickets": [
{
"product": { "id": 123456789 },
"quantity": 2
}
]
}'The response includes the cart with the requested items and calculated totals:
{
"uuid": "d83d4e0a-e62b-4c81-b403-4206914cd697",
"items": [
{
"uuid": "e21aee18-f035-4198-a2f5-2bec63501d1b",
"status": "PREBOOK_OK",
"quantity": 2,
"total_price": {
"currency": "EUR",
"value": 48,
"formatted_value": "€ 48.00"
}
}
],
"full_price": {
"currency": "EUR",
"value": 48,
"formatted_value": "€ 48.00"
}
}You can include customer details when creating a cart:
curl -X POST '{baseUrl}/carts' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
--data-raw '{
"customer": {
"email": "customer@example.com",
"firstname": "John",
"lastname": "Doe",
"country": { "id": 1 },
"mobile": "+1234567890"
}
}'If a customer with the provided email already exists, their record will be updated with the new information. Otherwise, a new customer record is created.
The response includes the customer object:
{
"uuid": "cc6fcf36-2ec6-41b8-b715-1072d4e441e4",
"items": [],
"customer": {
"email": "customer@example.com",
"firstname": "John",
"lastname": "Doe"
}
}You can apply a promo code or gift card when creating a cart using the discount_code parameter:
curl -X POST '{baseUrl}/carts' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
--data-raw '{
"discount_code": "PROMO10"
}'If the code is a valid promo code, the response includes a promo_code object:
{
"uuid": "bf82a0af-e3b2-48a8-9368-a7417539d5e1",
"items": [],
"promo_code": {
"code": "PROMO10"
}
}If the code is a valid gift card, the response includes a gift_card object instead:
{
"uuid": "bf82a0af-e3b2-48a8-9368-a7417539d5e1",
"items": [],
"gift_card": {
"code": "GIFTCARD123",
"balance": {
"currency": "EUR",
"value": 50,
"formatted_value": "€ 50.00"
}
}
}For more information on promo codes, see the promo codes page.
Some promo codes have a "once per customer" rule. To validate these codes before adding full customer details, use the customer_email parameter:
curl -X POST '{baseUrl}/carts' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
--data-raw '{
"discount_code": "ONCE_PER_USER",
"customer_email": "customer@example.com"
}'This allows the API to check if the customer has already used the code without requiring full customer information upfront.
A successful cart creation returns the following properties:
| Property | Description |
|---|---|
uuid | Unique identifier for the cart |
items | Array of cart items (empty for new carts without tickets) |
full_price | Total price before discounts |
full_price_without_service_fee | Total price excluding service fees (API v3.4.0+) |
discount | Total discount amount |
retail_price | Final price after discounts |
retail_price_without_service_fee | Final price excluding service fees (API v3.4.0+) |
service_fee | Service fee amount |
customer | Customer object (if provided) |
promo_code | Promo code object (if applied) |
gift_card | Gift card object (if applied) |
Cart creation can fail for several reasons:
If you include tickets with a non-existent product ID:
{
"code": "1001",
"message": "Product code not valid"
}If the requested product is no longer available:
{
"code": "2101",
"message": "Failed to add Ticket to Cart. Ticket is not available."
}If the provided discount code is invalid or expired:
{
"code": "3001",
"message": "The discount code is invalid"
}If using JWT authentication without the required legacy OAuth2 client claim:
{
"code": "4001",
"message": "claim_legacy_oauth2_client_public_id not found in the JWT payload"
}Carts without an order are automatically removed after three months.