Skip to content
/Carts

Musement API (3.5.0)

For merchant or affiliate partners wishing to use the Musement API.

Find out more about Musement API

Authentication

See the Authentication section for details on how to authenticate with the API.

Release notes

2024-06-18

Endpoints

  • GET /activities/{activityUuid}/dates/{date}
    • Changed default min_buy value from -1 to 1

2024-02-21

Endpoints

  • Added GET /orders/{orderUuid}/refunds
    • Returns an array of paid refunds for an order

2024-02-20

Endpoints

  • GET /activities/{activityUuid}/dates/{date}
    • Added availability, max_buy and min_buy properties to timeslots. For more info, check out our guide
Download OpenAPI description
openapi.json
openapi.yaml
Overview
API distribution team
api-distribution@tui.com
License
Apache 2.0
Terms of Service
Languages
Servers
Mock server
https://partner-api.musement.com/_mock/reference/openapi
Sandbox server
https://sandbox.musement.com/api/v3
Production server
https://api.musement.com/api/v3

Searching activities

A collection of endpoints which can be used to search the catalog for relevant activities.

Operations

Activity info

A collection of endpoints which can be used to provide information to customers about a specific activity.

Operations

Pickups

Some activities require selecting a pickup location as part of the booking flow.

Operations

Dates

A collection of endpoints for selecting available dates and products.

Operations

Carts

A collection of endpoints for managing a customer's cart during the booking flow.

Operations

Create cart

Request

Creating a cart is a key step in the reservation flow.

It's not necessary to provide customer info at this stage. Customer info can be supplied later using the PUT /carts/{cartUuid}/customer endpoint.

Carts without an order are automatically removed after three months.

For more info, check out our guide.
Headers
Accept-Languagestring(Language code)

The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.

Default en-US
X-Musement-Applicationstring(Application value)

A partner's application value, used for analyzing API usage and to identify areas of improvement.

For more info, check out our guide.
X-Musement-Currencystring(Currency code)

A valid currency code from the /currencies endpoint. Default value may vary depending on the X-Musement-Market header value.

Default USD
X-Musement-Marketstring(Musement market)

Musement markets contain a modified catalog of activities and prices. Partners are expected to use their assigned market code to view their customized catalog.

An invalid X-Musement-Market value will return a 400 status code response.

Default us
For more info, check out our guide.
X-Musement-Versionstring^[0-9]+?.[0-9]+?.[0-9]+?$

The API version to use for the request.

When absent, the latest version is used by default, however the latest version may not be stable. Partners are encouraged to use the latest stable version: 3.4.0.

Example: 3.4.0
For more info, check out our guide.
Bodyapplication/jsonrequired

If customer info is not available at this stage, the request can be an empty object: {}

customerobject
curl -i -X POST \
  https://partner-api.musement.com/_mock/reference/openapi/carts \
  -H 'Accept-Language: en-US' \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Currency: USD' \
  -H 'X-Musement-Market: us' \
  -H 'X-Musement-Version: 3.4.0' \
  -d '{}'

Responses

Cart

Bodyapplication/json
customerobject(Customer)

The cart's customer info.

Example: {"email":"api-distribution@tui.com","events_related_newsletter":"NO","extra_customer_data":{"1223356a-69a0-4c45-bf51-bd903820d210":{"phone_number":1234567890}},"firstname":"John","lastname":"Smith","musement_newsletter":"NO","thirdparty_newsletter":"NO"}
discountobject(Price)

Discount info for the cart if a promo code has been applied.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
full_priceobject(Price)

The sum of every product's original_retail_price property value multiplied by the corresponding cart item's quantity.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
full_price_without_service_feeobject(Price)

The sum of every product's original_retail_price_without_service_fee property value multiplied by the corresponding cart item's quantity.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
itemsArray of objects(CartItem)unique

The cart items.

preferred_payment_gatewaystring

This property defines which payment gateway should be used for partners following the split payment flow.

Enum"ADYEN""STRIPE"
promo_codeobject

The promo code (if any) applied to cart for a discount.

retail_priceobject(Price)

