Bookings

Create, list, and manage bookings. This is the core of AvailEngine.

Public Booking

POST /v1/bookings/

Create a booking from a public booking widget. Requires an API key with write scope (rate-limited to 60 RPM by default). Use an avail_test_ key for development.

Request body:

{
  "business_id": "uuid",
  "booking_date": "2026-05-15",
  "start_time": "14:00",
  "capacity": 1,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "phone": "+301234567890",
  "customer_notes": "Prefers window seat"
}

Field	Type	Required	Description
business_id	UUID	Yes	Target business
booking_date	date	Yes	YYYY-MM-DD
start_time	time	Yes	HH:MM (24h)
capacity	int	No	Party size (1–50), default 1
first_name	string	Yes	Customer first name (1–100 chars)
last_name	string	Yes	Customer last name (1–100 chars)
email	email	Yes	Valid email address
phone	string	Yes	7–20 chars. Returning customers matched by phone.
customer_notes	string	No	Max 1000 chars

Without deposit:

{
  "booking": {
    "id": "uuid",
    "status": "confirmed",
    "confirmation_code": "AV-ABC123",
    "booking_date": "2026-05-15",
    "start_time": "14:00:00",
    "end_time": "15:00:00",
    "capacity": 1,
    "resource_id": "uuid"
  }
}

With deposit (charge):

{
  "booking": {
    "id": "uuid",
    "status": "pending",
    "confirmation_code": "AV-ABC123",
    "booking_date": "2026-05-15",
    "start_time": "14:00:00",
    "end_time": "15:00:00",
    "capacity": 1
  },
  "stripe_client_secret": "pi_xxx_secret_yyy",
  "deposit_type": "charge"
}

With authorization hold:

{
  "booking": {
    "id": "uuid",
    "status": "pending",
    "confirmation_code": "AV-ABC123",
    "booking_date": "2026-05-15",
    "start_time": "14:00:00",
    "end_time": "15:00:00",
    "capacity": 1
  },
  "stripe_client_secret": "pi_xxx_secret_yyy",
  "deposit_type": "authorization_hold"
}

Deposit types:

• charge — Customer pays now. Refunded if they cancel within policy.
• authorization_hold — Amount blocked on card, captured only on no-show. Premium plans only.

Staff Bookings

Dashboards use these endpoints. All require authentication.

POST /v1/manage/bookings/staff

Create a booking from the dashboard. No deposit, instantly confirmed, source set to staff.

curl -X POST https://api.availengine.com/v1/manage/bookings/staff \
  -H "Authorization: Bearer avail_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-05-15",
    "time": "14:00",
    "capacity": 2,
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+301234567890",
    "email": "jane@example.com",
    "notes": "Walk-in, prefers Maria"
  }'

Field	Type	Required	Description
date	date	Yes	Booking date
time	time	Yes	Start time (HH:MM)
capacity	int	No	Party size (1–50), default 1
first_name	string	Yes	1–100 chars
last_name	string	Yes	1–100 chars
phone	string	Yes	7–20 chars
email	string	No	Up to 254 chars, not validated as email
notes	string	No	Staff notes (max 1000 chars)

Auto-assigns a free resource. Returns 409 if none available.

POST /v1/manage/bookings/staff-deposit

Create a booking with a Stripe payment link. Sends the customer a payment email via Brevo.

curl -X POST https://api.availengine.com/v1/manage/bookings/staff-deposit \
  -H "Authorization: Bearer avail_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-05-15",
    "time": "14:00",
    "capacity": 1,
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+301234567890",
    "email": "jane@example.com",
    "notes": "Phone booking, needs to prepay"
  }'

Field	Type	Required	Description
date	date	Yes	Booking date
time	time	Yes	Start time (HH:MM)
capacity	int	No	Party size (1–50), default 1
first_name	string	Yes	1–100 chars
last_name	string	Yes	1–100 chars
phone	string	Yes	7–20 chars
email	email	Yes	Must be valid — payment link is sent here
notes	string	No	Staff notes (max 1000 chars)

Response:

{
  "booking": { "id": "uuid", "status": "pending", ... },
  "checkout_url": "https://checkout.stripe.com/...",
  "expires_at": "2026-05-15T16:00:00Z"
}

The checkout link expires in 2 hours. If unpaid, the booking is auto-cancelled.

Listing Bookings

GET /v1/manage/bookings

List bookings for the current business. Cursor-paginated.

Param	Type	Description
res_date	date	Filter by booking date (alias: booking_date)
status	string	Filter by status
code	string	Search by confirmation code (case-insensitive partial match)
latest	bool	Most recent first (by created_at)
limit	int	Page size (default 50, max 200)
cursor	string	Pagination cursor

Response includes joined data:

{
  "items": [
    {
      "id": "uuid",
      "customer": {
        "id": "uuid",
        "first_name": "Jane",
        "last_name": "Doe",
        "phone": "+301234567890",
        "email": "jane@example.com"
      },
      "resource": {
        "name": "Maria",
        "capacity_max": 1,
        "section": "Main Floor"
      },
      "deposit": {
        "status": "held",
        "amount_cents": 2000
      },
      "booking_date": "2026-05-15",
      "start_time": "14:00",
      "end_time": "15:00",
      "status": "confirmed",
      "confirmation_code": "AV-ABC123",
      "capacity": 2,
      "source": "online",
      "customer_notes": null,
      "staff_notes": null,
      "created_at": "2026-05-14T10:30:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Updating a Booking

PATCH /v1/manage/bookings/{booking_id}

Update status, resource, or capacity. Only allowed transitions are enforced.

Field	Type	Description
status	string	New status (see transitions below)
resource_id	UUID	Move booking to a different resource
capacity	int	Change party size (1–50)

Status transitions:

pending    → confirmed, cancelled
confirmed  → checked_in, cancelled, no_show
checked_in → completed, no_show
completed  → (terminal)
cancelled  → (terminal)
no_show    → (terminal)

Invalid transitions return 409 Conflict.

PATCH /v1/manage/bookings/{booking_id}/notes

Save internal staff notes. Separate from status updates so notes don't get overwritten.

curl -X PATCH https://api.availengine.com/v1/manage/bookings/{booking_id}/notes \
  -H "Authorization: Bearer avail_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"staff_notes": "Allergic to latex — use nitrile gloves"}'

Field	Type	Required	Description
staff_notes	string	Yes	Max 2000 chars

Resource Reassignment

GET /v1/manage/bookings/{booking_id}/available-resources

When moving a booking, see which other resources are free during its time slot.

curl https://api.availengine.com/v1/manage/bookings/{booking_id}/available-resources \
  -H "Authorization: Bearer avail_live_YOUR_KEY"

Returns all active resources with sufficient capacity that have no conflicting bookings in the same time window. Excludes the booking's current resource.

No-Show Handling

POST /v1/manage/bookings/{booking_id}/no-show

Mark booking as no-show. If the business uses authorization holds, the hold is captured (charged).

curl -X POST https://api.availengine.com/v1/manage/bookings/{booking_id}/no-show \
  -H "Authorization: Bearer avail_live_YOUR_KEY"

Preconditions:

• Booking status must not be cancelled, completed, or no_show
• A deposit must exist with status held

Response:

{ "detail": "No-show recorded. EUR 20 hold captured." }

POST /v1/manage/bookings/{booking_id}/release-hold

Release an authorization hold without charging. The customer is billed manually instead.

curl -X POST https://api.availengine.com/v1/manage/bookings/{booking_id}/release-hold \
  -H "Authorization: Bearer avail_live_YOUR_KEY"

{ "detail": "Hold released. Deduct EUR 20 from the customer's bill manually." }

Precondition: deposit must exist with status held.

This is useful when a business wants to handle the charge at the POS rather than through the booking system.

Confirmation Codes

Every booking gets a unique 8-character alphanumeric confirmation code (e.g. AV-ABC123). These are generated with retry logic to handle collisions. The code is shown in confirmation emails and can be searched in the dashboard.