Introduction to BookEase API

Welcome to the BookEase API documentation. This guide will help you integrate our booking management system into your application, allowing you to create, manage, and track bookings programmatically.

ℹ️ Base URL

All API requests should be made to: https://api.bookease.io/v2

Authentication

BookEase uses API keys to authenticate requests. You can view and manage your API keys in the Developer Dashboard. API keys carry many privileges, so be sure to keep them secure!

⚠️ Security Notice

Do not share your API keys in client-side code, public repositories, or browser console logs. Use environment variables or a secure backend proxy.

Usage

Include your API key in the Authorization header using the Bearer scheme:

HTTP

GET /v2/bookings HTTP/1.1
Host: api.bookease.io
Authorization: Bearer sk_live_your_api_key_here
Content-Type: application/json

Quickstart Guide

Follow these steps to make your first API call:

Sign up for a BookEase account and access your API keys.
Install the SDK or use raw HTTP requests.
Authenticate every request with your secret key.
Make a request to retrieve or create bookings.

JavaScript

import { BookEase } from '@bookease/sdk';

const client = new BookEase('sk_live_your_key');

const bookings = await client.bookings.list({
  status: 'confirmed',
  limit: 10,
  sort: 'created_at_desc'
});

console.log(bookings.data);

Bookings Endpoint

Manage appointments, reservations, and service bookings. Each booking belongs to a user and references a specific service.

List Bookings

Returns a paginated list of bookings based on optional filters.

Parameter	Type	Description
`status`	string	Filter by status: `pending`, `confirmed`, `cancelled`, `completed`
`date_from`	string (ISO 8601)	Filter bookings created after this date
`date_to`	string (ISO 8601)	Filter bookings created before this date
`limit`	integer	Number of results per page (default: 20, max: 100)
`cursor`	string	Pagination cursor from previous response

✅ Success Response (200)

{
  "data": [
    {
      "id": "bk_9f8s7d6f5g4h",
      "status": "confirmed",
      "service_id": "svc_haircut_premium",
      "customer_name": "Alex Morgan",
      "scheduled_at": "2025-08-15T14:30:00Z",
      "created_at": "2025-08-10T09:12:44Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJsYXN0X2lkIjoiYmtfOWY4czdkNmY1ZzRoIn0",
    "has_more": true
  }
}

Create Booking

Creates a new booking for a specified service and customer.

cURL

curl -X POST https://api.bookease.io/v2/bookings \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "svc_yoga_morning",
    "customer_email": "jane@example.com",
    "scheduled_at": "2025-09-01T10:00:00Z",
    "notes": "First-time visitor, bring mat."
  }'

Webhooks

Subscribe to real-time events like booking confirmations, cancellations, or payment completions. Configure webhook endpoints in your dashboard.

Event	Description
`booking.created`	A new booking has been submitted
`booking.confirmed`	Booking status changed to confirmed
`booking.cancelled`	Booking was cancelled by user or system
`payment.completed`	Payment successfully processed

ℹ️ Webhook Verification

Always verify webhook signatures using the X-Bookease-Signature header to prevent spoofing requests.

Rate Limits

API requests are limited to protect system stability. Limits vary by plan:

Free: 60 requests/minute
Pro: 600 requests/minute
Enterprise: Custom limits with dedicated infrastructure

Rate limit headers are included in every response:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Requests remaining in window
X-RateLimit-Reset: Unix timestamp when limit resets

FAQ & Troubleshooting

Why am I getting a 401 Unauthorized error?

This usually means your API key is missing, malformed, or expired. Double-check that you're using a sk_live_ or sk_test_ key in the Authorization header.

How do I handle timezone conversions?

All datetime fields are returned in UTC (ISO 8601 format). Convert them to local time on your frontend using libraries like date-fns or moment-timezone.

Can I update a booking after creation?

Yes! Use the PATCH /v2/bookings/{id} endpoint. Only status, notes, and scheduled_at (if within 24h) can be modified.