Understanding cart prices is essential for partners to accurately display pricing information to customers and ensure correct billing. The cart pricing structure includes multiple levels: product prices, cart item prices, and cart-level totals.
To view the complete pricing breakdown for a cart, 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}' \
-H 'X-Musement-Currency: USD'Below is an example response showing the full pricing structure:
{
"uuid": "87881148-9739-4e4c-bffa-d5085e7d74f7",
"items": [
{
"uuid": "dd0a0840-f09d-4406-b02a-f672dbf4b172",
"status": "PREBOOK_OK",
"quantity": 2,
"total_price": {
"currency": "USD",
"value": 21.6,
"formatted_value": "$ 21.60",
"formatted_iso_value": "$21.60"
},
"total_price_without_service_fee": {
"currency": "USD",
"value": 17.6,
"formatted_value": "$ 17.60",
"formatted_iso_value": "$17.60"
},
"product": {
"id": "249217479",
"title": "Skip-the-line Colosseum Tour",
"original_retail_price": {
"currency": "USD",
"value": 12.0,
"formatted_value": "$ 12.00",
"formatted_iso_value": "$12.00"
},
"original_retail_price_without_service_fee": {
"currency": "USD",
"value": 10.0,
"formatted_value": "$ 10.00",
"formatted_iso_value": "$10.00"
},
"retail_price": {
"currency": "USD",
"value": 10.8,
"formatted_value": "$ 10.80",
"formatted_iso_value": "$10.80"
},
"retail_price_without_service_fee": {
"currency": "USD",
"value": 8.8,
"formatted_value": "$ 8.80",
"formatted_iso_value": "$8.80"
},
"discount_amount": {
"currency": "USD",
"value": 1.2,
"formatted_value": "$ 1.20",
"formatted_iso_value": "$1.20"
},
"service_fee": {
"currency": "USD",
"value": 2.0,
"formatted_value": "$ 2.00",
"formatted_iso_value": "$2.00"
}
}
}
],
"full_price": {
"currency": "USD",
"value": 24.0,
"formatted_value": "$ 24.00",
"formatted_iso_value": "$24.00"
},
"full_price_without_service_fee": {
"currency": "USD",
"value": 20.0,
"formatted_value": "$ 20.00",
"formatted_iso_value": "$20.00"
},
"discount": {
"currency": "USD",
"value": 4.75,
"formatted_value": "$ 4.75",
"formatted_iso_value": "$4.75"
},
"total_discount": {
"currency": "USD",
"value": 7.15,
"formatted_value": "$ 7.15",
"formatted_iso_value": "$7.15"
},
"retail_price": {
"currency": "USD",
"value": 16.85,
"formatted_value": "$ 16.85",
"formatted_iso_value": "$16.85"
},
"retail_price_without_service_fee": {
"currency": "USD",
"value": 12.85,
"formatted_value": "$ 12.85",
"formatted_iso_value": "$12.85"
},
"service_fee": {
"currency": "USD",
"value": 4.0,
"formatted_value": "$ 4.00",
"formatted_iso_value": "$4.00"
}
}The price model used throughout the API contains the following fields:
| Field | Type | Description |
|---|---|---|
currency | string | ISO currency code (e.g., "EUR", "USD") |
value | number | Numeric price value (use decimal/arbitrary-precision types for calculations, not binary floating-point) |
formatted_value | string | Locale-formatted price (e.g., "$ 10.00") |
formatted_iso_value | string | ISO-formatted price (e.g., "$10.00") |
Every cart item contains information about the activity product. All of the price properties that appear in the product correspond to the same properties described on the activity prices page.
Regardless of the quantity of products in the cart item, the product pricing corresponds to a quantity of one.
Product-level price properties include:
| Property | Description |
|---|---|
original_retail_price | Base price including service fee, before any discounts |
original_retail_price_without_service_fee | Base price without service fee or discounts |
retail_price | Final unit price after discounts, including service fee |
retail_price_without_service_fee | Final unit price after discounts, excluding service fee |
discount_amount | Discount applied due to promotions or special events |
service_fee | Additional fee to cover booking costs |
The relationship between these prices is:
retail_price = original_retail_price - discount_amount
retail_price_without_service_fee = original_retail_price_without_service_fee - discount_amount
original_retail_price = original_retail_price_without_service_fee + service_feeEach cart item contains price properties which take the product quantity into account:
| Property | Description | Calculation |
|---|---|---|
total_price | Total price for this cart item | quantity × product.retail_price |
total_price_without_service_fee | Total price excluding service fees | quantity × product.retail_price_without_service_fee |
For example, if a product has a retail_price of $10.80 and the cart item quantity is 2, the total_price will be $21.60.
Cart-level prices aggregate all items and include additional discount information:
| Property | Description | Calculation |
|---|---|---|
full_price | Original total before any discounts | Sum of (product.original_retail_price × quantity) for all items |
full_price_without_service_fee | Original total excluding service fees | Sum of (product.original_retail_price_without_service_fee × quantity) for all items |
discount | Promo code or gift card discount | Discount from applied promo code or gift card |
total_discount | Combined discount from all sources | discount + sum of (product.discount_amount × quantity) for all items |
retail_price | Final price for customers | Sum of all total_price values minus discount |
retail_price_without_service_fee | Final price excluding service fees | Sum of all total_price_without_service_fee values minus discount |
service_fee | Total service fees | Sum of (product.service_fee × quantity) for all items |
The cart supports multiple discount layers that are applied in sequence:
- Product discounts: Promotional discounts configured at the product level, reflected in
discount_amount - Custom discounts: Partner-specific discounts applied when adding items to cart (requires authorization)
- Promo codes: Customer-entered codes that apply a percentage or fixed discount to the cart total
- Gift cards: Prepaid value that reduces the cart total
When multiple discounts apply, they are calculated in the following order:
1. Product discount applied to base price
2. Custom discount applied (if authorized)
3. Cart-level discounts applied to cart total (promo codes and gift cards)Note: Both promo codes and gift cards are combined in the discount field in the API response. Percentage-based promo codes are calculated on the subtotal before fixed-amount discounts like gift cards are applied.
Prices are returned in the currency specified by the X-Musement-Currency header. If the header is missing, USD is used by default.
When the requested currency differs from the cart's current currency:
- The cart currency is updated to match the request
- Exchange rates are applied to all prices
- All cart items are recalculated
curl -X GET '{baseUrl}/carts/{cartUuid}' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}' \
-H 'X-Musement-Currency: EUR'If a cart is locked by a paid order, attempting to retrieve it with a different currency will return a 423 (Locked) status code. You must use the same currency as the locked cart.
Partners with merchant agreements may see an additional merchant_price field in the cart response. This represents the price that partners pay to Musement, based on specific commercial agreements.
{
"retail_price": {
"currency": "USD",
"value": 44.10,
"formatted_value": "$ 44.10",
"formatted_iso_value": "$44.10"
},
"merchant_price": {
"currency": "USD",
"value": 40.18,
"formatted_value": "$ 40.18",
"formatted_iso_value": "$40.18"
}
}In this example, customers pay the retail_price of $44.10, while partners pay Musement the merchant_price of $40.18.
The merchant_price field is only visible to authenticated partners with merchant role permissions. Contact the Strategic Partnerships team for more information.
Prices are automatically recalculated when:
- Items are added to or removed from the cart
- The cart currency is changed
- A promo code or gift card is applied or removed
- The cart is retrieved via the API
This ensures that prices always reflect the current state of products, exchange rates, and applicable discounts.
Consider a cart with two items and a promo code:
| Item | Product Price | Quantity | Service Fee | Discount | Item Total |
|---|---|---|---|---|---|
| Tour A | $100.00 | 2 | $5.00 | 10% ($10) | $180.00 |
| Tour B | $50.00 | 1 | $3.00 | 0% | $50.00 |
With a 5% promo code applied:
{
"full_price": {
"currency": "USD",
"value": 263.0,
"formatted_value": "$ 263.00",
"formatted_iso_value": "$263.00"
},
"full_price_without_service_fee": {
"currency": "USD",
"value": 250.0,
"formatted_value": "$ 250.00",
"formatted_iso_value": "$250.00"
},
"discount": {
"currency": "USD",
"value": 11.5,
"formatted_value": "$ 11.50",
"formatted_iso_value": "$11.50"
},
"total_discount": {
"currency": "USD",
"value": 31.5,
"formatted_value": "$ 31.50",
"formatted_iso_value": "$31.50"
},
"retail_price": {
"currency": "USD",
"value": 231.5,
"formatted_value": "$ 231.50",
"formatted_iso_value": "$231.50"
},
"service_fee": {
"currency": "USD",
"value": 13.0,
"formatted_value": "$ 13.00",
"formatted_iso_value": "$13.00"
}
}