# Adding items to cart

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


```bash
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:

| Property | Type | Required | Description |
|  --- | --- | --- | --- |
| `type` | string | Yes | Product type. Must be one of: `musement`, `musement-realtime`, `musement-gift` |
| `product_identifier` | string | Yes | Product identifier obtained from the `/activities/{activityUuid}/dates/{date}` endpoint |
| `quantity` | integer | Yes | Number of products to add. Must be greater than 0 |
| `language` | string | No | Two-letter language code (e.g., `en`, `it`). Required for activities with language options |
| `pickup` | string (UUID) | No | Pickup point UUID. Required for activities with pickups |


## Response

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


```json
{
	"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

| Property | Type | Description |
|  --- | --- | --- |
| `uuid` | string | Unique identifier for the cart item |
| `status` | string | Availability status: `PREBOOK_OK` (available) or `PREBOOK_KO` (unavailable) |
| `quantity` | integer | Number of products in this cart item |
| `total_price` | object | Total price for this cart item (retail_price × quantity) |
| `total_price_without_service_fee` | object | Total price excluding service fees |
| `product` | object | Details about the selected product |


Response behavior
When adding multiple items in a single request, the response returns only the first item.

## Adding multiple items

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


```bash
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:


```bash
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:


```json
{
	"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](/api/booking-flow/product).

### Product types

| Type | Description |
|  --- | --- |
| `musement` | Standard Musement product |
| `musement-realtime` | Real-time product with live availability check from external supplier |
| `musement-gift` | Gift product |


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:


```json
{
	"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:


```json
{
	"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:


```json
{
	"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](/api/booking-flow/product/quantities).

## 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](/api/booking-flow/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](/api/booking-flow/product/pickups).

Changes in 3.5.0
Starting in version 3.5.0, the API will return a 400 status code when using the `pickup` property for an activity that does not use pickups.

## 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:


```json
{
	"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:**


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

**Invalid quantity error:**


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

### 404 Not Found

Returned when the cart UUID does not exist:


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

### 410 Gone

Returned when the product is no longer available:


```json
{
	"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:


```json
{
	"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:


```json
{
	"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](/api/booking-flow/cart/prices).

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