Ordering tickets

Each showtime has a collection of available ticket types that can be purchased. Use the GetTicketPricesForShowtime endpoint to load the available ticket types and prices for a showtime.

{
  "ticketPrices": [
    {
      "ticketTypeId": "0000000003-0022",
      "price": {
        "valueIncludingTax": 19.5,
        "valueExcludingTax": 16.24,
        "tax": 3.26
      },
      "isDefault": true,
      "bookingFee": null,
      "restrictions": [],
      "rewardId": null,
      "voucherTypeCodes": [],
      "thirdPartyMemberSchemeId": null,
      "isShownAsPreviewWhenRestricted": false,
      "displayPriority": 1,
      "subscriptionId": null,
      "discountId": null,
      "discount": null
    },
    {
      "ticketTypeId": "0000000003-0022",
      "price": {
        "valueIncludingTax": 9.75,
        "valueExcludingTax": 8.12,
        "tax": 1.63
      },
      "isDefault": false,
      "bookingFee": null,
      "restrictions": ["Discount"],
      "rewardId": null,
      "voucherTypeCodes": [],
      "thirdPartyMemberSchemeId": null,
      "isShownAsPreviewWhenRestricted": false,
      "displayPriority": 1,
      "subscriptionId": null,
      "discountId": "0000000003-0000000004",
      "discount": {
        "calculation": {
          "percentageOff": 50.0,
          "type": "PercentageOff"
        },
        "amountSaved": {
          "valueIncludingTax": 9.75,
          "valueExcludingTax": 8.12,
          "tax": 1.63
        }
      }
    }
  ]
}

Ticket types and prices

Each price returned in ticketPrices represents a potential price for a ticket. The price includes the actual price of the ticket as well as details as to what special conditions (restrictions) are required for purchase.

The details of the ticket type itself (including the name, description, and areaCategoryId) are returned in the relatedData section. This data should be combined with the pricing data to present the ticket 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 restrictions are:

• Member - patron must be an authenticated loyalty member.
• MemberReward - patron must be an authenticated loyalty member and have an associated reward against their membership.
• MemberSubscriptionCard - patron must be an authenticated loyalty member and have access to an active subscription.
• ThirdPartyMemberCard - patron must enter 3rd-party membership card details.
• Voucher - patron must enter a voucher barcode.
• Discount - 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 ticket for a specific price. If the client has not been built to handle a certain restriction, that restriction's price should be hidden from the interface until it can be implemented.

As well as hiding unsupported ticket prices, the client may disable/enable certain prices based on the currently-signed-in Loyalty member, and/or any vouchers and cards the patron has applied to the order. The isShownAsPreviewWhenRestricted property can be used to determine if a price is intended to be visible to a patron before they qualify or only appear afterwards.

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

Expected error responses

When submitting ticketing requests the errorCode property of the 400 response should be inspected for expected validation scenarios. The following example describes that happens when the number of sets requested are not available for the showtime.

{
  "errorCode": 10000,
  "status": 400,
  "title": "Seats unavailable",
  "detail": "There are not enough seats available for requested tickets."
}

Member tickets

• When a price has a Member restriction it means the ticket is only available to loyalty members.
• The API will only accept orders for member tickets when the member authentication token/cookie is provided.

Member reward tickets

• When a price has a MemberReward restriction it means the ticket is only available to loyalty members.
• The rewardId property of the price must be checked against the available rewards returned from the member rewards 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 tickets available at this price.

Member subscription tickets

• When a price has a MemberSubscriptionCard restriction it means the ticket is only available to loyalty members with access to an active subscription card.
• A member may have access to multiple subscription cards, as member friends may have shared their subscription with the member. Use the GetMemberTicketRedemptionCards endpoint to get the MemberSubscriptionCard entities available to the authenticated member.
• The subscriptionId property of the price indicates the subscription required to purchase this ticket.
• These tickets should be hidden/disabled until the patron has added their subscription card to the order via the AddTicketRedemptionCard endpoint.

Third-party member tickets

• When a price has a ThirdPartyMemberCard restriction it means the ticket is only available if the patron provides their card details for the specified 3rd-party provider.
• The thirdPartyMemberSchemeId property of the ticket type indicates the 3rd-party schema the ticket is for.
• Typically these tickets are hidden/disabled until the patron has added their 3rd party card to the order via the AddTicketRedemptionCard endpoint.

Voucher tickets

• When a price has a Voucher restriction it means the ticket is only available if the patron provides a voucher code.
• The voucherTypeCodes property of the price indicates which vouchers this ticket is available for.
• Vouchers are added using the AddVoucher endpoint.

Discounted tickets

• When a price has a Discount restriction it means the ticket is only available via a discount.
• The discountId property indicates the discount required to purchase this ticket 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 ticket price restrictions

Discount restrictions

• MemberReward (patron must be an authenticated loyalty member and have an associated reward against their membership).

Package tickets

Package tickets combine one or more individual tickets and food and beverage items into a single ticket which typically offers a saving.

Use cases include:

• A 'family pass' - two adult tickets and two child tickets for a discounted price.
• A 'two for one' package - two tickets for the price of one standard ticket.
• A 'food & drink' package - a ticket, popcorn, and drink combo.

{
  "type": "Package",
  "tickets": [
    {
      "ticketTypeId": "0000000003-0022",
      "quantity": 2
    },
    {
      "ticketTypeId": "0000000003-0024",
      "quantity": 2
    }
  ],
  "items": [
    {
      "itemId": "0000000003-12",
      "quantity": 1
    }
  ],
  "id": "0000000003-0059",
  "description": {
    "text": "Family Pass"
  }
}

The relatedData property of the ticket price response should include all the details of items and tickets within a package needed to render the full details.

The package ticket is purchased in the same way as a normal ticket (using the SetShowtime endpoint) although with a potentially larger number of seat selections (one seat for each ticket included in the package).

{
  "tickets": [
    {
      "ticketTypeId": "0000000003-0059"
    }
  ],
  "seats": ["1_7_11", "1_7_13", "1_7_14", "1_7_15"]
}