---
title: "Create a booking"
method: POST
path: "/bookings"
tags: ["Bookings"]
---

# Create a booking

`POST /bookings`

Creates a new booking for a Lugg delivery service.

You can create a booking in three ways:
- **Using a quote**: Provide `quote_id` + arrival window details
- **Two-stop booking**: Provide `origin` + `destination` + `product` + arrival window details
- **Multi-stop booking**: Provide `stops` array + `product` + arrival window details

Arrival window is required. Provide either `arrival_window_id` (from the schedules endpoint) or `arrival_window_from` for a custom future ISO 8601 time. `arrival_window_to` is optional and defaults to one hour after `arrival_window_from`. `arrival_window_ref` defaults to `origin`; use `destination` for dropoff-window scheduling. Booking can fail if the requested window cannot be reserved.

`customer` is optional and organization-only.

In the sandbox, set `test_specifications.mode` to `auto` to automatically dispatch and complete the booking through the normal webhook and billing flow. The simulation starts immediately and does not wait for the requested arrival-window time.

All other parameters are optional.

## Request body

- union
  - object
    - `quote_id` string, uuid — Pre-calculated quote ID that contains origin, destination, and product.
    - `stops` object[] — Array of stops in route order. First stop is origin, last is destination.
      - `location` union, required
        - string, uuid — Location UUID from a previously created location
        - number[] — Coordinates as [longitude, latitude] in decimal degrees
        - string — Free-form address string (street address, business name, or place)
      - `instructions` string, nullable — Operational instructions for this stop.
    - `origin` union
      - string, uuid — Location UUID from a previously created location
      - number[] — Coordinates as [longitude, latitude] in decimal degrees
      - string — Free-form address string (street address, business name, or place)
    - `destination` union
      - string, uuid — Location UUID from a previously created location
      - number[] — Coordinates as [longitude, latitude] in decimal degrees
      - string — Free-form address string (street address, business name, or place)
    - `product` 'lite' | 'pickup' | 'van' | 'xl' | 'box' — Product type for the service
    - `arrival_window_id` string, required — Pre-selected arrival window ID from the schedule endpoint. Cannot be used together with arrival_window_from/to.
    - `arrival_window_from` string, date-time — Custom future arrival window start time (ISO 8601). Cannot be used together with arrival_window_id.
    - `arrival_window_to` string, date-time — Custom future arrival window end time (ISO 8601). Optional; defaults to 1 hour after arrival_window_from.
    - `arrival_window_ref` 'origin' | 'destination' — Reference point for the arrival window timing. Defaults to 'origin'. Use 'destination' for dropoff-window scheduling.
    - `description` string — Optional description or special instructions for the booking.
    - `customer` Customer — Customer contact information. Must provide at least email or phone_number (or both).
      - `name` string — Customer's name
      - `email` string, email — Customer's email address
      - `phone_number` string — Customer's phone number in E.164 format
    - `contacts` ContactInput[] — Optional notification contacts. Each contact may set `stop_positions` to scope it to specific route stops ([0] = pickup, last = dropoff); omitted/empty applies to all stops. When contacts are provided they are the booking's notification recipients — the `customer` record is not also added as a contact.
      - `name` string — Contact's name
      - `phone_number` string, required — Contact's phone number in E.164 format
      - `email` string, email — Contact's email address
      - `stop_positions` integer[] — Route positions (0-indexed) this contact applies to. 0 = origin/pickup, last = destination/dropoff, intermediate values = intermediate stops. Omitted or empty applies the contact to all stops. Positions outside the route (negative or >= the number of stops) are rejected with a 400.
    - `photo_urls` string[] — Array of photo URLs showing items to be moved.
    - `metadata` object — Custom metadata object for storing additional information.
    - `order_number` string — Order number or reference identifier for the booking.
    - `tip` union — Optional booking-level tip in integer cents (USD). Use 0 for no tip; positive values must be at least 100 cents. The tip can only be set when creating a booking and is included in the final fare.
      - 0
      - integer
    - `test_specifications` object — Sandbox only. Automatically dispatches and completes the booking through the normal webhook and billing flow. Simulation starts immediately and does not wait for the requested arrival-window time.
      - `mode` 'auto', required
  - object
    - `quote_id` string, uuid — Pre-calculated quote ID that contains origin, destination, and product.
    - `stops` object[] — Array of stops in route order. First stop is origin, last is destination.
      - `location` union, required
        - string, uuid — Location UUID from a previously created location
        - number[] — Coordinates as [longitude, latitude] in decimal degrees
        - string — Free-form address string (street address, business name, or place)
      - `instructions` string, nullable — Operational instructions for this stop.
    - `origin` union
      - string, uuid — Location UUID from a previously created location
      - number[] — Coordinates as [longitude, latitude] in decimal degrees
      - string — Free-form address string (street address, business name, or place)
    - `destination` union
      - string, uuid — Location UUID from a previously created location
      - number[] — Coordinates as [longitude, latitude] in decimal degrees
      - string — Free-form address string (street address, business name, or place)
    - `product` 'lite' | 'pickup' | 'van' | 'xl' | 'box' — Product type for the service
    - `arrival_window_id` string — Pre-selected arrival window ID from the schedule endpoint. Cannot be used together with arrival_window_from/to.
    - `arrival_window_from` string, date-time, required — Custom future arrival window start time (ISO 8601). Cannot be used together with arrival_window_id.
    - `arrival_window_to` string, date-time — Custom future arrival window end time (ISO 8601). Optional; defaults to 1 hour after arrival_window_from.
    - `arrival_window_ref` 'origin' | 'destination' — Reference point for the arrival window timing. Defaults to 'origin'. Use 'destination' for dropoff-window scheduling.
    - `description` string — Optional description or special instructions for the booking.
    - `customer` Customer — Customer contact information. Must provide at least email or phone_number (or both).
      - `name` string — Customer's name
      - `email` string, email — Customer's email address
      - `phone_number` string — Customer's phone number in E.164 format
    - `contacts` ContactInput[] — Optional notification contacts. Each contact may set `stop_positions` to scope it to specific route stops ([0] = pickup, last = dropoff); omitted/empty applies to all stops. When contacts are provided they are the booking's notification recipients — the `customer` record is not also added as a contact.
      - `name` string — Contact's name
      - `phone_number` string, required — Contact's phone number in E.164 format
      - `email` string, email — Contact's email address
      - `stop_positions` integer[] — Route positions (0-indexed) this contact applies to. 0 = origin/pickup, last = destination/dropoff, intermediate values = intermediate stops. Omitted or empty applies the contact to all stops. Positions outside the route (negative or >= the number of stops) are rejected with a 400.
    - `photo_urls` string[] — Array of photo URLs showing items to be moved.
    - `metadata` object — Custom metadata object for storing additional information.
    - `order_number` string — Order number or reference identifier for the booking.
    - `tip` union — Optional booking-level tip in integer cents (USD). Use 0 for no tip; positive values must be at least 100 cents. The tip can only be set when creating a booking and is included in the final fare.
      - 0
      - integer
    - `test_specifications` object — Sandbox only. Automatically dispatches and completes the booking through the normal webhook and billing flow. Simulation starts immediately and does not wait for the requested arrival-window time.
      - `mode` 'auto', required

## Response `201`

Created

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `403` — Insufficient scopes
- `409` — Conflict
- `422` — Business logic errors
- `503` — Service unavailable

---

[API](https://skmtc.net/lugg/apis/lugg-partner-api.md) · [All operations](https://skmtc.net/lugg/apis/lugg-partner-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lugg/lugg-partner-api/revisions/cdae4166b346/schema)