Skip to main content

Set up a box office

Ticketlayer has two ways to sell without writing a website, and a way to scan what was sold.

The hosted box office​

Every sales channel can have a hosted storefront: a complete ticket shop (events, dates, tickets, cart, checkout, account, confirmation) served by Ticketlayer on a hostname you point at it. It is the same code that renders the embedded checkout on your own site.

  1. In Backstage create a sales channel and list the events it sells.
  2. Give the channel a storefront domain. On staging channels are served at <slug>.hbo.staging.t9r.dev; a custom domain is a CNAME to the same place, registered on the channel so the storefront can resolve which channel a request is for (it resolves by Host, so there is no key in the page).
  3. Assign a theme to the channel (logo, colours, fonts). The storefront and every Element on your own site read the same theme.

There is nothing to deploy: the storefront is live when the channel is.

Selling at the counter​

Staff sales go through the Backstage API's carts operations rather than the customer-facing sales surface, so a staff member can sell on a customer's behalf, take cash, and print. With a staff token or an organisation API key:

  • POST /v1/sales-channels/{channelId}/carts creates a staff cart on the box office channel, POST .../carts/{cartId}/items adds tickets, POST .../carts/{cartId}/checkout completes it.
  • POST /v1/orders/{orderId}/payments initiates the payment and GET /v1/orders/{orderId}/payment-status reports it.
  • GET /v1/orders/{orderId}/passes/{passId}/ticket.pdf and POST /v1/orders/{orderId}/passes/{passId}/print produce the tickets; ticket templates (/v1/ticket-templates) control the layout.

These are in the Backstage API reference under Sales channels (Carts) and Orders. A dedicated box-office app for staff is part of the platform and its guide will appear under Applications when it is documented.

Scanning at the door​

Entry is a device paired to the organisation (a phone or a handheld scanner running the scanning app):

  1. Pair the device: POST /v1/devices/pairing starts a pairing, a staff member claims and confirms it (POST /v1/devices/pairing/claim, POST /v1/devices/pairing/{pairingId}/confirm), and the device receives its credential.
  2. Configure scanning: a scan config (/v1/scan-configs) says which events and occurrences a device admits and is assigned to devices.
  3. Scan: the device fetches its manifest (GET /v1/scan/manifest) so it can work offline, and submits scan operations (POST /v1/scan/operations) which redeem passes. Every redemption emits a ticket.redeemed webhook and can be reversed (POST /v1/redemptions/{redemptionId}/reverse).

The full device model (pairing, credentials, commands, events, locations) is under Devices in the Backstage API reference.