Skip to main content

Courier

A courier is a delivery company your account is connected to and can submit orders to. The connection is made in the Spoke Connect app, so the API only reads couriers, it never creates or changes them.

{
  "id": "couriers/QyZ8mp34RFlIfwREp1js",
  "name": "Northside Logistics"
}
FieldMeaning
idThe courier id, always couriers/{id}. This is the value POST /orders:submit takes as courierId.
nameThe courier's display name, as it appears in the Spoke Connect app.

What a courier is, and is not​

GET /couriers returns your connections, not a directory. A courier you are not connected to is not visible through this API, and asking for one by id answers 404 courier_not_found exactly as a courier that does not exist would. That is deliberate: the API never reveals couriers outside your own connections.

A page of couriers can come back shorter than maxPageSize while more results exist, because a connection whose courier record no longer exists is dropped from the page. Keep paging until nextPageToken is null.

What a courier decides​

Some of what happens to an order is the courier's to decide, not yours:

  • Whether it accepts the order. A courier covers a certain area and keeps its own rules about what it will carry. Whether it takes an order, including whether the delivery address is one it serves, is settled on the courier's side after you submit, not by the submit call.
  • Whether ETAs are available. ETAs are part of the courier's subscription, not yours. When it does not include them, every order with that courier reports progress.eta.status: "restricted".
  • Whether proof of attempt is enforced. Setting proofOfAttemptRequirements.enabled to true asks for proof. The courier's own policy decides whether it is captured.

Couriers that charge per delivery cannot be submitted to through this API at all. Those orders go through the Spoke Connect app, which handles payment, and the API answers 422 order_courier_requires_payment.

Submit itself validates each order against your own account settings before the courier ever sees it. An order missing a field your account marks required, or one whose address is beyond a maximum distance from the pickup your account has set, comes back in the submit response's failed array with order_invalid_fields. See Submit and withdraw an order.