# Create order

When a customer cart is ready, it's time to create an order and proceed to payment. We strongly recommend creating orders only when payment is guaranteed in order to reduce unnecessary API calls and avoid misleading results in sales reports.

Partners are able to include more details to help map the order to their own orders system.

Endpoint: POST /orders
Version: 3.5.0

## Header parameters:

  - `Accept-Language` (string)
    The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.

  - `X-Musement-Application` (string)
    A partner's application value, used for analyzing API usage and to identify areas of improvement.

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

  - `X-Musement-Version` (string)
    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"

## Request fields (application/json):

  - `affiliate` (string)
    The affiliate partner's alphanumeric ID.

  - `affiliate_channel` (string)
    A partner's channel ID for the order. Requires the affiliate property in the request body.

  - `cart_uuid` (string, required)
    The cart's UUID.
    Example: "ff111070-984a-4cff-87c7-2a32cd76de36"

  - `email_notification` (string)
    Specify which email notifications are sent:

  * ALL: all relevant notification emails
  * NONE: no emails are sent
  * TO-CUSTOMER: notification emails are sent to the customer only
    Enum: "ALL", "NONE", "TO-CUSTOMER"

  - `extra_data` (string)
    Additional info about the order that partners may want to save. This value only accepts 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\"}"

  - `sms_notification_to` (string)
    A phone number for SMS notifications related to the order. Values must follow the E.164 international standard.

  - `source` (string)
    The name of the application creating the order.

  - `cart_id` (integer)
    The cart's numeric ID. Please use the cart_uuid property instead.

