Customer API

The customer API is what a logged-in customer (someone with a BookFlow account who books appointments) can do. Tokens are issued by POST /api/customer-auth/login and target the aud: customer audience.

A single customer account can have bookings with many tenants. The token is not tenant-scoped — the customer's /me page shows their full booking history across all BookFlow businesses.

Auth

• POST /api/customer-auth/register — create a new customer account
• POST /api/customer-auth/login — sign in, returns token
• POST /api/customer-auth/logout — invalidate session
• GET /api/customer-auth/me — current customer
• PATCH /api/customer-auth/me — update profile
• POST /api/customer-auth/change-password — change password
• POST /api/customer-auth/forgot-password — start reset flow

Self-service

The customer profile is at /api/customer-auth/me. Booking self-service is at /api/me/*:

• GET /api/me/bookings — every booking this customer has, across all tenants
• GET /api/me/bookings/:id — single booking detail
• POST /api/me/bookings/:id/reschedule — move to a new time
• POST /api/me/bookings/:id/cancel — cancel a booking
• GET /api/me/stats — counts (total bookings, completed, no-shows, favorite salon, etc.)

Register

{
  "data": {
    "token": "eyJ...",
    "sessionId": "...",
    "customer": {
      "id": "cu_abc",
      "email": "jane@example.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "phone": null,
      "defaultTimezone": "America/Vancouver",
      "emailVerified": false,
      "marketingOptIn": false,
      "createdAt": "2026-08-15T18:00:00Z",
      "lastLoginAt": null
    }
  }
}

Login

{`{ "data": { "token": "eyJ...", "sessionId": "...", "customer": { "id": "cu_abc", "email": "jane@example.com", ... } } }`}

My bookings

{
  "data": [
    {
      "id": "bk_abc",
      "tenantId": "tn_xxx",
      "startDatetime": "2026-08-15T16:00:00Z",
      "endDatetime": "2026-08-15T16:45:00Z",
      "durationMinutes": 45,
      "timezone": "America/Vancouver",
      "subtotal": 6500,
      "totalAmount": 6500,
      "amountPaid": 0,
      "currency": "CAD",
      "status": "confirmed",
      "paymentStatus": "unpaid",
      "cancellationReason": null,
      "cancelledAt": null,
      "notes": null,
      "source": "online",
      "confirmationCode": "BF-A4F2X9",
      "createdAt": "2026-08-14T09:11:00Z",
      "service": { "id": "sv_abc", "name": "Haircut" },
      "staff": { "id": "sp_alice", "name": "Alice" },
      "business": {
        "id": "tn_xxx",
        "name": "Demo Salon",
        "slug": "demo-salon",
        "logoUrl": null,
        "widgetColor": "#6366F1"
      }
    }
  ]
}

Reschedule

Cancel

Stats

{
  "data": {
    "totalBookings": 23,
    "totalSpent": 145000,
    "upcomingCount": 2,
    "pastCount": 20,
    "cancelledCount": 1,
    "favoriteSalon": {
      "tenantId": "tn_xxx",
      "name": "Demo Salon",
      "slug": "demo-salon",
      "bookings": 14
    }
  }
}

Common errors

• 400 invalid_request — body validation failed (Zod). details.fieldErrors has field-level messages.
• 401 unauthorized — token missing, invalid, or expired (24h lifetime).
• 404 not_found — booking doesn't exist or doesn't belong to this customer.
• 409 not_reschedulable — booking is cancelled, completed, or no_show.
• 409 not_cancellable — booking is completed or no_show.
• 409 slot_taken — reschedule target is already booked.
• 429 rate_limited — too many requests; check Retry-After.