This property is the final price for customers. It is the sum of every cart item's total_price property value minus the cart's discount value.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
retail_price_without_service_feeobject(Price)

The sum of every cart item's total_price_without_service_fee property value minus the cart's discount value.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
service_feeobject(Price)

The sum of every product's service_fee property value.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
total_discountobject(Price)

The sum of:

  • The cart's discount property
  • Every product's discount_amount property value multiplied by the corresponding cart item's quantity.
Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
uuidstring(uuid)

The UUID of the cart.

Response
application/json
{
  "customer": {
    "email": "api-distribution@tui.com",
    "events_related_newsletter": "NO",
    "extra_customer_data": { … },
    "firstname": "John",
    "lastname": "Smith",
    "musement_newsletter": "NO",
    "thirdparty_newsletter": "NO"
  },
  "discount": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "full_price": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "full_price_without_service_fee": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "items": [
    { … }
  ],
  "preferred_payment_gateway": "ADYEN",
  "promo_code": {
    "code": "string"
  },
  "retail_price": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "retail_price_without_service_fee": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "service_fee": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "total_discount": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Get cart

Request

Returns a cart.

Carts without an order are automatically removed after three months.

Once the cart is connected to a closed order, the cart can only be viewed when the X-Musement-Currency header value matches the cart's original currency. Attempts to access the cart with different currencies will result in a 423 status code response.

Path
cartUuidstring(uuid)required

The UUID of the cart.

Headers
Accept-Languagestring(Language code)

The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.

Default en-US
X-Musement-Applicationstring(Application value)

A partner's application value, used for analyzing API usage and to identify areas of improvement.

For more info, check out our guide.
X-Musement-Currencystring(Currency code)

A valid currency code from the /currencies endpoint. Default value may vary depending on the X-Musement-Market header value.

Default USD
X-Musement-Marketstring(Musement market)

Musement markets contain a modified catalog of activities and prices. Partners are expected to use their assigned market code to view their customized catalog.

An invalid X-Musement-Market value will return a 400 status code response.

Default us
For more info, check out our guide.
X-Musement-Versionstring^[0-9]+?.[0-9]+?.[0-9]+?$

The API version to use for the request.

When absent, the latest version is used by default, however the latest version may not be stable. Partners are encouraged to use the latest stable version: 3.4.0.

Example: 3.4.0
For more info, check out our guide.
curl -i -X GET \
  'https://partner-api.musement.com/_mock/reference/openapi/carts/{cartUuid}' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Currency: USD' \
  -H 'X-Musement-Market: us' \
  -H 'X-Musement-Version: 3.4.0'

Responses

Cart

Bodyapplication/json
customerobject(Customer)

The cart's customer info.

Example: {"email":"api-distribution@tui.com","events_related_newsletter":"NO","extra_customer_data":{"1223356a-69a0-4c45-bf51-bd903820d210":{"phone_number":1234567890}},"firstname":"John","lastname":"Smith","musement_newsletter":"NO","thirdparty_newsletter":"NO"}
discountobject(Price)

Discount info for the cart if a promo code has been applied.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
full_priceobject(Price)

The sum of every product's original_retail_price property value multiplied by the corresponding cart item's quantity.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
full_price_without_service_feeobject(Price)

The sum of every product's original_retail_price_without_service_fee property value multiplied by the corresponding cart item's quantity.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
itemsArray of objects(CartItem)unique

The cart items.

preferred_payment_gatewaystring

This property defines which payment gateway should be used for partners following the split payment flow.

Enum"ADYEN""STRIPE"
promo_codeobject

The promo code (if any) applied to cart for a discount.

retail_priceobject(Price)

This property is the final price for customers. It is the sum of every cart item's total_price property value minus the cart's discount value.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
retail_price_without_service_feeobject(Price)

The sum of every cart item's total_price_without_service_fee property value minus the cart's discount value.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
service_feeobject(Price)

The sum of every product's service_fee property value.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
total_discountobject(Price)

The sum of:

  • The cart's discount property
  • Every product's discount_amount property value multiplied by the corresponding cart item's quantity.
Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
uuidstring(uuid)

The UUID of the cart.

Response
application/json
{
  "customer": {
    "email": "api-distribution@tui.com",
    "events_related_newsletter": "NO",
    "extra_customer_data": { … },
    "firstname": "John",
    "lastname": "Smith",
    "musement_newsletter": "NO",
    "thirdparty_newsletter": "NO"
  },
  "discount": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "full_price": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "full_price_without_service_fee": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "items": [
    { … }
  ],
  "preferred_payment_gateway": "ADYEN",
  "promo_code": {
    "code": "string"
  },
  "retail_price": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "retail_price_without_service_fee": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "service_fee": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "total_discount": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Add items to cart

Request

While this endpoint accepts multiple items, only the first item is returned. A cart can hold a maximum of 100 items. Carts are allowed to contain items from different activities.

For more info, check out our guide.
Path
cartUuidstring(uuid)required

The UUID of the cart.

Headers
Accept-Languagestring(Language code)

The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.

Default en-US
X-Musement-Applicationstring(Application value)

A partner's application value, used for analyzing API usage and to identify areas of improvement.

For more info, check out our guide.
X-Musement-Currencystring(Currency code)

A valid currency code from the /currencies endpoint. Default value may vary depending on the X-Musement-Market header value.

Default USD
X-Musement-Marketstring(Musement market)

Musement markets contain a modified catalog of activities and prices. Partners are expected to use their assigned market code to view their customized catalog.

An invalid X-Musement-Market value will return a 400 status code response.

Default us
For more info, check out our guide.
X-Musement-Versionstring^[0-9]+?.[0-9]+?.[0-9]+?$

The API version to use for the request.

When absent, the latest version is used by default, however the latest version may not be stable. Partners are encouraged to use the latest stable version: 3.4.0.

Example: 3.4.0
For more info, check out our guide.
Bodyapplication/jsonrequired

An array of items to add to cart.

Array [
languagestring(Language code)[a-z]{2}

The selected language (if any).

pickupstring(uuid)(Pickup UUID)

The selected pickup.

This property is required for activities with pickups.

For more info, check out our guide.
product_identifierstringrequired

The product identifier. Depending on the activity configuration, this could be a numeric value or a complex string.

Example: "4445092627"
quantityinteger>= 1required

The number of products to add to cart.

Example: 2
typestringrequired

The type of product.

Enum"musement""musement-realtime"
Example: "musement"
]
curl -i -X POST \
  'https://partner-api.musement.com/_mock/reference/openapi/carts/{cartUuid}/items' \
  -H 'Accept-Language: en-US' \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Currency: USD' \
  -H 'X-Musement-Market: us' \
  -H 'X-Musement-Version: 3.4.0' \
  -d '[
    {
      "type": "musement",
      "product_identifier": "4445092627",
      "quantity": 2
    }
  ]'

Responses

Cart item

Bodyapplication/json
productobject(Product)

The selected product.

Example: {"activity_uuid":"df542cb8-8fca-44d0-94e6-715399c783f0","api_url":"https://sandbox.musement.com/api/v3/activities/df542cb8-8fca-44d0-94e6-715399c783f0","cover_image_url":"https://images-sandbox.musement.com/cover/0001/93/washington-d-c-day-tour-from-new-york-city-1_header-92769.jpeg","date":"2022-05-01 10:15","discount_amount":{"currency":"EUR","formatted_value":"€ 0.00","formatted_iso_value":"€0.00","value":0},"id":"4445102588","language":{"code":"en","name":"English"},"max_confirmation_time":"P0D","original_retail_price":{"currency":"EUR","formatted_value":"€ 9.00","formatted_iso_value":"€9.00","value":9},"original_retail_price_without_service_fee":{"currency":"EUR","formatted_value":"€ 9.00","formatted_iso_value":"€9.00","value":9},"retail_price":{"currency":"EUR","formatted_value":"€ 9.00","formatted_iso_value":"€9.00","value":9},"retail_price_without_service_fee":{"currency":"EUR","formatted_value":"€ 9.00","formatted_iso_value":"€9.00","value":9},"service_fee":{"currency":"EUR","formatted_value":"€ 0.00","formatted_iso_value":"€0.00","value":0},"title":"Calendar activity with pickups and multiple price tag features","type":"musement","url":"https://.sbox.musement.com/bo-2b/washington-dc/calendar-activity-with-pickups-and-multiple-price-tag-features-175737/"}
quantityinteger>= 1

The quantity of requested product.

statusstring

The status of the cart item:

  • PREBOOK_KO: the cart item is no longer available.
  • PREBOOK_OK: the cart item is still available for purchase.
Enum"PREBOOK_OK""PREBOOK_KO"
total_priceobject(Price)

The product's retail_price multiplied by the cart's quantity property.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
total_price_without_service_feeobject(Price)

The product's retail_price_without_service_fee multiplied by the cart's quantity property.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
uuidstring(uuid)

The cart item's UUID.

Response
application/json
{
  "product": {
    "activity_uuid": "df542cb8-8fca-44d0-94e6-715399c783f0",
    "api_url": "https://sandbox.musement.com/api/v3/activities/df542cb8-8fca-44d0-94e6-715399c783f0",
    "cover_image_url": "https://images-sandbox.musement.com/cover/0001/93/washington-d-c-day-tour-from-new-york-city-1_header-92769.jpeg",
    "date": "2022-05-01 10:15",
    "discount_amount": { … },
    "id": "4445102588",
    "language": { … },
    "max_confirmation_time": "P0D",
    "original_retail_price": { … },
    "original_retail_price_without_service_fee": { … },
    "retail_price": { … },
    "retail_price_without_service_fee": { … },
    "service_fee": { … },
    "title": "Calendar activity with pickups and multiple price tag features",
    "type": "musement",
    "url": "https://.sbox.musement.com/bo-2b/washington-dc/calendar-activity-with-pickups-and-multiple-price-tag-features-175737/"
  },
  "quantity": 1,
  "status": "PREBOOK_OK",
  "total_price": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "total_price_without_service_fee": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Customer info

When making a reservation, different steps must be taken to provide information about the customers. This collection includes endpoints for submitting info about the lead booker, extra customer data and participant info.

Operations

Orders

A collection of endpoints for managing orders as part of the booking flow.

Operations

Payments

A collection of endpoints regarding payment during the booking flow. Partners have multiple payment options at their disposal, depending on agreements with the Strategic partnerships team.

Operations

Cancellations

It is possible to cancel reservations, provided that the activity in question is refundable.

Operations

Activities

Activities can be any tour, attraction or experience that customers can reserve via the Musement API.

Operations

Categories

Categories group activities based on similar characteristics.

Operations

Cities

Cities are different types of destinations: islands, natural landmarks, beaches, actual cities and more.

Operations

Countries

A collection of endpoints related to countries in the Musement catalog.

Operations

Lists

Lists are collections of Musement activities and third-party destinations grouped together based on editorial themes.

Operations

Venues

Venues are popular attractions or landmarks.

Operations

Additional searches

A collection of additional endpoints which can be used to search parts of the catalog.

Operations

Carts

A collection of cart endpoints which are not strictly necessary for the booking flow.

Operations

Metadata

Metadata is used for configuring several activity properties.

Operations

Reviews

Customers may leave reviews about their experience with an activity. Reviews consist of a numeric rating and optional written comment.

Operations

Vouchers

A collection of endpoints to use at the end of the booking flow to retrieve reserved tickets and vouchers.

Operations

Webhooks

A collection of webhook requests that Musement's API can make to a partner's service.

Webhooks

Activities

A collection of deprecated endpoints for activities.

Operations

Carts

A collection of deprecated endpoints for carts.

Operations

Cities

A collection of deprecated endpoints for cities.

Operations

Verticals

Verticals are a type of macro category which group various parts of the catalog together based on similar characteristics.

They are considered deprecated.

Operations

Cities

A collection of endpoints for cities that were removed from the API.

Operations

Countries

A collection of endpoints for countries that were removed from the API.

Operations

Events

A collection of endpoints for events, an older term for activities, that were removed from the API.

Operations

Misc

A collection of various endpoints that were removed from the API.

Operations

Venues

A collection of endpoints for venues that were removed from the API.

Operations
Copyright © TUI Musement. All rights reserved.