# Cart prices 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. ## Retrieving cart prices To view the complete pricing breakdown for a cart, 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}' \ -H 'X-Musement-Currency: USD' ``` Below is an example response showing the full pricing structure: ```json { "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" } } ``` ## Price structure 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") | ## Product prices 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](/api/catalog/activities/prices). 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_fee ``` ## Cart item prices Each 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 prices 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 | ## Discount types The cart supports multiple discount layers that are applied in sequence: 1. **Product discounts**: Promotional discounts configured at the product level, reflected in `discount_amount` 2. **Custom discounts**: Partner-specific discounts applied when adding items to cart (requires authorization) 3. **Promo codes**: Customer-entered codes that apply a percentage or fixed discount to the cart total 4. **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. ## Currency handling 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: 1. The cart currency is updated to match the request 2. Exchange rates are applied to all prices 3. All cart items are recalculated ```bash 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' ``` Locked carts 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. ## Merchant pricing 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. ```json { "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. Merchant pricing availability The `merchant_price` field is only visible to authenticated partners with merchant role permissions. Contact the [Strategic Partnerships team](mailto:business@musement.com) for more information. ## Price recalculation 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. ## Example: Complete pricing breakdown 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: ```json { "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" } } ```