Manage items

Once the cart is created the first thing you probably want to do is add an item to it.

curl -X POST \
  https://api.musement.com/api/v3/carts/[CART_UUID]/items \
  -H 'Authorization: Bearer ValidAccessToken' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Currency: USD' \
  -d '{
  "type" : "musement",
  "product_identifier" : "249217479",
  "quantity": 2,
  "language": "it",
   "pickup" : "5ee32dbd-898d-4f2e-aa9b-bb430b9a4960"
}'

There are 5 values you need to specify:

  • type | Is the type of product of the item
  • product_identifier | Product unique identifier. Please note that this can be an integer or a string
  • quantity | Desiderated number of products
  • language | This value can be specified only for the some products. See "Language" section later.
  • pickup | This value must be specified for activity with mandatory pickups. See "Pick-Ups" documentation.

The value for type and product are available in the response for

curl -X GET \
  https://api.musement.com/api/v3/activities/[ACTIVITY_UUID]/dates/[YYYY-MM-DD] \
  -H 'Authorization: Bearer ValidAccessToken' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Currency: USD'

you must find type and product_id in the product model

[..]
{
  "holder_code": "1-person",
  "name": "1 Person",
  "type": "musement",
  "default": false,
  "product_id": "249217479",
  "min_buy": 1,
  "max_buy": 15,
  "availability": 55,
  "original_retail_price": {
    "currency": "USD",
    "value": 63,
    "formatted_value": "$ 63.00"
  },
  "discount_amount": {
    "currency": "USD",
    "value": 0,
    "formatted_value": "$ 0.00"
  },
  "retail_price": {
    "currency": "USD",
    "value": 63,
    "formatted_value": "$ 63.00"
  }
}
[..]

Here a sample call

curl -X POST \
  https://api.musement.com/api/v3/carts/[CART_UUID]/items \
  -H 'Authorization: Bearer ValidAccessToken' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Currency: USD' \
  -d '{
  "type" : "musement",
  "product_identifier" : "249217479",
  "quantity": 2
}'

You will get a response with all the details related to the cart item.

{
    "uuid": "af8c936c-8716-4ae8-899d-74e7d1a3e4b2",
    "status": "PREBOOK_OK",
    "quantity": 2,
    "total_price": {
        "currency": "USD",
        "value": 42,
        "formatted_value": "$ 42.00"
    },
    "product": {
        "type": "musement",
        "max_confirmation_time": "P0D",
        "price_tag": {
            "price_feature": "Tour",
            "ticket_holder": "Adult",
            "price_feature_code": "tour",
            "ticket_holder_code": "adult"
        },
        "date": "2018-09-01 15:30",
        "id": "434696106",
        "title": "Exclusive skip-the-line guided visit of Leonardo da Vinci's vineyard",
        "api_url": "https://api.musement.com/api/v3/activities/11eeb25c-2046-11e7-9cc9-06a7e332783f",
        "url": "https://www.musement.com/us/milan/exclusive-skip-the-line-guided-visit-of-leonardo-da-vinci-s-vineyard-3936/",
        "cover_image_url": "https://images.musement.com/cover/0002/50/thumb_149030_cover_header.jpeg",
        "original_retail_price": {
            "currency": "USD",
            "value": 21,
            "formatted_value": "$ 21.00"
        },
        "retail_price": {
            "currency": "USD",
            "value": 21,
            "formatted_value": "$ 21.00"
        },
        "discount_amount": {
            "currency": "USD",
            "value": 0,
            "formatted_value": "$ 0.00"
        },
        "service_fee": {
            "currency": "USD",
            "value": 0,
            "formatted_value": "$ 0.00"
        }
    }
}

You can now add more items to the cart.

Language

For some activity's timeslots is possible to specify the language. The list of available languages is presented in the array languages given in response for the call https://api.musement.com/api/v3/activities/[ACTIVITY_UUID]/dates/[YYYY-MM-DD].

An sample response is like

