API Reference

Bookings

Create appointments on behalf of your customers, read the salon calendar, and pull a single booking by id. Every booking belongs to the business that owns the API key. Mobile (at-customer) bookings are supported with live travel-fee quoting.

Scope and plan

Reading bookings requires the bookings:read scope. Creating a booking requires bookings:write. API keys are available on the PRO and ENTERPRISE plans. The path businessId must match the business your key belongs to.

List bookings

GET/businesses/{businessId}/bookings

bookings:readPRO plan

Returns a paginated list of bookings for the business, newest first by default.

Path parameters

Name	Type	Required	Description
`businessId`	uuid	Required	Your business id.

Query parameters

Name	Type	Required	Description
`status`	enum	Optional	Filter by booking status (PENDING, CONFIRMED, IN_PROGRESS, COMPLETED, CANCELLED, NO_SHOW).
`paymentStatus`	string	Optional	Comma-separated payment statuses (e.g. PENDING,ON_SITE).
`staffId`	uuid	Optional	Only bookings assigned to this staff member.
`customerId`	uuid	Optional	Only bookings for this customer.
`startDate`	date	Optional	Inclusive lower bound (YYYY-MM-DD).
`endDate`	date	Optional	Inclusive upper bound (YYYY-MM-DD).
`search`	string	Optional	Match customer name, email, phone, or booking number.
`sortOrder`	asc \| desc	Optional	Sort direction by date. Defaults to desc.
`page`	integer	Optional	Page number. Defaults to 1.
`limit`	integer	Optional	Items per page (1-100). Defaults to 20.

curl "https://api.salonify.eu/api/v1/businesses/b_8f3a/bookings?status=CONFIRMED&limit=20" \
  -H "X-API-Key: sk_live_..."

Response

{
  "data": [
    {
      "id": "bk_3f9c2a",
      "bookingNumber": "B-100247",
      "businessId": "b_8f3a",
      "customerId": "cu_9a21",
      "staffId": "st_4d11",
      "date": "2026-07-02",
      "startTime": "09:00",
      "endTime": "10:00",
      "totalDuration": 60,
      "subtotal": 45,
      "travelCost": 0,
      "discount": 0,
      "total": 45,
      "tipAmount": 0,
      "status": "CONFIRMED",
      "customerName": "Anna Berg",
      "customerEmail": "[email protected]",
      "isMobile": false,
      "paymentMethod": "ON_SITE",
      "paymentStatus": "PENDING",
      "depositRequired": false,
      "depositPaid": false,
      "rescheduledCount": 0,
      "reminderSent": false,
      "createdAt": "2026-06-20T11:04:12.000Z",
      "updatedAt": "2026-06-20T11:04:12.000Z",
      "services": [
        {
          "id": "bs_01",
          "serviceId": "sv_77",
          "serviceName": "Women's Cut",
          "price": 45,
          "duration": 60,
          "addons": []
        }
      ]
    }
  ],
  "meta": { "total": 312, "page": 1, "limit": 20, "totalPages": 16 }
}

Retrieve a booking

GET/businesses/{businessId}/bookings/{bookingId}

bookings:readPRO plan

Path parameters

Name	Type	Required	Description
`businessId`	uuid	Required	Your business id.
`bookingId`	uuid	Required	The booking id.

curl "https://api.salonify.eu/api/v1/businesses/b_8f3a/bookings/bk_3f9c2a" \
  -H "X-API-Key: sk_live_..."

Response

{
  "data": {
    "id": "bk_3f9c2a",
    "bookingNumber": "B-100247",
    "status": "CONFIRMED",
    "date": "2026-07-02",
    "startTime": "09:00",
    "endTime": "10:00",
    "total": 45,
    "paymentStatus": "PENDING",
    "customerName": "Anna Berg",
    "services": [
      { "id": "bs_01", "serviceId": "sv_77", "serviceName": "Women's Cut", "price": 45, "duration": 60, "addons": [] }
    ],
    "staff": { "id": "st_4d11", "firstName": "Marie", "lastName": "Dupont" }
  }
}

Create a booking

POST/businesses/{businessId}/bookings

bookings:writePRO plan

Books one or more services for a customer. Supply a customerId to book on behalf of an existing customer, or set isWalkIn with customerName/customerEmail for a walk-in. For at-customer (mobile) appointments, pass mobileAddress or addressId.

Idempotency

Pass an Idempotency-Key header to safely retry a create without risk of a duplicate booking. The same key replays the original response for 24 hours.

Body parameters

