API

BooTickets exposes a public, read-and-write HTTP API under /public/*. It powers our own event pages and embed widget, and you can call it directly to build a custom integration.

Base URL

https://api.bootickets.com

All public endpoints are prefixed with /public. For example: https://api.bootickets.com/public/events/<event-id>.

Authentication & access

  • No API key is required for public endpoints — they serve publicly available event and checkout data.
  • Order endpoints are the exception. Reading an order needs the order's grant, a short secret proving the caller is the buyer (see Order access below).
  • Responses are JSON unless noted (calendar and invoice endpoints return files).
  • CORS is configured for browser use. If you're calling from a server, no CORS applies.
  • Don't expose anything secret in client code — these endpoints are for public-facing data and the standard checkout flow only.

Key endpoints

Get an event

GET /public/events/{idOrSlug}

Returns the event, its venue, current status, currency, pricing flags and organiser summary. Accepts either an event ID or its slug.

StatusMeaning
ON_SALETickets can be bought.
WAITLISTSold out, but buyers can join the waiting list.
SOLD_OUTSold out, with no waiting list.
UPCOMINGNot on sale yet.
PAUSEDOn sale, but the organiser can't take payments right now.
CLOSEDSales have ended, or the event is in the past.

List events in a series

GET /public/series/{seriesId}/events

Returns the series and its live events (chronological).

Apply a promo code (preview a discount)

POST /public/events/{eventId}/promo/apply
Content-Type: application/json

{ "code": "EARLY20", "items": { "<tierId>": 2 } }

Validates the code and returns the discount that would apply.

Create an order (start checkout)

POST /public/orders/payment/initiate
Content-Type: application/json

{
  "eventId": "<event-id>",
  "items": { "<tierId>": 2 },
  "buyer": { "name": "Jane Doe", "email": "jane@example.com" },
  "promoCode": "EARLY20",
  "termsAccepted": true,
  "ticketAnswers": [
    { "tierId": "<tierId>", "slotIndex": 0, "answers": { "<questionId>": "yes" } },
    { "tierId": "<tierId>", "slotIndex": 1, "answers": { "<questionId>": "no" } }
  ],
  "payDeposit": false,
  "mailingListOptIn": false,
  "returnUrl": "https://your-site.example/whats-on",
  "attribution": { "utmSource": "newsletter", "utmMedium": "email" }
}

Only eventId, items and buyer are always required. The rest depend on the event:

FieldWhen to send it
promoCodeThe buyer entered a promo code.
termsAcceptedThe event has booking terms. Must be true, or the order is refused.
ticketAnswersA tier asks questions. One entry per ticket, numbered from 0 within each tier, with answers keyed by question ID. Yes/No answers are "yes" or "no".
payDeposittrue to pay the deposit now and the balance later, where the event offers it.
mailingListOptIntrue if the buyer ticked the organiser's mailing-list box.
returnUrlYour page's URL, so the order confirmation page can link the buyer back to it.
attributionCampaign data (utmSource, utmMedium, utmCampaign, utmContent, gclid, gbraid, wbraid).

Returns an orderId, a grant for the order, the payment provider, and the provider-specific fields your client needs to complete payment (e.g. a Stripe client secret, or a SumUp checkout ID). Free orders come back already PAID.

Confirm a payment

POST /public/orders/payment/confirm
Content-Type: application/json

{ "orderId": "<order-id>", "paymentIntentId": "..." }   // Stripe
{ "orderId": "<order-id>", "checkoutId": "..." }         // SumUp

Marks the order paid (or failed), issues tickets, and returns a fresh grant.

Start a donation

POST /public/donations/payment/initiate
Content-Type: application/json

{
  "customerId": "<organiser-id>",
  "amountCents": 1000,
  "currency": "GBP",
  "buyer": { "name": "Jane Doe", "email": "jane@example.com" }
}

Get a paid order (ticket page data)

GET /public/orders/{orderId}
Authorization: Bearer <grant>

Only returns data for paid orders. Also available: GET /public/orders/{orderId}/calendar.ics?g=<grant> for an iCalendar file.

Organiser profile

GET /public/o/{organiserId}

Returns 404 unless the organiser has turned on their public organiser page.

Order access

An order ID on its own doesn't open an order. Order endpoints need a grant:

  • initiate and confirm return one, so the browser that placed the order already has it.
  • Send it as Authorization: Bearer <grant> on API calls, or as ?g=<grant> on file downloads (a plain link can't set a header).
  • Without a valid grant, a JSON call returns 401 with { "error": "unlock_required" }. The buyer proves who they are by confirming the email address they booked with:
POST /public/orders/{orderId}/unlock
Content-Type: application/json

{ "email": "jane@example.com" }

A correct address returns a new grant. A wrong address, an unknown order and an unpaid order all get the same 401, so the response never reveals which it was.

Error responses

Errors return a non-2xx status and a JSON body like:

{ "error": "Event is not on sale (status=COMING_SOON)", "message": "This event is not currently on sale." }

message is written for buyers and is safe to show. error is for your code: sometimes a short code (INSUFFICIENT_STOCK, TIER_NOT_ON_SALE, PROMO_LIMIT_REACHED), sometimes a plain description like the one above.

Common statuses:

StatusMeaning
400Bad request: a missing field, an invalid email, unanswered questions.
401No valid grant for this order (unlock_required).
404Not found.
409Conflict: sold out, not on sale, seats taken, a limit reached.
429Too many attempts. Wait and try again. Applies to starting checkout and to unlocking an order.
500Server error.

Most integrations don't need the API. To sell tickets from your own site, the Buy ticket button sends buyers to the BooTickets checkout for you. Use the API when you need custom behaviour the widget doesn't cover.