Build on Bookatu.
REST, webhooks & MCP

Guides

• Your sandboxes: Make, reset and delete your sandbox businesses and get their test keys (sign in first).
• Testing with a sandbox: Build and test against a sandbox business with bk_test_ keys: realistic sample data, a test outbox instead of real messages, a simulated checkout instead of real payments, and a simulator for the events you would otherwise wait for.
• Test your AI agent: Point an AI agent at a sandbox through the Bookatu MCP server, with a test key or OAuth, and check what it did: the bookings it made, the messages it would have sent and the payments it would have taken, with nothing reaching a real client.
• Rate limits: How many calls the Bookatu API takes per key, per business and per address; the RateLimit headers on every answer; the standard and raised tiers; and what to do on a 429.
• Versioning: How the Bookatu API changes without breaking you: versions named by date, the Bookatu-Version header, the version your key is pinned to, the policy, and the deprecation headers.
• Changelog: Every change to the Bookatu v1 REST API, the MCP server and webhooks a developer needs to know about, newest first, each dated by the change that made it.
• Going live: Move an integration from a sandbox and its bk_test_ key to a live business and its bk_live_ key, with the checklist of what to change and what to check first.

Authentication

The public endpoints (business, services, staff, availability, book) require no authentication and can be called from any origin. The key-protected endpoints (customers, appointments and their checkout, booking requests, class sessions, reports and the audit log) and the MCP server need an API key issued from your admin dashboard at /{slug}/admin/api.

The customer booking-management endpoints take no API key. A booking carries a manage key, the client's credential for changing it: it is the k query parameter on the manage link in the client's confirmation email, POST /book returns it as manageKey, and it may be sent as the X-Manage-Key header instead of k. With the appointment id alone, GET /booking/{id} answers a read-only status (access "view", no selfService), and the availability, reschedule and cancel endpoints answer 403 with code MANAGE_KEY_REQUIRED; with the key (access "manage") everything works as described. Bookings made before manage keys existed have none and are managed on their id alone, as the links already emailed for them expect. Ids are apt_ followed by a 16-character nanoid, and are scoped to the business in the URL, so a valid id or key from one business can never be read or acted on through another's. Treat the manage key, and the id, like a password: show them to nobody but the person who booked, and never store them where others can read them. Every one of these endpoints is rate limited per IP, returns only what the person who booked already knows, and answers a 404 for anything that is not this business's booking.

Pass the key as a Bearer token in the Authorization header, or in the X-Api-Key header.

Authorization: Bearer bk_live_YOUR_KEY
X-Api-Key: bk_live_YOUR_KEY

• Keys are issued from the admin dashboard and shown exactly once at creation. Store them in a secret manager or environment variable; they cannot be retrieved again.
• A key is a random token (bk_live_ followed by a 32-character id). Only its SHA-256 hash is stored, and verification uses a timing-safe comparison.
• Keys support an optional expiry, are checked against revocation on every request, and record a lastUsedAt timestamp so you can audit usage.
• Each key has scopes, picked when it is made: bookings:read, bookings:write, availability:read, catalog:read, catalog:write, staff:read, customers:read, reports:read, content:read, content:write, webhooks:read, webhooks:write, checkout:read, checkout:write, audit:read, customers:write. Every key-protected endpoint and every MCP tool needs exactly one, named on it below (GET /customers needs customers:read, reading bookings bookings:read, making, moving, cancelling or answering them and changing a class roster bookings:write, the money reports reports:read), and tools/list shows only the tools the key can call. A call outside the key's scopes returns 403 naming the scope it needed (missingScope in the body; error.data.missingScope over MCP).
• checkout:read, checkout:write, audit:read, customers:write are carried only by a key made with them ticked: the checkout scopes are for another point of sale (such as Moneris MGR) checking bookings out, audit:read reads the audit log, and customers:write puts the business's tags on clients and takes them off. A key made before scopes never has them, whatever its access level, and neither does a connected app. Anything that names a client (their name, email and phone) needs customers:read as well.
• A key can never do more than the person who made it may do in the business: they can only give it scopes their role holds (customers:read needs Export data, reports:read needs See analytics & earnings), and if their role later loses a right, or they leave the team, their keys lose it too. A connected app is held to the person who approved it the same way.
• Keys made before scopes keep the access level they were made with: read-write (full access) or read-only. A read-only key may call the GET endpoints and read-only MCP tools, but write endpoints — creating or cancelling a booking — return 403. The checkout and audit scopes are the exception: such a key never has them. The dashboard marks them as legacy; replace them with scoped keys.
• Revoke a key immediately from the dashboard if it is ever exposed. Revoked and expired keys stop authenticating at once.
• Test keys start bk_test_ and belong to a sandbox business, a test business made for building and testing (see /developers/testing): a sandbox issues only test keys and a live business only bk_live_ keys, with the same scopes. A key of the other mode is refused with 403 and code LIVEMODE_MISMATCH, and every JSON answer says livemode (false from a sandbox), as does the Bookatu-Livemode header.

Base URL & CORS

https://bookatu.com/api/v1/{slug}

Replace {slug} with the business URL slug visible in your admin and public booking link. All responses are application/json. Errors always return { ok: false, error: "..." } (validation errors also include a fieldErrors map). Stack traces are never leaked.

The public endpoints (business, services, staff, availability, book) return Access-Control-Allow-Origin: * and answer the CORS preflight (OPTIONS) with 204, so any site or agent can call them directly from a browser. Key-protected endpoints deliberately do NOT send the wildcard — their allowed CORS origin is the platform's own origin, because business data has no legitimate cross-origin browser use. The customer booking-management endpoints (everything under /booking/{id}) do not send it either, and answer no preflight: they are authorised by the booking's manage key (or, for a booking from before manage keys, its id), which has no business being replayed from a third-party page. Neither restriction affects server-to-server or native mobile callers, which are not subject to browser CORS at all. Never embed a bk_live_ key in browser or mobile-client code — call key-protected endpoints from your own server.

Endpoint reference

Across responses, a booking status is one of: pending, confirmed, completed, cancelled, no_show.

GET /business

GET /api/v1/{slug}/business

Business profile + opening hours

