Create a booking

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. Add-ons are inherited unchanged; including addons returns 400.
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. If arrival_window_to is omitted, the applicable route arrival-window policy supplies the duration, defaulting to one hour when no policy applies. arrival_window_ref defaults to origin; use destination for dropoff-window scheduling. Booking can fail if the requested window cannot be reserved.

When quote_id is provided, the booking copies the quote's complete route, including each stop's apartment or suite. It ignores origin, destination, and stops in the booking request. Set apartment or suite values when creating the quote.

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.

OAuth scopes

one of:

org
org:write

user
user:write

Body

required

application/json

arrival_window_id
Type: string
required

Pre-selected arrival window ID from the schedule endpoint. Cannot be used together with arrival_window_from/to.

addons
Type:

Complete desired addon slugs. Omit to preserve the selection, or send [] to clear it. New quotes and direct bookings start without addons. Cannot be combined with quote_id when creating a booking (400). Booking addon edits update the existing quote in place, preserving its ID and retained addon prices. Invalid or unavailable additions reject the request without partial changes. A later booking-creation admission or payment failure follows the existing failed-booking lifecycle.

arrival_window_from
Type: stringFormat: date-time

Custom future arrival window start time (ISO 8601). Cannot be used together with arrival_window_id.

arrival_window_ref
Type: "origin" or "destination"enum

Reference point for the arrival window timing. Defaults to 'origin'. Use 'destination' for dropoff-window scheduling.

arrival_window_to
Type: stringFormat: date-time

Custom future arrival window end time (ISO 8601). Optional; uses the route arrival-window policy duration, or 1 hour when no policy applies.

contacts
Type:

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.

Properties: 4
customer
Type:

Optional customer contact details. Only available for organization bookings.

Properties: 3
customer_notifications_enabled
Type: boolean

Whether Lugg sends automated notifications to the booking user, customer, and contacts. Defaults to true. Webhooks and operational notifications are unaffected.

description
Type: string

Optional description or special instructions for the booking.

destination

DEPRECATED: Use stops array instead. Dropoff location.

Type: Format: uuid
deprecated

Location UUID from a previously created location

metadata
Type: object

Custom metadata object for storing additional information.

order_number
Type: string

Order number or reference identifier for the booking.

origin

DEPRECATED: Use stops array instead. Pickup location.

Type: Format: uuid
deprecated

Location UUID from a previously created location

photo_urls
Type: array of stringFormat: uri

Array of photo URLs showing items to be moved.

product
Type: enum

Service type (pickup, van, xl, etc.).

values
lite

Single lugger in a pickup truck

pickup

Two luggers in a pickup truck

van

Two luggers in a cargo van

xl

Two luggers in a sprinter van

box

Two luggers in a box truck

quote_id
Type: stringFormat: uuid

Pre-calculated quote ID that contains the authoritative route and product.

stops
Type: array of object 2…7

Array of stops in route order. First stop is origin, last is destination.

Properties: 5
test_specifications
Type: object
write-only

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.

Properties: 1
tip

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.

Type: 0enum
const:
0

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.

Responses

application/vnd.lugg+json;version=2
application/vnd.lugg+json;version=2
application/vnd.lugg+json;version=2
application/vnd.lugg+json;version=2
application/vnd.lugg+json;version=2
application/vnd.lugg+json;version=2
application/vnd.lugg+json;version=2

post/bookings

curl https://api.lugg.com/bookings \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "addons": [
    "assembly"
  ],
  "quote_id": "",
  "stops": [
    {
      "location": "123e4567-e89b-12d3-a456-426614174000",
      "instructions": null,
      "address2": null,
      "floor": null,
      "elevator": null
    }
  ],
  "product": "pickup",
  "arrival_window_id": "",
  "arrival_window_from": "",
  "arrival_window_to": "",
  "arrival_window_ref": "origin",
  "description": "",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone_number": "+14155551234"
  },
  "contacts": [
    {
      "name": "Store Team",
      "phone_number": "+14155550100",
      "email": "store@example.com",
      "stop_positions": [
        0
      ]
    }
  ],
  "photo_urls": [
    ""
  ],
  "metadata": {},
  "order_number": "",
  "tip": 0,
  "customer_notifications_enabled": true,
  "test_specifications": {
    "mode": "auto"
  }
}'

