Direct Delivery API

The Direct Delivery API enables retailers and DSP aggregators to request delivery quotes, create deliveries from those quotes, and receive real-time status updates via webhooks.

The flow is two-step: quote first, then create. A quote returns availability, pickup ETA, delivery ETA, and locked delivery cost; the create call promotes that quote into an active delivery, honoring the same locked terms.

Authentication

All requests require an Autolane API key in the Authorization header and a per-site x-retailer-id header. Your organization and retailer context are resolved automatically from these.

$
curl -X POST https://api.goautolane.com/dd/v1/deliveries/quote \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "x-retailer-id: a1b2c3d4-e5f6-7890-1234-567890abcdef" \
>
  -H "Content-Type: application/json" \
>
  -d '{ ... }'

Permissions

API keys carry granular permissions:

Create API keys in the Autolane Portal under Organization Settings > API Keys.

Delivery Lifecycle

1. Quote — POST /dd/v1/deliveries/quote with the customer phone, delivery address, ready-by time, and order items. The response includes available, pickup_eta, delivery_eta, delivery_fee_cents, and expires_at (5 minutes from creation). When available is false, the response carries an unavailable_reason (OUT_OF_SERVICE_AREA, NO_DRIVERS_ONLINE, or CUSTOMER_OPTED_OUT).
2. Create — POST /dd/v1/deliveries with the same external_delivery_id you used on the quote. The locked terms (price, ETAs) carry over from the quote; the response returns the created delivery.
3. Pending — the delivery starts in PENDING status.
4. Ready — at the ready_by time, the delivery automatically transitions to READY and becomes visible in the driver queue.
5. Pickup — a driver claims the delivery, picks it up from the store, and delivers it to the customer.
6. Complete — delivery confirmed.

Quote Semantics

• A quote is identified by (retailer, external_delivery_id). Re-quoting with the same key replaces the prior quote.
• A quote is valid for 5 minutes. After expires_at, calling POST /dd/v1/deliveries returns 410 QUOTE_EXPIRED.
• A quote can only be consumed once. After a successful create, re-creating with the same external_delivery_id returns 409 QUOTE_ALREADY_CONSUMED.
• A quote with available: false cannot be promoted to a delivery. Calling create returns 422 QUOTE_NOT_AVAILABLE.

Cancellation

Cancel a delivery via PATCH /dd/v1/deliveries/{external_delivery_id} with { "status": "CANCELLED" }. Cancellation is allowed any time before the delivery reaches a terminal state (CANCELLED, EXPIRED). If a pickup is in progress, it is also cancelled.

Error Codes