Name	Type	Required	Description
`date`	date	Required	Appointment date (YYYY-MM-DD).
`startTime`	string	Required	Start time in HH:mm.
`services`	object[]	Required	Array of { serviceId, variantId?, addons?: [{ addonId }] }.
`staffId`	uuid	Optional	Staff member. Auto-assigned if omitted.
`customerId`	uuid	Optional	Book on behalf of an existing customer.
`isWalkIn`	boolean	Optional	Mark as a walk-in customer.
`customerName`	string	Optional	Walk-in customer name.
`customerEmail`	string	Optional	Walk-in customer email.
`customerPhone`	string	Optional	Walk-in customer phone.
`customerNotes`	string	Optional	Customer notes or special requests.
`mobileAddress`	string	Optional	Free-text address for an at-customer booking.
`addressId`	uuid	Optional	Saved customer address id for a mobile booking.
`paymentMethod`	enum	Optional	ON_SITE (default) or ONLINE.
`tipAmount`	number	Optional	Tip in main currency units (0-500). 100% goes to the venue.
`couponCode`	string	Optional	Coupon code to apply.
`giftCardCodes`	string[]	Optional	Gift card codes to apply.
`bookingSource`	enum	Optional	WEBSITE, WIDGET, MOBILE_APP, DASHBOARD, MARKETPLACE, GOOGLE.

Request

curl -X POST "https://api.salonify.eu/api/v1/businesses/b_8f3a/bookings" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4c1f9b2e-..." \
  -d '{
    "date": "2026-07-02",
    "startTime": "09:00",
    "staffId": "st_4d11",
    "customerId": "cu_9a21",
    "services": [{ "serviceId": "sv_77" }],
    "paymentMethod": "ON_SITE"
  }'

Response

{
  "booking": {
    "id": "bk_3f9c2a",
    "bookingNumber": "B-100247",
    "status": "CONFIRMED",
    "date": "2026-07-02",
    "startTime": "09:00",
    "endTime": "10:00",
    "total": 45,
    "paymentMethod": "ON_SITE",
    "paymentStatus": "PENDING",
    "services": [
      { "id": "bs_01", "serviceId": "sv_77", "serviceName": "Women's Cut", "price": 45, "duration": 60, "addons": [] }
    ]
  },
  "depositInfo": null
}

Reschedule a booking

PATCH/businesses/{businessId}/bookings/{bookingId}/reschedule

bookings:writePRO plan

Body parameters

Name	Type	Required	Description
`date`	date	Required	New date (YYYY-MM-DD).
`startTime`	string	Required	New start time in HH:mm.
`staffId`	uuid	Optional	Reassign to a different staff member.

curl -X PATCH "https://api.salonify.eu/api/v1/businesses/b_8f3a/bookings/bk_3f9c2a/reschedule" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "date": "2026-07-03", "startTime": "11:00" }'

Response

{
  "data": {
    "id": "bk_3f9c2a",
    "status": "CONFIRMED",
    "date": "2026-07-03",
    "startTime": "11:00",
    "endTime": "12:00",
    "rescheduledCount": 1,
    "rescheduledFrom": "2026-07-02T09:00:00.000Z"
  }
}

Cancel a booking

PATCH/businesses/{businessId}/bookings/{bookingId}/cancel

bookings:writePRO plan

Body parameters

Name	Type	Required	Description
`cancelReason`	string	Optional	Free-text cancellation reason.
`cancelReasonKey`	enum	Optional	scheduleConflict, personalReasons, illness, providerUnreachable, noLongerNeeded, other.

curl -X PATCH "https://api.salonify.eu/api/v1/businesses/b_8f3a/bookings/bk_3f9c2a/cancel" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "cancelReasonKey": "noLongerNeeded" }'

Response

{
  "data": {
    "id": "bk_3f9c2a",
    "status": "CANCELLED",
    "cancelledAt": "2026-06-21T08:15:00.000Z",
    "cancelReason": "noLongerNeeded"
  }
}

Quote a mobile booking

POST/businesses/{businessId}/bookings/mobile-quote

PRO plan

Returns a live travel-fee quote for an at-customer (mobile) booking before you create it. Pass a saved address id, a free-text address to geocode, or raw lat/lng coordinates, plus the service subtotal.

Body parameters

Name	Type	Required	Description
`subtotal`	number	Required	Service subtotal before travel cost or discount.
`addressId`	uuid	Optional	Saved customer address id to quote against.
`mobileAddress`	string	Optional	Free-text address to geocode.
`lat`	number	Optional	Customer latitude (used if no address is given).
`lng`	number	Optional	Customer longitude (used if no address is given).

curl -X POST "https://api.salonify.eu/api/v1/businesses/b_8f3a/bookings/mobile-quote" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "subtotal": 60, "mobileAddress": "Place Guillaume II, Luxembourg" }'

Response

{
  "travelCost": 12.5,
  "travelDistanceKm": 8.4,
  "subtotal": 60,
  "total": 72.5,
  "withinRadius": true
}

Booking lifecycle actions

The status transitions confirm, start, complete, no-show, mark-paid and mark-remaining-paid all live under PATCH /businesses/{businessId}/bookings/{bookingId}/<action> and require the bookings:write scope. They take no body unless noted above.