Show Schema

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "hid": "67GH8J",
  "created_at": "2026-09-25T18:00:11.460Z",
  "updated_at": "2026-09-25T18:00:11.460Z",
  "product": "pickup",
  "origin": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "IKEA Emeryville",
    "address2": "APT C",
    "coordinates": [
      125.6,
      10.1
    ],
    "address": {
      "number": "78",
      "street": "1st St.",
      "street2": "APT C",
      "locality": "San Francisco",
      "region": "CA",
      "postal_code": "94131"
    },
    "location_type": "street_address"
  },
  "destination": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "IKEA Emeryville",
    "address2": "APT C",
    "coordinates": [
      125.6,
      10.1
    ],
    "address": {
      "number": "78",
      "street": "1st St.",
      "street2": "APT C",
      "locality": "San Francisco",
      "region": "CA",
      "postal_code": "94131"
    },
    "location_type": "street_address"
  },
  "route": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "position": 0,
      "location": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "IKEA Emeryville",
        "address2": "APT C",
        "coordinates": [
          125.6,
          10.1
        ],
        "address": {
          "number": "78",
          "street": "1st St.",
          "street2": "APT C",
          "locality": "San Francisco",
          "region": "CA",
          "postal_code": "94131"
        },
        "location_type": "street_address"
      },
      "instructions": null,
      "address2": null,
      "floor": null,
      "elevator": null
    }
  ],
  "arrival_window": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "available": true,
    "ondemand": true,
    "start_at": null,
    "end_at": null,
    "label": "2:00 PM - 4:00 PM"
  },
  "arrival_window_ref": "origin",
  "description": null,
  "order_number": "ORD-12345",
  "tip": 0,
  "customer_notifications_enabled": true,
  "photo_urls": [
    "https://example.com"
  ],
  "state": "created",
  "dispatch_state": "origin_pending",
  "share_url": "https://example.com",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone_number": "+14155551234"
  },
  "contacts": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Store Team",
      "phone_number": "+14155550100",
      "email": "store@example.com",
      "notification_scope": "all",
      "stop_positions": [
        0
      ],
      "stops": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "position": 0
        }
      ]
    }
  ],
  "crew": null,
  "dispatch": {
    "state": "stop_pending",
    "route_position": 0,
    "route_stop_id": null,
    "events": [
      {
        "state": "stop_pending",
        "route_position": 0,
        "route_stop_id": null,
        "triggered_at": "2026-09-25T18:00:11.460Z",
        "photo_urls": [
          "https://example.com"
        ]
      }
    ]
  },
  "quote": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "origin": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "IKEA Emeryville",
      "address2": "APT C",
      "coordinates": [
        125.6,
        10.1
      ],
      "address": {
        "number": "78",
        "street": "1st St.",
        "street2": "APT C",
        "locality": "San Francisco",
        "region": "CA",
        "postal_code": "94131"
      },
      "location_type": "street_address"
    },
    "destination": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "IKEA Emeryville",
      "address2": "APT C",
      "coordinates": [
        125.6,
        10.1
      ],
      "address": {
        "number": "78",
        "street": "1st St.",
        "street2": "APT C",
        "locality": "San Francisco",
        "region": "CA",
        "postal_code": "94131"
      },
      "location_type": "street_address"
    },
    "route": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "position": 0,
        "location": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "IKEA Emeryville",
          "address2": "APT C",
          "coordinates": [
            125.6,
            10.1
          ],
          "address": {
            "number": "78",
            "street": "1st St.",
            "street2": "APT C",
            "locality": "San Francisco",
            "region": "CA",
            "postal_code": "94131"
          },
          "location_type": "street_address"
        },
        "instructions": null,
        "address2": null,
        "floor": null,
        "elevator": null
      }
    ],
    "travel_duration": 1,
    "travel_distance": 1,
    "product": "pickup",
    "fare_structure": {
      "base": 1,
      "per_mile": 1,
      "included_miles": 0,
      "per_minute_labor": 1,
      "per_minute_travel": 1,
      "per_stop": 1
    },
    "fare_estimate": [
      {
        "total": 1,
        "base": 1,
        "labor": 1,
        "travel_distance": 1,
        "billed_miles": 0,
        "travel_duration": 1,
        "stops": 1,
        "adjustments": [
          {
            "kind": "refund",
            "name": "string",
            "amount": 1,
            "created_at": "2026-09-25T18:00:11.460Z"
          }
        ]
      }
    ],
    "addons": [
      {
        "slug": "assembly",
        "name": "Assembly",
        "description": "Our crew will assemble your furniture at the destination.",
        "amount": 1500
      }
    ],
    "created_at": "2026-09-25T18:00:11.460Z",
    "updated_at": "2026-09-25T18:00:11.460Z"
  },
  "fare": {
    "total": 1,
    "base": 1,
    "labor": 1,
    "travel_distance": 1,
    "billed_miles": 0,
    "travel_duration": 1,
    "stops": 1,
    "adjustments": [
      {
        "kind": "refund",
        "name": "string",
        "amount": 1,
        "created_at": "2026-09-25T18:00:11.460Z"
      }
    ]
  },
  "metadata": null
}

Created