Ordering concessions

Concessions represent a wide range of purchasable items within Vista. They are often referred to as items. Concessions can be added to any order either by themselves or along with tickets (or even as part of a package ticket).

Standard concessions

Ordering a concession can be as simple as providing the ItemId of the item to purchase and the quantity required. The HeadOfficeItemCode can also be used instead of the cinema-based ItemId.

POST: /RESTTicketing.svc/order/concessions

Request (using ItemId):

{
    "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
    "CinemaId": "0001",
    "Concessions": [
        {
            "ItemId": "123",
            "Quantity": 1
        }
    ],
	"ReturnOrder": true
}

Request (using HeadOfficeItemCode ):

{
    "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
    "CinemaId": "0001",
    "Concessions": [
        {
            "HeadOfficeItemCode ": "AO002458",
            "Quantity": 1
        }
    ],
	"ReturnOrder": true
}

Response:

{
    "Order": {
        "Concessions": [
            {
                "Id": "1",
                "DealPriceCents": 500,
                "ItemId": "123",
                "Quantity": 1
        }],
        "TotalValueCents": 500,
    },
    "Result": 0
}

Parent sales / alternate items

Parent sales concessions are configured where a single concession item has a single mandatory choice of several alternate items the purchaser actually wishes to receive. The most common example of this is the 'large soft drink' concession item which as a parent sales concession requires the choice of flavour (for example, Lemonade, Cola, Orange).

These type of concessions can be used to provide simpler user interfaces by automatically grouping alternate versions of concessions together rather than having individual concession items.

When configured, the alternate items will be returned under the concession item in question:

GET: /RESTData.svc/concession-items?cinemaId=0001

{
    "ConcessionItems": [
        {
            "AlternateItems": [
                {
                    "Description": "Cola",
                    "Id": "27",
                    "PriceInCents": 500
                },
                {
                    "Description": "Lemonade",
                    "Id": "28",
                    "PriceInCents": 500
                },
                {
                    "Description": "Orange Drink",
                    "Id": "29",
                    "PriceInCents": 600
                },
            ],
            "Description": "Soft Drink",
            "Id": "37",
            "PriceInCents": 500,
        }]
}

To purchase the item correctly, the ItemId of the specific alternate is ordered with the ItemId of the parent sales concession recorded as additional data.

POST: /RESTTicketing.svc/order/concessions

{
    "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
    "CinemaId": "0001",
    "Concessions": [
        {
            "ItemId": "29",
            "Quantity": 1,
			"ParentSaleItem": {
				"ItemId": "37"
			}
        }
    ],
	"ReturnOrder": true
}

Modifiers

Concessions may have modifiers applied to them, which lets the purchaser customise the concession they are purchasing. Modifiers may be required, and may have associated quantity limits and additional costs.

The following example shows a burger concession with optional extras that can be added and a mandatory decision around the bun.

GET: /RESTData.svc/concession-items?cinemaId=0001

{
    "ConcessionItems": [
        {
            "Description": "Burger",
            "Id": "92",
            "IsAvailableForInSeatDelivery": true,
            "IsAvailableForPickupAtCounter": true,
            "ModifierGroups": [
                {
                    "Description": "Burger Additions Modifer Group",
                    "FreeQuantity": 0,
                    "Id": "94",
                    "MaximumQuantity": 0,
                    "MinimumQuantity": 0,
                    "Modifiers": [
                        {
                            "Description": "Add Avocado",
                            "Id": "93",
                            "PriceInCents": 200
                        },
                        {
                            "Description": "Add Bacon",
                            "Id": "96",
                            "PriceInCents": 220
                        },
                        {
                            "Description": "Add Egg",
                            "Id": "97",
                            "PriceInCents": 80
                        }
                    ]
                },
                {
                    "Description": "Burger Bun Modifer Group",
                    "FreeQuantity": 0,
                    "Id": "101",
                    "MaximumQuantity": 1,
                    "MinimumQuantity": 1,
                    "Modifiers": [
                        {
                            "Description": "Standard Bun",
                            "Id": "99",
                            "PriceInCents": 0
                        },
                        {
                            "Description": "Brioche Bun",
                            "Id": "98",
                            "PriceInCents": 100
                        },
                        {
                            "Description": "Gluten Free Bun",
                            "Id": "100",
                            "PriceInCents": 200
                        }
                    ]
                },
            ],
            "PriceInCents": 800
        }]
}

