Concession availability

Selling limits

Selling limits restrict the quantity of an item available for sale at a cinema. Once the specified quantity of an item has been sold, the item is unavailable to order.

Note: This feature is separate from the standard Vista stock-management system.

Selling limits are set up in POS. They can be set up either as a daily quantity (only applies for the day) or as an indefinite quantity (applied forever).

Retrieving limits

An item's selling limit, along with its current availability, are returned via the GetConcessions endpoint.

POST: /RESTData.svc/concession-items?cinemaId={{cinemaId}}

Response:

{
    "ResponseCode": 0,
    "ConcessionItems": [
        {
            "Id": "72",
            "Description": "K Bar",
            "PriceInCents": 199,
            "SellingLimits": {
                "DailyLimits": [],
                "IndefiniteLimit": {
                    "QuantityAvailable": 158
                }
            }
        },
        {
            "Id": "72",
            "Description": "K Bar",
            "PriceInCents": 199,
            "SellingLimits": {
                "DailyLimits": [
                    {
                        "Date": "2019-05-23",
                        "QuantityAvailable": 16
                    }
                ],
                "IndefiniteLimit": null
            }
        }
    ]        
}

Error handling

When making an AddConcessions call, any items that exceed available quantity will result in an InvalidRequestData response code. Inspect the FailedConcession property for details on which items failed due to selling limit restrictions.

POST: /RESTTicketing.svc/order/concessions?userSessionId=

Response:

{
    "ExtendedResultCode": 4,
    "Order": null,
    "FailedConcessions": [
        {
            "ItemId": "72",
            "ErrorDescription": "Quantity available: 0. Selling limit applies on 2019-05-23.",
            "ErrorCode": 164
        }
    ],
    "Result": 4,
    "ErrorDescription": "Cannot order one or more concessions at Sales Server because it exceeded the sales limit."
}

Selling time restrictions

Selling time restrictions are time brackets that determine when a consession item is available for sale. Selling time restrictions are set up in Back Office. If selling time restrictions have been configured for an item, the response will include an entry for each day of the week. Each entry can have one of the following availabilty types:

• Available - the concession is available for sale for the entirety of the day. AvailableHours will be an empty array.
• Unavailable - the concession is unavailable for sale for the entirety of the day. AvailableHours will be an empty array.
• Restricted - the concession is restricted for sale to certain times of the day. AvailableHours will contain a collection of AvailableFrom and AvailableUntil pairs. The times are inclusive and are returned in the format HH:MM:SS.

Retrieving selling time restrictions

The time restrictions are returned via the GetConcessions endpoint.

POST: /RESTData.svc/concession-items?cinemaId={{cinemaId}}

Response:

{
    "ResponseCode": 0,
    "ConcessionItems": [
        {
			"Id": "72",
			"Description": "K Bar",
			"PriceInCents": 199,
			"SellingTimeRestrictions": [
				{
					"DayOfWeek": "Sunday",
					"Availability": "Available",
					"AvailableHours": []
				},
				{
					"DayOfWeek": "Monday",
					"Availability": "Unavailable",
					"AvailableHours": []
				},
				{
					"DayOfWeek": "Tuesday",
					"Availability": "Restricted",
					"AvailableHours": [
						{
							"AvailableFrom": "12:00:00",
							"AvailableUntil": "18:00:00"
						}
					]
				},
				{
					"DayOfWeek": "Wednesday",
					"Availability": "Restricted",
					"AvailableHours": [
						{
							"AvailableFrom": "07:30:00",
							"AvailableUntil": "10:00:00"
						},
						{
							"AvailableFrom": "12:00:00",
							"AvailableUntil": "15:00:00"
						},
						{
							"AvailableFrom": "17:00:00",
							"AvailableUntil": "20:00:00"
						}
					]
				},
				{
					"DayOfWeek": "Thursday",
					"Availability": "Available",
					"AvailableHours": []
				},
				{
					"DayOfWeek": "Friday",
					"Availability": "Available",
					"AvailableHours": []
				},
				{
					"DayOfWeek": "Saturday",
					"Availability": "Unavailable",
					"AvailableHours": []
				}
			]
		}
    ]        
}

Error handling

When making an AddConcessions call, any items being ordered outside their allocated time bracket will result in an InvalidRequestData response code. Inspect the FailedConcession property for details on which items failed due to selling time restrictions.

POST: /RESTTicketing.svc/order/concessions?userSessionId=

Response:

{
    "ExtendedResultCode": 4,
    "Order": null,
    "FailedConcessions": [
        {
            "ItemId": "72",
            "ErrorDescription": "Quantity available: 0.",
            "ErrorCode": 207
        }
    ],
    "Result": 4,
    "ErrorDescription": "Cannot order one or more concessions at Sales Server because it is outside of the available selling time restrictions"
}