Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.boothzen.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you from a fresh BoothZen account to a successful GET /api/v1/bookings call in under five minutes. No tooling beyond curl is required.

​
Step 1 — Issue a test API key

API keys are managed in the BoothZen app. The portal never asks for credentials directly — every “manage keys” link in this documentation deep-links to the single source of truth in the admin UI.

Open API Keys

Issue a bz_test_* key with the read:bookings scope. The full secret is shown once on creation — copy it now.
Keys come in two flavours:
  • bz_live_* — production data, real money, real bookings.
  • bz_test_* — sandbox data, fully isolated. Recommended for the first call.
The mode is bound to the key itself: a bz_test_* key cannot read live data, and vice versa. There is no ?mode= flag to toggle.

​
Step 2 — Make your first call

Export your key and call the bookings list endpoint: 
export BZ_KEY="bz_test_..."

curl -sS https://app.boothzen.com/api/v1/bookings \
  -H "Authorization: Bearer ${BZ_KEY}"
Or, with the key inline: 
curl -sS https://app.boothzen.com/api/v1/bookings \
  -H "Authorization: Bearer bz_test_replace_me_with_your_real_key"
A successful response looks like this: 
{
  "data": [
    {
      "id": "bk_01HX9K8VAAYZWJ3M2P4Q5R6T7N",
      "status": "confirmed",
      "starts_at": "2026-06-14T13:00:00Z",
      "ends_at": "2026-06-14T17:00:00Z",
      "customer_id": "cu_01HX9K7H3D5G2N8Q4P6R7T9V1B",
      "total": { "amount": 45000, "currency": "GBP" }
    }
  ],
  "next_cursor": null
}
Three things worth noting in that response:
  1. Prefixed IDs. bk_ is a booking, cu_ is a customer. Every public resource has a stable two-or-three-letter prefix (bk_, ld_, qt_, inv_, cu_, srv_, un_).
  2. Money envelope. total is always { amount, currency } with amount in integer minor units (45000 = £450.00).
  3. Cursor pagination. next_cursor is null because this account is empty. When there’s more, pass it back as ?cursor=...&limit=25.

​
Step 3 — Read the API Reference

Every endpoint, request body, query parameter, and response shape is documented from the live OpenAPI 3.1 spec at https://app.boothzen.com/api/v1/openapi.json. The interactive playground in this portal lets you “Try it” against your test key without leaving the page.

API Reference

Browse all 15 paths with live request examples and response schemas.

​
Step 4 — Next steps

Authentication

API-key Bearer auth and OAuth 2.1 PKCE for third-party apps.

Webhooks

Subscribe to the 13 platform events and verify signatures.

Error Codes

Error envelope, idempotency, and the standard HTTP code surface.

Downloads

SDKs, WordPress + Joomla plugins, Zapier and Make.com integrations.