Important concepts

Important concepts

A few objects and ideas turn up across the whole API. Reading these once saves re-reading them on every endpoint.

Addresses

An address is always the same object, whatever key it appears under: collection_address and delivery_address have identical fields.

"collection_address": {
  "type": "business",
  "company": "Bob Go",
  "street_address": "125 Dallas Avenue",
  "local_area": "Menlyn",
  "city": "Pretoria",
  "zone": "Gauteng",
  "country": "ZA",
  "code": "0181"
}
Field Type Notes
type string business, residential, locker or unknown. Defaults to unknown. Affects both price and which service levels are offered.
company string Optional.
street_address string Street number and name.
local_area string Suburb.
city string
zone string Province, as its name (Gauteng) or its code (GP). Bob Go stores the code, so addresses come back with EC, FS, GP, KZN, LP, MP, NC, NW or WC, and filters on the province take the code.
code string Postal code.
country string ZA or South Africa. Bob Go ships within South Africa only, and an empty value is read as South Africa. Addresses come back with South Africa.
lat, lng number Optional. Supply them and Bob Go skips geocoding.

Send the fields separately rather than packing everything into street_address. Rating and courier acceptance both depend on the address resolving to a real point on the map, and a single free-text line geocodes badly.

Parcels

Wherever a set of parcels is sent, it is the same array.

"parcels": [
  {
    "description": "Box",
    "submitted_length_cm": 42.5,
    "submitted_width_cm": 38.5,
    "submitted_height_cm": 5.5,
    "submitted_weight_kg": 3,
    "custom_parcel_reference": "custom reference"
  },
  {
    "description": "Flyer",
    "submitted_length_cm": 42.5,
    "submitted_width_cm": 38.5,
    "submitted_height_cm": 5.5,
    "submitted_weight_kg": 1.3
  }
]
Field Type Notes
submitted_length_cm number Max 1000.
submitted_width_cm number Max 1000.
submitted_height_cm number Max 1000.
submitted_weight_kg number A parcel over the maximum weight is rejected, and the message gives the limit. Each service level also has its own limit, on the total and the volumetric weight: a consignment over it fails that one rate with the limit in failed_reason, rather than failing the request.
description string Optional.
custom_parcel_reference string Optional, your own reference.

The submitted_ prefix is deliberate: these are the dimensions you declared. Couriers re-measure, and the values they come back with land in the matching actual_ fields on the shipment. Couriers charge on the greater of actual and volumetric weight, so dimensions matter as much as weight, and a parcel declared smaller than it is will be re-rated after collection.

Rates at checkout vs. Rates

Two endpoints return shipping prices, and they answer different questions.

Rates at checkout (POST /v2/rates-at-checkout) returns the options you have configured in Bob Go: your service levels, your zones, your markups, your exclusions. It is what a buyer should see in a cart. Each option is priced the way you set it up, whether that is a dynamic, fixed, courier or formula rate, and it can deliberately return nothing for an area you do not ship to.

Rates (POST /v2/rates) returns what each courier will cost you for a specific consignment, with none of your checkout rules applied. It is what you use to decide which courier to book.

Rates at checkout Rates
Answers "What should this buyer be charged?" "What will each courier charge me?"
Shaped by Your Bob Go configuration The couriers
Typical caller Your cart or checkout page Your fulfilment code
Returns Priced options, buyer-facing Per-courier quotes with a rate_amount

The two are not interchangeable. A buyer quoted a checkout rate is not being quoted the courier's price, and the difference between them is your shipping margin.

Pickup points

Shipments can collect from, or deliver to, a locker or counter instead of an address. Pickup points work through the same rates, checkout-rates and shipment endpoints, with a couple of extra fields. See Pickup points.

View as Markdown