Shipments

Create a shipment

POST /v2/shipments Bearer token

Books a courier for a set of parcels. You choose the courier and service level, usually one of the rates returned by POST /v2/rates, and Bob Go creates the shipment, charges your account and submits it to the courier.

The response returns as soon as the shipment exists, unless you ask it to wait with timeout. Rating and submission to the courier happen asynchronously, so the price and the courier's own waybill number appear on the shipment a short while after it is created.

Request

Field Type Required Notes
provider_slug string yes The courier, e.g. tcg. Take it from the rate you selected.
service_level_code string yes The service level, e.g. ECO. Take it from the rate you selected.
collection_address object yes Same shape as on POST /v2/rates. Not needed when you send collection_pickup_point_location_id.
delivery_address object yes Not needed when you send delivery_pickup_point_location_id.
parcels array yes At least one parcel.
collection_contact_name string yes First name.
delivery_contact_name string yes First name.
selected_rate_request_id integer no The id from the rates response. Send it so the quoted rate is used for the funds check.
declared_value number no Value of the contents in ZAR.
custom_order_number string no Your own order number. Shows on the shipment and on labels, and comes back as meta.custom_order_number.
custom_tracking_reference string no Your own tracking reference.
collection_min_date timestamp no Earliest date the courier may collect. Leave it out, or send a date in the past, for the earliest possible. Bob Go moves it to the next business day, and past the service level's cut-off time.
collection_after / collection_before string no Collection window on the collection date, hh:mm:ss (hh:mm is padded), e.g. 09:00:00 / 17:00:00. Send both or neither, with the hour zero-padded, between 08:00:00 and 17:00:00. Defaults to the whole of that window.
instructions_collection string no Free-text note for the collection driver.
instructions_delivery string no Free-text note for the delivery driver.
shipping_label_emails array of string no Email the label to these addresses once it is generated.
collection_contact_surname string no
collection_contact_mobile_number string no
collection_contact_email string no Checked when you send it.
delivery_contact_surname string no
delivery_contact_mobile_number string no Used for delivery notifications, so worth sending.
delivery_contact_email string no Used for tracking emails. Checked when you send it.
collection_pickup_point_location_id integer no Collect from a pickup point instead of an address.
delivery_pickup_point_location_id integer no Deliver to a pickup point / locker instead of an address. Ignored on a door-to-door service level.
timeout integer no Milliseconds to wait for the submission to settle before responding, capped at 25000. As on POST /v2/rates, the last five seconds are reserved, so anything up to 5000 does not wait. Defaults to 0.

Contact fields take a first name and surname here. POST /v2/rates takes a single *_full_name, but also accepts *_contact_name and *_contact_surname and joins them, so you can send the same contact fields to both.

Response

See the example response.

A new shipment starts with submission_status: "pending-rates" and an empty status. Unless you sent a long enough timeout, that is what the response shows. charged_amount and charged_weight_kg fill in once Bob Go has rated the shipment.

Store tracking_reference: it is Bob Go's identifier for the shipment and what you use to look it up, track it and match webhook events. provider_tracking_reference is the courier's own waybill number and is filled in once the courier accepts the submission.

Statuses

submission_status tracks getting the shipment to the courier:

Status Meaning
pending-rates Created, waiting on the courier's rate.
pending-submission Rated, queued for the courier.
success The courier accepted the shipment.
no-rates No bookable rate for this lane.
failed-will-retry Transient failure. Bob Go will retry.
failed-indefinitely Failed for good; failed_reason says why.

status tracks the parcel in the real world. It is empty until the courier accepts the shipment, then one of pending-collection, awaiting-dropoff, collected, in-transit, out-for-delivery, ready-for-pickup, delivered, finalised, returned-to-sender, collection-exception, delivery-exception, failed-collection, failed-delivery, cancelled, cancelled-by-courier.

Notes

  • Creating a shipment charges your Bob Go account once it has been rated. Before that, Bob Go checks your funds: against the quoted rate when you send selected_rate_request_id, and against your balance and credit limit either way. Either check fails with a 400 saying the account has insufficient funds.
  • Funds are checked again when the courier's rate arrives. A shipment that fails there ends failed-indefinitely, with the insufficient-funds message as failed_reason.
  • Shipments on a courier account connected with your own credentials skip the funds checks.
  • Rates can move between quoting and booking. charged_amount on the shipment is authoritative, not the earlier quote.
View as Markdown