Orders
Use the v3 order endpoints for new integrations. Order creation requires orders:write; reads require orders:read.
Start with the workflow recipes for complete integration shapes. See Delivery lifecycle for status transitions and Auto-routing strategies for provider selection.
Create
Section titled “Create”Send a stable external identifier and merchant identifier with customer, address, scheduling, and value fields required by your workflow. Save the returned First Delivery order ID. Reusing a unique external identifier is safer than creating a second order after an ambiguous timeout.
Times should be valid ISO 8601 values with an offset. Make the intended pickup or delivery target explicit and do not infer the account timezone.
Update
Section titled “Update”Only fields allowed by the endpoint can be changed. Some fields and status transitions become immutable after fulfillment begins. Treat a 400 response as a request or state error and refetch the order before deciding what to do.
Cancel
Section titled “Cancel”Cancellation is a command, not a local status edit. Use the published cancel endpoint and retain its response. A cancellation can be rejected when work has progressed too far or an external provider cannot accept it.
Poll only when webhooks are unsuitable. Use bounded intervals and stop after the order reaches a terminal state. The order ID is the canonical identifier for support and follow-up API calls.