> For the complete documentation index, see [llms.txt](https://support.ordereazi.com/central/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.ordereazi.com/central/developers/api-guides/shipments.md).

# Shipments

Get courier quotes, book a courier for an order, and read or record shipments with the OrderEazi API.

Your shop may want to show a delivery price at checkout, or book the courier when the order is placed. You may also need to tell OrderEazi about a parcel you sent another way. The OrderEazi API works with the courier apps the organisation has installed, and records every shipment on its project (OrderEazi's record of the order).

### Before you start

You'll need:

* **A courier app:** The organisation installs one from the App gallery, such as Courier Guy or ShipLogic.
* **Permissions:** Courier quotes, courier lists, and reading shipments need **Read** on **For Administrative Data**. Recording a shipment needs **Write** on **For Administrative Data**. Booking a courier for an order needs **Write** on **For Project**.
* **Product sizes:** For quotes worked out from products, each product needs its dimensions and weight in OrderEazi.

### How to get a courier quote

1. Call `GET /api/courier/list` to get the installed couriers. Each has an `Id`.
2. Send a POST to `/api/courier/quote`, with that `Id` as `AppId`.

Send either `Parcels`, if you've packed already, or `Products`, to have OrderEazi pack them into the organisation's boxes:

```json
{
  "AppId": 4,
  "ServiceLevel": "DEFAULT",
  "Origin": { "Address1": "1 Depot Rd", "Suburb": "Midrand", "City": "Johannesburg", "Province": "Gauteng", "PostalCode": "1685", "Country": "ZA" },
  "Destination": { "Address1": "12 Main Rd", "Suburb": "Rosebank", "City": "Johannesburg", "Province": "Gauteng", "PostalCode": "2196", "Country": "ZA" },
  "Products": [ { "Code": "CHAIR-01", "Quantity": 2 } ]
}
```

`"ServiceLevel": "DEFAULT"` returns every service the courier offers. Each courier quote in `Data.Quotes` has a `ServiceLevelCode`, a `ServiceLevelDescription`, a `QuoteCost`, delivery dates, and the `Parcels` it was worked out for. Courier quotes aren't held, so book soon after you get one.

To list the organisation's standard boxes, call `GET /api/courier/boxes`. Sizes are in centimetres.

### How to book a courier

> **Warning:** Booking sends the booking to the courier. Check the order and its parcels before you book.

Book the courier with the order, by adding a `ShippingRequest` to `POST /api/order/{channel}`. Or book it later, for an order that's already in OrderEazi, with `POST /api/order/ship`:

```json
{
  "AppId": 4,
  "ProjectNumber": "PRO001234",
  "ServiceLevelCode": "ECO",
  "ServiceLevelDescription": "Economy",
  "Cost": { "QuoteCurrency": { "CurrencyISO": "ZAR" }, "Cost": 120.50, "IncludesTax": true },
  "Origin": { "CompanyName": "Warehouse", "Address1": "1 Depot Rd", "City": "Johannesburg", "PostalCode": "1685", "Country": "ZA", "Phone": "0110000000" },
  "Destination": { "CompanyName": "Clientco", "Address1": "12 Main Rd", "City": "Johannesburg", "PostalCode": "2196", "Country": "ZA", "Phone": "0115550000" },
  "Parcels": [
    {
      "Number": "1", "Kilograms": 12.5, "Length": 60, "Width": 50, "Height": 90,
      "Products": [ { "ProjectLineId": "b2f4c1d0-7c1e-4a8b-9d3f-0a1b2c3d4e5f", "Quantity": 2 } ]
    }
  ]
}
```

* **From a courier quote:** Copy the chosen quote's `ServiceLevelCode`, `ServiceLevelDescription`, and `QuoteCost` (as `Cost`), and its `Parcels`. Then list each parcel's order lines, as below.
* **Order lines:** Each parcel lists the order lines it carries, by `ProjectLineId` from `GET /api/project/{pro}/lines`, where `{pro}` is the project number. You can't ship more of a line than is left to ship.
* **Shipping charge:** The courier's cost is added to the order as a shipping line, unless you send `"FreeShipping": true`.

The response's `ShippingResponse` has the `WaybillNumber`, and links to the waybill and labels. Booking doesn't create a Delivery Note or change the order's status.

### How to read shipments

`GET /api/shipment/list/{pro}` returns an order's shipments, where `{pro}` is the project number. `GET /api/shipment/{reference}` returns one shipment, by the courier's waybill number.

Each shipment has its `Courier`, `CourierReference` (the waybill number), `ShipmentStatus`, and parcels.

### How to record a shipment booked elsewhere

If you booked the courier outside OrderEazi, record it on the project with `POST /api/shipment`:

```json
{
  "PrimaryProjectNumber": "PRO001234",
  "Courier": "Local Courier",
  "CourierReference": "LC-998877",
  "ShipmentRequest": "{\"booking\":\"your request\"}",
  "ShipmentResponse": "{\"booking\":\"the courier's response\"}"
}
```

All five fields are required. `ShipmentRequest` and `ShipmentResponse` are text, usually the raw request you sent to the courier and the response you got back. Recording a shipment doesn't book a courier, add a charge, or check for duplicates.

### Related pages

* [Receiving orders from a sales channel](/central/developers/api-guides/receiving-orders-from-a-sales-channel.md): book shipping with the order
* [Projects and documents](/central/developers/api-guides/projects-and-documents.md): get an order's line IDs