The business profile: name, industry, country, currency, timezone, locale, address, phone, the public booking link, and the full week of opening hours. Lets an agent introduce the business and know when it is open before checking availability. At a business that lets clients book several services in one visit, visits says so, with the most services one visit takes: { "maxServices": 4 } (absent everywhere else). At a business that asks booking questions for every service, questions lists those (each service's own are on GET /services); absent otherwise. No authentication required.

curl https://bookatu.com/api/v1/your-salon/business

{
  "name": "Parnell Nails",
  "slug": "parnell-nails",
  "industry": "nails",
  "country": "NZ",
  "currency": "NZD",
  "timezone": "Pacific/Auckland",
  "locale": "en-NZ",
  "address": "12 Queen St, Auckland",
  "phone": "09 555 0100",
  "bookingUrl": "https://bookatu.com/parnell-nails/book",
  "hours": [
    { "weekday": 0, "open": false, "openMin": null, "closeMin": null, "breakStartMin": null, "breakEndMin": null },
    { "weekday": 1, "open": true,  "openMin": 540,  "closeMin": 1080, "breakStartMin": 780, "breakEndMin": 840 },
    { "weekday": 2, "open": true,  "openMin": 540,  "closeMin": 1080, "breakStartMin": null, "breakEndMin": null },
    { "weekday": 3, "open": true,  "openMin": 540,  "closeMin": 1080, "breakStartMin": null, "breakEndMin": null },
    { "weekday": 4, "open": true,  "openMin": 540,  "closeMin": 1080, "breakStartMin": null, "breakEndMin": null },
    { "weekday": 5, "open": true,  "openMin": 540,  "closeMin": 1140, "breakStartMin": null, "breakEndMin": null },
    { "weekday": 6, "open": true,  "openMin": 600,  "closeMin": 960,  "breakStartMin": null, "breakEndMin": null }
  ]
}

// hours always has all 7 days. weekday 0 = Sunday .. 6 = Saturday.
// openMin / closeMin are minutes from local midnight, and are null when closed.
// breakStartMin / breakEndMin are a mid-day closure (Monday above shuts 1pm to
// 2pm) and are null when the day runs straight through. A day with a break
// trades openMin-breakStartMin and breakEndMin-closeMin, and NOTHING between:
// treat the outer pair alone as open all day and you will send someone to a
// locked door.

GET /services

GET /api/v1/{slug}/services

List active, online-bookable services

The org's public profile plus every service that is active and bookable online, ordered by sort order then name. Use a service id and durationMin when checking availability and booking. At a business with extras, each service also has addOns: the extras offered with it under the business's combination rules ({ id, name, description, priceCents, durationMin, addsTime }; addsTime true means its durationMin is added to the booking). Pass their ids as addOnIds when booking. A business with no extras returns no addOns. A service with combination rules lists them as combinations: onlyWith, the only other services it can share a visit with (absent: any), and neverWith, the services and extras it is never booked with, whichever of the two set it (a 4 braids and a 6 braids, say). A service two or more of the team do at once says how many as peopleNeeded. Each only when there is something to say, so every other row is exactly as it was. A service that needs two or more kinds of resource at once (a treatment room and a laser machine, say) lists them as resourceKinds, in order: a time is offered only when a person and one free resource of each kind are free together, and a booking of it holds one of each for its whole length, the first kind's as the booking's own room. Absent on a service that needs one kind or none, so its row is exactly as it was. A service the business asks booking questions for lists them as questions, in the order they are asked: { id, type (text, textarea, radio, checkboxes, yes_no, number or date), label, required, helpText?, options? (radio and checkboxes), allServices? (true: asked for every service) }. Answer them as answers on POST /book; a required one must be answered (422 ANSWERS_REQUIRED). A service with no questions has no questions field. A service that lasts whole days (a trip) is booked by the business only (its New booking form and POST /appointments) and is never listed or booked here. No authentication required.

curl https://bookatu.com/api/v1/your-salon/services

{
  "org": {
    "name": "Parnell Nails",
    "slug": "parnell-nails",
    "currency": "NZD",
    "timezone": "Pacific/Auckland"
  },
  "services": [
    {
      "id": "svc_abc123",
      "name": "Gel Manicure",
      "description": "Long-lasting gel polish with cuticle care.",
      "category": "Nails",
      "durationMin": 60,
      "priceCents": 7500,
      "currency": "NZD",
      "questions": [
        { "id": "bq_hairlength", "type": "yes_no", "label": "Are your nails longer than 1 cm?", "required": true, "helpText": "So we book enough time." },
        { "id": "bq_heard", "type": "radio", "label": "How did you hear about us?", "required": false, "options": ["A friend", "Instagram"], "allServices": true }
      ]
    }
  ]
}

// description is the service description, or null when none is set.
// questions is there only on a service the business asks booking questions
// for: answer them as answers on POST /book.

GET /staff

GET /api/v1/{slug}/staff

List bookable team members

The bookable team members (id, name, title, bio) so an agent can offer "book with X". Public-facing fields only — never staff email or phone. No authentication required.

curl https://bookatu.com/api/v1/your-salon/staff

{
  "org": { "name": "Parnell Nails", "slug": "parnell-nails", "timezone": "Pacific/Auckland" },
  "staff": [
    { "id": "stf_abc", "name": "Anna", "title": "Senior Nail Tech", "bio": null }
  ]
}

// title and bio are null when not set.

GET /availability

GET /api/v1/{slug}/availability

Open slots for a service

Bookable slots for a service across a date window. The engine accounts for opening hours, existing appointments, blocked time (one-off or weekly, for a person, for everyone, or for a room or chair the service needs: when another room of the kind is free the slot stays and uses it), buffer times, resources and minimum booking notice. Each slot's startAt is a UTC ISO 8601 string ready to pass straight to a booking call. Each time also comes as when: { utc, primary, business: { timeZone, local, utcOffset, abbr, display }, client } with the offset in force on that day (a slot after the clocks change carries the new one), on the business's clock (the branch's at a branch) and, when the client's zone is known, on theirs (client is null otherwise; dayDiffers says their date is another day). Quote display rather than converting a time yourself. timeZone names the clock the slots and the from/to dates are on. No authentication required. This is the read for a NEW booking: to move an existing one, use GET /booking/{id}/availability instead, because this read counts that booking's own slot as busy. A slot a surcharge covers (a public holiday or a busy time the business charges more for) also carries priceCents (the price before it, before any discount code), surcharges (the one that applies: label, amountType percent or fixed, amount as a whole percent or in minor units, and amountCents, what it adds) and totalCents, what the booking comes to at that time. When two of the business's surcharges cover one time, only the higher applies, so surcharges has one entry. Show it to the client before they book. Every other slot has none of these fields.

curl "https://bookatu.com/api/v1/your-salon/availability?serviceId=svc_abc123&from=2026-06-10&to=2026-06-14"

{
  "org": { "name": "Parnell Nails", "slug": "parnell-nails", "timezone": "Pacific/Auckland" },
  "days": [
    {
      "date": "2026-06-10",
      "open": true,
      "slots": [
        {
          "startMin": 540,
          "startAt": "2026-06-09T21:00:00.000Z",
          "when": {
            "utc": "2026-06-09T21:00:00Z",
            "primary": "business",
            "business": {
              "timeZone": "Pacific/Auckland",
              "local": "2026-06-10T09:00:00+12:00",
              "utcOffset": "+12:00",
              "abbr": "NZST",
              "display": "Wednesday, 10 June at 9:00 am NZST"
            },
            "client": null
          }
        }
      ]
    },
    { "date": "2026-06-11", "open": false, "slots": [] }
  ],
  "timeZone": "Pacific/Auckland",
  "datesAreOn": "business"
}

// startMin is minutes from local midnight; startAt is the UTC instant to book.

// A slot on a date the business charges a surcharge on also has:
//   "priceCents": 8000,
//   "surcharges": [{ "label": "Public holiday surcharge", "amountType": "percent", "amount": 15, "amountCents": 1200 }],
//   "totalCents": 9200

POST /book

POST /api/v1/{slug}/book

Create a booking (online source)

The customer-facing booking call, with no key and no account, so nobody calling it has proved who they are. The slot is validated server-side (race-condition safe) and a booking reference is returned. As an online-source booking it fully respects availability and minimum notice. A customer record is matched by email then phone or created, but an email match changes nothing: every customer is treated as new (a business that approves new clients' bookings gets a request), no deposit is waived, nothing on an existing record is filled in, and the answer is the same for a known email and an unknown one. A service that takes a deposit is refused with 409 and code DEPOSIT_NEEDS_BOOKING_PAGE, with bookingPageUrl, the business's own booking page where the deposit can be paid; nothing is booked. So is a service the business requires a card saved to hold (409, code CARD_REQUIRED_USE_BOOKING_PAGE, with bookingPageUrl): a card is only ever saved in the booking page's own card step. At a business that has set booking terms, the person must accept them: send acceptTerms: true (and the termsVersion they were shown); without it the answer is 422 with code TERMS_NOT_ACCEPTED and the terms to show, and nothing is booked. At a business that asks booking questions (GET /services lists them on each service as questions), send the person's answers as answers; a required question without an answer is 422 with code ANSWERS_REQUIRED and missingQuestionIds, an answer that cannot be read 422 ANSWERS_INVALID with invalidAnswers, and nothing is booked. The appointmentId in the answer is the person's private key to their booking: never show it, store it or put it in a chat; the person manages the booking from the confirmation email they are sent. The manageKey beside it is what changes the booking, and is just as private: an app of the person's own sends it as k (or X-Manage-Key) to /booking/{id}. The answer's when is the booked time on the business's clock and, with clientTimeZone, the client's. A booking made at a surcharged time also has priceCents (its total, the surcharge included) and surcharge: { label, amountCents }; a booking without one has neither. A booking keeps the surcharge it was made with. A service that lasts whole days (a trip) is booked by the business only (its New booking form and POST /appointments) and is never listed or booked here. No authentication required; at most 5 bookings per address per business in 10 minutes and 15 a day, and 40 a day per business.

curl -X POST https://bookatu.com/api/v1/your-salon/book \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "svc_abc123",
    "startAt": "2026-06-10T09:00:00Z",
    "name": "Alex Smith",
    "email": "alex@example.com",
    "phone": "+64 21 555 0100"
  }'

{
  "ok": true,
  "ref": "VRD-7QK2M9",
  "appointmentId": "apt_abc123",
  "manageKey": "3q2-Lr8xN0b6VfJm1oZ4sYtKcE9uWgHdAiPkQnTwXeU",
  "status": "confirmed",
  "needsPayment": false
}

// status is "pending" for a request the business still has to accept.
// At a surcharged time (a public holiday), also:
//   "priceCents": 9200, "surcharge": { "label": "Public holiday surcharge", "amountCents": 1200 }
// appointmentId and manageKey are the person's private keys to their booking:
// never show them, store them or put them in a chat; they manage it from the
// email they are sent. An app of their own sends manageKey as k (or
// X-Manage-Key) to /booking/{id} to cancel or move it.

// A service that takes a deposit is refused, and nothing is booked:
// HTTP 409
{
  "ok": false,
  "error": "This service takes a deposit, which can only be paid on the business's booking page. Nothing was booked: send the person to bookingPageUrl.",
  "code": "DEPOSIT_NEEDS_BOOKING_PAGE",
  "bookingPageUrl": "https://bookatu.com/your-salon/book?service=svc_abc123"
}

// So is a service the business requires a card saved to hold:
// HTTP 409
{
  "ok": false,
  "error": "This service needs a card saved to hold the booking, which can only be done on the business's booking page. Nothing was booked: send the person to bookingPageUrl.",
  "code": "CARD_REQUIRED_USE_BOOKING_PAGE",
  "bookingPageUrl": "https://bookatu.com/your-salon/book?service=svc_abc123"
}

// At a business with booking terms, a booking without acceptTerms: true:
// HTTP 422
{
  "ok": false,
  "error": "This business asks clients to accept its booking terms to book. Show the person the terms (terms.text), and send acceptTerms: true only once they have accepted them. Nothing was booked.",
  "code": "TERMS_NOT_ACCEPTED",
  "terms": { "text": "Please arrive 10 minutes early.", "version": "3f2a…" }
}

// At a business with booking questions, a booking without a required answer:
// HTTP 422
{
  "ok": false,
  "error": "This business asks a few questions before it takes this booking. Send the answers to the required questions (missingQuestionIds), or book on the business's booking page.",
  "code": "ANSWERS_REQUIRED",
  "missingQuestionIds": ["bq_hairlength"]
}

GET /booking/{id}

No API key. Authorised by the booking's manage key (k, or X-Manage-Key); the appointment id alone reads a read-only status.

GET /api/v1/{slug}/booking/{id}

Read one booking (the customer's own)

The JSON twin of the manage-booking page a customer reaches from their confirmation email: their booking, its service, its team member, its price and deposit, plus the business's cancellation policy and what the customer may still change online (selfService), worked out by the same rules the web page and the change endpoints apply: whether a cancel or a move would be accepted now and why not, until when online changes stay open, how many online moves are left, and, when the business lets customers choose someone else when they move, who they may choose. Authorised by the booking's manage key (k or X-Manage-Key) — no API key, no account — and deliberately narrow; with the appointment id alone it answers a read-only status (access "view": no selfService, no quickSwap): only what the person who booked already knows. No customer record, no notes, no other bookings. When the booking is one service of a visit of several, visit lists the visit's services still on ({ id, services: [{ appointmentId, service, staff, startAt, endAt, durationMin, priceCents, status }] }), and selfService is the visit's, under the rules of its first service. A booking two or more of the team do at once also has booking.additionalStaff: the others' names, besides staff. At a business that switched Quick swap on, quickSwap says what the manage-booking page would offer about swapping out of a late cancellation: status (null, requested, claimed, withdrawn or expired), requestedAt, cutoffAt (when offers stop), canAsk and, when not, block (off, approval, closed, not_confirmed, checked_in, request_open, not_offered, asked, past_cutoff or not_late), and canWithdraw (the client's ask stands and the time is still on offer: false once the business has stopped offering it, for example by switching Quick swap off). Read only: the customer asks and withdraws on the web page. Inside the last hours before the start (after cutoffAt, the hours the business set for offers to stop, or its free-cancellation window if that is shorter), a business may have chosen to charge a client who cancels the full price of the booking (for a visit, every service of it still on, as one fee), less any deposit it keeps, up to its maximum fee: for every booking, or only for bookings Quick swap could offer. It applies only where cancelling would already cost a late-cancellation fee or the deposit, only where the business requires a card to hold bookings, and only to a booking made on the business's booking page whose client was shown it there before confirming: a booking made through this API, an assistant or by the business, or before the business chose it, keeps the usual late-cancellation fee. If the business later changes its Quick swap choice or hours, the usual fee is charged instead; if it changes its cancellation policy, the fee is not charged; a no-show is charged as before. The manage-booking page says what cancelling would cost. when is the booking's start on the business's clock and, when the client's zone was kept with the booking, on theirs (source "booking"). A booking made at a surcharged time also has surcharge: { label, amountCents }, part of priceCents. Rate limited to 30 requests per IP every 5 minutes.

curl https://bookatu.com/api/v1/your-salon/booking/apt_abc123

{
  "org": {
    "slug": "parnell-nails",
    "name": "Parnell Nails",
    "currency": "NZD",
    "timezone": "Pacific/Auckland"
  },
  "booking": {
    "id": "apt_abc123",
    "ref": "VRD-7QK2M9",
    "status": "confirmed",
    "startAt": "2026-06-10T21:00:00.000Z",
    "endAt": "2026-06-10T22:00:00.000Z",
    "durationMin": 60,
    "service": "Gel Manicure",
    "staff": "Anna",
    "priceCents": 7500,
    "depositCents": 2000,
    "addOns": [{ "name": "Nail art", "priceCents": 1500 }]
  },
  "policy": {
    "cancellationWindowHours": 24,
    "forfeitDepositOnLateCancel": true
  },
  "selfService": {
    "canCancel": true,
    "canReschedule": true,
    "cancelBlocked": null,
    "rescheduleBlocked": null,
    "changesCloseAt": "2026-06-09T21:00:00.000Z",
    "movesLeft": 2,
    "canChangeStaff": true,
    "staffOptions": [
      { "id": "stf_anna", "name": "Anna", "current": true },
      { "id": "stf_mia", "name": "Mia", "current": false }
    ],
    "message": null,
    "contact": null
  }
}

// policy is the business's cancellation policy: cancelling or moving more than
// cancellationWindowHours before the start is free, and inside that window a
// paid deposit is kept when forfeitDepositOnLateCancel is true. ref and staff
// are null when unset; addOns is [] when there are none.
//
// selfService is what the customer may change online right now. canCancel and
// canReschedule say whether POST /cancel and POST /reschedule would be accepted;
// when not, cancelBlocked / rescheduleBlocked carry the same code those
// endpoints' 409 does: cancel_off or reschedule_off (the business takes that
// change by phone or email only), past_cutoff, reschedule_limit, cancel_closed
// or move_closed (the booking is cancelled, completed, a no-show or has
// started), or deposit_unpaid (rescheduleBlocked only: the booking is held
// until its deposit is paid, and cannot be moved before). changesCloseAt is when online changes stop (null: never); movesLeft
// is null when there is no limit. staffOptions lists who the booking can be
// moved to (the booked person first, current: true) and is [] unless
// canChangeStaff. message and contact are what the web page shows instead of
// the changes the business keeps for itself, in its language: null when
// nothing is kept back, and for a booking that is over.
//
// At a business that switched Quick swap on there is also quickSwap, e.g.
// { "status": null, "requestedAt": null, "cutoffAt": "2026-06-10T19:00:00.000Z",
//   "canAsk": true, "block": null, "canWithdraw": false }: whether the customer
// may ask to swap out of a late cancellation on the web page now, and when
// offers stop.

GET /booking/{id}/availability

No API key. Authorised by the booking's manage key (k, or X-Manage-Key); the appointment id alone reads a read-only status.

GET /api/v1/{slug}/booking/{id}/availability

Open slots for MOVING this booking

Bookable slots for moving an existing booking, across a date window. This differs from GET /availability in two ways that matter: the booking's own slot is EXCLUDED from the busy set (otherwise an appointment's own hold hides the very time its owner is trying to shift around), and the fit uses the booking's own service and its own length — which is not always the service's default, because an add-on or a duration override can make the booking longer. Pass a returned startAt straight to POST /booking/{id}/reschedule. Authorised by the booking's manage key (k or X-Manage-Key); with the id alone it answers 403 MANAGE_KEY_REQUIRED. For one service of a visit of several, the slots are the starts the whole visit fits, each service keeping its person and length, and visit gives its id and its whole length ({ id, durationMin }). Rate limited to 30 requests per IP every 5 minutes.

curl "https://bookatu.com/api/v1/your-salon/booking/apt_abc123/availability?from=2026-06-10&to=2026-06-14"

{
  "org": { "slug": "parnell-nails", "name": "Parnell Nails", "timezone": "Pacific/Auckland" },
  "booking": { "id": "apt_abc123", "durationMin": 60 },
  "days": [
    {
      "date": "2026-06-10",
      "open": true,
      "slots": [
        { "startMin": 540, "startAt": "2026-06-09T21:00:00.000Z" }
      ]
    },
    { "date": "2026-06-11", "open": false, "slots": [] }
  ]
}

// booking.durationMin is the length being fitted (the booking's, not the
// service's default). startMin is minutes from local midnight; startAt is the
// UTC instant to send back when rescheduling.

POST /booking/{id}/reschedule

No API key. Authorised by the booking's manage key (k, or X-Manage-Key); the appointment id alone reads a read-only status.

POST /api/v1/{slug}/booking/{id}/reschedule

Move a booking to a new time

The customer-facing reschedule — the same call the manage-booking web page makes, with the same strict rules. The new time is validated as a real, open slot: opening hours, existing bookings, buffers, resources and the business's minimum booking notice all apply, and the booking's own hold is excluded so it can be moved within its own slot. A time that is not bookable returns 409 with the reason, and nothing changes. The booking keeps its team member unless the availability engine has to reassign it, and its length is unchanged. Moving a booking fires the booking.rescheduled webhook and updates any connected calendar. Only an upcoming pending or confirmed booking can be moved: a cancelled, completed, no-show or past booking returns 409 — the same rule as the web page, so a cancelled booking can never be quietly reinstated. For one service of a visit of several, the whole visit moves: every service keeps its person and length, startAt is the first service's new start, it counts once against the business's limit on moves, and nobody else can be picked (staffId). Rate limited to 10 requests per IP every 10 minutes.

curl -X POST https://bookatu.com/api/v1/your-salon/booking/apt_abc123/reschedule \
  -H "Content-Type: application/json" \
  -d '{ "startAt": "2026-06-12T21:00:00.000Z" }'

{ "ok": true, "startAt": "2026-06-12T21:00:00.000Z" }

// startAt echoes the time that was taken, so the new booking can be rendered
// without a second read.

POST /booking/{id}/cancel

No API key. Authorised by the booking's manage key (k, or X-Manage-Key); the appointment id alone reads a read-only status.

POST /api/v1/{slug}/booking/{id}/cancel

Cancel a booking (the customer's own)

The customer-facing cancellation — the same call the manage-booking web page makes, so the cancellation policy, any deposit refund or forfeiture, the booking.cancelled webhook, the waitlist re-offer and the cancellation emails the business may have switched on are identical however it is triggered. The forfeited flag says whether a paid deposit was kept under the policy, which an app needs in order to tell the person the truth on the confirmation screen. Cancelling an already-cancelled booking is idempotent (alreadyCancelled: true), so a retry after a dropped connection is safe. Only an upcoming pending or confirmed booking can be cancelled: a completed, no-show or started booking returns 409. For one service of a visit of several, the whole visit is cancelled, under the rules of its first service, with one email each way. Rate limited to 10 requests per IP every 10 minutes.

curl -X POST https://bookatu.com/api/v1/your-salon/booking/apt_abc123/cancel

{ "ok": true, "alreadyCancelled": false, "forfeited": false }

// forfeited is true when a paid deposit was kept under the cancellation policy
// (see policy on GET /booking/{id}).

GET /customers

Needs the customers:read scope.

GET /api/v1/{slug}/customers

List customers

Up to 1000 customers in this org (id, name, email, phone and tags), ordered by name. tags lists the business's own tags on it ({ id, name, color }: color is a palette name such as indigo or rose), in name order, [] for none. Tags are the team's internal labels: never show them to a client, and they are never in a webhook payload. Requires a valid API key whose org matches the {slug}.

curl https://bookatu.com/api/v1/your-salon/customers \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "customers": [
    {
      "id": "cus_xyz",
      "name": "Alex Smith",
      "email": "alex@example.com",
      "phone": "+64211234567",
      "tags": [{ "id": "tag_vip123", "name": "VIP", "color": "indigo" }]
    }
  ]
}

