Create a parcel quote (get rates)

Create a parcel quote. Choose **direction** (`import` | `export`) and **transport_mode** (`air` | `ocean`). ### Customer identification Identify the sender with **one** of (all resolve the same parcel customer record): - `address_suffix` — customer **unique ID** (recommended), e.g. `YSDX-UGTE-1234` or `1234` (business prefix applied automatically) - `parcel_customer_token` — internal customer token **or** the same unique ID (`YSDX-UGTE-1234` or short `1234`) - `sender.name` — same value as the unique ID - Full `sender` object — name, phone, email, and address (no link required) Do not send both `address_suffix` and `parcel_customer_token`; if both are present, `parcel_customer_token` wins. **Export** requires a full **`sender`** (name, phone, origin address) — customer ID alone is for **import** only. Pickup is scheduled separately after booking, not in the quote request. Parcel-customer accounts must send one customer identifier or `sender.name` (unique ID) on **import**. ### Delivery (last mile) `recipient` is always required. It defines where cargo is delivered: - **Last mile on** — customer's full delivery address (name, phone, email, street, city, state, postal code, country) - **Last mile off** — your business address in Nigeria (same as the booking link when last mile is disabled) ### Flow matrix | direction | transport_mode | Quote status | Next step | | --- | --- | --- | --- | | `export` | `air` | `pending` | Pick a rate from `rates[]`, then `POST /v1/packages/{id}/create_shipment` | | `import` | `air` | `pending` | Confirm with `POST /v1/packages/{id}/create_shipment`; no carrier purchase | | `import` | `ocean` | `pending` | One `Ocean Freight` rate in `rates[]`; confirm with `POST /v1/packages/{id}/create_shipment` | | `export` | `ocean` | `pending` | One `Ocean Freight` rate in `rates[]`; confirm with `POST /v1/packages/{id}/create_shipment` | ### Pricing - **`estimated_price`** — NGN total from `selected_rate.rate` when present. For pending ocean, use the single `rates[]` row until it is confirmed. Final amount may change at warehouse receive; customer payment is invoiced separately. - **`booked_at`** — when the quote became `booked`. **`purchased_at`** is the same timestamp (legacy field). **Request shape:** use flat fields (`dest_*`, etc.) — same as the Send dashboard — **or** nested `sender` / `recipient` objects. Import ocean does not require `origin_*` when using `parcel_customer_token` or `address_suffix`. **Export air** uses the `package` object (weight, dimensions, `item_description`). **Import air** uses `packages[]` — one row per cargo unit: ```json "packages": [ { "package_type": "Pallet", "weight": 120, "length": 120, "width": 100, "height": 80 } ] ``` **Ocean** uses `packages[]` — one row per cargo type. Fixed containers use the exact values `20'`, `40'`, `40' HC`, `40' REEF`, or `20' REEF` and are priced per container. LCL is priced per CBM. Ro-Ro and Breakbulk are priced per RT (the greater of CBM and metric tonnes): ```json "packages": [ { "container_size": "40'", "quantity": 2, "commodity": "Textiles" } ] ``` Import ocean origin (China warehouse) and sender contact are applied automatically from the linked parcel customer — do not send `origin_*` or `origin_mobile` unless overriding. Import ocean FCL pricing uses baseline USD rates per container, converted to NGN. LCL is priced per CBM. Ro-Ro and Breakbulk are priced per RT. **Rate validity:** pending **export air** and **ocean** rates include a `created_at` timestamp on each rate. After **one hour**, `GET` the quote again to refresh pricing. `create_shipment` returns `QUOTE_RATE_OUTDATED` if you use a stale `rate_id`. **Ocean transit:** ocean rates return `estimated_delivery_days: 11` and `estimated_delivery_date`. Typical door-to-door transit is 10–12 days (best ~7, worst case up to 14).