## Response 200 fields (application/json):

  - `customer` (object, 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.country` (object)
    The customer's country.

  - `customer.country.country_prefix` (string)
    The country's main telephone country code.
    Example: "+39"

  - `customer.country.currency_code` (string)
    The main currency for the country as a Musement currency code. For a complete list of currencies, refer to the /currencies endpoint.
    Example: "EUR"

  - `customer.country.iso_code` (string, required)
    The two-character ISO code for the country.
    Example: "IT"

  - `customer.country.iso3char` (string, required)
    The three-character ISO code for the country.
    Example: "ITA"

  - `customer.country.name` (string, required)
    The country's name, translated based on the Accept-Language header value.
    Example: "Italy"

  - `customer.country.id` (integer, required)
    The country's numeric ID. This property will be removed in the future.
    Example: 82

  - `customer.email` (string, required)
    The customer's email address.
    Example: "api-distribution@tui.com"

  - `customer.extra_customer_data` (object)
    Extra customer data, based on the customer's cart items.
    Example: {"1223356a-69a0-4c45-bf51-bd903820d210":{"phone_number":1234567890}}

  - `customer.firstname` (string, required)
    The customer's first name.
    Example: "John"

  - `customer.lastname` (string, required)
    The customer's last name.
    Example: "Smith"

  - `customer.thirdparty_newsletter` (string)
    Whether the customer wants to receive newsletters from third parties or not.
    Enum: "NO", "YES"

  - `customer.musement_newsletter` (string)
    Whether the customer wants to receive newsletters from Musement or not.
    Enum: "NO", "YES"

  - `customer.events_related_newsletter` (string)
    Whether the customer wants to receive newsletters for related activities or not.
    Enum: "NO", "YES"

  - `customer.id` (integer)

  - `customer.avatar` (string)

  - `customer.currency` (object)

  - `customer.currency.code` (string)
    The currency's unique identifying code.
    Example: "USD"

  - `customer.currency.name` (string)
    The currency's name, translated based on the Accept-Language header value.
    Example: "US Dollar"

  - `customer.currency.symbol` (string)
    The currency's symbol.
    Example: "$"

  - `customer.birthdate` (string)
    Example: "1970-04-13"

  - `customer.gender` (object)

  - `customer.gender.code` (string)
    Customer's gender code. Possible values are:
 * MALE: Male
 * FEMALE: Female
 * OTHER: Other
    Enum: "MALE", "FEMALE", "OTHER"

  - `customer.gender.name` (string)
    Customer's gender label. | This value depends on the value of the header Accept-Language

  - `customer.id_number` (string)

  - `customer.mobile` (string)

  - `customer.address` (string)

  - `customer.favourite_city` (object)

  - `customer.favourite_city.activities_count` (integer)
    The number of available activities for the city.

  - `customer.favourite_city.id` (integer)
    The city's numeric ID.

  - `customer.favourite_city.code` (string)
    A string identifier for the city, based on the English version of the city name. This property is not affected by the Accept-Language header.

  - `customer.favourite_city.content` (string)
    A plain text description of the city, translated according to the Accept-Language header value.

  - `customer.favourite_city.content_html` (string)
    A description of the city with HTML tags, translated according to the Accept-Language header value.

  - `customer.favourite_city.country` (object)

  - `customer.favourite_city.cover_image_url` (string)
    A URL for the city's cover image.

  - `customer.favourite_city.event_count` (integer)
    The number of available activities for the city.

  - `customer.favourite_city.headline` (string)
    An SEO-friendly version of the city name for a page headline, translated based on the Accept-Language header value.

  - `customer.favourite_city.latitude` (number)

  - `customer.favourite_city.longitude` (number)

  - `customer.favourite_city.list_count` (integer)
    The number of available Musement list pages for the city.

  - `customer.favourite_city.meta_description` (string)
    An SEO-friendly description of the city, translated based on the Accept-Language header value.

  - `customer.favourite_city.meta_title` (string)
    An SEO-friendly version of the city name, translated based on the Accept-Language header value.

  - `customer.favourite_city.name` (string)
    The name of city, translated according to the Accept-Language header value.

  - `customer.favourite_city.slug` (string)
    The city slug, used for creating the city URL. Changes based on the value of the Accept-Language value.

  - `customer.favourite_city.time_zone` (string)
    The city's time zone.

  - `customer.favourite_city.top` (boolean)
    When true, the city is considered one of Musement's most popular cities.

  - `customer.favourite_city.url` (string)
    An automatically generated Musement URL for the city based on the X-Musement-Market header and slug property. The URL is only valid for select X-Musement-Market values and cities.

  - `customer.favourite_city.uuid` (string)
    The city's UUID.

  - `customer.favourite_city.venue_count` (integer)
    The number of available venues in the city.

  - `customer.favourite_city.weight` (integer)
    A property used for ranking multiple cities by popularity. Top selling cities will have a higher value.

  - `customer.favourite_city.more` (string)
    Additional information about the city in plain text, ideal for a "Read more" section, translated based on the Accept-Language header value.

  - `customer.favourite_city.more_html` (string)
    Additional information about the city with HTML tags, ideal for a "Read more" section, translated based on the Accept-Language header value.

  - `customer.locale` (string)

  - `date` (string, required)
    The order's creation date and time.

  - `discount_amount` (object, 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}

  - `discount_amount.currency` (string, required)
    The currency of the price, using a currency code from the /currencies endpoint.
    Example: "USD"

  - `discount_amount.formatted_iso_value` (string, required)
    The price and currency, formatted based on the value of the Accept-Language header value.
    Example: "$10.00"

  - `discount_amount.formatted_value` (string, required)
    The currency symbol and price, separated by a space.
    Example: "$ 10.00"

  - `discount_amount.value` (number, required)
    The numeric value of the price.
    Example: 10

  - `extra_data` (string)
    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\"}"

  - `identifier` (string, required)
    A unique human-friendly identifier for the order.

  - `items` (array, required)
    The items for the order.

  - `items.quantity` (integer)
    The booked quantity.

  - `items.b2b_price` (object)
    The amount a merchant or agency paid for the order item, in the currency used for payment.

  - `items.cancellation_additional_info` (string)
    Additional information about the cancellation which partners wish to communicate to Musement Customer Care.
    Example: "Customer rejected suggested change to reservation date."

  - `items.cancellation_reason` (string)
    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"

  - `items.error_status` (boolean)
    When true, there was an error while booking the order item.

  - `items.extra_customer_data` (array)
    Submitted extra customer data for the order item.

  - `items.extra_customer_data.name` (string)

  - `items.is_gift_redeem` (boolean)
    When true, the order item was used to redeem a gift or gift box.

  - `items.participants_info` (array)
    Submitted participant info for the order item.

  - `items.participants_info.salutation` (string)

  - `items.participants_info.firstname` (string)

  - `items.participants_info.lastname` (string)

  - `items.participants_info.date_of_birth` (string)

  - `items.participants_info.passport` (string)

  - `items.participants_info.email` (string)

  - `items.participants_info.passport_expiry_date` (string)

  - `items.participants_info.nationality` (string)

  - `items.participants_info.medical_notes` (string)

  - `items.participants_info.fan_card` (string)

  - `items.participants_info.weight` (number)

  - `items.participants_info.phone_number` (string)

  - `items.product` (object)
    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.product.activity_uuid` (string)
    The UUID of the selected activity.
    Example: "df542cb8-8fca-44d0-94e6-715399c783f0"

  - `items.product.api_url` (string)
    The API endpoint to use for more information about the selected activity.
    Example: "https://sandbox.musement.com/api/v3/activities/df542cb8-8fca-44d0-94e6-715399c783f0"

  - `items.product.cover_image_url` (string)
    A URL for the activity's cover image.
    Example: "https://images-sandbox.musement.com/cover/0001/93/washington-d-c-day-tour-from-new-york-city-1_header-92769.jpeg"

  - `items.product.date` (string)
    The selected date and time in the following format: Y-m-d H:i.
    Example: "2022-05-01 10:15"

  - `items.product.discount_amount` (object)
    A discount to subtract from the the "base price", for a quantity of 1, due to promotions or special events.
    Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}

  - `items.product.id` (string)
    The ID of the selected product.
    Example: "4445102588"

  - `items.product.language` (object)
    The selected language for the product.
    Example: {"code":"en","name":"English"}

  - `items.product.language.code` (string, required)
    The language code, following RFC 3066.
    Example: "en"

  - `items.product.language.name` (string, required)
    The name of the language, translated based on the Accept-Language header value.
    Example: "English"

  - `items.product.max_confirmation_time` (string)
    The maximum amount of time an activity provider needs to process a reservation request. Values follow the ISO 8601 standard.