// Capped at 1000 customers, ordered by name.

GET /appointments

Needs the bookings:read scope.

GET /api/v1/{slug}/appointments

List appointments

By default, upcoming appointments with status pending or confirmed whose startAt is now or later, ordered by start time, capped at 200. Optional filters let you pull a specific window or statuses, and limit/offset page through results — when more rows may exist the response includes nextOffset. Each row says where the booking came from: source (online: the client; phone, walk_in or admin: the team, the API or the phone app; magic_fill: a waitlist claim), leadSource (the tag it came in with, as stored, e.g. a booking link's ?via=) and channel (google, instagram, facebook, apple_maps or bing for a client who came through one of the business's booking links, else null); seriesId names the repeat series a booking is a visit of, and visitId the visit of several services it is one of (each null when it is neither; GET /visits/{id} reads a visit). notifyClient is false for a booking whose client Bookatu does not message (made with notifyClient: false on POST /appointments, or switched off on the booking's page), else true. A trip (a booking of a service that lasts whole days) also has startDate and endDate (its first and last day on the business's calendar, both inclusive) and days, after notifyClient; startAt is its first day's midnight there and endAt the midnight after its last day. Other bookings have none of the three. A booking that two or more of the team do at once also has additionalStaffIds: the others on it besides staffId, in their order (absent on every other booking). A booking of a service that needs two or more kinds of resource at once, or one holding more than one resource, also has resources: every room, chair or machine it holds, { id, name, kind }, its own room first and then the others in the order of the service's resourceKinds. A booking saved without one of its kinds lists only what it holds ([] for nothing). Absent on every other booking. Quick swap: a booking whose client asked to swap out of a late cancellation (the business offers the time to its waitlist while the client stays booked) also has swap ({ status, requestedAt, cutoffAt, closedAt, claimedAppointmentId }). status is requested (offered to the waitlist until cutoffAt), claimed (a waiting client took it over: claimedAppointmentId is their booking, and this one is cancelled with no fee), withdrawn or expired (nobody took it by the cutoff, or the booking changed since). The ask is on the first service of a visit. Absent on every other booking, so a business that never switched Quick swap on reads exactly as before. tags lists the business's own tags on it ({ id, name, color }: color is a palette name such as indigo or rose), in name order, [] for none. Tags are the team's internal labels: never show them to a client, and they are never in a webhook payload. Requires a valid API key scoped to this org.

curl "https://bookatu.com/api/v1/your-salon/appointments?status=completed&from=2026-06-01&limit=50" \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "appointments": [
    {
      "id": "apt_abc123",
      "ref": "VRD-7QK2M9",
      "serviceName": "Gel Manicure",
      "startAt": "2026-06-10T21:00:00.000Z",
      "endAt": "2026-06-10T22:00:00.000Z",
      "durationMin": 60,
      "priceCents": 7500,
      "status": "confirmed",
      "customerId": "cus_xyz",
      "staffId": "stf_abc",
      "notes": null,
      "createdAt": "2026-06-01T03:12:00.000Z",
      "notifyClient": true,
      "source": "online",
      "leadSource": "google",
      "channel": "google",
      "seriesId": null,
      "visitId": null,
      "tags": [{ "id": "tag_bridal456", "name": "Bridal", "color": "rose" }]
    }
  ]
}

// Only pending + confirmed, startAt >= now, oldest first, max 200 rows.

GET /services/{id}

GET /api/v1/{slug}/services/{id}

Get one service

A single active, online-bookable service by id — the same shape as a row of GET /services, addOns included at a business with extras. A service with combination rules lists them as combinations: onlyWith, the only other services it can share a visit with (absent: any), and neverWith, the services and extras it is never booked with, whichever of the two set it (a 4 braids and a 6 braids, say). A service two or more of the team do at once says how many as peopleNeeded. Each only when there is something to say, so every other row is exactly as it was. A service that needs two or more kinds of resource at once (a treatment room and a laser machine, say) lists them as resourceKinds, in order: a time is offered only when a person and one free resource of each kind are free together, and a booking of it holds one of each for its whole length, the first kind's as the booking's own room. Absent on a service that needs one kind or none, so its row is exactly as it was. A service the business asks booking questions for lists them as questions, in the order they are asked: { id, type (text, textarea, radio, checkboxes, yes_no, number or date), label, required, helpText?, options? (radio and checkboxes), allServices? (true: asked for every service) }. Answer them as answers on POST /book; a required one must be answered (422 ANSWERS_REQUIRED). A service with no questions has no questions field. No authentication required.

curl https://bookatu.com/api/v1/your-salon/services/svc_abc123

{
  "id": "svc_abc123",
  "name": "Gel Manicure",
  "description": "Long-lasting gel polish with cuticle care.",
  "category": "Nails",
  "durationMin": 60,
  "priceCents": 7500,
  "currency": "NZD"
}

GET /appointments/{id}

Needs the bookings:read scope.

GET /api/v1/{slug}/appointments/{id}

Get one appointment

A single appointment by id, scoped to the key's org (a key for one business can never read another's). Same lean shape as a row of GET /appointments, source, leadSource, channel, seriesId, visitId, notifyClient and tags included. notifyClient is false for a booking whose client Bookatu does not message (made with notifyClient: false on POST /appointments, or switched off on the booking's page), else true. A trip (a booking of a service that lasts whole days) also has startDate and endDate (its first and last day on the business's calendar, both inclusive) and days, after notifyClient; startAt is its first day's midnight there and endAt the midnight after its last day. Other bookings have none of the three. A booking that two or more of the team do at once also has additionalStaffIds: the others on it besides staffId, in their order (absent on every other booking). A booking of a service that needs two or more kinds of resource at once, or one holding more than one resource, also has resources: every room, chair or machine it holds, { id, name, kind }, its own room first and then the others in the order of the service's resourceKinds. A booking saved without one of its kinds lists only what it holds ([] for nothing). Absent on every other booking. Quick swap: a booking whose client asked to swap out of a late cancellation (the business offers the time to its waitlist while the client stays booked) also has swap ({ status, requestedAt, cutoffAt, closedAt, claimedAppointmentId }). status is requested (offered to the waitlist until cutoffAt), claimed (a waiting client took it over: claimedAppointmentId is their booking, and this one is cancelled with no fee), withdrawn or expired (nobody took it by the cutoff, or the booking changed since). The ask is on the first service of a visit. Absent on every other booking, so a business that never switched Quick swap on reads exactly as before. tags lists the business's own tags on it ({ id, name, color }: color is a palette name such as indigo or rose), in name order, [] for none. Tags are the team's internal labels: never show them to a client, and they are never in a webhook payload. A booking made at a surcharged time also has surcharge: { label, amountCents }, part of priceCents. A read-only key may call this. Requires a valid API key scoped to this org.

curl https://bookatu.com/api/v1/your-salon/appointments/apt_abc123 \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "id": "apt_abc123",
  "ref": "VRD-7QK2M9",
  "serviceName": "Gel Manicure",
  "startAt": "2026-06-10T21:00:00.000Z",
  "endAt": "2026-06-10T22:00:00.000Z",
  "durationMin": 60,
  "priceCents": 7500,
  "status": "confirmed",
  "customerId": "cus_xyz",
  "staffId": "stf_abc",
  "notes": null,
  "createdAt": "2026-06-01T03:12:00.000Z",
  "notifyClient": true,
  "source": "phone",
  "leadSource": null,
  "channel": null,
  "seriesId": "ser_abc123",
  "visitId": null,
  "tags": []
}

POST /appointments

Needs the bookings:write scope.

POST /api/v1/{slug}/appointments

Create a booking (admin source)

Create a booking with source: admin and the same body as POST /book, plus requestDeposit, additionalStaffIds (the others on a booking two or more of the team do at once, then named in the answer too) and notifyClient (false: Bookatu never messages the client about this booking; the team's alerts and the webhooks are unchanged). For a service that needs two or more kinds of resource at once (resourceKinds on GET /services), the engine holds one free resource of each kind at a time it offers, resourceId prefers the first kind's one (the room), and the answer lists everything the booking holds as resources ({ id, name, kind }); at a time the engine does not offer it may hold fewer, exactly as a room is left off, and resources says what it holds. The other resources are always the engine's choice and cannot be named. To book a visit of several services, use POST /visits. An admin-source booking deliberately bypasses online restrictions: minimum booking notice is not enforced, and — unlike POST /book — a slot conflict does NOT reject the request. The availability engine is used only to resolve a free staff member and resource; it does not block the booking. The one guard that still applies is the database uniqueness constraint on (staff, start time), which returns 409 if that exact staff member is already booked at that instant. Use this for trusted staff-side tools and agents acting on behalf of the business; use POST /book for customer-facing flows that must respect availability. A booking made at a surcharged time also has priceCents (its total, the surcharge included) and surcharge: { label, amountCents }; a booking without one has neither. A booking keeps the surcharge it was made with. A service that lasts whole days (a trip: Services, Length in Whole days) is booked by its days, startDate with endDate or with days, never by a time, and is priced once per booking; the answer then has startDate, endDate and days too. Its person must be free on every one of its days, and each resource its service needs is held for them; it takes no extras and does not repeat. notifyClient: false keeps its client unmessaged, as for any booking. Requires a valid API key scoped to this org.

curl -X POST https://bookatu.com/api/v1/your-salon/appointments \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "svc_abc123",
    "startAt": "2026-06-10T09:00:00Z",
    "name": "Alex Smith",
    "email": "alex@example.com",
    "phone": "+64 21 555 0100"
  }'

{
  "ok": true,
  "ref": "VRD-7QK2M9",
  "appointmentId": "apt_abc123",
  "status": "confirmed",
  "needsPayment": false
}

// When a deposit is required, status is "pending" and a payLink is returned:
{
  "ok": true,
  "ref": "VRD-7QK2M9",
  "appointmentId": "apt_abc123",
  "status": "pending",
  "needsPayment": true,
  "payLink": "https://bookatu.com/your-salon/book/success?apt=apt_abc123"
}

POST /appointments/{id}/cancel

Needs the bookings:write scope.

POST /api/v1/{slug}/appointments/{id}/cancel

Cancel a booking

Cancel a booking. Scoped to the key's org, so a key for one business can never touch another's data. Fires the booking.cancelled webhook and re-offers the freed slot to the waitlist. The forfeited flag is true when a paid deposit was forfeited under the cancellation policy. Cancelling an already-cancelled booking is idempotent. Requires a valid API key scoped to this org.

curl -X POST https://bookatu.com/api/v1/your-salon/appointments/apt_abc123/cancel \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer requested" }'

{ "ok": true, "id": "apt_abc123", "forfeited": false }

GET /appointments/{id}/checkout

Needs the checkout:read scope, on a key made with it ticked.

GET /api/v1/{slug}/appointments/{id}/checkout

What a booking comes to at checkout (MGR hand-off)

For a point of sale that is not Bookatu's (Moneris MGR, or any other): start checkout from a booking and carry it into your sale rather than ringing it up again by hand. The answer is the sale Bookatu's own point of sale would open with: the booking and its ref, the client, who it is with, each line (the service, then each extra; every service of a visit of several services) at its booked price and discount with the person credited for it (staffId, staffName), each line's tax and the tax lines as the point of sale would charge them (tax.mode: included in the prices, added on top at checkout, or none), the deposit already paid (depositPaidCents) and dueCents: what is left to take, tax added on top included and the deposit taken off. Charge exactly dueCents, then POST the sale back to the same address. checkout.allowed says whether it can be checked out now; when not, checkout.blocked says why (not_live: finished, cancelled or a no-show; deposit_pending: the client is still paying an online deposit; already_checked_out: then sale is the sale that closed it, whichever point of sale took it). Each line's lineId is stable while the booking is open; name it to credit a line to someone else when you post the sale. The client comes by id (customer.id); their name, email and phone come too only when the key also has customers:read. A visit of several services is one sale under its first service, whichever service's id you ask with. Requires an API key made with the checkout:read scope ticked (the scope needs See everyone's calendar). Changes nothing.