Desired modifiers are included in the purchase request along with the burger concession item. The following will add a burger with a standard bun, added avocado and double added bacon.

POST: /RESTTicketing.svc/order/concessions

{
    "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
    "CinemaId": "0001",
    "Concessions": [
        {
            "ItemId": "92",
            "Modifiers": [
                {
                    "ModifierItemId": "93",
                },
                {
                    "ModifierItemId": "96",
                },
                {
                    "ModifierItemId": "96",
                },
                {
                    "ModifierItemId": "99",
                }
            ],
            "Quantity": 1
        }
    ],
    "ReturnOrder": true
}

Concession packages can contain concession items with modifiers. These modifiers are requested identically to the modifiers on standard concession items, but under the PackageChildItems property of the AddConcessions request.

POST: /RESTTicketing.svc/order/concessions

{
    "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
    "CinemaId": "0001",
    "Concessions": [
        {
            "ItemId": "90",
			"PackageChildItems": [
				{
					"ItemId": "92",
					"Modifiers": [
						{
							"ModifierItemId": "93",
						},
						{
							"ModifierItemId": "96",
						},
						{
							"ModifierItemId": "96",
						},
						{
							"ModifierItemId": "99",
						}
					]
				},
				{
					"ItemId": "91"
				}
			],
            "Quantity": 1
        }
    ],
    "ReturnOrder": true
}

Modifier group properties

The following properties are applied to each individual item that has the modifier group, i.e. if multiple items in a concession package have the same modifier group these properties apply to each of those items individually.

• MinimumQuantity: At least this many modifiers from the modifier group need to be added when ordering the item.
• MaximumQuantity: No more than this many modifiers from the modifier group can be added when ordering the item.
• FreeQuantity: This many of the cheapest modifiers from the modifier group will be free to the customer. This may or may not include modifiers that already have zero cost depending on your Connect configuration.

Smart modifiers

Smart modifiers allow the recipe of a concession to be modified, either adding extra, removing, or putting to the side components of the concession's recipe.

The following example shows a salad concession with the recipe components available for modification. The price refers to the cost of ordering extra of the component.

GET: /RESTData.svc/concession-items?cinemaId=0001

{
    "ConcessionItems": [
        {
            "Description": "Caesar salad",
            "Id": "24",
            "IsAvailableForInSeatDelivery": true,
            "IsAvailableForPickupAtCounter": true,
            "SmartModifiers": [
				{
                    "Id": "25",
                    "Description": "Croutons",
                    "DescriptionAlt": "",
                    "DescriptionTranslations": [],
                    "PriceInCents": 100,
                    "TaxInCents": 14
                },
                {
                    "Id": "26",
                    "Description": "Egg",
                    "DescriptionAlt": "",
                    "DescriptionTranslations": [],
                    "PriceInCents": 250,
                    "TaxInCents": 34
                },
                {
                    "Id": "27",
                    "Description": "Anchovies",
                    "DescriptionAlt": "",
                    "DescriptionTranslations": [],
                    "PriceInCents": 300,
                    "TaxInCents": 41
                },
                {
                    "Id": "28",
                    "Description": "Parmesan",
                    "DescriptionAlt": "",
                    "DescriptionTranslations": [],
                    "PriceInCents": 200,
                    "TaxInCents": 28
                }
			],
            "PriceInCents": 1200
        }]
}

Smart modifiers are requested alongside the concession being modified. There are two groups available for requesting smart modifiers, base recipe modifications and extra modifications. Note that all smart modifiers provided in the GetConcessionItems request can be passed in to either group:

• Base recipe modifications - These modifications are passed in to the SmartModifiers property and change the recipe components that come with the concession by default. Note that only recipe components that you wish to modify need to be provided in this group, components that aren't specified here will be included in the concession as would be expected with a recipe based concession without smart modifiers. These modifications will not change the order value and the items can be modified in one of two ways:
  • Remove - Removes the recipe component from the concession. Requested as Modification: 0.
  • Side - Serve the recipe component separately from the concession. Requested as Modification: 1.
