Ordering food and beverage items

Each client can be configured with a set of food and beverage items for sale which can vary by site. This is known as an item profile. Use the GetItemProfileForSite endpoint to load the item profile for a particular site.

Copy
Copied
{
    "itemProfile": {
        "siteId": "0000000003",
        "pages": [
            {
                "number": 1,
                "title": {
                    "text": "Snacks",
                    "translations": []
                },
                "buttons": [
                    {
                        "title": null,
                        "displayPriority": 0,
                        "itemId": "0000000003-1223456",
                        "prices": [
                            {
                                "price": {
                                    "valueIncludingTax": 2.67,
                                    "valueExcludingTax": 2.23,
                                    "tax": 0.44
                                },
                                "isDefault": true,
                                "restrictions": [],
                                "rewardId": null,
                                "discount": null,
                                "discountId": null
                            }
                        ]
                    },
                    {
                        "title": null,
                        "displayPriority": 1,
                        "itemId": "0000000003-700732",
                        "prices": [
                            {
                                "price": {
                                    "valueIncludingTax": 25.0,
                                    "valueExcludingTax": 21.74,
                                    "tax": 3.26
                                },
                                "isDefault": true,
                                "restrictions": [],
                                "rewardId": null,
                                "discount": null,
                                "discountId": null
                            }
                        ]
                    }
                ],
                "displayPriority": 1
            }
        ]
    },
    "relatedData": {
        "items": [
            {
                "type": "Normal",
                "modifierGroups": [],
                "id": "0000000003-1223456",
                "name": {
                    "text": "Popcorn"
                },
                "restrictions": [],
                "itemClassId": "0004",
                "isPreparationRequired": false,
                "allowedDeliveryMethods": [
                    "CounterPickup"
                ]
            },
            {
                "type": "Normal",
                "modifierGroups": [],
                "id": "0000000003-700732",
                "name": {
                    "text": "Milkshake"
                }
                "restrictions": [],
                "itemClassId": "0004",
                "isPreparationRequired": false,
                "allowedDeliveryMethods": [
                    "CounterPickup"
                ],
                "availableHoursId": null
            },
        ]
    }
}

Buttons, prices, and items

Buttons define the intended displayPriority of the items as well as the potential for a custom title which can be used to override the default name of the item.

Each button has one or more prices. The price includes the actual price of the item as well as details as to what special conditions (restrictions) are required for purchase.

The details of the item itself are returned in the relatedData section. This data should be combined with the pricing data to present the item selection interface.

Restrictions

The restrictions property of the price indicates a special requirement the patron must fulfil in order to be eligible for the price. These include:

  • MemberReward - patron must be a loyalty member and have an associated reward against their membership
  • InheritedMemberReward - patron must be a loyalty member and have an associated reward against their membership
  • Discount - discount identifier must be provided for the discounted price
  • InheritedDiscount - discount identifier must be provided for the discounted price

Clients must have custom handling for each restriction for users to be able to purchase the item for a specific price. If the client has not been built to handle a certain restriction it should hide the price from the interface until it can be implemented.

Clients may implement their own logic based on known item pricing configuration to automatically favour one item price over another or potentially even auto-select the item prices if appropriate.

Setting items for an order

The SetItems endpoint sets all items for an order in one request. Subsequent requests will replace/remove any items added via the previous call. Items cannot be added and removed individually.

Ordering multiple of a single item requires sending multiple entries. This allows each instance of the item to be modified separately as required.

The SetItems makes use of polymorphism, so the type enumeration is required for each item being requested.

Copy
Copied
{
  "items": [
    {
      "itemId": "string",
      "type": "Normal",
      "modifierGroups": []
    },
    {
      "itemId": "string",
      "type": "Package",
      "items": []
    },
    {
      "itemId": "string",
      "type": "Recipe",
      "components": [],
      "modifierGroups": []
    }
  ]
}

Member reward items

  • A price with a MemberReward restriction means the price is only available to loyalty members.
  • The rewardId property of the price must then be checked against the available rewards returned from the GetMemberRewards endpoint.
  • The availableQuantity of the member's reward as well as the limitPerOrder on the reward itself must be taken into account when presenting the amount of items available at this price.
  • The relevant rewardId must be specified in the SetItems request to apply the reward-restricted price.