curl https://bookatu.com/api/v1/your-salon/appointments/apt_abc123/checkout \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "version": 1,
  "appointment": {
    "id": "apt_abc123",
    "ref": "VRD-7QK2M9",
    "status": "confirmed",
    "startAt": "2026-06-10T21:00:00.000Z",
    "endAt": "2026-06-10T22:10:00.000Z",
    "serviceName": "Cut",
    "customerId": "cus_xyz",
    "staffId": "stf_sam",
    "source": "online",
    "visitId": null
  },
  "customer": { "id": "cus_xyz", "name": "Jane Doe", "email": "jane@example.com", "phone": "+16045550100" },
  "staff": { "id": "stf_sam", "name": "Sam" },
  "currency": "CAD",
  "lines": [
    {
      "lineId": "apt_abc123:service",
      "kind": "service",
      "appointmentId": "apt_abc123",
      "label": "Cut",
      "qty": 1,
      "unitCents": 4000,
      "discountCents": 400,
      "totalCents": 3600,
      "taxCents": 432,
      "serviceId": "svc_cut",
      "staffId": "stf_sam",
      "staffName": "Sam"
    },
    {
      "lineId": "apt_abc123:add_on:1",
      "kind": "add_on",
      "appointmentId": "apt_abc123",
      "label": "Head massage",
      "qty": 1,
      "unitCents": 1500,
      "discountCents": 0,
      "totalCents": 1500,
      "taxCents": 180,
      "serviceId": "svc_massage",
      "staffId": "stf_sam",
      "staffName": "Sam"
    }
  ],
  "subtotalCents": 5500,
  "discountCents": 400,
  "totalCents": 5100,
  "tax": {
    "mode": "added",
    "taxCents": 612,
    "lines": [
      { "rateId": "gst", "label": "GST", "rateMilli": 5000, "taxCents": 255 },
      { "rateId": "pst", "label": "PST", "rateMilli": 7000, "taxCents": 357 }
    ]
  },
  "depositPaidCents": 2000,
  "dueCents": 3712,
  "checkout": { "allowed": true, "blocked": null },
  "sale": null
}

// A booking already checked out: dueCents 0, checkout.blocked
// "already_checked_out", and sale is the sale that closed it:
// "sale": {
    "id": "sale_x1y2z3",
    "receipt": "X1Y2Z3",
    "at": "2026-06-10T22:12:00.000Z",
    "source": "moneris_mgr",
    "externalSaleId": "MGR-000123",
    "method": "Card",
    "tender": "card",
    "collectedCents": 3712,
    "saleTotalCents": 3712,
    "tipCents": 500,
    "products": []
  }
//
// sale.source is "bookatu" for Bookatu's own point of sale (externalSaleId
// null), else the name the outside point of sale posted. tax.lines[].rateId is null for a business
// with one tax inside its prices. customer has only id without customers:read.

POST /appointments/{id}/checkout

Needs the checkout:write scope, on a key made with it ticked.

POST /api/v1/{slug}/appointments/{id}/checkout

Post an outside sale back: the booking is checked out (MGR hand-off)

The sale your point of sale took for the booking. The booking is checked out exactly as Bookatu's own point of sale checks it out: one sale linked to the booking (its receipt number on Bookatu's side), a line for the service and each extra credited to who did it, the booking's payment on the ledger (so it drops off Payments owed), the tip and who got it, and the booking is completed, with the thank-you, loyalty points and booking.completed webhook every completed booking gets. It is idempotent on externalSaleId: the same sale posted again (a retry after a dropped connection) finds the sale it made, answers replayed: true and writes nothing more, so it is always safe to retry. amountCents must be the checkout's dueCents: a sale for a different amount is refused with the amount it comes to (amount_mismatch), because two points of sale that disagree on the price cannot both be right in the books; change the booking's price in Bookatu first. A tip is recorded only when the business has switched on Accept tips at checkout, as at its own point of sale (sale.tipCents says what was). Products you sell with it stay in your own system. Fires booking.checked_out to the endpoints subscribed to it. The answer is the checkout payload as GET now returns it, with ok and replayed. Requires an API key made with the checkout:write scope ticked (the scope needs Edit the calendar).

curl -X POST https://bookatu.com/api/v1/your-salon/appointments/apt_abc123/checkout \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalSaleId": "MGR-000123",
    "source": "moneris_mgr",
    "amountCents": 3712,
    "currency": "CAD",
    "tender": "card",
    "tipCents": 500,
    "lines": [{ "lineId": "apt_abc123:add_on:1", "staffId": "stf_mia" }]
  }'

{
  "ok": true,
  "replayed": false,
  "version": 1,
  "appointment": { "id": "apt_abc123", "ref": "VRD-7QK2M9", "status": "completed", ... },
  "lines": [ ...each line with the person it is now credited to... ],
  "depositPaidCents": 2000,
  "dueCents": 0,
  "checkout": { "allowed": false, "blocked": "already_checked_out" },
  "sale": {
    "id": "sale_x1y2z3",
    "receipt": "X1Y2Z3",
    "at": "2026-06-10T22:12:00.000Z",
    "source": "moneris_mgr",
    "externalSaleId": "MGR-000123",
    "method": "Card",
    "tender": "card",
    "collectedCents": 3712,
    "saleTotalCents": 3712,
    "tipCents": 500,
    "products": []
  }
}

// The same externalSaleId posted again: the same answer with "replayed": true,
// and nothing written. A refusal is { ok: false, error, reason, ... }.

POST /appointments/{id}/deposit-request

Needs the bookings:write scope.

POST /api/v1/{slug}/appointments/{id}/deposit-request

Send the deposit pay link again

For a booking the business made (by phone or walk-in, or POST /appointments with requestDeposit) that is waiting on the deposit it asked the client for: send the client the pay link again. The Stripe Checkout before is closed first, so a client holding two links can never pay twice, and the new link is open for a day. Paying is marked by Stripe's webhook, exactly as an online deposit, and the deposit then comes off the bill at checkout. One audit row names the key. Requires an API key with bookings:write.

curl -X POST https://bookatu.com/api/v1/your-salon/appointments/apt_abc123/deposit-request \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "ok": true,
  "appointmentId": "apt_abc123",
  "sent": true,
  "amountCents": 2000,
  "emailedTo": "jane@example.com",
  "texted": false,
  "expiresAt": "2026-06-02T03:12:00.000Z"
}

POST /appointments/{id}/deposit-request/cancel

Needs the bookings:write scope.

POST /api/v1/{slug}/appointments/{id}/deposit-request/cancel

Stop asking for the deposit

The client will pay in person after all: the pay link stops working and the booking no longer waits on a deposit, so it can be edited and checked out. Refused once the client has paid it. The booking itself is never cancelled. One audit row names the key. Requires an API key with bookings:write.

curl -X POST https://bookatu.com/api/v1/your-salon/appointments/apt_abc123/deposit-request/cancel \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{ "ok": true, "appointmentId": "apt_abc123" }

GET /booking-requests

Needs the bookings:read scope.

GET /api/v1/{slug}/booking-requests

List booking requests waiting for an answer

At a business that approves online bookings before they are confirmed: the requests that can be answered now, oldest first. kind booking is a client's new booking, pending and holding its time; kind move is a client's move of a confirmed booking, which keeps its own time until the move is accepted (requestedStartAt, requestedStaffName). deadline is when it is declined for the business if nobody answers. A request whose deposit is still being paid is not listed until it is. A visit of several services is one request, under its first service. The client comes by id; customer (their name, email and phone) only for a key that also has customers:read. A request for a service that needs two or more kinds of resource at once also has resources: every room, chair or machine it holds, { id, name, kind }, its own room first, as on GET /appointments. Requires an API key with bookings:read.

curl https://bookatu.com/api/v1/your-salon/booking-requests \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "requests": [
    {
      "id": "apt_abc123",
      "ref": "VRD-7QK2M9",
      "kind": "booking",
      "customerId": "cus_xyz",
      "serviceName": "Gel Manicure",
      "staffId": "stf_abc",
      "staffName": "Anna",
      "startAt": "2026-06-10T21:00:00.000Z",
      "durationMin": 60,
      "requestedStartAt": null,
      "requestedStaffName": null,
      "requestedAt": "2026-06-08T02:00:00.000Z",
      "deadline": "2026-06-10T02:00:00.000Z",
      "depositPaidCents": 0,
      "priceCents": 7500,
      "notes": null
    }
  ]
}

POST /booking-requests/{id}/accept

Needs the bookings:write scope.

POST /api/v1/{slug}/booking-requests/{id}/accept

Accept a booking request

The booking is confirmed, with everything a confirmed booking gets (the client's confirmation, the calendar entry), or the client's move is carried out after its time is checked again, exactly as Accept on the Requests list. A request is answered once: a second answer, from anyone, is 409. One audit row names the key. Requires an API key with bookings:write.

curl -X POST https://bookatu.com/api/v1/your-salon/booking-requests/apt_abc123/accept \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{ "ok": true, "id": "apt_abc123", "kind": "booking", "status": "confirmed" }

POST /booking-requests/{id}/decline

Needs the bookings:write scope.

POST /api/v1/{slug}/booking-requests/{id}/decline

Decline a booking request

A booking is cancelled as the business (any deposit refunded, the time freed for the waitlist); a move is dropped and the booking keeps its time. Either way the client is emailed, with the note when one is given. Answered once. One audit row names the key. Requires an API key with bookings:write.

curl -X POST https://bookatu.com/api/v1/your-salon/booking-requests/apt_abc123/decline \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "We are closed that day, sorry." }'

{ "ok": true, "id": "apt_abc123", "kind": "booking", "status": "cancelled" }

GET /class-sessions

Needs the bookings:read scope.

GET /api/v1/{slug}/class-sessions

List class sessions

The business's class sessions, soonest first, with how full each is. By default the scheduled sessions still to start, up to 100. A business that does not run classes lists none. At a business with two or more branches, each session also has locationId: the branch it is held at (its own, else its class's, else the main branch); its start and end are on that branch's clock. Requires an API key with bookings:read.

curl "https://bookatu.com/api/v1/your-salon/class-sessions?from=2026-06-01&to=2026-07-01" \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "sessions": [
    {
      "id": "cls_abc123",
      "serviceId": "svc_yoga",
      "className": "Sunrise yoga",
      "staffId": "stf_abc",
      "resourceId": null,
      "startAt": "2026-06-10T18:00:00.000Z",
      "endAt": "2026-06-10T19:00:00.000Z",
      "capacity": 12,
      "enrolledCount": 9,
      "spotsLeft": 3,
      "priceCents": 2000,
      "status": "scheduled",
      "seriesId": null
    }
  ]
}

GET /class-sessions/{id}/roster

Needs the bookings:read scope.

GET /api/v1/{slug}/class-sessions/{id}/roster

Who holds a place on a class session

The session, and everyone holding a live place on it, in sign-up order: each place's enrolmentId, the client's id, its status (booked, attended, no_show) and how it was paid (payment: paid_online, checkout_open, pay_at_door, free, refunded or forfeited). A cancelled place is off the roster. The client comes by id; customer (name, email, phone) only for a key that also has customers:read. At a business with two or more branches, the session also has locationId, as GET /class-sessions lists it. Requires an API key with bookings:read.

curl https://bookatu.com/api/v1/your-salon/class-sessions/cls_abc123/roster \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "session": {
      "id": "cls_abc123",
      "serviceId": "svc_yoga",
      "className": "Sunrise yoga",
      "staffId": "stf_abc",
      "resourceId": null,
      "startAt": "2026-06-10T18:00:00.000Z",
      "endAt": "2026-06-10T19:00:00.000Z",
      "capacity": 12,
      "enrolledCount": 9,
      "spotsLeft": 3,
      "priceCents": 2000,
      "status": "scheduled",
      "seriesId": null
    },
  "roster": [
    {
      "enrolmentId": "enr_abc123",
      "customerId": "cus_xyz",
      "status": "booked",
      "payment": "paid_online",
      "depositStatus": "paid",
      "depositPaidCents": 2000,
      "priceCents": 2000,
      "source": "online",
      "createdAt": "2026-06-01T03:12:00.000Z"
    }
  ]
}

POST /class-sessions/{id}/roster

Needs the bookings:write scope.

POST /api/v1/{slug}/class-sessions/{id}/roster

Put a phone or walk-in client on a class session

Through the roster's own code, as Add on the session page: the client already on file is matched by email (then phone), or added; they are never opted in to marketing through the API (record their choice on their profile); nothing is taken, so the place is paid at the door; their ticket is emailed when they have an email and the session is still to come. A full session stays full: 409 with the spots left, and nothing is written. One audit row names the key. Requires an API key with bookings:write.

curl -X POST https://bookatu.com/api/v1/your-salon/class-sessions/cls_abc123/roster \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Pat Visitor", "email": "pat@example.com", "source": "phone" }'

{
  "ok": true,
  "sessionId": "cls_abc123",
  "enrolmentId": "enr_def456",
  "customerId": "cus_pat",
  "name": "Pat Visitor",
  "matched": false,
  "emailed": true
}

// matched is true when an existing client was found by email or phone (their
// name on file is kept); emailed says whether their ticket went out.

POST /class-sessions/{id}/roster/{enrolmentId}/cancel

Needs the bookings:write scope.

POST /api/v1/{slug}/class-sessions/{id}/roster/{enrolmentId}/cancel

Cancel one person's place on a class session

Their spot is freed, what they paid comes back as account credit (creditedCents), and they are emailed, exactly as Remove on the roster and as cancelling the whole session does for each person. A place marked attended or a no-show is refused until the mark is undone. One audit row names the key. Requires an API key with bookings:write.

curl -X POST https://bookatu.com/api/v1/your-salon/class-sessions/cls_abc123/roster/enr_abc123/cancel \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{ "ok": true, "sessionId": "cls_abc123", "enrolmentId": "enr_abc123", "creditedCents": 2000 }

POST /class-sessions/{id}/roster/{enrolmentId}/attendance

Needs the bookings:write scope.

POST /api/v1/{slug}/class-sessions/{id}/roster/{enrolmentId}/attendance

Mark who came to a class session

attended is the very state the ticket scan at the door sets; no_show records that they did not come; booked undoes a mark. The headcount, what they paid and their client record are untouched. The same mark again changes nothing (changed: false). A change is one audit row naming the key. Requires an API key with bookings:write.

curl -X POST https://bookatu.com/api/v1/your-salon/class-sessions/cls_abc123/roster/enr_abc123/attendance \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mark": "attended" }'

