BookEase API Reference

Version v1.2.0 • Base URL: https://api.bookease.dev/v1

The BookEase API allows you to programmatically manage bookings, services, users, and webhooks. All requests must be made over HTTPS. Calls made over plain HTTP will fail.

curl -X GET "https://api.bookease.dev/v1/bookings" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

Authentication

Authenticate your API requests using Bearer tokens. Include your API key in the Authorization header.

Authorization: Bearer sk_live_51J7xK9s...Z8vY

Never expose your secret keys in client-side code. Use environment variables to store them securely.

Rate Limits

API requests are rate-limited to ensure fair usage. Standard limits apply:

Plan	Requests/min	Requests/day
Free	60	1,000
Pro	300	50,000
Business	1,000	Unlimited

Exceeding limits returns 429 Too Many Requests. Monitor your usage via the X-RateLimit-Remaining header.

Bookings Endpoints

GET /bookings

Returns a list of bookings sorted by creation date (newest first). Supports pagination.

Query Parameters

Parameter	Type	Description
limit	integer	Number of results (default: 20, max: 100)
offset	integer	Skips first N records
status	string	Filter by: `confirmed`, `pending`, `cancelled`

Request

Response

GET /v1/bookings?limit=10&status=confirmed HTTP/1.1
Host: api.bookease.dev
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "data": [
    {
      "id": "bk_8xK2mN9pQ1",
      "user_id": "usr_7hJ4kL2",
      "service_id": "svc_9zR3vT5",
      "date": "2025-06-15",
      "time": "14:00:00",
      "status": "confirmed",
      "created_at": "2025-05-20T10:30:00Z"
    }
  ],
  "meta": {
    "total": 142,
    "limit": 10,
    "offset": 0
  }
}

POST /bookings

Creates a new booking. The system validates availability before confirming.

Request Body

Field	Type	Description
user_idrequired	string	ID of the customer
service_idrequired	string	ID of the service being booked
daterequired	string	ISO date (YYYY-MM-DD)
timerequired	string	24h format (HH:MM:SS)
notes	string	Optional customer notes

Request

Response

POST /v1/bookings HTTP/1.1
Host: api.bookease.dev
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "user_id": "usr_7hJ4kL2",
  "service_id": "svc_9zR3vT5",
  "date": "2025-07-10",
  "time": "09:30:00",
  "notes": "Please reserve a window seat."
}

{
  "id": "bk_9yL3nO0qR2",
  "status": "confirmed",
  "date": "2025-07-10",
  "time": "09:30:00",
  "created_at": "2025-05-20T11:45:00Z",
  "payment_required": false
}

DELETE /bookings/:id

Cancels an existing booking. Only works if cancellation policy allows it.

DELETE /v1/bookings/bk_9yL3nO0qR2 HTTP/1.1
Host: api.bookease.dev
Authorization: Bearer sk_live_...

// Returns 200 OK if successful
{
  "id": "bk_9yL3nO0qR2",
  "status": "cancelled",
  "cancelled_at": "2025-05-20T12:00:00Z",
  "refund_status": "pending"
}

Error Handling

The API uses standard HTTP status codes and returns detailed error objects:

400 Bad Request – Invalid parameters or missing fields

401 Unauthorized – Invalid or missing API key

403 Forbidden – Insufficient permissions

404 Not Found – Resource does not exist

429 Too Many Requests – Rate limit exceeded

500 Internal Server Error – BookEase platform issue

{
  "error": {
    "code": "invalid_request",
    "message": "The 'date' field must be in YYYY-MM-DD format.",
    "status": 400
  }
}

Webhooks

Receive real-time notifications when booking events occur. Configure endpoints in your dashboard.

Event Types

Event	Description
`booking.created`	New booking successfully created
`booking.cancelled`	Booking was cancelled
`booking.reminder`	24-hour reminder triggered
`payment.completed`	Payment successfully processed

{
  "event": "booking.created",
  "timestamp": "2025-05-20T10:30:00Z",
  "payload": {
    "booking_id": "bk_8xK2mN9pQ1",
    "user_id": "usr_7hJ4kL2",
    "service": "Premium Hair Styling",
    "date": "2025-06-15",
    "time": "14:00:00"
  }
}

Note: Webhook payloads are signed with HMAC-SHA256. Verify signatures using your webhook secret.