Copy
Copied
{
  "items": [
    {
      "itemId": "0000000003-1223456",
      "type": "Normal",
      "rewardId": 56
    }
  ]
}

Discounted items

  • A price with a Discount restriction means the item is only available via a discount.
  • The discountId property indicates the discount required to purchase this price.
  • The discount property describes the actual amount to be saved by purchasing with the discount.
  • Discount details are available in the relatedData section of the response.
  • Discounts have their own set of restrictions which work similar to the item price restrictions.

Discount restrictions

  • MemberReward - patron must be a loyalty member and have an associated reward against their membership
  • Availability - discount is only available at certain times
NOTE

The Voucher restriction does not currently apply to item price discounts.

Discounts restricted to member reward

Discounts with a MemberReward restriction require the discountId and the rewardId to be supplied in the SetItems request to apply the discount.

Copy
Copied
{
  "items": [
    {
      "itemId": "0000000003-1223456",
      "type": "Normal",
      "discountId": "DISC123",
      "rewardId": 56
    }
  ]
}

Discounts restricted by availability

A discount with an Availability restriction indicates the item is only available for sale during certain times of the day and certain days of the week. The availableHoursId property of the item itself will link to one of the availableHours returned in the relatedData.

For a client to support this kind of discount, the client must process the availability data, as well as know the current time in the timezone of the order's site.

If the items are being purchased along with a ticket then the availability values apply to the start time of the showtime at the site. If items are being purchased in an order that doesn't contain tickets, then the available values apply to the current time at the site.

Item delivery and preparation

When ordering food and beverage items, the client may also indicate where and when the items should be delivered. This is done by providing one or more itemDeliveries and linking requested items to these. These item deliveries can be the following types:

  • OrderItemInSeatDeliveryCreate - item will be delivered to a seat during a showtime.
  • OrderItemServiceAreaPickupCreate - item will be delivered to to the configured service area associated with the item.

Clients must inspect the allowedDeliveryMethods property of items to determine which type of delivery is supported. Custom delivery details can only be supplied for items that support either InSeatDelivery or ServiceAreaPickup.

In-seat delivery

When creating an OrderItemInSeatDeliveryCreate delivery, the showtimeId and seats properties must be provided. Typically these are made available to the client by beginning the in-seat delivery process from the view of the completed ticketing order.

Service areas delivery

When creating an OrderItemServiceAreaPickupCreate delivery, no extra information is required as the service areas are back-end configuration and not able to be defined by the client.

Delivery comments

Both delivery types allow for the comments property to be provided which will be made visible to those preparing the item. This can be used to offer free-text additional requests above and beyond system-defined modifiers.

Delivery schedules

Both delivery types also include a schedule to define when the item is to be prepared and delivered. There are three types of available schedules:

  • OrderItemDeliveryScheduleImmediate - items will be delivered immediately
  • OrderItemDeliveryScheduleOnRequest - items will only be delivered upon request
  • OrderItemDeliveryScheduleShowtimeDeliveryWindow - items will be delivered during a specified window

Showtime delivery windows

When specifying an OrderItemDeliveryScheduleShowtimeDeliveryWindow schedule, the showtimeDeliveryWindowId must be provided. The window options are returned as the itemShowtimeDeliveryWindows property of the item profile.

Copy
Copied
{
  "itemProfile": {
    "siteId": "0000000003",
    "itemShowtimeDeliveryWindows": [
      {
        "minutes": 10,
        "type": "MinutesFromStart",
        "id": "0000000003-FirstService",
        "name": {
          "text": "First Service - 10 mins"
        }
      },
      {
        "minutes": 45,
        "type": "MinutesFromStart",
        "id": "0000000003-SecondService",
        "name": {
          "text": "Second Service - 45 mins"
        }
      }
    ]
  }
}

Manually triggering preparation and delivery

When the OrderItemDeliveryScheduleOnRequest delivery is specified, food & beverage items will not be prepared (and thus not delivered to the patron) until further action is taken.

The PrepareAllItemDeliveries endpoint can be used to request the preparation of every item delivery in the order.

Alternatively, the PrepareItemDelivery endpoint can be used to request the preparation of a single item delivery.