{ "ok": true, "sessionId": "cls_abc123", "enrolmentId": "enr_abc123", "status": "attended", "changed": true }

GET /reports/earnings

Needs the reports:read scope.

GET /api/v1/{slug}/reports/earnings

Staff earnings and commission

What Reports > Staff earnings shows, as JSON: each person's completed visits and the products they sold, their commission under the business's rules on the day of each (tiered rules counted from the start of the pay period), refunds and voids taking commission back, and tips; in total, by period and line by line (up to 500 lines; linesTruncated says when there are more, and the totals always cover them all). Booth renters earn no commission and are listed apart (boothRenter), with employeeTotals and renterTotals beside the totals. Clients are never named. Reads only. Requires an API key with reports:read (the scope needs See analytics & earnings).

curl "https://bookatu.com/api/v1/your-salon/reports/earnings?range=last_month&by=week" \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "query": { "range": "last_month", "from": "2026-05-01", "to": "2026-05-31", "groupBy": "week", "staffId": null, "label": "Last month" },
  "currency": "CAD",
  "totals": { "visits": 41, "serviceSalesCents": 312000, "serviceCommissionCents": 124800, "productUnits": 9, "productSalesCents": 27000, "productCommissionCents": 2700, "refundsSalesCents": -4000, "refundsCommissionCents": -1600, "commissionCents": 125900, "tipsCents": 18500 },
  "hasBoothRenters": false,
  "employeeTotals": { ... },
  "renterTotals": { ... },
  "hasRules": true,
  "people": [{ "staffId": "stf_abc", "name": "Anna", "boothRenter": false, "visits": 23, "commissionCents": 70100, ... }],
  "periods": [{ "key": "2026-04-27", "label": "27 Apr", "from": "2026-04-27", "to": "2026-05-03", "totals": { ... }, "people": [ ... ] }],
  "lines": [{ "id": "visit:apt_abc123", "source": "visit", "at": "2026-05-02T21:00:00.000Z", "staffId": "stf_abc", "appliesTo": "service", "label": "Cut + Head massage", "ref": "VRD-7QK2M9", "receipt": "X1Y2Z3", "appointmentId": "apt_abc123", "saleId": "sale_x1y2z3", "category": "Hair", "units": 1, "salesCents": 5100, "commissionCents": 2040, "tipCents": 0, "ruleId": "crl_abc", "boothRenter": false }],
  "linesTruncated": false
}

GET /reports/tips

Needs the reports:read scope.

GET /api/v1/{slug}/reports/tips

Tips

What Reports > Tips shows, as JSON: the tips taken at checkout by person and by period, each row of the record (who got what, by which rule, and any adjustment and its reason), and each tipped sale with how it is split now. config says whether the business takes tips and its rule. Up to 500 entries and sales (entriesTruncated). Reads only. Requires an API key with reports:read.

curl "https://bookatu.com/api/v1/your-salon/reports/tips?range=this_month" \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "query": { "range": "this_month", "from": "2026-06-01", "to": "2026-06-30", "groupBy": "week", "staffId": null, "label": "This month" },
  "currency": "CAD",
  "config": { "enabled": true, "rule": "service_share", "presets": [1000, 1500, 2000] },
  "totalCents": 18500,
  "people": [{ "staffId": "stf_abc", "name": "Anna", "tipsCents": 11000 }],
  "periods": [{ "key": "2026-06-01", "label": "1 Jun", "from": "2026-06-01", "to": "2026-06-07", "totalCents": 6000, "people": [ ... ] }],
  "entries": [{ "id": "tal_abc", "saleId": "sale_x1y2z3", "receipt": "X1Y2Z3", "staffId": "stf_abc", "name": "Anna", "amountCents": 500, "rule": "service_share", "adjustmentId": null, "reason": null, "at": "2026-06-02T22:12:00.000Z", "method": "Card", "bookingRef": "VRD-7QK2M9", "appointmentId": "apt_abc123" }],
  "entriesTruncated": false,
  "sales": [{ "saleId": "sale_x1y2z3", "receipt": "X1Y2Z3", "at": "2026-06-02T22:12:00.000Z", "method": "Card", "tipCents": 500, "appointmentId": "apt_abc123", "bookingRef": "VRD-7QK2M9", "current": [{ "staffId": "stf_abc", "name": "Anna", "amountCents": 500 }], "rule": "service_share", "adjusted": false }]
}

GET /reports/deposits

Needs the reports:read scope.

GET /api/v1/{slug}/reports/deposits

Deposit reconciliation

What Reports > Deposits shows, as JSON: each deposit taken (online when the client booked, by a pay link the business sent, or from account credit) and what became of it: taken off the bill at checkout (applied), kept for a no-show or late cancellation (kept), refunded to the card or as credit, still held for a visit to come (held), or still held on a booking that is over (unresolved, worth a look); with Stripe's own record beside each (stripeCheck) and in total. Every total balances because every row does. Up to 500 rows (rowsTruncated). The client is not named. Reads only. Requires an API key with reports:read.

curl "https://bookatu.com/api/v1/your-salon/reports/deposits?range=month&basis=taken" \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "query": { "range": "month", "basis": "taken", "groupBy": "month", "from": "2026-06-01", "to": "2026-06-30", "label": "This month" },
  "currency": "CAD",
  "totals": { "bookings": 12, "takenCents": 24000, "takenOnlineCents": 20000, "takenPayLinkCents": 2000, "takenCreditCents": 2000, "appliedCents": 16000, "keptCents": 2000, "refundedCents": 2000, "heldCents": 4000, "unresolvedCents": 0, "refundUnconfirmedCents": 0 },
  "periods": [{ "key": "2026-06", "label": "Jun 2026", "fromKey": "2026-06-01", "toKey": "2026-06-30", "bookings": 12, ... }],
  "rows": [{ "appointmentId": "apt_abc123", "ref": "VRD-7QK2M9", "serviceName": "Cut", "staffName": "Anna", "visitAt": "2026-06-10T21:00:00.000Z", "status": "completed", "depositStatus": "paid", "method": "online", "takenCents": 2000, "takenAt": "2026-06-01T03:12:00.000Z", "bookedCents": 2000, "stripeCents": 2000, "stripeRefundCents": 0, "stripeCheck": "matches", "appliedCents": 2000, "appliedAt": "2026-06-10T22:12:00.000Z", "receipt": "X1Y2Z3", "keptCents": 0, "keptReason": null, "keptAt": null, "refundedCents": 0, "refundedAt": null, "refundedTo": null, "refundUnconfirmedCents": 0, "heldCents": 0, "unresolvedCents": 0, "notes": [] }],
  "rowsTruncated": false,
  "stripe": { "bookedCardCents": 22000, "stripeCardCents": 22000, "stripeRefundCents": 2000, "checks": { "matches": 11, "not_card": 1, "missing": 0, "unrecorded": 0, "more": 0, "less": 0 }, "byDate": { ... } }
}

GET /audit-log

Needs the audit:read scope, on a key made with it ticked.

GET /api/v1/{slug}/audit-log

The audit log

Who did what in the business, and when, newest first, as the Audit log page shows it: bookings, clients, money, loyalty and gift cards, classes, sign-ins, team access, keys, webhooks, settings and downloads. Each row names who acted (a team member with their email and role, an API key, a connected app, a client online, or Bookatu itself), what was done to which record, a summary, what changed (notes, secrets and bank details by name only), and where it came from for a team member, key or app. The client a row is about is named by id (clientId). Filters and pages as the page takes them. Reading it writes nothing. Requires an API key made with the audit:read scope ticked, by someone the business lets manage it (owners and admins on the standard grid); it stops working if they lose that right or leave.

curl "https://bookatu.com/api/v1/your-salon/audit-log?action=booking.*&from=2026-06-01" \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "events": [
    {
      "id": "aud_abc123",
      "at": "2026-06-02T09:30:00.000Z",
      "action": "booking.cancelled",
      "actionLabel": "Booking cancelled",
      "actor": { "type": "user", "id": "usr_abc", "name": "Alex Owner", "email": "alex@example.com", "role": "owner", "roleLabel": "Owner" },
      "target": { "type": "booking", "id": "apt_abc123" },
      "clientId": "cus_xyz",
      "summary": "VRD-7QK2M9 cancelled (Gel Manicure, Wed 10 Jun 2026, 9:00 am)",
      "changes": [{ "field": "status", "to": "cancelled" }],
      "ip": "203.0.113.7",
      "userAgent": "Mozilla/5.0 ..."
    }
  ],
  "page": 1,
  "pageSize": 50,
  "hasMore": false,
  "filters": { "action": "booking.*", "from": "2026-06-01" }
}

POST /customers/{id}/tags

Needs the customers:write scope, on a key made with it ticked.

POST /api/v1/{slug}/customers/{id}/tags

Tag a client

Put one of the business's tags on a client, by the tag's id or its name. Changes nothing else about the client. Org-scoped: a client or a tag of another business is 404 and nothing is written. Answers the client's tags as they now stand. Needs the opt-in customers:write scope: only a key made with "Tag clients" ticked carries it, never a key made before scopes or a connected app. A read-only key is refused.

curl -X POST https://bookatu.com/api/v1/your-salon/customers/cus_xyz/tags \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "VIP" }'

{
  "ok": true,
  "id": "cus_xyz",
  "changed": true,
  "tags": [{ "id": "tag_vip123", "name": "VIP", "color": "indigo" }]
}

// changed is false when nothing needed doing (the tag was already on, or already off).

DELETE /customers/{id}/tags/{tagId}

Needs the customers:write scope, on a key made with it ticked.

DELETE /api/v1/{slug}/customers/{id}/tags/{tagId}

Untag a client

Take a tag off a client. Already off answers changed: false. Org-scoped like the POST. Needs the opt-in customers:write scope, on a key made with it ticked.

curl -X DELETE https://bookatu.com/api/v1/your-salon/customers/cus_xyz/tags/tag_vip123 \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "ok": true,
  "id": "cus_xyz",
  "changed": true,
  "tags": []
}

// changed is false when nothing needed doing (the tag was already on, or already off).

POST /appointments/{id}/tags

Needs the bookings:write scope.

POST /api/v1/{slug}/appointments/{id}/tags

Tag a booking

Put one of the business's tags on a booking, by the tag's id or its name. Changes nothing else about the booking and sends no email or webhook. Org-scoped: a booking or a tag of another business is 404 and nothing is written. Answers the booking's tags as they now stand. Needs bookings:write; a read-only key is refused.

curl -X POST https://bookatu.com/api/v1/your-salon/appointments/apt_abc123/tags \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tagId": "tag_bridal456" }'

{
  "ok": true,
  "id": "apt_abc123",
  "changed": true,
  "tags": [{ "id": "tag_bridal456", "name": "Bridal", "color": "rose" }]
}

// changed is false when nothing needed doing (the tag was already on, or already off).

DELETE /appointments/{id}/tags/{tagId}

Needs the bookings:write scope.

DELETE /api/v1/{slug}/appointments/{id}/tags/{tagId}

Untag a booking

Take a tag off a booking. Already off answers changed: false. Org-scoped like the POST. Needs bookings:write.

curl -X DELETE https://bookatu.com/api/v1/your-salon/appointments/apt_abc123/tags/tag_bridal456 \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "ok": true,
  "id": "apt_abc123",
  "changed": true,
  "tags": []
}

// changed is false when nothing needed doing (the tag was already on, or already off).

GET /sandbox/outbox

Needs the customers:read scope.

GET /api/v1/{slug}/sandbox/outbox

The test outbox (sandbox only)

Test mode: what a sandbox business would have sent, newest first. Every email, text, WhatsApp message (and voice or push message) a sandbox sends, to clients or to its own team, is kept here and never sent: booking confirmations, reminders, receipts, staff alerts, inbox replies, scheduled reports. The newest 500 are kept. Filter by channel and by time, and page with limit and nextCursor. The answer says livemode false. Only for a sandbox (a live business answers 404 NOT_A_SANDBOX), with the sandbox's TEST key (bk_test_): a live key is refused with 403 LIVEMODE_MISMATCH. Requires an API key with customers:read (the messages carry client addresses). 30 calls a minute per sandbox, all its test keys together. Over MCP, the sandbox_outbox tool reads the same, within the same limits.

curl "https://bookatu.com/api/v1/your-test-salon/sandbox/outbox?channel=email&limit=20" \
  -H "Authorization: Bearer bk_test_YOUR_KEY"

{
  "messages": [
    {
      "id": "sbo_8xKq2...",
      "channel": "email",
      "kind": "booking_confirmation",
      "to": "pat.example@example.com",
      "subject": "You're booked in at Test Salon",
      "text": null,
      "html": "<!doctype html>...",
      "appointmentId": "apt_abc123",
      "customerId": "cus_xyz",
      "createdAt": "2026-10-30T09:15:00.000Z",
      "meta": { "dedupeKey": "booking_confirmation:apt_abc123" }
    },
    {
      "id": "sbo_3Lm9...",
      "channel": "sms",
      "kind": "reminder_24h",
      "to": "+15555550123",
      "subject": null,
      "text": "Test Salon: reminder of your Cut tomorrow at 10:00 am.",
      "html": null,
      "appointmentId": "apt_abc123",
      "customerId": "cus_xyz",
      "createdAt": "2026-10-30T09:14:00.000Z",
      "meta": {}
    }
  ],
  "nextCursor": "MjAyNi0xMC0zMFQwOToxNDowMC4wMDBafHNib18zTG05",
  "livemode": false
}

POST /sandbox/simulate/{event}

Needs the bookings:write scope.

POST /api/v1/{slug}/sandbox/simulate/{event}

Simulate an event (sandbox only)

