Order a Non-Dedicated Delivery
Placing an order for a non-dedicated delivery with Zippd requires all delivery data upfront. This will include things like:
- Pick-up and drop-off addresses
- Details about the goods
- Additional data that can be referenced later for your team’s benefit
Placing an order is as simple as sending a POST request to our API. Take a look at the endpoint reference for specifics on the data required.
Ready for Collection (Second Signal)
Some accounts are configured to require a separate confirmation that the goods are ready for collection. For these accounts, creating an order registers the delivery and can generate labels, but route planning waits for this second signal.
- Create the order using
POST /api/v1/orders-non-dedicated. - Read
data.requires_ready_for_collectionin the201 Createdresponse. When it istrue, save the order UUID fromdata.idand send the second signal once the goods are ready. The flag is omitted for orders that do not require this step. - Send
POST /api/v1/orders-non-dedicated/{id}/ready-for-collection, replacing{id}with that UUID, using your usual bearer token. No request body is required.
The create-order response is wrapped in data. For an account requiring the second signal, the relevant fields look like this (other order fields are omitted here):
Send the Readiness Request
Use data.id as the path parameter, rather than data.code or your internal_ref. Send an empty body: no order data, readiness flag or timestamp is needed. The server records the readiness time. Include both the Authorization and Accept headers shown below.
For example, after preparing the goods:
Read the Response
A successful call returns 202 Accepted with a JSON body:
All four fields are present in a successful readiness response.
Scheduling and route planning continue asynchronously. This response confirms readiness was recorded; it does not confirm a driver assignment or that the goods have been collected. Labels and barcodes can be generated before readiness, and the readiness signal does not mark parcels as received.
You can retry the signal for an eligible order: successful repeated calls preserve the original ready_for_collection_at timestamp and do not restart an operational order. Completed, cancelled or otherwise terminal orders return 409 Conflict, even if an earlier call succeeded. The create-order flag requires_ready_for_collection describes the requirement, not the current readiness status.
Handle Errors
The endpoint returns 401 Unauthorized for missing or invalid authentication and 403 Forbidden when the account lacks API access.
The endpoint returns 404 Not Found if the UUID is unknown, deleted or outside your active workspace. It returns 409 Conflict if the order does not support collection readiness, is terminal, or is no longer awaiting collection before the first signal. See the endpoint reference for response details.
Send Readiness Requests in Bulk
To confirm readiness for several orders, send POST /api/v1/orders-non-dedicated/ready-for-collection/bulk with an ids array containing 1–100 distinct order UUIDs from data.id. UUIDs must be unique regardless of letter case. Use the same bearer token as the single-order endpoint and include Accept: application/json and Content-Type: application/json.
A valid request returns 202 Accepted:
data.total is the number of UUIDs accepted for processing. Unlike the single-order response, this confirms background processing has been accepted; it does not confirm readiness has been recorded for each order or return individual results.
Each order must belong to your active customer workspace membership and support collection readiness. Another customer in the same workspace cannot update it. Unknown, inaccessible, ineligible or terminal orders fail individually during processing while other items continue. Successful repeated signals preserve the original readiness timestamp, as with the single-order endpoint.
Missing, empty, duplicate, malformed or oversized UUID lists return 422 Unprocessable Entity with message and errors; no updates are queued for an invalid payload. Authentication and API access errors return 401 and 403, respectively. See the bulk endpoint reference for the full contract.
Pricing
It is not possible to receive pricing estimates for this type of order. Currently, pricing for non-dedicated deliveries is agreed during account set-up and configured on the account level.
Location Addresses
You can provide either a pick-up address only, a drop-off address only, or both addresses. Anything else will result in a 422 failure response.
Examples
Send only the drop-off address:
When both locations are provided, the address data in each object will be treated separately. This means you can pull a previously used address for one location and add a new address for the other:
id field for an address object, the API will return with an error response if any of the following fields are also in the object:
address_line_1, city, postcode, contact_nameOur system makes use of latitude/longitude coordinates for geographical processes such as calculating distances and displaying points on maps. If you have the coordinates for your addresses, you can provide them with the latitude and longitude items in the address object:
Where the latitude and longitude items have not been provided, the API will geocode the address on your behalf.
Date and Time
Collection and delivery scheduling use the routing profile and cut-off times configured for your account.
For orders requiring the second signal, the final schedule is calculated after readiness is confirmed. If processing occurs at or after the applicable cut-off, collection can move to the next available day. Queue delays can also move an order that has not yet entered route planning to a later schedule. Do not treat the fulfilment date returned at creation as a guaranteed collection date.
Get Updates on Order Progress
Through webhooks, you can receive status updates about your orders as they happen. See the documentation.
You can also make requests to the API the retrieve order data as and when you need it. See the API reference.