• Extra modifications - These modifications are passed in to the SmartModifierExtras property and add more of the specified component to the concession. These modifications will increase the order value by the value indicated in the PriceInCents property associated to the smart modifier. The Side flag allows these extras to be served separately from the concession.

Here the salad is being requested with the anchovies removed, the egg served on the side, extra parmesan, and some extra egg, also served on the side.

POST: /RESTTicketing.svc/order/concessions

Request:

{
    "UserSessionId": "bf932218645a4f4fbcd61cf936a2bc62",
    "CinemaId": "0001",
    "Concessions": [
        {
            "ItemId": "24",
            "SmartModifiers": [
				{
					"SmartModifierItemId": "27",
					"Modification": 0
				},
				{
					"SmartModifierItemId": "26",
					"Modification": 1
				}
			],
			"SmartModifierExtras": [
				{
					"SmartModifierItemId": "28"
				},
				{
					"SmartModifierItemId": "26",
					"Side": true
				}
			]
            "Quantity": 1
        }
    ],
    "ReturnOrder": true
}

Response:

{
    "ExtendedResultCode": 0,
    "Order": {
        "UserSessionId": "bf932218645a4f4fbcd61cf936a2bc62",
        "CinemaId": "0001",
        "TotalValueCents": 1650,
        "TaxValueCents": 228,
        "BookingFeeValueCents": 0,
        "BookingFeeTaxValueCents": 0,
        "Sessions": null,
        "Concessions": [
            {
                "Id": "1",
                "ItemId": "24",
                "Quantity": 1,
                "SmartModifiers": [
                    {
                        "SmartModifierItemId": "27",
                        "Modification": 0
                    },
                    {
                        "SmartModifierItemId": "26",
                        "Modification": 1
                    }
                ],
                "SmartModifierExtras": [
                    {
                        "SmartModifierItemId": "28",
                        "PriceInCents": 200,
                        "TaxInCents": 28,
                        "Side": true
                    },
                    {
                        "SmartModifierItemId": "26",
                        "PriceInCents": 250,
                        "TaxInCents": 35,
                        "Side": false
                    }
                ],
                "DealPriceCents": 1200,
                "FinalPriceCents": 1200,
                "TaxCents": 165,
                "SessionId": null
            }
        ],
        "LastUpdated": "/Date(1535407118596+1200)/",
        "LastUpdatedUtc": "2018-08-27T21:58:38.5967619Z",
        "ExpiryDate": "/Date(1535407418596+1200)/",
        "ExpiryDateUtc": "2018-08-27T22:03:38.5967619Z",
    },
    "Result": 0,
    "ErrorDescription": null
}

Note: There are a couple of rules that should be followed when requesting smart modifiers. Namely:

• A recipe component can only be specified in the SmartModifiers group once
• A recipe component can not be removed in SmartModifiers and have extra ordered in SmartModifierExtras

Requests that do not meet these rules will get one of the following error responses:

{
    "ExtendedResultCode": 4,
    "Order": null,
    "Result": 4,
    "ErrorDescription": "Smart modifier(s) 28 have been specified multiple times in the SmartModifiers list. Use the SmartModifierExtras list to order extras."
}

{
    "ExtendedResultCode": 4,
    "Order": null,
    "Result": 4,
    "ErrorDescription": "Smart modifier(s) 28 have both been removed and had extra ordered."
}

As with regular modifiers, concession packages may contain concession items with smart modifiers. These are requested identically to smart modifiers on concession items, but under the PackageChildItems property of the AddConcessions request.

Recipe items

The special concession types mentioned above (Parent Sales/Alternate Items, Modifiers, and Smart Modifiers) may be available on the recipe items of a concession rather than directly on the concession itself. These will behave identically to those on regular concessions but will be listed under the RecipeItems property on GetConcessionItems or GetConcessionItemsGroupedByTabs:

GET: /RESTData.svc/concession-items?cinemaId=0001

