Pickup points

Get pickup point locations

GET /v2/locations?lat=-25.785641&lng=28.278871&stacked_height=5&stacked_width=38&stacked_length=40&total_weight=2 Bearer token

A pickup point is a locker or a staffed counter that stands in for a street address. It can be either end of a shipment: collect from one, deliver to one, or both.

This endpoint finds them: by id, near a point, or inside a map area, optionally leaving out the ones a parcel will not physically fit into. Pickup points do not have their own rating or booking endpoints. They work through Rates at checkout, Rates and Shipments, with a couple of extra fields identifying the location instead of an address.

Two ways in

Let checkout choose

The buyer picks a pickup point option at checkout, and you carry the identifiers through the rest of the flow.

  1. Call POST /v2/rates-at-checkout. Pickup point options come back with type: "pickup-point".
  2. The chosen rate carries pickup_point_location_id and provider_slug.
  3. Pass those into POST /v2/rates as collection_pickup_point_location_id or delivery_pickup_point_location_id, plus pickup_point_provider_slug.
  4. Pass the same location id into POST /v2/shipments, plus provider_slug.

A checkout rate for a pickup point looks like this:

{
  "id": 1731,
  "service_name": "Bob Box Locker - Shiplogic Locker Test (approx. 0.0 km)",
  "service_code": "bobgo_PP_1731_102_107_2",
  "total_price": 44.61,
  "type": "pickup-point",
  "pickup_point_location_id": 107,
  "provider_slug": "demo",
  "service_level_code": "BOXL-S"
}

Choose the location yourself

Show the buyer a map or a list, and drive it from GET /v2/locations.

  1. Fetch locations near the buyer, or inside the map area they are looking at.
  2. Take the id of the one they pick, together with its provider_slug.
  3. Rate with that id as collection_pickup_point_location_id or delivery_pickup_point_location_id, and pickup_point_provider_slug.
  4. Book with the same location id and provider_slug.

Fields when rating

Scenario Send
Pickup point → door collection_pickup_point_location_id, pickup_point_provider_slug
Door → pickup point delivery_pickup_point_location_id, pickup_point_provider_slug
Pickup point → pickup point both location ids, plus pickup_point_provider_slug

Fields when booking

Scenario Send
Pickup point → door collection_pickup_point_location_id, provider_slug
Door → pickup point delivery_pickup_point_location_id, provider_slug
Pickup point → pickup point both location ids, plus provider_slug

Both ends must belong to the same provider. A shipment cannot run between two pickup points served by different couriers, and rating a mixed pair gives prices you cannot book.

Finding locations

Use one of these three ways:

Send
One specific location location_id and provider_slug
Near an address lat and lng
Inside a map area min_lat, max_lat, min_lng, max_lng, all four

lat and lng must be sent together, or the call fails with Invalid coordinates. provider_slug is required whenever location_id is used. Sending more than one way does not fail: location_id is used first, then the map area, then lat and lng, and the rest is ignored.

A Bob Box locker scheduled for removal from the network stops appearing in searches 10 days before its removal date, so a buyer is not offered a locker that will be gone before their parcel reaches it. A lookup by location_id still returns it, so a locker somebody has already chosen keeps resolving.

Name Type Notes
location_id integer A specific location.
provider_slug string Restrict to one provider. Required with location_id.
provider_slugs array of string Restrict to several providers. provider_slug overrides it.
lat, lng number Search around this point.
min_lat, max_lat, min_lng, max_lng number Bounding-box search.
limit integer Cap the number of locations returned per provider, so limit=1 with two providers returns two. Leave it out and each provider applies its own limit.

Filtering by parcel size

These four are optional, and only take effect when all four are sent. Where there is more than one parcel, send the stacked dimensions, because locker compartments are checked against a single footprint. Only Bob Box lockers are checked this way.

Name Notes
stacked_height Total stacked height, in cm.
stacked_width Total stacked width, in cm.
stacked_length Total stacked length, in cm.
total_weight Combined weight of all parcels, in kg.

Response

See the example response.

id and provider_slug are the pair you carry into the rate request and the shipment. compartment_errors explains why a location was returned but cannot take your parcel. Check it before offering the location to a buyer. It is null for providers that do not report compartments.

A provider that fails to answer is left out rather than failing the call, so an empty locations array does not always mean there is nothing nearby.

View as Markdown