Skip to content
/Payments

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

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

Pay for order via "no-payment flow"

Request

Confirm order payment with the "no-payment flow".

This flow can be used by any partner if the total price of an order is zero.

For orders with a total price greater than zero, this flow is reserved for partners acting as merchant of record. Permission to use this flow must be set up ahead of time.

For more info, check out our guide.
Security
Partner
Headers
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-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
uuidstring(uuid)required

The order's UUID.

Example: "de52057f-e788-46d6-8b18-6ccb8f9267d9"
idintegerDeprecated

The numeric order ID.

curl -i -X POST \
  https://partner-api.musement.com/_mock/reference/openapi/payments/no/payment \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Currency: USD' \
  -H 'X-Musement-Version: 3.4.0' \
  -d '{
    "uuid": "de52057f-e788-46d6-8b18-6ccb8f9267d9"
  }'

Responses

Order

Bodyapplication/json
customerobject(Customer)required

The customer for the order.

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"}
customer.​countryobject(Country)

The customer's country.

customer.​emailstring(email)required

The customer's email address.

Example: "api-distribution@tui.com"
customer.​extra_customer_dataobject(Extra customer data)

Extra customer data, based on the customer's cart items.

Example: {"1223356a-69a0-4c45-bf51-bd903820d210":{"phone_number":1234567890}}
customer.​firstnamestringrequired

The customer's first name.

Example: "John"
customer.​lastnamestringrequired

The customer's last name.

Example: "Smith"
customer.​thirdparty_newsletterstring

Whether the customer wants to receive newsletters from third parties or not.

Enum"NO""YES"
Example: "NO"
customer.​musement_newsletterstring

Whether the customer wants to receive newsletters from Musement or not.

Enum"NO""YES"
Example: "NO"
customer.​events_related_newsletterstring

Whether the customer wants to receive newsletters for related activities or not.

Enum"NO""YES"
Example: "NO"
customer.​idinteger
customer.​avatarstring
customer.​currencyobject(Currency)
customer.​birthdatestring(date)(Birthdate)
Example: "1970-04-13"
customer.​genderobject(CustomerGender)
customer.​id_numberstring
customer.​mobilestring
customer.​addressstring
customer.​favourite_cityobject(City)
customer.​localestring
datestring(date-time)required

The order's creation date and time.

discount_amountobject(Price)required

The total discount for the order, the sum of every order item's total_discount. The currency property matches the currency used for payment. Unpaid orders default to EUR.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
For more info, check out our guide.
discount_amount.​currencystring= 3 charactersrequired

The currency of the price, using a currency code from the /currencies endpoint.

Example: "USD"
discount_amount.​formatted_iso_valuestringrequired

The price and currency, formatted based on the value of the Accept-Language header value.

Example: "$10.00"
discount_amount.​formatted_valuestringrequired

The currency symbol and price, separated by a space.

Example: "$ 10.00"
discount_amount.​valuenumber(float)required

The numeric value of the price.

Example: 10
extra_datastring

Additional info about the order, provided by the partner. This property contains a serialized JSON object of key-value pairs.

Example: "{\"clientReferenceId\":\"12345678\",\"firstName\":\"John\",\"lastName\":\"Smith\",\"reservationId\":\"3E5B7445-00E6-4ED6-9321-19E30D73A128\",\"utm_campaign\":\"example-it\",\"utm_content\":\"it-native\",\"utm_medium\":\"example-App it\",\"utm_source\":\"channel-abc\"}"
identifierstring^MUS[0-9]+?$required

A unique human-friendly identifier for the order.

itemsArray of objects(OrderItem)uniquerequired

The items for the order.

items[].​quantityinteger>= 1

The booked quantity.

items[].​b2b_priceobject(Price)

The amount a merchant or agency paid for the order item, in the currency used for payment.

items[].​cancellation_additional_infostring<= 255 characters

Additional information about the cancellation which partners wish to communicate to Musement Customer Care.

Example: "Customer rejected suggested change to reservation date."
items[].​cancellation_reasonstring

Reason for a booking cancellation.

Enum"API-ISSUE""CANCELLED-BY-CUSTOMER""GRACE-PERIOD""MISSING-MEETING-POINT-DETAILS""MISSING-PASSENGER-INFO""REJECTED-ORDER""REJECTED-SCHEDULE-CHANGE""TECHNICAL-ISSUE""VENUE-CLOSED"
Example: "REJECTED-SCHEDULE-CHANGE"
items[].​error_statusboolean

When true, there was an error while booking the order item.

items[].​extra_customer_dataArray of objects(NameValue)

Submitted extra customer data for the order item.

items[].​is_gift_redeemboolean

When true, the order item was used to redeem a gift or gift box.

items[].​participants_infoArray of objects(PassengerInfo)

Submitted participant info for the order item.

items[].​productobject(Product)

The selected product for the order item.

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/"}
items[].​statusstring

