Adding items to cart

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Once the cart has been created, you can start adding products to it in the form of cart items. A cart can hold a maximum of 100 items. Carts are allowed to contain items from different activities.

Request

curl -X POST '{baseUrl}/carts/{cartUuid}/items' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
--data-raw '[
	{
		"type": "musement",
		"product_identifier": "249217479",
		"quantity": 2,
		"language": "it",
		"pickup": "5ee32dbd-898d-4f2e-aa9b-bb430b9a4960"
	}
]'

Request body properties

The endpoint expects an array of cart items in the request body. Each item contains the following properties:

Response

A successful request returns a 200 status code with the cart item details:

{
	"uuid": "dd0a0840-f09d-4406-b02a-f672dbf4b172",
	"status": "PREBOOK_OK",
	"quantity": 2,
	"total_price": {
		"currency": "EUR",
		"value": 50.0,
		"formatted_value": "€ 50.00",
		"formatted_iso_value": "€50.00"
	},
	"total_price_without_service_fee": {
		"currency": "EUR",
		"value": 45.0,
		"formatted_value": "€ 45.00",
		"formatted_iso_value": "€45.00"
	},
	"product": {
		"id": "249217479",
		"type": "musement",
		"title": "Adult ticket",
		"retail_price": {
			"currency": "EUR",
			"value": 25.0,
			"formatted_value": "€ 25.00",
			"formatted_iso_value": "€25.00"
		}
	}
}

Response properties

Adding multiple items

You can add multiple items to a cart in a single request:

curl -X POST '{baseUrl}/carts/{cartUuid}/items' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
--data-raw '[
	{
		"type": "musement",
		"product_identifier": "249217479",
		"quantity": 2,
		"language": "it",
		"pickup": "5ee32dbd-898d-4f2e-aa9b-bb430b9a4960"
	},
	{
		"type": "musement",
		"product_identifier": "249217478",
		"quantity": 1,
		"language": "it",
		"pickup": "5ee32dbd-898d-4f2e-aa9b-bb430b9a4960"
	}
]'

Partners can repeat this action for one cart as many times as needed before finalizing an order, even with products that belong to different activities.

To confirm that a cart contains all the requested items, call the /carts/{cartUuid} endpoint:

curl -X GET '{baseUrl}/carts/{cartUuid}' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

The following is an example response with two items:

{
	"uuid": "87881148-9739-4e4c-bffa-d5085e7d74f7",
	"items": [
		{
			"uuid": "dd0a0840-f09d-4406-b02a-f672dbf4b172",
			"status": "PREBOOK_OK",
			"quantity": 2
		},
		{
			"uuid": "a23baee2-b77c-44b1-80ed-d67940af513d",
			"status": "PREBOOK_OK",
			"quantity": 1
		}
	]
}

Product type and identifier

Each product has its own type and unique identifier which refer to a specific combination of options based on a customer's selection. For more information on selecting a product, refer to the dedicated section.

Product types

Be aware that after an item is added to cart, its product identifier may change. Note the lengthy product_id in the musement-realtime example below:

{
	"holder_code": "standard-price",
	"name": "Standard price",
	"type": "musement-realtime",
	"default": false,
	"product_id": "HruSLWn9fIB9Y8Z8L0/9ritXa7+REpxL9g7drGds1wNH3pcRaR91BKVdJGwuRv6JBg1bJvhTjcQRYzbl/W84dMK2B5wMLGhrHd6jSRBSenMFJ8E+W3j9pHkeqLejqGgIw66Ft00mcUQBfLhPgp6zOKlJuy4YfOMUXLSatCWlM0MtGi57HQ+6GxqCxcetgmg/BvLV1P4c8fVuvuZNhBhT815MKYFANews1zykD1iRTwtd9xiKV7URlbXioUtu9pKZKkmo+Z2icacVnqd+w9S2bgeHPKGosVXOdb1KOP2aq+HxEA6WC9KSwV4nlf8TS8fZ7rDQhu44hVy0U8SAcDEIhmt2OjzmdRoFFhjZdI8ud9W01rQXSKmElOlGXIkt2H2Rt6TNmctDFxHWHnvoPSqc2K7G9Tj4tbWbIAuj2BubaKRW4Q5oiJslnZJ07IufGHWmf9O7PqtAtQP+iGGqvy2C4cC5NYvMxq99DyYLBgJBiDE0rpbot1iTG73UTndGLTXJ3GWQNLOLyJEHGCddxCL2JEllTprXqrL3qo3Ca2h3q6yntmgCrZQOhJjtu3JgdBVB0vDmi15AtuNhS+YoekHzkMMaU2lNNNfaomDtAunHpKlGjotenbECziNV8lpnvNZPlY9eYzWvCihYJRw+A8u2T3zsHmxcClilkSG+3lWx2igYSufmWsjXH1N14YJHyHCvDZsP/u1EauF9+QABduQjoCa6bJAzDX12VZ5r7kToGNhUxOHmjGphYR4V6XAbUn8Lrr5mgd97xDegYKK3lXuzj/B0G2p5t4e/9ceO"
}

