Handle delivery update requests
Respond when Otter asks you to revise an in-flight delivery (cost, pickup, payments, or tip).
Before you begin
- Delivery webhooks configured and signatures validated
- Ability to call
POST /v1/delivery/{deliveryReferenceId}/updatewith scopedelivery.provider
Steps
- Receive the Update delivery request (
delivery.update_request) webhook (payload includesdeliveryReferenceIdand the revised fields Otter is requesting). - Apply the change on your courier / logistics side.
- The callback is optional for completion of Otter's update-request operation.
If you send it, call
POST /v1/delivery/{deliveryReferenceId}/update, include updated cost or currency when applicable, and send the original event'sX-Event-Id. - Continue normal status updates with
PUT /v1/delivery/{deliveryReferenceId}/statusuntil a terminal state.
Verify
Trigger an update request and confirm the delivery continues to completion or cancel. If you send the optional callback, confirm it returns 204.
Common failures
| Symptom | Likely cause | Fix |
|---|---|---|
| 404 on callback | Wrong deliveryReferenceId or store | Use ids from the webhook and X-Store-Id for the linked store |
| 422 | Body missing required update fields | Match the callback schema in the API reference |