POST /v1/bulk-deliveries/{ref}/confirm

POST /v1/bulk-deliveries/{ref}/confirm

Scope	Idempotency-Key	Operation ID
`delivery.create`	Required	`confirmBulkDelivery`

Confirm the reviewed revision; one job per child.

Confirms the quote revision the sender reviewed. Everything is re-read under the parent's lock: every active recipient confirmed (BULK_RECIPIENTS_PENDING), the revision still current and every child quote open and unexpired by the server clock (BULK_QUOTE_CHANGED, with detail.quote_revision), and each child revalidated as a single delivery is. Then, in one transaction, each child becomes one ordinary delivery job through the single confirmation path, carrying the child's DX- reference, its own pricing snapshot and payment state, and is dispatched on its own (its own candidate search; HDZE may batch compatible children under its own rules). Each recipient is sent their tracking link; the sender follows …/progress. The tenant is sent bulk.confirmed. A confirmed Bulk replays its result. Idempotency-Key required. Audited (bulk.confirm).

Request

Signed with your API credential: see Authentication.

Parameter	In	Required	Description
`Idempotency-Key`	header	Yes	One key per user intent, reused for every retry of that intent. See Idempotency.
`ref`	path	Yes	Pattern `^BK-[0-9A-HJKMNP-TV-Z]{8}$`.

Body

Field	Type	Required	Description
`quote_revision`	integer	Yes	The revision the sender reviewed

Responses

200

Confirmed (or already confirmed); each child is a delivery.

Field	Type	Required	Description
`bulk_reference`	string	Yes	Pattern `^BK-[0-9A-HJKMNP-TV-Z]{8}$`.
`status`	string	Yes	One of: `BULK_DRAFT`, `BULK_AWAITING_RECIPIENTS`, `BULK_PARTIALLY_CONFIRMED`, `BULK_READY_FOR_QUOTE`, `BULK_AWAITING_SENDER_CONFIRMATION`, `BULK_DISPATCHING`, `BULK_IN_PROGRESS`, `BULK_PARTIALLY_COMPLETED`, `BULK_COMPLETED`, `BULK_CANCELLED`, `BULK_EXCEPTION`.
`recipient_count`	integer	Yes	2–5.
`active_recipient_count`	integer	Yes	0–5.
`confirmed_count`	integer	Yes	0–5.
`quote_revision`	integer	Yes
`total`	string or null	Yes	The sum of the children's quotes, null until every active child is quoted.
`currency`	string	Yes	One of: `GHS`.
`children`	array of object	Yes
`children[].position`	integer	Yes	1–5.
`children[].delivery_reference`	string	Yes	Public reference of a delivery job or Bulk child. Pattern `^DX-[0-9A-HJKMNP-TV-Z]{8}$`.
`children[].status`	string	Yes	The child request's status (request-level states; REMOVED once removed)
`children[].location_confirmed`	boolean	Yes	The recipient confirmed the drop-off
`children[].recipient`	object	Yes
`children[].recipient.first_name`	string	Yes
`children[].recipient.last_name`	string	Yes
`children[].recipient.phone`	string	Yes	Masked: the last three digits only
`children[].link_expires_at`	string or null, date-time	Yes	When the child's live link stops working; null once revoked
`children[].resends_remaining`	integer or null	Yes	Resends left while the recipient is awaited, else null
`children[].resend_available_at`	string or null, date-time	Yes	When the resend cooldown ends while the recipient is awaited, else null
`children[].quote`	object or null	Yes	The child's own quote: the server's total only, never its arithmetic. `expired` is judged by the server clock. Null before the child is quoted.
`children[].quote.reference`	string	Yes	Pattern `^QT-[0-9A-HJKMNP-TV-Z]{8}$`.
`children[].quote.total`	string	Yes	Exact decimal with two places; never a JSON number. Pattern `^-?[0-9]+\.[0-9]{2}$`.
`children[].quote.currency`	string	Yes	One of: `GHS`.
`children[].quote.expires_at`	string, date-time	Yes
`children[].quote.expired`	boolean	Yes
`children[].customer_status`	string or null	Yes	The child's delivery status as tracking shows it, once dispatched
`children[].tracking_links`	object	No	The child's tracking links, shown once on the tenant's confirming response: the sender's link confirms the handover
`children[].tracking_links.sender_url`	string	Yes
`children[].tracking_links.recipient_url`	string	Yes
`children[].tracking_links.expires_at`	string, date-time	Yes
`cancellations`	array of object	No	After dispatch, each child's answer to the cancellation; present only on that answer.
`cancellations[].delivery_reference`	string	Yes	Public reference of a delivery job or Bulk child. Pattern `^DX-[0-9A-HJKMNP-TV-Z]{8}$`.
`cancellations[].cancelled`	boolean	Yes
`cancellations[].reason`	string or null	Yes	Why the stage policy left it, e.g. after_pickup
`created_at`	string, date-time	Yes