API Documentation

Build integrations with BookEase's booking management API. RESTful, JSON-based, and designed for developers.

ℹ️

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authentication

BookEase uses API keys to authenticate requests. You can view and manage your API keys in the dashboard.

Include your secret key in the Authorization header:

# Authorization Header
Authorization: Bearer your_secret_api_key_here

⚠️

Never expose your secret API key in client-side code, public repositories, or frontend applications.

Base URL & Versioning

All endpoints are relative to the base URL:

https://api.bookease.io/v1

The API is versioned via the URL path. The current stable version is v1.

GET List Bookings /bookings

Retrieve a paginated list of all bookings for your account.

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number for pagination. Defaults to 1.
limit	integer	Optional	Number of results per page. Max 100. Defaults to 20.
status	string	Optional	Filter by status: `upcoming`, `completed`, `cancelled`.

Example Request

GET https://api.bookease.io/v1/bookings?status=upcoming&limit=10
Authorization: Bearer sk_live_abc123...

Example Response

200 OK

                    
                    {
                      "data": [
                        {
                          "id": "bk_8x92kl01",
                          "service": "Haircut & Styling",
                          "customer_name": "Alex Johnson",
                          "scheduled_at": "2024-11-15T14:00:00Z",
                          "status": "upcoming"
                        }
                      ],
                      "pagination": {
                        "current_page": 1,
                        "total_pages": 5,
                        "total_items": 42
                      }
                    }
                

POST Create Booking /bookings

Create a new booking for a specific service and time slot.

Request Body

Field	Type	Required	Description
service_id	string	Required	ID of the service to book.
customer_name	string	Required	Full name of the customer.
customer_email	string	Required	Customer email for confirmations.
scheduled_at	datetime	Required	ISO 8601 datetime for the booking.
notes	string	Optional	Additional booking notes.

Example Request

                    
                    {
                      "service_id": "svc_salon_hair_01",
                      "customer_name": "Taylor Reed",
                      "customer_email": "taylor@example.com",
                      "scheduled_at": "2024-12-01T10:30:00Z",
                      "notes": "Prefers quiet section"
                    }
                

Example Response

201 Created

                    
                    {
                      "id": "bk_new_9x21",
                      "status": "confirmed",
                      "created_at": "2024-10-28T14:22:11Z",
                      "confirmation_number": "BE-884291"
                    }
                

PUT Update Booking /bookings/:id

Update an existing booking. Only certain fields can be modified after creation.

                    
                    PUT https://api.bookease.io/v1/bookings/bk_8x92kl01

                    {
                      "scheduled_at": "2024-11-16T14:00:00Z",
                      "notes": "Updated time request"
                    }

DELETE Cancel Booking /bookings/:id

Cancel a booking. Refunds are processed automatically if applicable.

DELETE https://api.bookease.io/v1/bookings/bk_8x92kl01

Error Handling

BookEase uses standard HTTP status codes and returns structured error objects:

Code	Meaning	Description
400	Bad Request	Missing or invalid parameters.
401	Unauthorized	Invalid or missing API key.
404	Not Found	Resource does not exist.
429	Too Many Requests	Rate limit exceeded.
500	Server Error	Internal server error. Contact support.

                    
                    {
                      "error": {
                        "code": "invalid_time_slot",
                        "message": "Selected time slot is already fully booked.",
                        "request_id": "req_7829xk"
                      }
                    }
                

Rate Limits

API requests are limited based on your plan:

Free: 60 requests/minute
Pro: 300 requests/minute
Business: 1,000 requests/minute

Rate limit headers are included in every response:

                    
                    X-RateLimit-Limit: 300

                    X-RateLimit-Remaining: 284

                    X-RateLimit-Reset: 1698765432

Webhooks

Receive real-time notifications when booking events occur. Configure your webhook URL in the dashboard.

Event	Description
`booking.created`	A new booking was successfully created.
`booking.updated`	Booking details were modified.
`booking.cancelled`	Booking was cancelled by user or admin.
`booking.completed`	Service was marked as completed.