The status of the order item:

  • CANCELLATION_ERROR: an error occurred while processing a cancellation. This status is temporary and will change to either OK or REFUNDED after examination by Musement Customer Care
  • KO: there was an issue finalizing the order item
  • OK: the order item is valid
  • PENDING: the order item's payment and confirmation are in progress
  • REFUND_STARTED: a refund request for the item is being processed. This status is temporary and will change to REFUNDED once the request has been resolved
  • REFUNDED: the order item has been cancelled and either partially or fully refunded
Enum"CANCELLATION_ERROR""KO""OK""PENDING""REFUND_STARTED""REFUNDED"
items[].​transaction_codestring

A code identifying the order item's internal reservation details.

items[].​uuidstring(uuid)

The order item's UUID.

items[].​vouchersArray of objects

Available vouchers for the order item.

items[].​retail_price_in_order_currencyobject(Price)

The retail_price of a single item's product, regardless of the quantity, in the currency used to create the order.

items[].​total_retail_price_in_order_currencyobject(Price)

The retail_price_in_order_currency times the item quantity, in the currency used to create the order.

items[].​original_retail_price_in_supplier_currencyobject(Price)

The base price with a service fee of a single item's product, but no discount, in the currency suppliers use.

items[].​total_original_retail_price_in_supplier_currencyobject(Price)

The base price with a service fee times the item quantity, but no discount, in the currency suppliers use.

marketstring(Market code)

The market code used for the order.

statusstringrequired

The status of the order:

  • KO: there was an issue finalizing the order or it has been cancelled without refund
  • OK: the order is valid
  • PENDING: the order's payment and item confirmation are in progress
  • REFUND_STARTED: a refund request for one or more order items is being processed. This status is temporary and will change to REFUNDED once the request has been resolved
  • REFUNDED: the order has been cancelled and either partially or fully refunded
Enum"KO""OK""PENDING""REFUND_STARTED""REFUNDED"
total_priceobject(Price)required

The total price customers are expected to pay, the sum of every order item's retail_price. The currency property matches the currency used for payment. Unpaid orders default to EUR.

Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}
For more info, check out our guide.
total_price.​currencystring= 3 charactersrequired

The currency of the price, using a currency code from the /currencies endpoint.

Example: "USD"
total_price.​formatted_iso_valuestringrequired

The price and currency, formatted based on the value of the Accept-Language header value.

Example: "$10.00"
total_price.​formatted_valuestringrequired

The currency symbol and price, separated by a space.

Example: "$ 10.00"
total_price.​valuenumber(float)required

The numeric value of the price.

Example: 10
trustpilot_urlstring(uri)

The URL customers can use to leave a review on Trustpilot about their experience making a reservation with Musement.

uuidstring(uuid)required

The order's UUID.

total_retail_price_in_order_currencyobject(Price)required
total_retail_price_in_order_currency.​currencystring= 3 charactersrequired

The currency of the price, using a currency code from the /currencies endpoint.

total_retail_price_in_order_currency.​formatted_iso_valuestringrequired

The price and currency, formatted based on the value of the Accept-Language header value.

total_retail_price_in_order_currency.​formatted_valuestringrequired

The currency symbol and price, separated by a space.

total_retail_price_in_order_currency.​valuenumber(float)required

The numeric value of the price.

total_supplier_original_retail_price_in_supplier_currencyobject(Price)required
total_supplier_original_retail_price_in_supplier_currency.​currencystring= 3 charactersrequired

The currency of the price, using a currency code from the /currencies endpoint.

total_supplier_original_retail_price_in_supplier_currency.​formatted_iso_valuestringrequired

The price and currency, formatted based on the value of the Accept-Language header value.

total_supplier_original_retail_price_in_supplier_currency.​formatted_valuestringrequired

The currency symbol and price, separated by a space.

total_supplier_original_retail_price_in_supplier_currency.​valuenumber(float)required

The numeric value of the price.

total_supplier_price_in_supplier_currencyobject(Price)required
total_supplier_price_in_supplier_currency.​currencystring= 3 charactersrequired

The currency of the price, using a currency code from the /currencies endpoint.

total_supplier_price_in_supplier_currency.​formatted_iso_valuestringrequired

The price and currency, formatted based on the value of the Accept-Language header value.

total_supplier_price_in_supplier_currency.​formatted_valuestringrequired

The currency symbol and price, separated by a space.

total_supplier_price_in_supplier_currency.​valuenumber(float)required

The numeric value of the price.

affiliateobject(Affiliate)required
affiliate.​uuidstring
affiliate.​emailstring
affiliate.​first_namestring
affiliate.​last_namestring
affiliate.​codestringrequired
affiliate.​namestringrequired
affiliate.​logo_urlstringrequired
affiliate.​secondary_logo_urlstring
affiliate.​headerstring
affiliate.​customer_care_phone_numberstring
affiliate.​customer_care_emailstring
affiliate.​whitelabelboolean
affiliate.​show_cobranded_headerboolean
affiliate.​show_cobranded_voucherboolean
affiliate.​show_cobranded_item_confirmation_emailboolean
affiliate.​setup_cookie_after_first_visitboolean
affiliate.​translationsArray of objects(AffiliateI18n)
affiliate_channelstring
promo_codesArray of objects(PromoCode)
sourcestring

