Integration workflows · Bob Box API

The delivery patterns the Bob Box network supports, and how each one maps onto the API. Read this before you build — picking the right reservation_type up front saves rework, because it decides which PIN your customer needs and who acts at the locker.

Picking a reservation type

Every reservation declares who does what at the locker. The name describes the client's action, not the courier's.

`reservation_type`	The client (end customer)	The courier	Use it for
`client-pickup`	Collects the parcel	Drops the parcel off	Door-to-locker delivery
`client-dropoff`	Drops the parcel off	Collects the parcel	Locker-to-door delivery
`client-dropoff-and-pickup`	Drops off, then a different end user collects	Not involved at the locker	Locker-to-locker, and peer-to-peer

Door-to-locker delivery

A parcel goes to a locker instead of an address. The most common courier flow.

Find a locker with space. GET /account/locations with the customer's coordinates, max_distance, the parcel dimensions, and include_availability=true. Filter to locations where the size your parcel matches is true. See Checking space before you reserve.
Reserve before you dispatch. POST /bob-box/reservations with reservation_type: "client-pickup". Do this before the driver leaves, so the compartment is held.
Give the driver the dropoff_pin. It is in the create response.
Driver drops off. The door closes and Bob Box fires the Parcel dropped webhook. Status moves to waiting-for-pickup.
Notify the customer with the pickup_pin and the locker address. If you enforce a collection deadline of your own, include it.
Customer collects. The Parcel collected webhook fires and the status becomes complete.

The flat-fee billing starts at the moment a reservation is created.

Locker-to-door collection

The customer puts a parcel in a locker and a courier takes it away. Returns, and customers sending parcels.

Reserve with reservation_type: "client-dropoff", and put your own tracking number in reference.
Send the customer the dropoff_pin and the locker address.
Customer drops off. The Parcel dropped webhook fires; status becomes waiting-for-pickup.
Dispatch a driver — the webhook is your trigger, so you are not sending anyone to an empty locker.
Driver collects with the pickup_pin. The Parcel collected webhook fires and the status becomes complete.
Complete the delivery to its final address on your own network.

Locker-to-locker shipment

Sender drops at one locker, recipient collects from another. Two reservations, one shipment.

Sender picks a drop-off locker; recipient picks a collection locker. Both from GET /account/locations, with the parcel dimensions and include_availability=true so you only offer lockers that can take the parcel.
Create two reservations, and link them with a shared reference or matching custom_data:
- Origin locker, reservation_type: "client-dropoff" — the sender drops off, your driver collects.
- Destination locker, reservation_type: "client-pickup" — your driver drops off, the recipient collects.
Sender drops off at the origin with its dropoff_pin.
Driver collects from the origin with its pickup_pin, then drops off at the destination with the destination reservation's dropoff_pin.
Recipient collects with the destination pickup_pin.

Create the destination reservation up front so you know the space exists before the parcel is in your hands. If the destination locker fills up while the parcel is in transit, you have a parcel with nowhere to go.

Checking space before you reserve

Do not find out at reservation time that a locker is full. Add include_availability=true to GET /account/locations and each location comes back with a map:

"compartment_availability": { "Small": true, "Medium": false, "Large": true }

What true means depends on whether you send parcel dimensions.

Scenario 1 — availability only

GET /account/locations
  ?lat=-26.107567&lng=28.053040&max_distance=10
  &include_availability=true

true means only: a compartment of that size is free. No fit check runs, because you sent no parcel. You must size the parcel yourself and read the right key.

Use this only if you already track compartment sizes on your side.

Scenario 2 — availability plus dimensions (recommended)

GET /account/locations
  ?lat=-26.107567&lng=28.053040&max_distance=10
  &parcel_length=30&parcel_width=20&parcel_height=10
  &include_availability=true

true now means: free, and your parcel fits, in any orientation — the sides are sorted before they are compared, so how you order them does not matter. Sizes too small go false, even when compartments of that size are standing empty.

Does the map predict the reservation?

Your create call	Map is accurate?
Dimensions + `allow_auto_upgrade: true`	Yes. Any `true` will work — both sides run the same rule.
`allow_auto_upgrade: false` (default)	No. Create uses only the smallest size the parcel fits. The map marks larger sizes too, so `Small: false, Medium: true` is ambiguous.

Send dimensions and allow_auto_upgrade: true. That is the only combination where the check and the reservation agree.