{
    "ConcessionItems": [
        {
            "Description": "Burger Combo",
            "Id": "91",
            "IsAvailableForInSeatDelivery": true,
            "IsAvailableForPickupAtCounter": true,
			"ModifierGroups": [
				{
					"Description": "Burger Combo Upsize Modifer Group",
					"FreeQuantity": 0,
					"Id": "94",
					"MaximumQuantity": 1,
					"MinimumQuantity": 0,
					"Modifiers": [
						{
							"Description": "Medium Combo",
							"Id": "90",
							"PriceInCents": 200
						},
						{
							"Description": "Large Combo",
							"Id": "89",
							"PriceInCents": 400
						}
					]
				}
				
			],
            "RecipeItems": [
				{
					"Id": 92,
					"Quantity": 1,
					"Description": "Burger",
					"ModifierGroups": [
						{
							"Description": "Burger Additions Modifer Group",
							"FreeQuantity": 0,
							"Id": "94",
							"MaximumQuantity": 0,
							"MinimumQuantity": 0,
							"Modifiers": [
								{
									"Description": "Add Avocado",
									"Id": "93",
									"PriceInCents": 200
								},
								{
									"Description": "Add Bacon",
									"Id": "96",
									"PriceInCents": 220
								},
								{
									"Description": "Add Egg",
									"Id": "97",
									"PriceInCents": 80
								}
							]
						},
						{
							"Description": "Burger Bun Modifer Group",
							"FreeQuantity": 0,
							"Id": "101",
							"MaximumQuantity": 1,
							"MinimumQuantity": 1,
							"Modifiers": [
								{
									"Description": "Standard Bun",
									"Id": "99",
									"PriceInCents": 0
								},
								{
									"Description": "Brioche Bun",
									"Id": "98",
									"PriceInCents": 100
								},
								{
									"Description": "Gluten Free Bun",
									"Id": "100",
									"PriceInCents": 200
								}
							]
						},
					]
				},
				{
					"Id": "37",
					"Quantity": 1
					"Description": "Soft Drink",
					"AlternateItems": [
						{
							"Description": "Cola",
							"Id": "27",
							"PriceInCents": 500
						},
						{
							"Description": "Lemonade",
							"Id": "28",
							"PriceInCents": 500
						},
						{
							"Description": "Orange Drink",
							"Id": "29",
							"PriceInCents": 600
						},
					]
				}
			],
            "PriceInCents": 1400
        }]
}

The properties available on recipe items (for example, modifiers, smart modifiers, alternate items, etc.) can be purchased/selected via the RecipeItems property on AddConcessions. The following request will purchase the Burger Combo above with a medium upsize, avocado and double bacon on the burger, and lemonade as the soft drink choice:

POST: /RESTTicketing.svc/order/concessions

{
    "UserSessionId": "a53ac319775849499dd04fd23a6c867b",
    "CinemaId": "0001",
    "Concessions": [
        {
            "ItemId": "91",
			"Modifiers": [
				{
					"ModifierItemId": "90"
				}
			],
			"RecipeItems": [
				{
					"RecipeItemId": "92",
					"Modifiers": [
						{
							"ModifierItemId": "93",
						},
						{
							"ModifierItemId": "96",
						},
						{
							"ModifierItemId": "96",
						},
						{
							"ModifierItemId": "99",
						}
					]
				},
				{
					"RecipeItemId": "28",
					"ParentSaleItem": {
						"ItemId": "37"
					}
				}
			],
            "Quantity": 1
        }
    ],
    "ReturnOrder": true
}

Variable price concessions

A concession may be set up as a variable price concession, which means customers can purchase the item at varying prices within a particular price range.

When getting concessions via the GetConcessionItems or GetConcessionItemsGroupedByTabs endpoints, variable price concessions will contain the following properties:

• IsVariablePriceItem set to true
• MinimumVariablePriceInCents, with some price value
• MaximumVariablePriceInCents with some price value

To set a price for a variable price concession, you can pass a value into the VariablePriceInCents property for a Concession object.

{
	"UserSessionId": "string",
	"CinemaId": "string",
	"Concessions": [
		{
			...
			"VariablePriceInCents": 100,
			...
		}
	],
}

Note: The price value must fall within the allowed price range - the following error will be thrown if the value falls outside the allowed price range:

{
    "ErrorDescription": "Invalid Concession or Promo Code : VariablePriceInCents must be between MinimumVariablePriceInCents(<value>) and MaximumVariablePriceInCents(<value>)",
    "Result": 4
}

If a VariablePriceInCents isn't specified for a variable price concession, the price for that concession will be set using the value in PriceInCents, similar to how prices are set for other concessions.