Build on Bookatu.
REST, webhooks & MCP

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: the appointment id IS the capability. Ids are apt_ followed by a 16-character nanoid — about 96 bits from a 64-character alphabet, the same order of unguessability as a magic link — and are only ever handed to the person who booked (their confirmation email and booking-success screen). They are also scoped to the business in the URL, so a valid id from one business can never be read or acted on through another's. Treat a booking id like a password: it lets the holder view, move or cancel that one booking, and nothing else. 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. 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 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, and audit:read reads the audit log. 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.

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 id itself, 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). 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. 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"
    }
  ]
}

// description is the service description, or null when none is set.

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, 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.

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.

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. 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 answer's when is the booked time on the business's clock and, with clientTimeZone, the client's. 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",
  "status": "confirmed",
  "needsPayment": false
}

// status is "pending" for a request the business still has to accept.
// appointmentId is the person's private key to their booking: never show it,
// store it or put it in a chat; they manage it from the email they are sent.

// 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"
}

GET /booking/{id}

No API key. Authorised by the appointment id in the path.

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 appointment id alone — no API key, no account — and deliberately narrow: 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. 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"). 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 appointment id in the path.

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 appointment id alone. 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 appointment id in the path.

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 appointment id in the path.

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), ordered by name. 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" }
  ]
}

// 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). 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. 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",
      "source": "online",
      "leadSource": "google",
      "channel": "google",
      "seriesId": null,
      "visitId": null
    }
  ]
}

// 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. 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 and visitId included. 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. 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",
  "source": "phone",
  "leadSource": null,
  "channel": null,
  "seriesId": "ser_abc123",
  "visitId": null
}

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 and additionalStaffIds (the others on a booking two or more of the team do at once, then named in the answer too). 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. 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 till): 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 till 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 till 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 till 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 till (externalSaleId null), else
// the name the outside till 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 till 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 tills 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 till (sale.tipCents says what was). Products you sell with it stay in your own till. 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. 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. 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" }
}

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. 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), 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), 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. 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.

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. 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 till (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 till 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 till), and See bookings so your till can list the day's bookings with GET /appointments. Add See clients if your till 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 till 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 till, so your till 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.

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");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Rate limits

There is currently no per-key rate limit enforced on the v1 REST API. That is not a promise of unlimited throughput. Build clients defensively: treat HTTP 429 and 5xx responses as retryable, back off (ideally exponentially, with jitter), and cache rarely-changing responses such as business, services and staff. Limits may be introduced in future, designed not to break well-behaved clients. The exception is the customer booking-management family under /booking/{id}, which IS limited per IP today — they carry no key, so the limit is what stops someone hammering them; each endpoint states its own budget, and a 429 always carries Retry-After.

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.

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 and the access level (read and write, or read only), then approve.

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" } }