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.
- Acknowledge with
POST /v1/delivery/{deliveryReferenceId}/update— include updated cost or currency when applicable; send the original event’sX-Event-Id. - Continue normal status updates with
PUT /v1/delivery/{deliveryReferenceId}/statusuntil a terminal state.
Verify
In staging, trigger an update request; your callback returns 204 and the delivery continues to completion or cancel.
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 |