Skip to main content

Shipping overview

A delivery goes through the same steps whichever way you create it: addresses, a price, a booking, and then webhooks until it is delivered. What changes is how much you know when you create it.

The core rule​

Creating a delivery and starting it are two different things. Reeds never sends a rider to an address nobody has confirmed. A delivery that can't move yet waits in the requires_action status, and required_actions tells you what it is waiting for.

A delivery that is created but blocked is a success (HTTP 201 with status: requires_action), not an error.

Path A: book from a quote​

Use this when your addresses are clear and the item is ready.

  1. POST /addresses for the pickup and the drop-off. Each returns an address id with status verified. See Addresses.
  2. POST /quotes with both address ids and the package. You get a quote id, the price, and the pickup and delivery times. A quote is valid for 24 hours. See Quotes.
  3. POST /deliveries with the quote id. The delivery is booked, your wallet is debited (or the delivery goes on the month's invoice), and the status is scheduled. See Book a delivery.
  4. Webhooks follow the delivery through to delivered. See Webhooks.

Path B: create a draft​

Use this when an address can't be matched exactly, or when you want Reeds to price and book in one call.

  1. POST /addresses returns needs_confirmation (an approximate match or no match), with Reeds' best suggestion.
  2. POST /deliveries with the address ids and no quote. The delivery is created as a draft with status requires_action and a list of required actions. Nothing is charged.
  3. You confirm the address, in the dashboard or with POST /addresses/{id}/confirm.
  4. Reeds prices the delivery. If the draft was created with auto_book: true and your account can pay, Reeds books it straight away. Otherwise it waits for POST /deliveries/{id}/book, or the Book button in the dashboard.
  5. From here it is the same as Path A.

See Drafts and required actions.

Path C: platforms and aggregators​

Use this when you ship for many merchants, for example an ecommerce platform or an aggregator that lists couriers at checkout.

  1. At the merchant's checkout, send POST /quotes with the pickup and drop-off inline (text, coordinates or a place id) and the package. Reeds saves both addresses and returns a quote, or available: false with a reason when it can't serve the route.
  2. When the order is placed, book with POST /deliveries and the quote id, naming the merchant in shipper.
  3. Webhooks follow the delivery, as in Path A. You map Reeds' statuses onto your own.

See Platforms.

Not ready yet​

The item isn't packed? In any path, book with ready: false. The delivery waits in requires_action with a MARK_READY action until you call POST /deliveries/{id}/ready. The pickup is scheduled from the moment you mark it ready, so Reeds never promises a time for a parcel that isn't there.

The order of things​

POST /addresses        -> verified (or needs_confirmation -> confirm)
POST /quotes           -> qt_...  (valid 24 hours, books once)
POST /deliveries       -> scheduled   (or requires_action for a draft)
webhooks               -> rider_assigned -> picked_up -> ... -> delivered

Next steps​