Fallbacks

Sometimes an on-demand delivery cannot happen: no driver accepts it (no_driver), or the goods are never ready (goods_not_ready). Rather than leaving the shopper with nothing, your fallback policy can move the delivery to a window. Delivr sets the policy for you at onboarding.

Policy	What happens after the order fails
recipient_choice (default)	You get order.awaiting_recipient with a choiceDeadline (30 minutes). The recipient picks a window on their tracking page, free for them. You are billed for the window delivery.
rebook_window	The nearest free window is booked automatically.
cancel	Nothing more happens. The order stays failed.

Successor orders

When a window is booked, Delivr creates a successor order:

1. The failed order sends order.successor_created with the successorId.
2. The successor sends its own order.placed, with predecessorId pointing back.
3. The successor keeps your externalRef, and the recipient’s tracking link follows along.

If no successor follows, you get order.fallback_cancelled with fallbackReason expired (the recipient did not choose in time) or no_window (no window was free).

Handling it

• Under recipient_choice and rebook_window, treat order.failed with no_driver or goods_not_ready as “may continue”: wait for order.successor_created or order.fallback_cancelled before you refund or tell the shopper.
• Under cancel, order.failed is final. No fallback event follows.
• Follow successorId with GET /v1/merchant/orders/{id} to reach the current order. GET /v1/merchant/orders?externalRef=… lists the failed order and its successors alike.
• Assisted checkout orders that are still held have no fallback.

In the sandbox, sandbox:no_driver in pickup.note fails an order at once, so you can watch your fallback run.