How a delivery works

This page explains what happens after you book, so you can show your customers accurate information and handle each stage correctly.

Delivery types

When you request a quote you choose a delivery type. What's available depends on the collection address, the delivery address and the time of day.

Type	Meaning
`IMMEDIATE`	Collected and delivered right away
`SAME_DAY`	Collected and delivered the same day
`NEXT_DAY`	Delivered the following day
`WINDOW`	Delivered inside a specific time window

The quote response tells you which are actually available — never assume. If a type can't be offered for that route, the rate carries an error explaining why.

Statuses

Every delivery and return moves through these statuses. The current one is on status.value, and the full history is in statusUpdates.

Status	What it means
`NOT_STARTED`	Booked and accepted. Nothing has happened physically yet.
`OUT_FOR_COLLECTION`	A courier is on the way to collect.
`COLLECTED`	The parcel is with the courier.
`OUT_FOR_DELIVERY`	On the way to the delivery address.
`COMPLETED`	Delivered successfully.
`FAILED`	Could not be delivered.
`CANCELLED`	Cancelled before completion.

COMPLETED, FAILED and CANCELLED are final — nothing follows them.

COMPLETED means the job finished, not always that the parcel reached the customer. Check substatus for the detail: ATTEMPT means a delivery attempt was made, and UNDELIVERABLE means it couldn't be delivered. Don't treat the status alone as proof of a successful handover.

A typical successful delivery reads:

NOT_STARTED → OUT_FOR_COLLECTION → COLLECTED → OUT_FOR_DELIVERY → COMPLETED

Statuses are not guaranteed to arrive in order over webhooks, and a status can repeat (for example, a second delivery attempt). Treat each update as "here is the current state", and ignore any that is older than what you already hold.

Collection and delivery windows

A booking carries two kinds of window, and the difference matters:

Committed window — what was promised at booking, and what you should show the customer.
Expected window — our live estimate, which narrows as the day progresses and the route firms up.

Subscribe to window-change events if you show estimated times, so your customer sees the same thing we do.

Collection cutoffs

Collections happen inside your fulfilment location's operating hours. Those hours are the window in which couriers may collect from you — not necessarily your shop's public opening hours. A collection is never scheduled after your location closes.

Two consequences worth designing for:

Book early in the day where you can. An order placed near closing time may be collected the next working day.
Collection day is not always delivery day. For NEXT_DAY in particular, the parcel is collected on one day and delivered on the next.

Keep your operating hours accurate — they directly determine what Quiver can promise your customers at checkout.

Returns

Returns work the same way, with collection and delivery reversed: we collect from your customer and bring the parcel back to you. They use the same statuses and the same endpoints shape, posted to /task/returns.

Tracking your customer sees

Every booking returns a trackingId and a trackingUrl. The tracking page shows live status and, once known, the expected delivery window. Give your customer the trackingUrl rather than building your own status page — it updates automatically.

What to build

A robust integration usually:

Stores taskId and trackingId against the order at booking time.
Subscribes to status webhooks rather than polling.
Shows the customer the committed window, then the expected window once it's set.
Treats FAILED and UNDELIVERABLE as cases needing human attention, not silent retries.

Next steps

Booking a delivery: worked example — the full flow with real requests
Errors and retries — handling failures safely