Test mode: make something happen to one of a sandbox's bookings, through the same code a real payment, cancellation or clock would run. {event} is one of: deposit.paid, payment.failed, checkout.expired, booking.client_cancelled, booking.no_show, reminders.due. deposit.paid: Pays the booking's open test checkout, as the test checkout page's "Pay (test)" does: checkout.session.completed runs through the Stripe webhook's own handler, the booking is confirmed with its deposit paid, the confirmation goes to the outbox and booking webhooks are sent. payment.failed: Declines the test card on the booking's open checkout, as "Decline (test)": the checkout stays open (as on Stripe's page) and nothing else changes; the answer says so (result.declined true, result.changed false). checkout.expired: Abandons the booking's open checkout, as "Abandon": checkout.session.expired runs, and an online booking held for its deposit is let go (cancelled as deposit_abandoned) and its time offered to the waitlist. booking.client_cancelled: The client's own cancellation (the manage page's), with the business's cancellation window, deposit rule, late-cancellation fee, emails and the booking.cancelled webhook. booking.no_show: Marks the booking a no-show. A no-show fee the cancellation policy sets is queued for the owner, as at a live business (result.fee): nothing charges it but the owner's Charge on the test business's No-show fees screen, which charges the client's saved TEST card: paid for a card saved with "Save test card", declined (card_declined) for one saved with "Save a card that will decline". reminders.due: Time passing: the booking's reminder email and reminder texts are sent as if now were its start minus each lead the business set (reminderHoursBefore, and its own text times). A booking reminded already is not reminded again. The answer gives the booking as it is now, the ids of the outbox messages the event kept (outbox), the webhook events it sent (webhooks) and what the event itself reported (result). Messages sent after the answer (a webhook retry, an email the system sends a moment later) still appear in GET /sandbox/outbox. Only for a sandbox (a live business answers 404 NOT_A_SANDBOX) and only for a booking of that sandbox (any other id is 404 APPOINTMENT_NOT_FOUND), with its TEST key (bk_test_): a live key is refused with 403 LIVEMODE_MISMATCH. Requires an API key with bookings:write. 10 calls a minute and 500 a day per sandbox, all its test keys together. Over MCP, the sandbox_simulate tool takes the same events, within the same limits.

curl -X POST "https://bookatu.com/api/v1/your-test-salon/sandbox/simulate/deposit.paid" \
  -H "Authorization: Bearer bk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "appointmentId": "apt_abc123" }'

{
  "ok": true,
  "event": "deposit.paid",
  "appointment": {
    "id": "apt_abc123",
    "status": "confirmed",
    "depositStatus": "paid",
    "depositCents": 2000,
    "depositPaidCents": 2000,
    "startAt": "2026-11-04T21:00:00.000Z",
    "endAt": "2026-11-04T21:30:00.000Z",
    "customerId": "cus_xyz",
    "checkoutSessionId": "cs_test_sbx_9Fh2..."
  },
  "outbox": ["sbo_8xKq2...", "sbo_Qw71..."],
  "webhooks": ["booking.confirmed"],
  "result": { "checkoutSessionId": "cs_test_sbx_9Fh2..." },
  "livemode": false
}

GET /sandbox/payments

Needs the reports:read scope.

GET /api/v1/{slug}/sandbox/payments

The test payments (sandbox only)

Test mode: every payment a sandbox business made in test mode, newest first, as its admin's Test payments page lists them. No card was charged and no money moved: the payment simulator made each one, through the same code a real payment runs. kind is one of: checkout, a test checkout (a deposit, a class place, the shop, a gift card, a package, a print, gallery extras or an invoice): paid, declined (the test card was declined and it is still open), abandoned (it expired) or open; payment, the payment a paid checkout made: paid, refunded or partly_refunded; card_hold, a card saved for later at the card step: card_saved, or open while it waits for the card; no_show_charge, a no-show or late-cancellation fee charged to a saved test card: paid, declined, refunded or partly_refunded; refund, a refund of a test payment: refunded. Each has its outcome, amountCents (whole cents of its currency; null for a card hold, which takes no money), refundedCents, currency, description (the checkout's own line items), the booking it belongs to (appointmentId) and the booking or sale it belongs to (belongsTo: booking, class_place, order, gift_card, package, invoice or gallery_photos, with its id when there is one), the checkout and payment it came through, and when it was made. Nothing in it names a client: no name, email or phone. Filter by kind and by time, and page with limit and nextCursor. The answer says livemode false. Only for a sandbox (a live business answers 404 NOT_A_SANDBOX), with the sandbox's TEST key (bk_test_): a live key is refused with 403 LIVEMODE_MISMATCH. Requires an API key with reports:read (the payments are the business's money, as the money reports are). 30 calls a minute per sandbox, all its test keys together. Over MCP, the sandbox_payments tool reads the same, within the same limits.

curl "https://bookatu.com/api/v1/your-test-salon/sandbox/payments?kind=checkout&limit=20" \
  -H "Authorization: Bearer bk_test_YOUR_KEY"

{
  "payments": [
    {
      "id": "cs_test_sbx_9Fh2...",
      "kind": "checkout",
      "outcome": "paid",
      "amountCents": 2000,
      "refundedCents": 0,
      "currency": "NZD",
      "description": "Deposit · Cut",
      "appointmentId": "apt_abc123",
      "belongsTo": { "type": "booking", "id": "apt_abc123" },
      "checkoutSessionId": "cs_test_sbx_9Fh2...",
      "paymentIntentId": "pi_test_sbx_4Kd8...",
      "createdAt": "2026-10-30T09:15:00.000Z",
      "updatedAt": "2026-10-30T09:16:10.000Z"
    },
    {
      "id": "re_test_sbx_7Qp1...",
      "kind": "refund",
      "outcome": "refunded",
      "amountCents": 2000,
      "refundedCents": 0,
      "currency": "NZD",
      "description": "Refund: Deposit · Colour",
      "appointmentId": "apt_def456",
      "belongsTo": { "type": "booking", "id": "apt_def456" },
      "checkoutSessionId": "cs_test_sbx_2Lm7...",
      "paymentIntentId": "pi_test_sbx_8Hs3...",
      "createdAt": "2026-10-30T09:12:00.000Z",
      "updatedAt": "2026-10-30T09:12:00.000Z"
    }
  ],
  "nextCursor": "MjAyNi0xMC0zMFQwOToxMjowMC4wMDBafHJlX3Rlc3Rfc2J4Xzd",
  "livemode": false
}

GET /walk-in

GET /api/v1/{slug}/walk-in

Walk-in wait now

The business's live walk-in wait: the answer its booking page, its walk-in widget and the MCP tool get_walk_in_wait give for the same moment. Worked out from its calendar for today, on its own clock, as a walk-in is served: the team's in-person bookings count and the minimum notice does not apply (online booking keeps it, so the booking page may offer a later first time). Or set by hand by the team (mode manual, with manual.setAt and manual.expiresAt) until it lapses. state is no_wait (the earliest start is within 5 minutes: walk in now), wait (5 to 90 minutes away; waitMin is rounded up to 5), busy (more than 90 minutes away; nextAt says when), full_today (open now, nothing fits before closing), closed (closed now; closed.opensAt says when it opens, null when no opening is in the next 14 days) or not_taking (set by hand). waitMin and nextAt beside state are the shortest wait. busy gives counts only (staffBusy of staffWorking with a client, appointmentsLeftToday) when the business shows them; no client or team member is ever named. services lists up to 12 walk-in services in menu order, each with its own state, waitMin, nextAt and bookUrl (its booking page on today's date; null for a service not booked online). Every time is an instant in UTC; timeZone is the business's clock. A business with walk-in wait times off answers 200 with status off and no numbers. Kept about a minute.

curl https://bookatu.com/api/v1/your-salon/walk-in

{
  "status": "on",
  "mode": "automatic",
  "state": "wait",
  "waitMin": 20,
  "nextAt": "2026-11-03T01:20:00.000Z",
  "updatedAt": "2026-11-03T01:02:00.000Z",
  "timeZone": "Pacific/Auckland",
  "busy": { "staffBusy": 3, "staffWorking": 4, "appointmentsLeftToday": 6 },
  "services": [
    { "id": "svc_cut", "name": "Cut", "state": "wait", "waitMin": 20, "nextAt": "2026-11-03T01:20:00.000Z", "bookUrl": "https://bookatu.com/your-salon/book?service=svc_cut&date=2026-11-03" },
    { "id": "svc_beard", "name": "Beard trim", "state": "busy", "nextAt": "2026-11-03T03:30:00.000Z", "bookUrl": "https://bookatu.com/your-salon/book?service=svc_beard&date=2026-11-03" }
  ],
  "livemode": true
}

// Turned off: { "status": "off", "livemode": true }

PUT /walk-in/manual

Needs the bookings:write scope.

PUT /api/v1/{slug}/walk-in/manual

Set the walk-in wait by hand

Set the walk-in wait by hand, as the team does from the dashboard: minutes (0 to 240; 0 is no wait) or notTaking true, for the whole business (or one branch while branches are on), until it lapses: expiry 1h, 2h or end_of_day (midnight at the end of the business's day), the business's own default when left out. Replaces the wait set before. Within about a minute GET /walk-in, the booking page and MCP give mode manual with manual.setAt and manual.expiresAt (the walk-in widget at its next refresh, within about two), and the booking page says when the team updated it; once it lapses the wait is worked out from the calendar again. Answers the walk-in answer as it now stands. Recorded in the audit log, naming the key. Refused with 409 WALK_IN_OFF while the business has walk-in wait times off. Needs bookings:write; a read-only key is refused.

curl -X PUT https://bookatu.com/api/v1/your-salon/walk-in/manual \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "minutes": 30, "expiry": "2h" }'

{
  "status": "on",
  "mode": "manual",
  "state": "wait",
  "waitMin": 30,
  "updatedAt": "2026-11-03T01:02:00.000Z",
  "timeZone": "Pacific/Auckland",
  "manual": { "setAt": "2026-11-03T01:02:00.000Z", "expiresAt": "2026-11-03T03:02:00.000Z" },
  "busy": { "staffBusy": 3, "staffWorking": 4, "appointmentsLeftToday": 6 },
  "services": [
    { "id": "svc_cut", "name": "Cut", "state": "wait", "waitMin": 30, "bookUrl": "https://bookatu.com/your-salon/book?service=svc_cut&date=2026-11-03" }
  ],
  "livemode": true
}

DELETE /walk-in/manual

Needs the bookings:write scope.

DELETE /api/v1/{slug}/walk-in/manual

Back to the automatic walk-in wait

Take off the wait set by hand, for the whole business (or one branch while branches are on), so the wait is worked out from the calendar again at once. Answers the walk-in answer as it now stands, with cleared true when a wait set by hand was in force and false when there was none. Recorded in the audit log, naming the key, when one was cleared. Works while walk-in wait times are off too (the answer is then status off). Needs bookings:write; a read-only key is refused.

curl -X DELETE https://bookatu.com/api/v1/your-salon/walk-in/manual \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "cleared": true,
  "status": "on",
  "mode": "automatic",
  "state": "no_wait",
  "waitMin": 0,
  "nextAt": "2026-11-03T01:05:00.000Z",
  "updatedAt": "2026-11-03T01:05:00.000Z",
  "timeZone": "Pacific/Auckland",
  "services": [
    { "id": "svc_cut", "name": "Cut", "state": "no_wait", "waitMin": 0, "nextAt": "2026-11-03T01:05:00.000Z", "bookUrl": "https://bookatu.com/your-salon/book?service=svc_cut&date=2026-11-03" }
  ],
  "livemode": true
}

// cleared is false when no wait set by hand was in force.

GET /visits/availability

GET /api/v1/{slug}/visits/availability

Open starts for a visit of several services

The starts a visit of several services fits (a colour, then a cut) across a date window: the booking page's own question, answered by the same code. The services run back to back: the first on the business's booking grid, each next one the moment the one before ends, each checked as a booking of it on its own would be (someone who does it and is free, its room, the hours and breaks, the business's buffer). Each slot lists every service with who does it and when; the same person carries on from one service to the next where they can. Only at a business that lets clients book several services in one visit (GET /business has visits); anywhere else it is a 409 with code not_offered. Book a returned startAt with POST /visits/book and the same serviceIds, staffId and addOnIds: a time offered here is a time it takes. Each time also comes as when: { utc, primary, business: { timeZone, local, utcOffset, abbr, display }, client } with the offset in force on that day (a slot after the clocks change carries the new one), on the business's clock (the branch's at a branch) and, when the client's zone is known, on theirs (client is null otherwise; dayDiffers says their date is another day). Quote display rather than converting a time yourself. A slot a surcharge covers (a public holiday or a busy time the business charges more for) also has priceCents, surcharges (label, amountType, amount, amountCents) and totalCents, the price at that time, to show the client before they book; other slots have none of these. No authentication required.

curl "https://bookatu.com/api/v1/your-salon/visits/availability?serviceIds=svc_colour,svc_cut&from=2026-06-10&to=2026-06-12"

{
  "org": { "name": "Parnell Hair", "slug": "parnell-hair", "timezone": "Pacific/Auckland" },
  "days": [
    {
      "date": "2026-06-10",
      "open": true,
      "slots": [
        {
          "startMin": 540,
          "startAt": "2026-06-09T21:00:00.000Z",
          "services": [
            { "serviceId": "svc_colour", "staffId": "stf_anna", "startAt": "2026-06-09T21:00:00.000Z", "endAt": "2026-06-09T22:30:00.000Z", "durationMin": 90 },
            { "serviceId": "svc_cut", "staffId": "stf_anna", "startAt": "2026-06-09T22:30:00.000Z", "endAt": "2026-06-09T23:00:00.000Z", "durationMin": 30 }
          ]
        }
      ]
    }
  ]
}

// startMin is minutes from local midnight; startAt is the visit's start, the
// UTC instant to book. A day shut or past the booking horizon reads exactly as
// it does on GET /availability.

POST /visits/book

POST /api/v1/{slug}/visits/book

Book a visit of several services (online source)

The customer-facing call for a visit of several services, exactly as the booking page books one: the whole visit or none of it, in one transaction, each service an appointment of its own with its person, time and price, sharing one visitId. The client gets one confirmation listing every service, one discount shared across the services, and, at a business that approves online bookings, one request (approvalRequested). Only at a business that lets clients book several services in one visit (else 409 not_offered, nothing booked); the services must be ones it offers online, and its combination rules hold. Like POST /book it takes no key, so it holds to the same rules: startAt is read strictly (TIME_NEEDS_OFFSET, TIME_INVALID), or localTime is sent instead (TIME_DOES_NOT_EXIST, TIME_AMBIGUOUS), an email match changes nothing, a marketing yes waits for the client's own confirmation, a visit that takes a deposit is refused with 409 and code DEPOSIT_NEEDS_BOOKING_PAGE with bookingPageUrl (nothing booked), so is one with a service the business requires a card saved to hold (409, code CARD_REQUIRED_USE_BOOKING_PAGE, with bookingPageUrl), booking terms the business has set must be accepted (acceptTerms: true, else 422 TERMS_NOT_ACCEPTED with the terms to show), the business's booking questions are answered once for the whole visit as answers (a required one without an answer is 422 ANSWERS_REQUIRED with missingQuestionIds, an unreadable answer 422 ANSWERS_INVALID), a paused business answers BOOKING_PAUSED, and the same per-address and per-business caps apply. The appointmentId in the answer is the person's private key to their booking: never show it, store it or put it in a chat. A visit booked at a surcharged time (a public holiday or a busy time the business charges more for) also has priceCents (the visit's total, the surcharge included) and surcharge: { label, amountCents }; a visit without one has neither. No authentication required.

curl -X POST https://bookatu.com/api/v1/your-salon/visits/book \
  -H "Content-Type: application/json" \
  -d '{
    "serviceIds": ["svc_colour", "svc_cut"],
    "startAt": "2026-06-09T21:00:00.000Z",
    "name": "Alex Smith",
    "email": "alex@example.com",
    "phone": "+64 21 555 0100"
  }'

{
  "ok": true,
  "visitId": "vis_abc123",
  "ref": "VRD-7QK2M9",
  "appointmentId": "apt_colour",
  "status": "confirmed",
  "needsPayment": false,
  "services": [
    { "appointmentId": "apt_colour", "ref": "VRD-7QK2M9", "serviceId": "svc_colour", "serviceName": "Colour", "staffId": "stf_anna", "staffName": "Anna", "startAt": "2026-06-09T21:00:00.000Z", "endAt": "2026-06-09T22:30:00.000Z", "durationMin": 90, "priceCents": 12000, "status": "confirmed" },
    { "appointmentId": "apt_cut", "ref": "VRD-8RL3N4", "serviceId": "svc_cut", "serviceName": "Cut", "staffId": "stf_anna", "staffName": "Anna", "startAt": "2026-06-09T22:30:00.000Z", "endAt": "2026-06-09T23:00:00.000Z", "durationMin": 30, "priceCents": 3500, "status": "confirmed" }
  ]
}

// At a business that approves online bookings, status is "pending" and
// approvalRequested is true until it answers. appointmentId and ref are the
// visit's first service, which its confirmation and manage link speak through.
// A visit that takes a deposit is refused (409, code DEPOSIT_NEEDS_BOOKING_PAGE,
// with bookingPageUrl) and nothing is booked, as is one the business requires
// a card saved to hold (409, code CARD_REQUIRED_USE_BOOKING_PAGE, with
// bookingPageUrl). At a business with booking terms, a visit without
// acceptTerms: true is a 422 with code TERMS_NOT_ACCEPTED and the terms. At a
// business with booking questions, a visit without a required answer is a 422
// with code ANSWERS_REQUIRED and missingQuestionIds.

POST /visits

Needs the bookings:write scope.

POST /api/v1/{slug}/visits

Book a visit of several services (the team's)

Book a visit of several services with the business's own key, as the team's New booking form does: each service with the person named for it (or whoever is free), back to back from startAt, whatever the business lets clients do online. The whole visit is booked or none of it, with one confirmation to the client; it may start off the booking grid and past the online booking horizon, but every service must fit at its time with its person, its room and its hours, and nobody is ever double-booked. When it does not fit, the 409 says which service (line), when and with whom. The business's combination rules hold, naming the two. A service of the visit that needs two or more kinds of resource at once also has resources: every room, chair or machine it holds, { id, name, kind }, its own room first. Requires an API key with bookings:write.

curl -X POST https://bookatu.com/api/v1/your-salon/visits \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "services": [
      { "serviceId": "svc_colour", "staffId": "stf_anna" },
      { "serviceId": "svc_cut", "staffId": "stf_sam" }
    ],
    "startAt": "2026-06-09T21:00:00.000Z",
    "name": "Alex Smith",
    "email": "alex@example.com",
    "phone": "+64 21 555 0100"
  }'

