Skip to main content
POST
/
api
/
bookings
Create a booking
curl --request POST \
  --url https://clarus-api.com/api/bookings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Clarus-Subdomain: <api-key>' \
  --data '
{
  "data": {
    "type": "bookings",
    "attributes": {
      "account_id": 1,
      "consignment_reference": "CONS-2024-001",
      "direction": "inbound",
      "end_time": "2024-09-15T09:00:00Z",
      "hazardous": false,
      "location_id": 10,
      "start_time": "2024-09-15T08:00:00Z",
      "status": "pending",
      "haulier": "DHL Express",
      "intake_type": "full_load",
      "storage_unit_quantity": 20,
      "notes": "Fragile goods - handle with care"
    }
  }
}
'
{
  "data": {
    "id": 123,
    "type": "bookings",
    "attributes": {
      "account_id": 1,
      "consignment_reference": "CONS-2024-001",
      "direction": "inbound",
      "end_time": "2024-09-15T09:00:00Z",
      "hazardous": false,
      "location_id": 10,
      "start_time": "2024-09-15T08:00:00Z",
      "status": "pending",
      "haulier": "DHL Express",
      "intake_type": "full_load",
      "storage_unit_quantity": 20,
      "notes": "Fragile goods - handle with care"
    }
  }
}

​
Request Structure

{
  "data": {
    "type": "bookings",
    "attributes": {
      "account_id": 1,
      "location_id": 10,
      "consignment_reference": "CONS-2024-001",
      "direction": "inbound",
      "hazardous": false,
      "start_time": "2024-09-15T08:00:00Z",
      "end_time": "2024-09-15T09:00:00Z",
      "haulier": "DHL Express",
      "intake_type": "full_load",
      "container_number": "MSKU1234567",
      "storage_unit_quantity": 20,
      "notes": "Fragile goods - handle with care"
    }
  }
}

​
Required Fields

FieldTypeDescription
account_idintegerStock account ID (owner of the goods)
location_idintegerDock location ID (must have available_in_booking_diary enabled)
consignment_referencestringConsignment reference number
directionstringOne of: inbound, outbound
hazardousbooleanWhether the goods are hazardous
start_timedatetimeBooking start time (ISO 8601)
end_timedatetimeBooking end time (must be after start_time)

​
Optional Fields

FieldTypeDescription
account_referencestringAccount’s own reference
booking_referencestringBooking reference number
container_numberstringContainer number (for container intake)
haulierstringHaulier/carrier name
intake_typestringOne of: container, part_load, full_load
notesstringFree text notes
statusstringOne of: pending, arrived, departed, fail_to_arrive, cancelled (default: pending)
storage_unit_quantityintegerExpected number of storage units (e.g., pallets)

​
Slot Availability Validation

The system validates that the requested time slot is available before creating the booking.

​
Opening Times Compliance

The location (or its parent warehouse) may have opening times configured. Opening hours vary by day of week, so the system checks the specific day’s hours for both start and end times. Error Response (code 295): 
{
  "errors": [
    {
      "code": 295,
      "symbol": "outside_of_opening_times",
      "details": "Provided start time is outside of opening times",
      "source": "start_time"
    }
  ]
}

​
No Overlapping Bookings

The system uses time range overlap detection to ensure no other booking exists at the same location during the requested period. Error Response (code 296): 
{
  "errors": [
    {
      "code": 296,
      "symbol": "overlapping_bookings",
      "details": "There are overlapping bookings for the selected time slot",
      "source": "time_slot"
    }
  ]
}

​
Finding Available Slots Workflow

To find an available time slot before creating a booking:
  1. Query eligible locations - Find locations where available_in_booking_diary is true (via GraphQL)
  2. Query existing bookings - Retrieve bookings for the target date range and location (via GraphQL)
  3. Calculate gaps - Identify time gaps that fall within the location’s opening hours for the target day of week
  4. Create booking - POST /bookings with the chosen slot

Authorizations

​
Authorization
string
header
required

OAuth 2.0 authentication. Use the client credentials or authorization code flow to obtain an access token.

​
X-Clarus-Subdomain
string
header
required

The subdomain/tenant name identifying which tenant's data to access. Required for all API requests.

Body

application/json
​
data
object
required

Response

Booking created successfully

​
data
object