Services API

The Services API provides access to your service catalog, including pricing, duration, and availability information.

List Services

GET

/v1/services

Retrieve all services

Query Parameters

Parameter	Type	Description
`category_id`	string	Filter by category
`active`	boolean	Filter by active status
`include`	string	Include related data (category, therapists)

Example Request

curl "https://api.bookwell.app/v1/services?active=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "srv_xyz789",
      "name": "60-Minute Massage",
      "description": "A relaxing full-body massage...",
      "duration": 60,
      "price": 9500,
      "currency": "usd",
      "category_id": "cat_abc123",
      "category_name": "Massage",
      "active": true,
      "online_booking": true,
      "created_at": "2024-06-01T10:00:00Z"
    },
    {
      "id": "srv_def456",
      "name": "90-Minute Massage",
      "description": "Extended relaxation massage...",
      "duration": 90,
      "price": 13500,
      "currency": "usd",
      "category_id": "cat_abc123",
      "category_name": "Massage",
      "active": true,
      "online_booking": true,
      "created_at": "2024-06-01T10:00:00Z"
    }
  ],
  "meta": {
    "total": 2
  }
}

Get Service

GET

/v1/services/:id

Retrieve a single service

Path Parameters

Parameter	Type	Description
`id`	string	The service ID

Query Parameters

Parameter	Type	Description
`include`	string	Include related data (therapists, addons)

Example Request

curl "https://api.bookwell.app/v1/services/srv_xyz789?include=therapists,addons" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "id": "srv_xyz789",
    "name": "60-Minute Massage",
    "description": "A relaxing full-body massage designed to ease tension and promote relaxation.",
    "duration": 60,
    "buffer_before": 0,
    "buffer_after": 15,
    "price": 9500,
    "currency": "usd",
    "category_id": "cat_abc123",
    "category_name": "Massage",
    "active": true,
    "online_booking": true,
    "min_advance_booking": 120,
    "max_advance_booking": 43200,
    "therapists": [
      {
        "id": "thr_ghi012",
        "name": "Sarah Johnson",
        "price": 9500
      },
      {
        "id": "thr_jkl345",
        "name": "Mike Brown",
        "price": 9500
      }
    ],
    "addons": [
      {
        "id": "add_mno678",
        "name": "Hot Stones",
        "price": 2000,
        "duration": 15
      },
      {
        "id": "add_pqr901",
        "name": "Aromatherapy",
        "price": 1500,
        "duration": 0
      }
    ],
    "created_at": "2024-06-01T10:00:00Z",
    "updated_at": "2024-09-15T14:30:00Z"
  }
}

Service Object

Fields

Field	Type	Description
`id`	string	Unique identifier
`name`	string	Service name
`description`	string	Full description
`duration`	integer	Service duration in minutes
`buffer_before`	integer	Buffer time before (minutes)
`buffer_after`	integer	Buffer time after (minutes)
`price`	integer	Price in smallest currency unit
`currency`	string	Currency code (usd, eur, etc.)
`category_id`	string	Category ID
`category_name`	string	Category name
`active`	boolean	Whether bookable
`online_booking`	boolean	Available for online booking
`min_advance_booking`	integer	Minimum booking lead time (minutes)
`max_advance_booking`	integer	Maximum booking lead time (minutes)
`created_at`	string	Creation timestamp
`updated_at`	string	Last update timestamp

Pricing Notes

Prices are in the smallest currency unit. For USD, 9500 = $95.00.

GET

/v1/categories

Retrieve service categories

Example Request

curl https://api.bookwell.app/v1/categories \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "cat_abc123",
      "name": "Massage",
      "description": "Various massage therapies",
      "order": 1,
      "service_count": 5
    },
    {
      "id": "cat_def456",
      "name": "Facials",
      "description": "Skin care treatments",
      "order": 2,
      "service_count": 3
    }
  ]
}

Service Availability

To check when a service is available:

GET

/v1/services/:id/availability

Get available slots for a service

Query Parameters

Parameter	Type	Required	Description
`date_from`	string	Yes	Start date (YYYY-MM-DD)
`date_to`	string	No	End date (default: date_from)
`therapist_id`	string	No	Filter by therapist

Example Request

curl "https://api.bookwell.app/v1/services/srv_xyz789/availability?date_from=2025-01-15&date_to=2025-01-17" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "service_id": "srv_xyz789",
    "dates": [
      {
        "date": "2025-01-15",
        "slots": [
          {
            "time": "09:00",
            "therapists": ["thr_ghi012", "thr_jkl345"]
          },
          {
            "time": "11:00",
            "therapists": ["thr_ghi012"]
          }
        ]
      },
      {
        "date": "2025-01-16",
        "slots": [
          {
            "time": "10:00",
            "therapists": ["thr_jkl345"]
          },
          {
            "time": "14:00",
            "therapists": ["thr_ghi012", "thr_jkl345"]
          }
        ]
      }
    ]
  }
}

Add-ons

Listing Service Add-ons

Include add-ons when fetching a service:

curl "https://api.bookwell.app/v1/services/srv_xyz789?include=addons"

Add-on Object

Field	Type	Description
`id`	string	Add-on identifier
`name`	string	Add-on name
`description`	string	Description
`price`	integer	Additional cost
`duration`	integer	Additional time (minutes)

Using Add-ons in Bookings

When creating an appointment, include add-on IDs:

{
  "service_id": "srv_xyz789",
  "start_time": "2025-01-15T10:00:00Z",
  "customer": {...},
  "addons": ["add_mno678", "add_pqr901"]
}

The price and duration are adjusted automatically.

Therapists for a Service

List Therapists

GET

/v1/services/:id/therapists

Get therapists who offer a service

Example Request

curl https://api.bookwell.app/v1/services/srv_xyz789/therapists \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "thr_ghi012",
      "name": "Sarah Johnson",
      "bio": "Licensed massage therapist with 10 years experience...",
      "photo_url": "https://...",
      "price": 9500
    },
    {
      "id": "thr_jkl345",
      "name": "Mike Brown",
      "bio": "Specializes in deep tissue and sports massage...",
      "photo_url": "https://...",
      "price": 9500
    }
  ]
}

Read-Only API

Note

The Services API is read-only through the public API. Service management is done through the admin dashboard or admin API.

For service management endpoints, contact us about admin API access.

Caching

Service data changes infrequently. Consider caching:

Service list: Cache for 5-15 minutes
Individual services: Cache for 5-15 minutes
Categories: Cache for 1 hour
Availability: Do not cache (real-time)

Next Steps

Appointments API

Create bookings with services.

Webhooks

Get notified of changes.

Retrieve and manage services via the Bookwell API.

Note

Appointments API

Webhooks