Skip to main content

Bulk deliveries over the API

A Bulk delivery sends items from one pickup to two to five recipients. It is not one delivery with several stops: each recipient gets an ordinary delivery of their own (a child, with its own DX-… reference, price, rider, tracking and receipt). The Bulk (BK-…) only coordinates them.

The flow​

  1. Create — POST /v1/bulk-deliveries with the delivery company (partner), the sender, the pickup, the vehicle and the recipients' names and phones. Each recipient gets an SMS link to confirm their own drop-off. You never send a drop-off for them.
  2. Wait for recipients — bulk.recipient_confirmed arrives as each one confirms. You can add recipients while positions remain, resend a link, or remove a recipient before the sender confirms.
  3. Quote — POST /v1/bulk-deliveries/{ref}/quote once every active recipient has confirmed (otherwise BULK_RECIPIENTS_PENDING). Each child is priced exactly as a single delivery would be. The total is their plain sum: there is no Bulk price or discount. The answer carries a quote_revision.
  4. Confirm — POST /v1/bulk-deliveries/{ref}/confirm with the quote_revision the sender reviewed. If anything changed since (a recipient moved their pin, a quote expired) you get BULK_QUOTE_CHANGED with the new revision: quote again and show the sender the new total.
  5. Follow — each child is dispatched on its own. GET /v1/bulk-deliveries/{ref}/progress gives the "3 of 5 delivered" view, and bulk.progress_updated and bulk.completed arrive as children move.

Limits and rules​

  • Two to five recipients; outside the limits set for your tenant, BULK_RECIPIENT_LIMIT and nothing is created.
  • A phone number may appear once unless your tenant allows duplicates.
  • A removed recipient keeps their position; a Bulk can never hold more than five children in total.
  • No recipient ever sees another recipient's details.
  • One child's problem never changes its siblings. A failed child does not cancel the others.

Cancelling​

Before the sender confirms, POST /v1/bulk-deliveries/{ref}/cancel cancels every child and stops every link. After confirmation the Bulk is never cancelled as a whole: each child is judged by its own stage, as a single delivery is, and the answer lists the result child by child.

If the Bulk module is not switched on for your tenant, these endpoints answer MODULE_DISABLED.