{
  "ok": true,
  "visitId": "vis_abc123",
  "ref": "VRD-7QK2M9",
  "appointmentId": "apt_colour",
  "status": "confirmed",
  "needsPayment": false,
  "services": [
    { "appointmentId": "apt_colour", "ref": "VRD-7QK2M9", "serviceId": "svc_colour", "serviceName": "Colour", "staffId": "stf_anna", "staffName": "Anna", "startAt": "2026-06-09T21:00:00.000Z", "endAt": "2026-06-09T22:30:00.000Z", "durationMin": 90, "priceCents": 12000, "status": "confirmed" },
    { "appointmentId": "apt_cut", "ref": "VRD-8RL3N4", "serviceId": "svc_cut", "serviceName": "Cut", "staffId": "stf_anna", "staffName": "Anna", "startAt": "2026-06-09T22:30:00.000Z", "endAt": "2026-06-09T23:00:00.000Z", "durationMin": 30, "priceCents": 3500, "status": "confirmed" }
  ]
}

// The same shape as POST /visits/book. A team booking takes no online deposit.

GET /visits/{id}

Needs the bookings:read scope.

GET /api/v1/{slug}/visits/{id}

Get one visit

One visit of several services, scoped to the key's business: its services in order, each with its booking (appointmentId, ref), who does it, when, its price and status, and the visit's start, end, length and price (of the services not cancelled). appointmentId and ref are the service the visit speaks through: its first, or its first still on. A booking's visitId (GET /appointments) names its visit. The client comes by id. A service of the visit that needs two or more kinds of resource at once also has resources: every room, chair or machine it holds, { id, name, kind }, its own room first. A visit booked with a surcharge also has surcharge: { label, amountCents }, part of priceCents. Requires an API key with bookings:read.

curl https://bookatu.com/api/v1/your-salon/visits/vis_abc123 \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "id": "vis_abc123",
  "appointmentId": "apt_colour",
  "ref": "VRD-7QK2M9",
  "status": "confirmed",
  "customerId": "cus_xyz",
  "startAt": "2026-06-09T21:00:00.000Z",
  "endAt": "2026-06-09T23:00:00.000Z",
  "durationMin": 120,
  "priceCents": 15500,
  "services": [
    { "appointmentId": "apt_colour", "ref": "VRD-7QK2M9", "serviceId": "svc_colour", "serviceName": "Colour", "staffId": "stf_anna", "staffName": "Anna", "startAt": "2026-06-09T21:00:00.000Z", "endAt": "2026-06-09T22:30:00.000Z", "durationMin": 90, "priceCents": 12000, "status": "confirmed" },
    { "appointmentId": "apt_cut", "ref": "VRD-8RL3N4", "serviceId": "svc_cut", "serviceName": "Cut", "staffId": "stf_anna", "staffName": "Anna", "startAt": "2026-06-09T22:30:00.000Z", "endAt": "2026-06-09T23:00:00.000Z", "durationMin": 30, "priceCents": 3500, "status": "confirmed" }
  ]
}

POST /visits/{id}/reschedule

Needs the bookings:write scope.

POST /api/v1/{slug}/visits/{id}/reschedule

Move a whole visit

Move a visit of several services so it starts at startAt: every service keeps its person, its length and its place in the order, and is checked again at its new time as the team's own calendar checks it (it may start off the booking grid and past the online horizon, but it must fit with every person, room and the hours). All of them move or none does; nothing is ever double-booked. The client is told once, the reminders follow the new times, each old time is offered to the waitlist, and each service fires booking.rescheduled. The answer is the visit as GET /visits/{id} now reads it, with the resources each service needing two or more kinds now holds, and when, its new start as a When. Requires an API key with bookings:write.

curl -X POST https://bookatu.com/api/v1/your-salon/visits/vis_abc123/reschedule \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "startAt": "2026-06-11T01:00:00.000Z" }'

{
  "ok": true,
  "visit": { "id": "vis_abc123", "startAt": "2026-06-11T01:00:00.000Z", "endAt": "2026-06-11T03:00:00.000Z", "services": [ ... ] }
}

POST /visits/{id}/cancel

Needs the bookings:write scope.

POST /api/v1/{slug}/visits/{id}/cancel

Cancel a whole visit

