Create a Booking

POST /v1/parcel_bookings
Content-Type: application/json
{
  "quote_id": "<quote_id>",
  "rate_id": "<rate_id>",
  "sender": { "customer_id": "<customer_id>" },
  "recipient": {
    "name": "Ada Example",
    "phone": "+2348000000000",
    "address": { "street": "10 Example Street", "city": "Lagos", "country": "NG" }
  }
}

• Requires the quote and rate references plus both parties (see Customers and Addresses).
• The sender is an existing customer (customer_id). The recipient reuses the sender or is entered manually.
• No payment is taken at booking and no payment fields are required — invoicing happens separately against the frozen booked price.
• The response is the booked quote with parcel_id: null.

Creating a booking does not create a parcel. The booking remains a parcel quote until warehouse receipt.

Use the customer as recipient

recipient is required when customer_as_recipient is omitted or false. Set customer_as_recipient: true with sender.customer_id only when that same customer is receiving the shipment. In that case, omit recipient because the backend loads the customer’s saved name, phone, email, and address and stores them in the booking’s recipient snapshot. The response still includes recipient. A complete customer profile in your account and API mode is required; no recipient details are guessed. Do not send non-empty recipient details together with the flag; this returns 422 INVALID_PARTY to avoid conflicting instructions.

{
  "quote_id": "pq_abc123xyz",
  "rate_id": "pqrate_abc123",
  "sender": { "customer_id": "CUSTOMER-ID" },
  "customer_as_recipient": true
}

Delivery estimates come from the quote rate and remain unchanged by booking. SendHQ air quotes return a 3-day delivery estimate and a date three calendar days after rating. Ocean quotes currently return an 11-day estimate and estimated date; these are estimates, not guaranteed arrival dates.