Skip to main content
This tutorial covers the complete booking flow: checking availability, creating a temporary reservation, and confirming with customer information.

​
Booking Flow Overview

The booking process follows these steps:
  1. Get available slots for a product and space
  2. Create temporary booking (reserves slot for 15 minutes)
  3. Collect customer information (name, email, phone)
  4. Add additional products (optional)
  5. Confirm booking with payment choice

​
1) Prerequisites

  • OAuth2 access token with booking:write
  • Product ID (booking product with duration metadata)
  • Space ID (the bookable resource)
  • Use UTC timestamps; avoid local timezone ambiguity

​
2) Get available slots

Query available time slots for a specific product and space: 
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.boseat.com/v1/bookings/slots?productId=$PRODUCT_ID&spaceId=$SPACE_ID&from=2024-07-15T00:00:00Z&to=31"
Parameters:
  • productId — UUID of the booking product
  • spaceId — UUID of the space
  • from — Start date (ISO 8601)
  • to — Number of days to look ahead (or end date)
Response returns an array of available slots: 
[
  {
    "from": "2024-07-15T09:00:00Z",
    "to": "2024-07-15T10:00:00Z"
  },
  {
    "from": "2024-07-15T10:00:00Z",
    "to": "2024-07-15T11:00:00Z"
  }
]

​
3) Create temporary booking

Create a booking with just the product, space, and slot. This reserves the slot for 15 minutes: 
curl -X POST "https://api.boseat.com/v1/bookings" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "$PRODUCT_ID",
    "spaceId": "$SPACE_ID",
    "slot": {
      "from": "2024-07-15T09:00:00Z",
      "to": "2024-07-15T10:00:00Z"
    }
  }'
Response (201 Created): 
{
  "id": "booking-uuid-here"
}
Important: The booking is created with status RESERVED_15_MIN and expires in 15 minutes if not confirmed.

​
4) Update booking with customer information

Update the booking with customer details and confirm it: 
curl -X PATCH "https://api.boseat.com/v1/bookings/$BOOKING_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Ada Lovelace",
    "phone": "+33123456789",
    "status": "CONFIRMED",
    "additionalProducts": ["product-uuid-1", "product-uuid-2"],
    "paymentEnabled": true,
    "successUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/cancel"
  }'
Fields:
  • email — Customer email (required)
  • name — Customer name (optional)
  • phone — Customer phone (required)
  • status — Set to CONFIRMED to finalize the booking
  • additionalProducts — Array of additional product IDs (optional)
  • paymentEnabled — If true, returns payment URL in Location header
  • successUrl — Redirect URL after successful payment
  • cancelUrl — Redirect URL if payment is cancelled
If paymentEnabled: true, the response includes a Location header with the payment URL: 
Location: https://checkout.stripe.com/pay/...

​
5) Booking statuses

  • RESERVED_15_MIN — Temporary reservation (expires in 15 minutes)
  • PENDING — Booking created but not yet confirmed
  • CONFIRMED — Booking confirmed and active
  • PAID — Payment completed
  • CANCEL — Booking cancelled
  • REFUNDED — Payment refunded

​
6) Cancel a booking

To cancel a booking before confirmation: 
curl -X PATCH "https://api.boseat.com/v1/bookings/$BOOKING_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "phone": "+33123456789",
    "status": "CANCEL"
  }'

​
7) Complete flow example

# 1. Get slots
SLOTS=$(curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.boseat.com/v1/bookings/slots?productId=$PRODUCT_ID&spaceId=$SPACE_ID&from=2024-07-15T00:00:00Z&to=31")

# 2. Create temporary booking
BOOKING=$(curl -X POST "https://api.boseat.com/v1/bookings" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "$PRODUCT_ID",
    "spaceId": "$SPACE_ID",
    "slot": {
      "from": "2024-07-15T09:00:00Z",
      "to": "2024-07-15T10:00:00Z"
    }
  }')

BOOKING_ID=$(echo $BOOKING | jq -r '.id')

# 3. Confirm booking (within 15 minutes)
curl -X PATCH "https://api.boseat.com/v1/bookings/$BOOKING_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Ada Lovelace",
    "phone": "+33123456789",
    "status": "CONFIRMED",
    "paymentEnabled": false
  }'

​
Best practices

  • Reserve quickly: Create the temporary booking immediately when user selects a slot
  • Confirm within 15 minutes: Update the booking with customer info before expiry
  • Handle expiry: If booking expires, create a new one or notify the user
  • Idempotency: Use idempotency keys for retries when updating bookings
  • Payment URLs: Redirect users to the Location URL if paymentEnabled: true

​
Listen for updates

Subscribe to booking webhooks to handle status changes:
  • booking.created — Temporary booking created
  • booking.updated — Booking status changed (confirmed, cancelled, etc.)
  • booking.paid — Payment completed