Before a cart can become an order, it must contain information about the customer (also called the lead booker). The info may be used for invoicing, notifications and even personalizing issued tickets.
The requested info can vary based on the cart items. To see the requested customer info for a cart, make the following request:
curl -X GET '{baseUrl}/carts/{cartUuid}/customer/schema' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'The response returns a JSON schema which describes the requested info for the cart and how it must be submitted.
All carts will request the following base customer information:
| Field | Type | Format | Required | Description |
|---|---|---|---|---|
firstname | string | - | Yes | Customer's first name |
lastname | string | - | Yes | Customer's last name |
email | string | Yes | Customer's email address | |
musement_newsletter | string | enum | Yes | Subscribe to Musement newsletter (YES or NO) |
allow_profiling | string | enum | Yes | Allow Musement to profile user data (YES or NO) |
thirdparty_newsletter | string | enum | Yes | Receive promotional materials from third parties (YES or NO) |
events_related_newsletter | string | enum | Yes | Receive third-party newsletters related to cart items (YES or NO) |
city | string | - | No | Customer's city |
address | string | - | No | Customer's address |
zipcode | string | - | No | Customer's postal code |
tax_id | string | - | No | Customer's tax identification number |
{
"type": "object",
"title": "cart_customer_guest",
"properties": {
"firstname": {
"type": "string",
"title": "firstname",
"propertyOrder": 1
},
"lastname": {
"type": "string",
"title": "lastname",
"propertyOrder": 2
},
"email": {
"type": "string",
"title": "email",
"format": "email",
"propertyOrder": 3
},
"musement_newsletter": {
"enum": ["NO", "YES"],
"enum_titles": ["NO", "YES"],
"type": "string",
"title": "musement_newsletter",
"propertyOrder": 4
},
"allow_profiling": {
"enum": ["YES", "NO"],
"enum_titles": ["YES", "NO"],
"type": "string",
"title": "allow_profiling",
"propertyOrder": 5
},
"thirdparty_newsletter": {
"enum": ["YES", "NO"],
"enum_titles": ["YES", "NO"],
"type": "string",
"title": "thirdparty_newsletter",
"propertyOrder": 6
},
"events_related_newsletter": {
"enum": ["YES", "NO"],
"enum_titles": ["YES", "NO"],
"type": "string",
"title": "events_related_newsletter",
"propertyOrder": 7
},
"city": {
"type": "string",
"title": "city",
"propertyOrder": 8
},
"address": {
"type": "string",
"title": "address",
"propertyOrder": 9
},
"zipcode": {
"type": "string",
"title": "zipcode",
"propertyOrder": 10
},
"tax_id": {
"type": "string",
"title": "tax_id",
"propertyOrder": 11
}
},
"required": [
"firstname",
"lastname",
"email",
"musement_newsletter",
"allow_profiling",
"thirdparty_newsletter",
"events_related_newsletter"
]
}The newsletter properties accept only YES or NO values:
allow_profiling- Allow Musement to profile the user's data for future use.events_related_newsletter- The customer wants to receive third-party newsletters related to cart item contents.musement_newsletter- The customer wants to subscribe to the Musement newsletter.thirdparty_newsletter- The customer wants to receive promotional materials from third parties.
Each property includes a propertyOrder integer that indicates the recommended display order for form fields.
Some activities require additional information beyond the base customer fields. When a cart contains products with extra customer data requirements, the schema response will include an extra_customer_data property.
The extra customer data is grouped by activity UUID, allowing you to identify which questions belong to which product in the cart. See Extra customer data for detailed information.
Extra customer data fields can be of various types, each mapped to a specific JSON Schema representation:
| Field Type | JSON Schema Type | Additional Properties |
|---|---|---|
| text | string | attr.min, attr.max, attr.min_max_length_units |
| paragraph | string | attr.min, attr.max, attr.min_max_length_units |
| number | number | attr.min, attr.max, attr.units, attr.integer_only |
| radio | string | enum, enum_titles |
| checkboxes | array | items.enum, uniqueItems: true |
| dropdown | string | enum, enum_titles, attr.include_blank_option |
| date | string | format: date |
| time | string | format: time (e.g., HH:mm) |
Text fields may include length constraints:
{
"type": "string",
"title": "Special requests",
"attr": {
"min": 10,
"max": 255,
"min_max_length_units": "characters"
}
}The min_max_length_units can be either characters or words.
Number fields may include value constraints:
{
"type": "number",
"title": "Number of participants",
"attr": {
"min": 1,
"max": 10,
"units": "Person",
"integer_only": true
}
}Choice fields (radio, checkboxes, dropdown) include options:
{
"type": "string",
"title": "Preferred language",
"enum": ["English", "Spanish", "French"],
"enum_titles": ["English", "Spanish", "French"]
}For checkboxes (multiple selection):
{
"type": "array",
"title": "Dietary restrictions",
"uniqueItems": true,
"items": {
"enum": ["Vegetarian", "Vegan", "Gluten-free"]
}
}Dropdown fields may include additional options:
{
"attr": {
"include_blank_option": true,
"include_other_option": true
}
}Since the requested details about customers and the accepted values can change, we recommend using the react-jsonschema-form tool to create user-friendly forms from the endpoint's response. The tool features a live playground where you can paste Musement API responses and see the resulting form in real time.
Once you have collected the required customer information, make the following request to update the cart:
curl -X PUT '{baseUrl}/carts/{cartUuid}/customer' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
--data-raw '{
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"musement_newsletter": "YES",
"allow_profiling": "NO",
"thirdparty_newsletter": "NO",
"events_related_newsletter": "NO"
}'curl -X PUT '{baseUrl}/carts/{cartUuid}/customer' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
--data-raw '{
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"musement_newsletter": "YES",
"allow_profiling": "NO",
"thirdparty_newsletter": "NO",
"events_related_newsletter": "NO",
"city": "Rome",
"address": "Via Roma 123",
"zipcode": "00100",
"tax_id": "RSSMRA80A01H501U"
}'When the cart requires extra customer data, include it in the same request:
curl -X PUT '{baseUrl}/carts/{cartUuid}/customer' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
--data-raw '{
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"musement_newsletter": "YES",
"allow_profiling": "NO",
"thirdparty_newsletter": "NO",
"events_related_newsletter": "NO",
"extra_customer_data": {
"1714c6a7-2046-11e7-9cc9-06a7e332783f": {
"phone_number": "1234567890"
}
}
}'A successful update returns the customer object:
{
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"musement_newsletter": "YES",
"thirdparty_newsletter": "NO",
"events_related_newsletter": "NO",
"extra_customer_data": {
"1714c6a7-2046-11e7-9cc9-06a7e332783f": {
"phone_number": "1234567890"
}
}
}When the cart UUID does not exist:
{
"code": 1400,
"message": "Cart with uuid {cartUuid} not found"
}When you don't have permission to access the cart. This occurs when the cart was created by an OAuth2 client with exclusive ownership (ROLE_SOLE_OWNER_OF_CART) and you're using a different client:
{
"code": 403,
"message": "You don't have permission to access this Cart."
}When attempting to update customer data on a cart that is connected to a paid order:
{
"code": 423,
"message": "Cart is locked by order"
}When submitted data doesn't match the schema requirements:
{
"code": 400,
"message": "Invalid submitted data",
"errors": {
"email": ["This value is not a valid email address."],
"firstname": ["This value should not be blank."]
}
}Field labels in the schema response are localized based on the request's locale information. Custom questions from integration partners are also returned in the user's preferred language when translations are available.