GET /v1/bulk-deliveries/{ref}/progress

GET /v1/bulk-deliveries/{ref}/progress

Scope	Idempotency-Key	Operation ID
`delivery.read`	—	`getBulkProgress`

The sender's Bulk progress view, "3 of 5 delivered".

A line per active recipient from that child's customer-safe tracking status; never a rider, a location or another recipient's details.

Request

Signed with your API credential: see Authentication.

Parameter	In	Required	Description
`ref`	path	Yes	Pattern `^BK-[0-9A-HJKMNP-TV-Z]{8}$`.

The progress view.

Field	Type	Required	Description
`bulk_reference`	string	Yes	Pattern `^BK-[0-9A-HJKMNP-TV-Z]{8}$`.
`status`	string	Yes
`delivered`	integer	Yes	0–5.
`total`	integer	Yes	Active recipients 0–5.
`failed_count`	integer	Yes	0–5.
`cancelled_count`	integer	Yes	0–5.
`recipients`	array of object	Yes
`recipients[].position`	integer	Yes	1–5.
`recipients[].delivery_reference`	string	Yes	Public reference of a delivery job or Bulk child. Pattern `^DX-[0-9A-HJKMNP-TV-Z]{8}$`.
`recipients[].recipient_first_name`	string	Yes
`recipients[].customer_status`	string or null	Yes	From the child's tracking projection; null before dispatch
`recipients[].rider_first_name`	string or null	Yes	The child's rider while the delivery is active (P7)
`recipients[].awaiting_handover`	boolean	Yes	The sender owes this child's handover now: its rider is at the pickup

Unknown, revoked or wrong-environment credential, bad signature, or expired session.

The error envelope: code, message, detail, request_id.

Tenant access denied (existence is not disclosed), insufficient scope, MFA/step-up required, partner blocked or module disabled.

The error envelope: code, message, detail, request_id.

Rate limit reached; honour Retry-After.

The error envelope: code, message, detail, request_id.

Unexpected failure. Only code and request_id are returned.

The error envelope: code, message, detail, request_id.