After adding the product to cart, its identifier in the response changes to a simpler numeric value:

{
	"product": {
		"id": "13423401784"
	}
}

This change only affects the item in the cart and does not affect the product identifiers in the /activities/{activityUuid}/dates/{date} endpoint.

Quantity

Include the number of products you are purchasing in the quantity property. The quantity must be greater than 0.

Be aware that if the quantity deviates from the min_buy, max_buy or availability restrictions for a product and its timeslot, you may receive an error.

In the example response below, we attempted to add a quantity larger than the product's max_buy and received an error:

{
	"code": "2201",
	"message": "Product 4302812251 must have a quantity between 1 and 15. You specified 20."
}

For more information on quantity limits, check out the quantity limits page.

Language

Some activities require selecting a language as part of the order, usually to reserve a dedicated guide or tour materials.

If a product does not include languages, the language property for an item can be omitted.

For more information, check out the page on product timeslots and languages.

Pickup point

The pickup property in the request body expects a pickup point UUID and is only necessary for activities with pickups. The property can be omitted for activities without pickups.

For more information on obtaining the pickup UUID, refer to the section about pickups points.

Adding child products

When adding items to cart for child products, we strongly recommend including items for adult products in the same request.

Some activities are connected to other API platforms which have additional restrictions on bookings, requiring the purchase of adult options together with child options. This information is not available via our API and can lead to errors when trying to add items for adult and child products to cart in separate requests.

While holders can vary depending on the activity configuration, any product which uses a holder_code that contains the word "child" is likely to require an adult product too.

This restriction does not necessarily apply to items with "infant" products, which can usually be added to cart regardless of whether there are items with adult products in the same request.

Availability validation

When items are added to cart, the system performs availability validation:

1. Verifies the product date/timeslot is active
2. Checks if the requested quantity is available
3. Validates the booking is within the allowed booking window
4. For real-time products, performs a live availability check with the supplier

If a product becomes unavailable during the add operation, it will be removed from the cart and an error response will be returned.

Error handling

The endpoint may return the following error responses:

400 Bad Request

Returned when the request payload is invalid:

{
	"code": "400",
	"message": "Invalid submitted data"
}

Common causes:

• Missing required fields (type, product_identifier, quantity)
• Invalid product type
• Quantity is 0 or negative
• Empty payload

Empty payload error:

{
	"code": "400",
	"message": "The payload you send can't be processed, seems that the payload is empty"
}

Invalid quantity error:

{
	"code": "400",
	"message": "Ticket quantity must be bigger than 0!"
}

404 Not Found

Returned when the cart UUID does not exist:

{
	"code": "404",
	"message": "Cart not found"
}

410 Gone

Returned when the product is no longer available:

{
	"code": "1442",
	"message": "The item is not available anymore"
}

This can occur when:

• The product has sold out
• The date/timeslot is no longer active
• The booking window has closed
• Insufficient inventory for the requested quantity

422 Unprocessable Entity

Returned when the cart item limit has been reached:

{
	"code": "422",
	"message": "Cart items limit reached. Maximum allowed: 100"
}

423 Locked

Returned when the cart is connected to an order and cannot be modified:

{
	"code": "-1",
	"message": "Cart is already connected to order with state 'paid'"
}

Price calculation

When items are added to cart, prices are automatically calculated:

• Product prices are computed including any applicable discounts
• Service fees are calculated and added
• Cart totals are updated to reflect all items
• If a promo code is applied to the cart, it is validated and may be removed if no longer valid

For more information on cart pricing, see the cart prices page.

Currency handling

If the cart currency differs from the currency specified in the request headers, the cart and all items will be updated to the new currency with appropriate exchange rate conversions.