The name of the application that created the order.

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"
  },
  "date": "2019-08-24T14:15:22Z",
  "discount_amount": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "extra_data": "{\"clientReferenceId\":\"12345678\",\"firstName\":\"John\",\"lastName\":\"Smith\",\"reservationId\":\"3E5B7445-00E6-4ED6-9321-19E30D73A128\",\"utm_campaign\":\"example-it\",\"utm_content\":\"it-native\",\"utm_medium\":\"example-App it\",\"utm_source\":\"channel-abc\"}",
  "identifier": "string",
  "items": [
    { … }
  ],
  "market": "string",
  "status": "KO",
  "total_price": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "trustpilot_url": "http://example.com",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "total_retail_price_in_order_currency": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "total_supplier_original_retail_price_in_supplier_currency": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "total_supplier_price_in_supplier_currency": {
    "currency": "USD",
    "formatted_value": "$ 10.00",
    "formatted_iso_value": "$10.00",
    "value": 10
  },
  "affiliate": {
    "uuid": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "code": "string",
    "name": "string",
    "logo_url": "string",
    "secondary_logo_url": "string",
    "header": "string",
    "customer_care_phone_number": "string",
    "customer_care_email": "string",
    "whitelabel": true,
    "show_cobranded_header": true,
    "show_cobranded_voucher": true,
    "show_cobranded_item_confirmation_email": true,
    "setup_cookie_after_first_visit": true,
    "translations": [ … ]
  },
  "affiliate_channel": "string",
  "promo_codes": [
    { … }
  ],
  "source": "string"
}

Begin payment via Adyen or Stripe

Request

Start paying for an order using either Adyen or Stripe.

Use of this endpoint requires completing payment with the POST /payments/split/complete_3d_secure endpoint.

For more info, check out our guide.
Headers
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-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
One of:
adyen_tokenstringrequired

The Adyen token, prepared on the client application's side.

card_brandstring

The name of the credit card company.

card_countrystring= 2 characters

The card's country code.

client_ipstring

The client application's IP address.

order_uuidstring(uuid)required

The UUID of the order to pay for.

redirect_url_success_3d_securestring(uri)

The URL to send customers to after they have completed 3D Secure authentication.

curl -i -X POST \
  https://partner-api.musement.com/_mock/reference/openapi/payments/split/payment \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Version: 3.4.0' \
  -d '{
    "adyen_token": "string",
    "card_brand": "string",
    "card_country": "st",
    "client_ip": "string",
    "order_uuid": "e56795c7-0bc3-4742-a52f-988d2af8608f",
    "redirect_url_success_3d_secure": "http://example.com"
  }'

Responses

Payment details

Bodyapplication/json
gatewaystring

The payment gateway to use.

Enum"ADYEN""STRIPE"
3d_secureobject(Payment3dSecure)

Information required for setting up 3D Secure authentication.

reasonstring

An indication of which payment gateway was selected:

  • BUSINESS_STRATEGY: automatically based on which gateway provides the best commission.
  • CLIENT_SELECTED: based on request body.
  • FALLBACK: when one gateway payment attempt fails, the other is selected for a second attempt.
Enum"BUSINESS_STRATEGY""CLIENT_SELECTED""FALLBACK"
Response
application/json
{
  "gateway": "ADYEN",
  "3d_secure": {
    "payload": {},
    "payment_intent_client_secret": "string",
    "type": "FORM",
    "url": "http://example.com"
  },
  "reason": "BUSINESS_STRATEGY"
}

Complete payment via Adyen or Stripe

Request

Finish paying for an order using either Adyen or Stripe.

After completing 3D Secure authentication, use this endpoint to confirm successful payment for the order.

For more info, check out our guide.
Headers
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-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
order_uuidstring(uuid)required

The order's UUID.

payment_intent_idstringrequired

The payment intent ID received from starting 3D Secure authentication.

curl -i -X POST \
  https://partner-api.musement.com/_mock/reference/openapi/payments/split/complete_3d_secure \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Version: 3.4.0' \
  -d '{
    "order_uuid": "e56795c7-0bc3-4742-a52f-988d2af8608f",
    "payment_intent_id": "string"
  }'

Responses

Payment details

Bodyapplication/json
3d_secureobject(Payment3dSecure)

Information required for setting up 3D Secure authentication.

Response
application/json
{
  "3d_secure": {
    "payload": {},
    "payment_intent_client_secret": "string",
    "type": "FORM",
    "url": "http://example.com"
  }
}

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.