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"
    }
  }
}
'

import requests

url = "https://clarus-api.com/api/bookings"

payload = { "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"
        }
    } }
headers = {
    "Authorization": "Bearer <token>",
    "X-Clarus-Subdomain": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Clarus-Subdomain': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
      }
    }
  })
};

fetch('https://clarus-api.com/api/bookings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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"
    }
  }
}

{
  "error": "<string>"
}

{
  "errors": [
    {
      "code": 123,
      "symbol": "<string>",
      "details": "<string>",
      "source": "<string>",
      "context": {}
    }
  ]
}

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"
    }
  }
}
'

import requests

url = "https://clarus-api.com/api/bookings"

payload = { "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"
        }
    } }
headers = {
    "Authorization": "Bearer <token>",
    "X-Clarus-Subdomain": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Clarus-Subdomain': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
      }
    }
  })
};

fetch('https://clarus-api.com/api/bookings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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"
    }
  }
}

{
  "error": "<string>"
}

{
  "errors": [
    {
      "code": 123,
      "symbol": "<string>",
      "details": "<string>",
      "source": "<string>",
      "context": {}
    }
  ]
}

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

Field	Type	Description
`account_id`	integer	Stock account ID (owner of the goods)
`location_id`	integer	Dock location ID (must have `available_in_booking_diary` enabled)
`consignment_reference`	string	Consignment reference number
`direction`	string	One of: `inbound`, `outbound`
`hazardous`	boolean	Whether the goods are hazardous
`start_time`	datetime	Booking start time (ISO 8601)
`end_time`	datetime	Booking end time (must be after start_time)

Optional Fields

Field	Type	Description
`account_reference`	string	Account’s own reference
`booking_reference`	string	Booking reference number
`container_number`	string	Container number (for container intake)
`haulier`	string	Haulier/carrier name
`intake_type`	string	One of: `container`, `part_load`, `full_load`
`notes`	string	Free text notes
`status`	string	One of: `pending`, `arrived`, `departed`, `fail_to_arrive`, `cancelled` (default: `pending`)
`storage_unit_quantity`	integer	Expected 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:

Query eligible locations - Find locations where available_in_booking_diary is true (via GraphQL)
Query existing bookings - Retrieve bookings for the target date range and location (via GraphQL)
Calculate gaps - Identify time gaps that fall within the location’s opening hours for the target day of week
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.

FlowAuthorization Code

Authorization URL: https://clarus-api.com/oauth/authorize
Token URL: https://clarus-api.com/oauth/token

FlowClient Credentials

Token URL: https://clarus-api.com/oauth/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

Show child attributes

Response

Booking created successfully

data

object

Show child attributes

​Request Structure

​Required Fields

​Optional Fields

​Slot Availability Validation

​Opening Times Compliance

​No Overlapping Bookings

​Finding Available Slots Workflow

Authorizations

Body

Response

Request Structure

Required Fields

Optional Fields

Slot Availability Validation

Opening Times Compliance

No Overlapping Bookings

Finding Available Slots Workflow