Quickstart

View as Markdown Open in Claude Open in ChatGPT

This guide takes you from an API key to a delivered sandbox order. It takes about ten minutes, and you only need curl.

export DELIVR_API=https://driver-staging-api.delivr.no
export DELIVR_API_KEY=dmk_your_sandbox_key

Check your key

List your store locations. An empty list is fine; it means your key works.
Terminal window
```
curl $DELIVR_API/v1/merchant/locations \
  -H "Authorization: Bearer $DELIVR_API_KEY"
```
```
{ "items": [] }
```
A 401 unauthenticated means the key is wrong or revoked. See Authentication.

Add a store

curl $DELIVR_API/v1/merchant/locations \
  -H "Authorization: Bearer $DELIVR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "externalStoreId": "oslo-sentrum",
    "name": "Oslo Sentrum",
    "street": "Akersgata 45",
    "postalCode": "0158",
    "city": "Oslo",
    "contactName": "Store staff",
    "contactPhone": "+4722000000",
    "prepMinutes": 10
  }'

The answer is the location, with its id. From now on you can name this store by your own externalStoreId.

Quote a delivery

Ask what Delivr can offer from the store to an address, for one 4.5 kg parcel.

curl $DELIVR_API/v1/merchant/quotes \
  -H "Authorization: Bearer $DELIVR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pickupExternalStoreId": "oslo-sentrum",
    "delivery": {
      "address": { "street": "Karl Johans gate 22", "postalCode": "0159", "city": "Oslo" }
    },
    "parcels": [{ "count": 1, "weightKg": 4.5, "lengthCm": 40, "widthCm": 30, "heightCm": 20 }]
  }'

{
  "quoteId": "3f0e9a52-8a7e-4f8e-9a51-2c0f3c9d1b7a",
  "expiresAt": "2026-11-03T13:05:00Z",
  "timeZone": "Europe/Oslo",
  "options": [
    {
      "type": "on_demand",
      "key": "on_demand",
      "eta": { "from": "2026-11-03T13:25:00Z", "to": "2026-11-03T13:55:00Z" },
      "price": { "amountMinor": 14900, "currency": "NOK" }
    },
    {
      "type": "window",
      "key": "window:2026-11-03T17:00:00+01:00/2026-11-03T19:00:00+01:00",
      "window": { "start": "2026-11-03T16:00:00Z", "end": "2026-11-03T18:00:00Z" },
      "cutoffAt": "2026-11-03T14:00:00Z",
      "price": { "amountMinor": 9900, "currency": "NOK" }
    }
  ]
}

Show these options to the shopper. Prices are what Delivr bills you, VAT included; what you charge the shopper is up to you.

Place the order

When the shopper pays, book the option they chose. Use your own order id as externalRef, and give the recipient’s name and phone so Delivr can text them a tracking link.

curl $DELIVR_API/v1/merchant/orders \
  -H "Authorization: Bearer $DELIVR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "quoteId": "3f0e9a52-8a7e-4f8e-9a51-2c0f3c9d1b7a",
    "option": "on_demand",
    "externalRef": "order-1001",
    "delivery": {
      "address": { "street": "Karl Johans gate 22", "postalCode": "0159", "city": "Oslo" },
      "contact": { "name": "Kari Nordmann", "phone": "+4791234567" },
      "dropoff": { "floor": 3, "doorCode": "1234" }
    }
  }'

You get 201 Created and the order. Its id is the quoteId, and reference (DD-…) is what you quote to Delivr support.

{
  "id": "3f0e9a52-8a7e-4f8e-9a51-2c0f3c9d1b7a",
  "reference": "DD-482913",
  "externalRef": "order-1001",
  "type": "on_demand",
  "status": "awaiting_goods",
  "readyBy": "2026-11-03T14:00:00Z",
  "readyAt": "2026-11-03T13:10:00Z",
  "trackingUrl": "https://tracking-stage.delivr.no/t/…",
  "eta": { "from": "2026-11-03T13:25:00Z", "to": "2026-11-03T13:55:00Z" },
  "timeZone": "Europe/Oslo",
  "version": 3,
  "createdAt": "2026-11-03T13:00:12Z",
  "updatedAt": "2026-11-03T13:00:13Z"
}

Say the goods are ready

The store has packed the parcel. Tell Delivr, and the driver search starts at once. Order paths take Delivr’s id or the DD- reference.
Terminal window
```
export ORDER=3f0e9a52-8a7e-4f8e-9a51-2c0f3c9d1b7a
curl -X POST $DELIVR_API/v1/merchant/orders/$ORDER/ready \
  -H "Authorization: Bearer $DELIVR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```
The order moves to searching. With the store’s default (readySignal: assumed) this step is optional: the goods count as ready after prepMinutes. See Goods ready signals.
Watch a robo driver deliver it

The sandbox has robo drivers parked at every store. One accepts within seconds, drives to the store, picks up and delivers. A delivery takes about two minutes. Poll the order to watch it move:
Terminal window
```
curl $DELIVR_API/v1/merchant/orders/$ORDER -H "Authorization: Bearer $DELIVR_API_KEY"
```
It goes searching → driver_assigned → picked_up → delivered, and the last answer has a proofOfDelivery. To test failures instead, put a directive such as sandbox:no_driver in pickup.note. See Sandbox and testing.
Receive the webhooks

If Delivr set up your webhook endpoint, it received order.placed, order.searching, order.driver_assigned, order.picked_up and order.delivered. Check the delivery log:
Terminal window
```
curl "$DELIVR_API/v1/merchant/webhooks/deliveries?orderId=$ORDER" \
  -H "Authorization: Bearer $DELIVR_API_KEY"
```
Then verify the signatures in your handler.

Quickstart

What to read next