Cancel every service of a visit still on, as the business. Its first service is cancelled as any booking is (the deposit it holds refunded or kept by the business's notice policy: forfeited says which), the rest go with it, the client is told, each freed time is offered to the waitlist and each service fires booking.cancelled. cancelled is how many services were cancelled. Cancelling a visit already cancelled is idempotent (alreadyCancelled: true). Requires an API key with bookings:write.

curl -X POST https://bookatu.com/api/v1/your-salon/visits/vis_abc123/cancel \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Client rang" }'

{ "ok": true, "visitId": "vis_abc123", "cancelled": 2, "forfeited": false }

// Again: { "ok": true, "visitId": "vis_abc123", "cancelled": 0, "alreadyCancelled": true, "forfeited": false }

Check out from another point of sale (Moneris MGR)

A business that takes payment on another point of sale, such as Moneris MGR, can start checkout from a Bookatu booking and post the sale back, so nobody rings up the visit twice and the booking, the sale, who did the work and the money all line up in Bookatu as if its own point of sale had taken it.

1. Make an API key with the checkout scopes ticked (See what a booking comes to at checkout, and Check bookings out from another point of sale), and See bookings so your point of sale can list the day's bookings with GET /appointments. Add See clients if your point of sale should get the client's name and contact details.
2. When a client comes to pay, start checkout from their booking: read GET /appointments/{id}/checkout and ring up its lines. Each line is the service or an extra at its booked price and discount, with who did it, and dueCents is exactly what to take (tax added on top included, the deposit already taken off).
3. Take the money on your terminal, then POST the sale to the same address with your own sale id as externalSaleId. Bookatu checks the booking out with the same code its own point of sale uses. Retrying with the same externalSaleId is always safe.
4. Subscribe a webhook endpoint to booking.checked_out to hear about every checkout, including the ones taken at Bookatu's own point of sale, so your point of sale never takes the same visit twice.

Visits of several services

A client can book several services in one visit, one straight after another (a colour, then a cut), with the same person or different people. Each service is a booking of its own, sharing a visitId, and the visit is one thing to the client: booked all or nothing, with one confirmation, one deposit and one manage link.

1. Read GET /business: visits is there, with the most services one visit takes, when the business lets clients book several services in one visit. GET /services says which services go together: combinations.onlyWith lists the only other services a service shares a visit with, and combinations.neverWith the ones it is never booked with (a 4 braids and a 6 braids, say).
2. Ask GET /visits/availability with the services in order (serviceIds), and the team member the client picked if they picked one. Each slot lists every service with who does it and when, back to back.
3. Book a slot's startAt with POST /visits/book and the same services. The business's own key books a visit with POST /visits instead, naming each service's person, whatever clients may do online.
4. Read, move and cancel the whole visit with GET /visits/{id}, POST /visits/{id}/reschedule and POST /visits/{id}/cancel; each booking's visitId on GET /appointments names its visit. The client's own /booking/{id} calls move and cancel the whole visit too, from any of its services. Over MCP, the same is get_visit_availability, create_visit, get_visit, reschedule_visit and cancel_visit.

Rooms and equipment

A business sets up its rooms, chairs and machines as resources, each of a kind (Room, Laser). A service can need one kind, which a booking of it holds as its room, or two or more kinds at once: a laser facial needs a treatment room and a laser machine. The booking engine offers a time only when a person and one free resource of each kind are free together, holds each of them for the booking's whole length, and never books one resource twice.

1. Read GET /services: a service that needs two or more kinds lists them as resourceKinds, in order (for example ["Room", "Laser"]); the first is the kind of the booking's own room. A service that needs one kind or none has no resourceKinds. Over MCP, list_services says the same.
2. Ask GET /availability as for any service: every slot it returns has one free resource of each kind, and its resourceIds are the free ones of the first kind. Book a slot's startAt with POST /book, or with POST /appointments and the business's key; resourceId prefers one of those, and the engine gives one free resource of each other kind.
3. Read what a booking holds on GET /appointments and GET /appointments/{id}, or over MCP with list_appointments: resources lists every room, chair or machine it holds, { id, name, kind }, its own room first. POST /appointments answers with it too, and each service of a visit has it on POST /visits, GET /visits/{id} (get_visit) and POST /visits/{id}/reschedule.
4. Moving a booking through the API (POST /booking/{id}/reschedule or MCP reschedule_booking) keeps each of its resources where it is still free and gives another of the same kind where it is not; moving a whole visit (POST /visits/{id}/reschedule) gives each of its services a free one of each kind. A time with none of a kind free is refused and nothing changes. Cancelling frees them all. Webhook payloads are unchanged: read the booking with your key to see what it holds.

Website widget: events, deep links and allowed sites

A business puts booking on its own website with one script, /embed.js (or the pinned /embed.v1.js, which never changes and can be loaded with the integrity hash shown in the admin's Website widget page). The widget runs in an iframe from our origin and tells the page it sits on what happens inside it, without ever handing over the client's name, email, phone, notes, the appointment id or a manage key.

1. Listen for window events named bookatu: followed by the event, or, with Google Tag Manager, dataLayer events named bookatu_ followed by the event, with the details under bookatu. Version 1 has these events: ready, service_selected, staff_selected, time_selected, booked, request_sent, handoff, error, closed. A handoff says why the visitor went to a new tab (deposit, card_required, multi_service, waitlist); an error carries one fixed code (generic, slot, details, phone, paused, velocity, deposit, staff, not_enabled, unavailable).
2. Every event has v (1), event, slug and dedupeId. Where they apply it also has ref (an opaque booking reference that is not the appointment id and opens nothing), service with id and name, staffId, branchId, start (RFC 3339, UTC), timeZone (an IANA name), value (minor units) with currency, and deposit. A booking fires once per dedupeId, even when its confirmation screen reloads.
3. With data-track="gtag" or data-track="meta" on the snippet, the widget also calls the Google tag or the Meta pixel the page has already loaded (a booking is the Meta standard event Schedule). It never loads a tag itself, so the page's own consent banner decides whether any of them run. The names from before version 1, bookatu:booked and bookatu_booking_complete, still fire, once per booking and, as before, for a request too (its event field then says request_sent).
4. Deep links work in every mode: data-service, data-staff, data-branch, data-date (YYYY-MM-DD), data-promo and data-lang. The booking page reads service, staff, branch, date and promo as query parameters too. The page's utm_source, utm_medium, utm_campaign, utm_term and utm_content go onto the booking's lead source, cleaned and shortened; a gclid or fbclid only as the marker +gclid or +fbclid, never the id.
5. When the business sets allowed domains, every widget page sends a Content-Security-Policy frame-ancestors naming exactly those sites and their subdomains, so browsers refuse to frame any step anywhere else, and the widget posts its messages only to the allowed site's origin.

Webhooks

Receive a POST to your own https endpoint when bookings change, an order is paid, a form is submitted or a campaign finishes sending, and, when you ask for it, when a booking is checked out. Add an endpoint in your admin dashboard at /{slug}/admin/api (admins only), or let your agent register one itself with the webhooks_create MCP tool. Payloads carry no customer contact details. Fetch the full record from GET /appointments with your API key when you need more.

{
  "event": "booking.created",
  "sentAt": "2026-06-01T03:12:00.000Z",
  "data": {
    "id": "apt_abc123",
    "ref": "VRD-7QK2M9",
    "service": "Gel Manicure",
    "startAt": "2026-06-10T21:00:00.000Z",
    "durationMin": 60,
    "priceCents": 7500,
    "status": "pending"
  }
}

{
  "event": "booking.cancelled",
  "sentAt": "2026-06-02T09:30:00.000Z",
  "data": {
    "id": "apt_abc123",
    "ref": "VRD-7QK2M9",
    "service": "Gel Manicure",
    "startAt": "2026-06-10T21:00:00.000Z",
    "status": "cancelled"
  }
}

{
  "event": "booking.completed",
  "sentAt": "2026-06-10T23:05:00.000Z",
  "data": {
    "id": "apt_abc123",
    "ref": "VRD-7QK2M9",
    "service": "Gel Manicure",
    "startAt": "2026-06-10T21:00:00.000Z",
    "status": "completed"
  }
}

{
  "event": "booking.rescheduled",
  "sentAt": "2026-06-03T11:00:00.000Z",
  "data": {
    "id": "apt_abc123",
    "ref": "VRD-7QK2M9",
    "service": "Gel Manicure",
    "startAt": "2026-06-12T21:00:00.000Z",
    "status": "confirmed"
  }
}

{
  "event": "order.paid",
  "sentAt": "2026-06-04T02:20:00.000Z",
  "data": {
    "id": "ord_abc123",
    "description": "2 items",
    "amountCents": 5400,
    "currency": "nzd",
    "items": [
      { "productId": "prd_a1", "product": "Repair Shampoo", "quantity": 1 },
      { "productId": "prd_b2", "product": "Leave-in Conditioner", "quantity": 1 }
    ]
  }
}

{
  "event": "form.submitted",
  "sentAt": "2026-06-05T20:41:00.000Z",
  "data": {
    "formId": "frm_abc123",
    "formName": "New client intake",
    "responseId": "frs_def456",
    "customerId": "cus_ghi789",
    "appointmentId": "apt_jkl012"
  }
}

{
  "event": "campaign.sent",
  "sentAt": "2026-06-06T09:00:00.000Z",
  "data": {
    "campaignId": "cmp_abc123",
    "subject": "Winter offers are live",
    "audience": "recent",
    "sent": 182,
    "recipients": 187
  }
}

{
  "event": "booking.checked_out",
  "sentAt": "2026-06-10T22:12:01.000Z",
  "data": {
    "version": 1,
    "appointment": { "id": "apt_abc123", "ref": "VRD-7QK2M9", "status": "completed", "startAt": "2026-06-10T21:00:00.000Z", "endAt": "2026-06-10T22:10:00.000Z", "serviceName": "Cut", "customerId": "cus_xyz", "staffId": "stf_sam", "source": "online", "visitId": null },
    "customer": { "id": "cus_xyz" },
    "staff": { "id": "stf_sam", "name": "Sam" },
    "currency": "CAD",
    "lines": [
      { "lineId": "apt_abc123:service", "kind": "service", "appointmentId": "apt_abc123", "label": "Cut", "qty": 1, "unitCents": 4000, "discountCents": 400, "totalCents": 3600, "taxCents": 432, "serviceId": "svc_cut", "staffId": "stf_sam", "staffName": "Sam" }
    ],
    "subtotalCents": 4000,
    "discountCents": 400,
    "totalCents": 3600,
    "tax": { "mode": "added", "taxCents": 432, "lines": [{ "rateId": "gst", "label": "GST", "rateMilli": 5000, "taxCents": 180 }, { "rateId": "pst", "label": "PST", "rateMilli": 7000, "taxCents": 252 }] },
    "depositPaidCents": 2000,
    "dueCents": 0,
    "checkout": { "allowed": false, "blocked": "already_checked_out" },
    "sale": { "id": "sale_x1y2z3", "receipt": "X1Y2Z3", "at": "2026-06-10T22:12:00.000Z", "source": "moneris_mgr", "externalSaleId": "MGR-000123", "method": "Card", "tender": "card", "collectedCents": 2032, "saleTotalCents": 2032, "tipCents": 500, "products": [] }
  }
}

Delivery & signing

Each delivery is signed with HMAC-SHA256 over the string "{timestamp}.{rawBody}", hex-encoded. Verify it before trusting the body. The endpoint secret is shown once when you create it and starts with whsec_.

• X-Bookatu-EventThe event name, e.g. booking.created.
• X-Bookatu-Signaturet={unixSeconds},v1={hmacSha256Hex}. Use t when recomputing the signature.
• X-Bookatu-AttemptDelivery attempt number, 1 to 3.
• User-AgentBookatu-Webhooks/1
• Content-Typeapplication/json

• Up to 3 attempts. Backoff between attempts is 500ms, then 1000ms, then 2000ms (the formula is capped at 4000ms). A delivery succeeds on any 2xx response; non-2xx responses, timeouts and network errors are retried.
• Each attempt times out after 4 seconds.
• Redirects are not followed (redirect: error). Endpoints must be public https URLs: localhost, .local / .internal / .localhost hosts and private, reserved, loopback and cloud-metadata IP ranges are rejected (SSRF protection), both when the endpoint is saved and again at send time.

Verify every delivery. Recompute the signature over {timestamp}.{rawBody} and compare it, in a timing-safe way, to the v1 value in X-Bookatu-Signature.

import crypto from "node:crypto";

// rawBody is the exact bytes you received (do not re-serialize).
// secret is your endpoint secret (whsec_...).
// t comes from the X-Bookatu-Signature header: "t=<seconds>,v1=<hmac>".
function verify(rawBody, t, v1, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(String(v1));
  // timingSafeEqual throws on buffers of different lengths: refuse those.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Rate limits

Every answer of the v1 REST API and the MCP servers says where the call stands: RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (in seconds) for the window closest to its limit, and RateLimit-Policy naming every window it was counted against, for example 30;w=60, 2000;w=86400. Each key is limited on its own and with its business's other keys, per minute and per day, at its plan's numbers; the keyless endpoints are limited per address at each business; test keys and sandboxes have lower limits whatever the plan. A call past a limit is answered 429 with Retry-After: wait that long, and back off with jitter on repeated 429 and 5xx answers. The full table, the raised tier and how to back off are at /developers/rate-limits. The customer booking-management family under /booking/{id} is limited per IP, and each of those endpoints states its own budget.

MCP server

Bookatu exposes a Model Context Protocol (MCP) server so any AI assistant (Claude, GPT-4o, Gemini, or a custom agent) can list services, check real-time availability, create bookings, look up customer and appointment data, manage the product and service catalog, write and publish posts on the business's blog, build intake and consent forms (and require them before a service), draft email campaigns, answer booking requests, run class rosters, read earnings, tips, deposits and the audit log, and see what a booking comes to at checkout — all in a single authenticated session. Each tool needs its scope on the key (writes a write scope; each tool's scope is in the table below), and there are no delete tools by design. Two deliberate limits: form-response listings are summaries only (clients' actual answers never leave the admin dashboard), and campaigns can only be drafted — there is no send or schedule tool, so mass email always stays an owner-confirmed action in the app.

https://bookatu.com/api/mcp

# Discover tools
curl -X POST https://bookatu.com/api/mcp \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST https://bookatu.com/api/mcp \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_availability",
      "arguments": {
        "serviceId": "svc_abc123",
        "from": "2026-06-10",
        "to": "2026-06-14"
      }
    }
  }'

Configure your AI assistant by pointing it at https://bookatu.com/api/mcp with your API key. All tools are automatically scoped to the key's organisation.

Sandbox-only tools

A sandbox (test mode) business lists four more tools, never shown at a live business: sandbox_outbox reads the messages it kept instead of sending, sandbox_payments reads the payments it made in test mode, sandbox_simulate makes a payment, a cancellation, a no-show or a reminder happen to one of its bookings, and sandbox_reset wipes it and seeds it again (only with its own test key). Every successful tool result says livemode in structuredContent: false at a sandbox, true at a live business. Every tool result, a refusal included, says it in result._meta["com.bookatu/livemode"], and every answer in the Bookatu-Livemode header.

How to point an agent at a sandbox, from Claude Desktop, Cursor or the MCP Inspector, and what to ask it: Test your AI agent.

Docs MCP server

A second MCP server reads Bookatu's own documentation: the help centre, in every language it is translated into, the blog, the engineering blog and these developer docs. It needs no API key and no sign-in, and it can only read, so any MCP client can connect to it. It never sees a business's data. To act on a business, use the MCP server above.

https://bookatu.com/api/mcp/docs

# No key needed
curl -X POST https://bookatu.com/api/mcp/docs \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_help",
      "arguments": { "query": "how do I take a deposit", "language": "en" }
    }
  }'

Every answer names the page it came from and its markdown copy, so an agent can cite the page. It is rate limited per IP, like the public REST endpoints.

Connect from Claude

Claude's custom connectors use OAuth rather than a pasted key, and the MCP server supports that flow natively. You sign in with your normal Bookatu account, pick which business to connect and whether Claude may write or only read, and Claude receives its own revocable token for that one business. Your password and your other businesses are never shared.

1. In Claude, open Settings → Connectors → Add custom connector.
2. Enter https://bookatu.com/api/mcp as the server URL and continue.
3. Claude sends you to Bookatu to sign in. You must be an owner or admin of the business you connect.
4. Choose the business, the access level (read and write, or read only) and whether the app may see your clients' names, emails and phone numbers: a box on the consent page that stays unticked unless you tick it. Then approve.

Without that box ticked, list_customers answers 403 naming customers:read, and booking requests, class rosters and form responses come without the client's details. To change your answer later, connect the app again.

The same rules apply as with API keys: every tool is scoped to the connected business, read-only connections are refused on any write tool, and there are no delete tools at all. Disconnect any time from Settings → Developer API → Connected apps in your dashboard, or from Claude's connector settings. The flow is the standard MCP authorization stack for any other OAuth-capable MCP client too: discovery at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource, dynamic client registration, authorization code with PKCE, and refresh token rotation.

Build an agent on Bookatu

An AI agent can run a Bookatu business end to end with two primitives: MCP tools to act (read data, create bookings, manage the catalog, draft campaigns) and signed webhooks to react (a POST arrives at the agent when something happens). Tools in, events out. That closes the loop: the agent no longer needs a human to tell it that a booking was cancelled or an order was paid.

Worked example: an agent that refills cancelled slots

# The agent registers where it wants events delivered (once, at setup)
curl -X POST https://bookatu.com/api/mcp \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "webhooks_create",
      "arguments": {
        "url": "https://agent.example.com/hooks/bookatu",
        "events": ["booking.cancelled"]
      }
    }
  }'
# → { "webhook": { "id": "whk_...", ... }, "secret": "whsec_..." }  (secret shown once)

# Later, a client cancels. Bookatu POSTs to the agent's endpoint:
POST /hooks/bookatu HTTP/1.1
X-Bookatu-Event: booking.cancelled
X-Bookatu-Signature: t=1780000000,v1=3f1c...9ab2
Content-Type: application/json

{
  "event": "booking.cancelled",
  "sentAt": "2026-07-30T02:14:00.000Z",
  "data": { "id": "apt_abc123", "ref": "VRD-7QK2M9",
            "service": "Gel Manicure",
            "startAt": "2026-08-02T21:00:00.000Z", "status": "cancelled" }
}

# The agent verifies the signature, then acts through MCP again:
# confirm the freed slot is really open...
{ "name": "get_availability",
  "arguments": { "serviceId": "svc_...", "from": "2026-08-02", "to": "2026-08-02" } }

# ...and rebook it for the next customer who asked for that time.
{ "name": "create_booking",
  "arguments": { "serviceId": "svc_...", "startAt": "2026-08-02T21:00:00.000Z",
                 "name": "Mia Chen", "email": "mia@example.com", "phone": "+64211234567" } }