This property is not used for instant confirmation activities.
    Example: "P0D"

  - `items.product.original_retail_price` (object)
    The base price for a quantity of 1 with a service fee, but no discount.
    Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}

  - `items.product.original_retail_price_without_service_fee` (object)
    The base price for a quantity of 1 with a discount, but no service fee.
    Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}

  - `items.product.pickup` (object)
    The selected pickup.
    Example: {"latitude":39.7191046,"longitude":3.4578191,"name":"Allsun Hotel Lux de Mar","tags":[{"id":"AC5257025","type":"CONTENT-MANAGER-DATA"},{"id":"472","type":"HOTEL-CODE"}],"type":"HOTEL","uuid":"c2326f61-c0d7-4353-8a1f-c1f12c4249f3"}

  - `items.product.pickup.name` (string)
    The name of the pickup location.
    Example: "Allsun Hotel Lux de Mar"

  - `items.product.pickup.place` (string)

  - `items.product.pickup.tags` (array)
    Example: [{"id":"AC5257025","type":"CONTENT-MANAGER-DATA"},{"id":"472","type":"HOTEL-CODE"}]

  - `items.product.pickup.tags.id` (string, required)
    The pickup tag's alphanumeric ID.

  - `items.product.pickup.tags.type` (string, required)
    The type of tag.
    Enum: "CONTENT-MANAGER-DATA", "HOTEL-CODE", "SUPPLIER"

  - `items.product.pickup.type` (string)
    The type of pickup:

* HOTEL: A hotel where customers can wait in the lobby.
* PICKUP: A general location. Customers may need to wait outside.
    Enum: "HOTEL", "PICKUP"

  - `items.product.pickup.uuid` (string)
    The pickup's UUID.
    Example: "c2326f61-c0d7-4353-8a1f-c1f12c4249f3"

  - `items.product.price_tag` (object)
    The selected option.
    Example: {"age_info":"18+","price_feature":"Tour","price_feature_code":"tour","ticket_holder":"Adult","ticket_holder_code":"adult"}

  - `items.product.price_tag.age_info` (string)
    The age range for the product. This could be depicted as a range with both a lower and a higher bound (such as 3-17) or as a single lower bound (such as 18+).
    Example: "18+"

  - `items.product.price_tag.price_feature` (string)
    The price tag feature, aka ticket option, translated based on the Accept-Language header value.
    Example: "Tour"

  - `items.product.price_tag.price_feature_code` (string)
    The unique alphanumeric identifier for the feature, aka ticket option.
    Example: "tour"

  - `items.product.price_tag.ticket_holder` (string)
    The price tag holder, translated based on the Accept-Language header value.
    Example: "Adult"

  - `items.product.price_tag.ticket_holder_code` (string)
    The unique alphanumerical identifier for the product's ticket holder.
    Example: "adult"

  - `items.product.retail_price` (object)
    The final price for customers for a quantity of 1.
    Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}

  - `items.product.retail_price_without_service_fee` (object)
    The base price for a quantity of 1 with a discount, but no service fee.
    Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}

  - `items.product.service_fee` (object)
    An extra fee to add to the base price, for a quantity of 1, to cover additional costs for creating a reservation.
    Example: {"currency":"USD","formatted_value":"$ 10.00","formatted_iso_value":"$10.00","value":10}

  - `items.product.title` (string)
    The title of the selected activity, translated based on the Accept-Language header value.
    Example: "Calendar activity with pickups and multiple price tag features"

  - `items.product.type` (string)
    The type of product.
    Enum: "musement", "musement-realtime"

  - `items.product.url` (string)
    An automatically generated Musement URL for the selected activity based on the X-Musement-Market header and item properties. The URL is only valid for select X-Musement-Market values and activities.
    Example: "https://.sbox.musement.com/bo-2b/washington-dc/calendar-activity-with-pickups-and-multiple-price-tag-features-175737/"

  - `items.status` (string)
    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_code` (string)
    A code identifying the order item's internal reservation details.

  - `items.uuid` (string)
    The order item's UUID.

  - `items.vouchers` (array)
    Available vouchers for the order item.

  - `items.vouchers.url` (string)
    URL to download the voucher for the order item.

  - `items.retail_price_in_order_currency` (object)
    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_currency` (object)
    The retail_price_in_order_currency times the item quantity, in the currency used to create the order.

  - `items.original_retail_price_in_supplier_currency` (object)
    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_currency` (object)
    The base price with a service fee times the item quantity, but no discount, in the currency suppliers use.

  - `market` (string)
    The market code used for the order.

  - `status` (string, required)
    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_price` (object, 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}

  - `trustpilot_url` (string)
    The URL customers can use to leave a review on Trustpilot about their experience making a reservation with Musement.

  - `uuid` (string, required)
    The order's UUID.

  - `total_retail_price_in_order_currency` (object, required)

  - `total_supplier_original_retail_price_in_supplier_currency` (object, required)

  - `total_supplier_price_in_supplier_currency` (object, required)

  - `affiliate` (object, required)

  - `affiliate.uuid` (string)

  - `affiliate.first_name` (string)

  - `affiliate.last_name` (string)

  - `affiliate.code` (string, required)

  - `affiliate.logo_url` (string, required)

  - `affiliate.secondary_logo_url` (string)

  - `affiliate.header` (string)

  - `affiliate.customer_care_phone_number` (string)

  - `affiliate.customer_care_email` (string)

  - `affiliate.whitelabel` (boolean)

  - `affiliate.show_cobranded_header` (boolean)

  - `affiliate.show_cobranded_voucher` (boolean)

  - `affiliate.show_cobranded_item_confirmation_email` (boolean)

  - `affiliate.setup_cookie_after_first_visit` (boolean)

  - `affiliate.translations` (array)

  - `affiliate_channel` (string)

  - `promo_codes` (array)

  - `promo_codes.active` (boolean)

  - `promo_codes.percentage` (boolean)

  - `promo_codes.discount` (integer)

  - `promo_codes.max_usage` (integer)

  - `promo_codes.valid_from` (string)

  - `promo_codes.valid_until` (string)

  - `promo_codes.minimum_amount` (number)

  - `source` (string)
    The name of the application that created the order.

## Response default fields (application/json):

  - `code` (string, required)
    The internal Musement code for the error.
    Example: "0"

  - `message` (string, required)
    A message with a brief explanation of the error.
    Example: "There was an error"