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.

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.

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.

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	Book a courier.
GET /v2/shipments	List and filter shipments.
POST /v2/shipments/cancel	Cancel a booking.
GET /v2/shipments/waybill	A4/A5/A6 waybill. Returns a link to the PDF.
GET /v2/shipments/sticker-waybill	Sticker label, as a link to a PDF or ZPL inline.
GET /v2/shipments/pod	Proof of delivery.
GET /v2/file-history	Collect a label batch that was queued rather than returned inline.