[
    {
        "groups": [
            {
                "feature_code": "tour",
                "name": "Tour",
                "default": false,
                "type": "TIME-BASED",
                "slots": [
                    {
                        "time": "14:30",
                        "languages": [
                            {
                                "code": "it",
                                "name": "Italian"
                            },
                            {
                                "code": "en",
                                "name": "English"
                            }
                        ],
                        "products": [
                            {
                                "holder_code": "adult",
                                "name": "Adult",
                                "type": "musement",
                                "default": false,
                                "product_id": "434696103",
                                "min_buy": 1,
                                "max_buy": 15,
                                "availability": -1,
                                "original_retail_price": {
                                    "currency": "USD",
                                    "value": 21,
                                    "formatted_value": "$ 21.00"
                                },
                                "discount_amount": {
                                    "currency": "USD",
                                    "value": 0,
                                    "formatted_value": "$ 0.00"
                                },
                                "retail_price": {
                                    "currency": "USD",
                                    "value": 21,
                                    "formatted_value": "$ 21.00"
                                },
                                "merchant_price": {
                                    "currency": "USD",
                                    "value": 13.3,
                                    "formatted_value": "$ 13.30"
                                }
                            }
                    },
                    {
                        "time": "15:30",
                        "languages": [
                            {
                                "code": "es",
                                "name": "Spanish"
                            },
                            {
                                "code": "fr",
                                "name": "French"
                            }
                        ],
                        "products": [
                            {
                                "holder_code": "senior",
                                "name": "Senior (65+)",
                                "type": "musement",
                                "default": false,
                                "product_id": "434696108",
                                "min_buy": 1,
                                "max_buy": 15,
                                "availability": -1,
                                "original_retail_price": {
                                    "currency": "USD",
                                    "value": 15,
                                    "formatted_value": "$ 15.00"
                                },
                                "discount_amount": {
                                    "currency": "USD",
                                    "value": 0,
                                    "formatted_value": "$ 0.00"
                                },
                                "retail_price": {
                                    "currency": "USD",
                                    "value": 15,
                                    "formatted_value": "$ 15.00"
                                },
                                "merchant_price": {
                                    "currency": "USD",
                                    "value": 12.1,
                                    "formatted_value": "$ 12.10"
                                }
                            }
                        ],
                        "tags": []
                    }
                ]
            }
        ]
    }
]

Please note that language can be different from one time slot to the other one.

Other operation available are:

Add

Information related to the Customer

The customer information can be added after the cart is created.

You can use this endpoint to know what customer information are required to create a cart:
GET {{api_base_url}}/carts/{cartUUID}/form

To add the customer in a second time, or to add data to an already existing cart you can use PATCH method and pass the information in body.

Example:
PATCH {{api_base_url}}/carts/{cartUUID}
Body:

{
  "customer" : {
    "email": "[email protected]",
    "firstname": "Guest136a",
    "lastname": "surname136a",
    "country": {
      "id": 123
    }
  }
}

🚧

Requirements

  • email, firstname, lastname, and country are all mandatory.

Failed to add Ticket to Cart

The "Failed to add Ticket to Cart" response can be received because of availability issues (activity is now sold out or buffer time) or because of technical issue we are facing coming from our suppliers' API or because your request goes against consistency checks.

example

A 400 error is returned when you pass a pickup which is not valid while trying to add an item to a cart.

{
    "code": "2102",
    "message": "The `pickup` in the payload is not valid for this activity. To see the list of available pickups for this specific activity call https://api.musement.com/api/v3/activities/{uuid}/pickups."
}

example

A 400 error is returned when you don't pass a pickup in the request while you should.

{
    "code": "2101",
    "message": "You must pass the parameter `pickup` in the body of the request. See https://api-docs.musement.com/docs for details"
}

Handling children Tickets

Children tickets must be added to the cart only together with adult ones.

Make sure you create a cart and then you pass two objects: one with adult tickets and one with child tickets.

curl -X POST \
  https://api.musement.com/api/v3/carts/[CART_UUID]/items \
  -H 'Authorization: Bearer ValidAccessToken' \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Currency: USD' \
  -d '{
  "type" : "musement",
  "product_identifier" : "bd1234567890",
  "quantity": 2,
  "language": "it",
   "pickup" : "5ee32dbd-898d-4f2e-aa9b-bb430b9a4960"
}, {
  "type" : "musement",
  "product_identifier" : "ab1234567890",
  "quantity": 2,
  "language": "it",
   "pickup" : "5ee32dbd-898d-4f2e-aa9b-bb430b9a4960"
}'

How do you know if a ticket belongs to a child?

When holder_code contains "child" , then it represents a ticket for children.

What about infants?

At the moment, infants are basically free entry ones, so we let you add "infant" tickets without any restriction.

Examples

curl -X POST \
  https://api.musement.com/api/v3/carts/[CART_UUID]/items \
  -H 'Authorization: Bearer ValidAccessToken' \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Currency: USD' \
  -d '{
    "type": "{{productType}}",
    "product_identifier": "{{productIdAdult}}",
    "quantity": 2,
    "language": "en"
}'
curl -X POST \
  https://api.musement.com/api/v3/carts/[CART_UUID]/items \
  -H 'Authorization: Bearer ValidAccessToken' \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Currency: USD' \
  -d '{
    "type": "{{productType}}",
    "product_identifier": "{{productIdAdult}}",
    "quantity": 1,
    "language": "en",
    "pickup": "{{pickup_uuid}}"
}'

When adding child tickets to cart, we have to add the child ticket at the same time as the adult.

In this scenario we should submit an array of objects.

curl -X POST \
  https://api.musement.com/api/v3/carts/[CART_UUID]/items \
  -H 'Authorization: Bearer ValidAccessToken' \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Currency: USD' \
  -d '[
  {
    "type": "{{productType}}",
    "product_identifier": "{{productIdAdult}}",
    "quantity": 2,
    "language": "en"
  },
  {
    "type": "{{productType}}",
    "product_identifier": "{{productIdChild}}",
    "quantity": 1,
    "language": "en"
  }
]'
curl -X POST \
  https://api.musement.com/api/v3/carts/[CART_UUID]/items \
  -H 'Authorization: Bearer ValidAccessToken' \
  -H 'Content-Type: application/json' \
  -H 'X-Musement-Currency: USD' \
  -d '[ 
  {
    "type": "{{productType}}",
    "product_identifier": "{{productIdAdult}}",
    "quantity": 2,
    "language": "en",
    "pickup": "{{pickup_uuid}}"
  },
  {
    "type": "{{productType}}",
    "product_identifier": "{{productIdChild}}",
    "quantity": 1,
    "language": "en",
    "pickup": "{{pickup_uuid}}"
  }
]'

When adding multiple tickets to cart by posting an array of objects (example C & D), the response contains information about the first ticket only.

However, if you call:

curl -X GET \
  https://api.musement.com/api/v3/carts/[CART_UUID]

You will see in the response that both items have been added to the cart.

You can use this response to verify the status of each item is PREBOOK_OK before proceeding with order.