Create reservation

Reserve a compartment at a location for a parcel. The response carries the compartment and all three PINs.

Compartment matching and allow_auto_upgrade are documented once, below, under How the parcel is sized. Read that before you build.

Request

Method: POST URL: https://api.bobbox.co.za/v2/bob-box/reservations

Request body parameters

location_id and bob_box_location_id are interchangeable; send one of them. Same for reference and custom_reference. When both are sent, the new name wins.

Field limits

Requests that exceed these limits will be rejected with a 400.

The character limits are counted in bytes, so accented and non-Latin letters use more than one each. The limit on reference applies to custom_reference too.

How the parcel is sized

This is the single reference for compartment matching. Other pages link here rather than repeat it.

Bob Box works in two steps:

1. Match a size. The parcel is matched to the smallest size it fits — Small, then Medium, then Large. Both sets of sides are sorted before they are compared, so orientation does not matter, and neither does the order you send the dimensions in.
2. Claim a compartment. The first free compartment of the matched size is claimed.

Compartment sizes

Every compartment is the same width and length. Only the height changes.

Volumetric factor: 4000. Volumetric weight in kg is length × width × height ÷ 4000, with the sides in centimetres. Each max_volumetric_weight above is just that compartment's own volume put through the same formula, so a parcel that fits a size by its sides also fits it by volumetric weight.

allow_auto_upgrade decides what happens when step 2 finds nothing. It defaults to false, so the reservation fails when the matched size is full — even when bigger compartments are standing empty. Send true and Bob Box falls back to any larger size instead.

Send allow_auto_upgrade: true unless you have a reason not to. It is also the only setting under which compartment_availability predicts this call exactly — see "Checking space before you reserve" in the Workflows section.

What to send

No single sizing field is required, but always send one of these three sets:

• The three dimensions — the normal case.

• volumetric_weight with no dimensions — each compartment is checked against its own max_volumetric_weight instead of against the parcel's sides.

  Watch out: step 1 still reads the dimensions, and with none sent it always lands on Small. With the default allow_auto_upgrade: false you can only ever get a Small compartment, however heavy the parcel is. Sizing by weight needs allow_auto_upgrade: true.

• Nothing at all — the request still succeeds and takes the smallest compartment. Only do this when you know the parcel is small.

A parcel larger than the biggest compartment is rejected with 400 Parcel dimensions exceed maximum compartment size before any compartment is checked.

Contact number format

The number is parsed as a South African number and must be valid for that region. Both +27833771167 and 0833771167 are accepted, and the value is stored in E.164 form. A valid number from another country is rejected.

Reference uniqueness

A reference must be unique among active reservations at the same location. Reusing one that is still tied to an active reservation there returns 400 There is already an active reservation with this reference at this location. The same reference is fine at a different location, or once the earlier reservation has finished.

If you send no reference but your custom_data contains a string field named shipment_reference, that value is used as the reservation's reference. That fallback is not length-checked and not uniqueness-checked — send reference directly if you need either.

Response

Status code: 200 OK Content-Type: application/json

All three PINs are returned here, immediately. They are read off the compartment as it is claimed — you do not need to poll or call the PINs endpoint to get them.

Response body example:

See the example response.

Response fields

Compartment fields:

Location fields (as returned here):

This object does not carry s3_image_url, s3_image_urls, hidden, compartment_availability, time_created, or time_modified — those belong to GET /account/locations only.

Using the PINs

Store the three PINs on your side and use them however suits your workflow: show them in your app, send them by SMS or email, print them on a label, or pass them to your courier's system. Each PIN is for a different person at a different point in the parcel's journey:

Things to know:

• Only give each PIN to the person who needs it. Anyone with a PIN can open the compartment at that point, so the PIN is what keeps the parcel safe.
• The drop-off PIN only works until the parcel is dropped off. After that, the locker no longer accepts it.
• PINs can change. If a reservation's PINs are reissued, the Pin reissued webhook sends you the new PINs, so subscribe to it if you store PINs. Replace the PINs you stored, and make sure anyone you already sent them to gets the new ones. See the Webhooks section.

Errors