Watch out

Dimensions never remove locations. A location can come back with every size false. Filter those out yourself.
The map is a snapshot. Someone can take the last compartment before you reserve, so still handle create failures.

Fallback

Skip the check, call POST /bob-box/reservations, and read the failure message. It names the size your parcel matched and the sizes that were checked. It costs a round trip after your customer has already picked a locker, so use it as a backup only. The Create reservation page lists every failure message, and explains the matching itself under "How the parcel is sized".

When the parcel does not fit

How sizing works — the smallest-size match, and what allow_auto_upgrade changes — is documented once, on the Create reservation endpoint page under "How the parcel is sized". Read it before you build. This section covers only what to do when you get it wrong.

If the parcel turns out not to fit the compartment you reserved:

POST /bob-box/reservations/cancel to release it. This works before dropoff only — the Cancel reservation endpoint page has the exact rule.
Create a new reservation with the corrected dimensions.

There is no resize endpoint. Cancel and re-create is the supported path, which is another reason to measure before you reserve.

Overstay and clearing

A parcel left in a locker costs money, and eventually the compartment is cleared. Two clocks run, and both come back on the reservation:

Field	What happens at it
`flat_fee_end_time`	The flat-fee window closes and overstay charges begin.
`intervention_time`	The reservation becomes eligible for Bob Box to clear the compartment. Sits after `flat_fee_end_time`.

When Bob Box intervenes after intervention_time, it will clear a compartment to free it up, the Reservation cleared webhook fires and the status becomes cleared. Clearing is an operations decision, not an automatic job, so it happens some time after intervention_time rather than at it.

Bob Box does not enforce a collection deadline. A parcel stays collectable until it is collected, returned, or the compartment is cleared. If your business needs a deadline, set and enforce it on your side. Time your reminders against flat_fee_end_time, because that is the moment overstay charges start costing your customer money.

If a parcel needs to go back to the sender, the return_pin opens the compartment and fires the Reservation returned webhook.

Keeping your locker list fresh

The network changes — lockers are installed, taken offline, and decommissioned.

Sync GET /account/locations periodically rather than hardcoding a list. Cache it, but re-fetch on a schedule.
Watch status. Only active and decommissioning locations accept new reservations. A location with a decommissioning_date in the past is rejected.
Check availability at reservation time, not display time. Re-run the check against a fresh GET /account/locations just before you reserve — see Checking space before you reserve.
Decide which lockers you service. Use coordinates and your own service areas to filter the list down to the lockers your drivers actually reach.

Notifications to end users

Customer notifications are your side of the integration by default. Bob Box does not SMS, email, or WhatsApp your customers unless your account has been configured for it. You send:

The PIN they need, and which action it is for.
The locker address and its trading hours — structured_trading_hours is there to render, and an empty start and end time means closed that day.
Your own collection deadline, if you set one, and reminders before it.
A tracking link, if you have one.

contact_name and contact_number on a reservation are for locker-side and support use. Setting them does not make Bob Box notify anyone while SMS is switched off for your account.

Bob Box can send the collection SMS for you. If your account is configured for it, Bob Box sends the customer an SMS with the pickup_pin and the locker name as soon as the parcel is dropped off. It needs both contact_name and contact_number on the reservation. It is off unless it has been switched on — contact the Bob Box team to activate it for your account.

Driver and operations support

Give drivers a way to report a locker problem — a jammed door, an offline unit, a compartment that will not open. Route it to Bob Box support rather than leaving the driver stuck at the locker.
Handle the PIN-reissue webhook. If Bob Box has to intervene at a locker, PINs can change. The Pin reissued webhook carries the new ones, and anything you have already sent a customer is stale.
Log the reservation_id against your own shipment record. It is what Bob Box support will ask for.

Building it in the right order

If you are starting from nothing, this is the order that surfaces problems earliest:

Authenticate and list locations. Confirms your key and your account's locker access.
Create and cancel a reservation on a dev locker. Confirms your sizing and field names.
Stand up a webhook endpoint and do a real dropoff on a dev locker. Confirms signature verification, which is the part most integrations get wrong.
Wire up your customer notifications.
Handle the unhappy paths: no space, overstay and clearing, PIN reissue.

These flows are deliberately courier-agnostic. Following them keeps your integration predictable for Bob Box operations, and keeps the network working the same way for everyone on it.