# Shipments

A shipment is a booking with a courier: parcels, two addresses, a service level
and a price. Creating one charges your Bob Go account and puts the consignment
in front of the courier.

**Rate before you book.** Which couriers and service levels are available
depends on the addresses and the parcels: a service level that works for a
Johannesburg business address may not exist for a residential address in a
small town. A `provider_slug` or `service_level_code` Bob Go does not know, or a
courier not enabled on your account, is a `400` straight away. A real service
level that did not come back in a rate request is accepted, and the shipment
then fails with `submission_status: "no-rates"` once Bob Go rates it. See
[Rates](../8_Rates/README.md).

**Submission is asynchronous.** The response arrives before the courier has
seen the shipment. `submission_status` moves from `pending-rates` through
`pending-submission` to `success`, or to a failure Bob Go may retry on its own.
`status` is empty until then, and afterwards tracks the parcel itself, from
`pending-collection` through to `delivered`. Both lists are in
[Create a shipment](shipment_create.md#statuses).

Build for that: read `submission_status` rather than assuming the booking
worked, and subscribe to the `shipment_submission_status/updated` and
`tracking/updated` webhooks instead of polling. See
[Webhooks](../11_Webhooks/README.md).

Common causes of `failed-indefinitely` are missing or invalid address detail,
insufficient funds once the shipment is rated, and a problem at the courier.
`failed_reason` says which.

## Endpoints

| | |
| --- | --- |
| [`POST /v2/shipments`](shipment_create.md) | Book a courier. |
| [`GET /v2/shipments`](shipment_list.md) | List and filter shipments. |
| [`POST /v2/shipments/cancel`](shipment_cancel.md) | Cancel a booking. |
| [`GET /v2/shipments/waybill`](shipment_waybill.md) | A4/A5/A6 waybill. Returns a link to the PDF. |
| [`GET /v2/shipments/sticker-waybill`](shipment_sticker_waybill.md) | Sticker label, as a link to a PDF or ZPL inline. |
| [`GET /v2/shipments/pod`](shipment_pod.md) | Proof of delivery. |
| [`GET /v2/file-history`](file_history.md) | Collect a label batch that was queued rather than returned inline. |