Skip to main content

PickupLocation

A pickup location is one of your own addresses that a courier can collect from, a warehouse or a shop. Locations are managed in the Spoke Connect app, so the API only reads them.

{
  "id": "pickupLocations/8Qm3RtBnZ9wXcLmPd2Fh",
  "name": "Camden warehouse"
}
FieldMeaning
idThe location id, always pickupLocations/{id}. This is the value an order's handOffInfo.pickupLocationId takes.
nameThe location's display name, as it appears in the Spoke Connect app.

Using one on an order​

A pickup location only means anything when the order's handOffType is pickup_by_courier. Setting pickupLocationId alongside ship_to_courier is rejected with 422 order_invalid_fields rather than quietly ignored, because the two say opposite things about who moves the package.

{
  "deliveryInstructions": {
    "handOffInfo": {
      "handOffType": "pickup_by_courier",
      "pickupLocationId": "pickupLocations/8Qm3RtBnZ9wXcLmPd2Fh"
    }
  }
}

Leaving pickupLocationId out of a pickup_by_courier order is fine: the courier collects from your main location. If your account has no main location to fall back on, the order is rejected with 422 order_invalid_fields naming pickupLocationId, and you have to name one explicitly.

Bind by id, never by name​

Names are not unique, and they change. The API takes ids for exactly that reason. Read the list once, keep the ids, and refresh them when a location is added or removed rather than matching on name at request time.

A location that was deleted, or that belongs to another account, is rejected with 422 order_invalid_fields. Deleted locations also stop appearing in GET /pickupLocations, so a cached id that starts failing usually means the location is gone.