# Quickstart
> Add a store, quote a delivery, place an order and watch it get delivered in the sandbox.
Source: https://docs.delivr.no/quickstart/
This guide takes you from an API key to a delivered sandbox order. It takes about ten minutes, and you only need `curl`.
```bash
export DELIVR_API=https://driver-staging-api.delivr.no
export DELIVR_API_KEY=dmk_your_sandbox_key
```
1. **Check your key**
List your store locations. An empty list is fine; it means your key works.
```bash
curl $DELIVR_API/v1/merchant/locations \
-H "Authorization: Bearer $DELIVR_API_KEY"
```
```json
{ "items": [] }
```
A `401 unauthenticated` means the key is wrong or revoked. See [Authentication](/authentication/).
2. **Add a store**
Register the store your goods are picked up from. Delivr finds it on the map from its address.
```bash
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`.
3. **Quote a delivery**
Ask what Delivr can offer from the store to an address, for one 4.5 kg parcel.
```bash
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 }]
}'
```
```json
{
"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.
4. **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.
```bash
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.
```json
{
"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"
}
```
5. **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.
```bash
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](/guides/ready-signals/).
6. **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:
```bash
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](/sandbox/).
7. **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:
```bash
curl "$DELIVR_API/v1/merchant/webhooks/deliveries?orderId=$ORDER" \
-H "Authorization: Bearer $DELIVR_API_KEY"
```
Then [verify the signatures](/webhooks/signatures/) in your handler.
## What to read next
- [Quotes and orders](/guides/quotes-and-orders/): expired quotes, price changes and booking without a quote.
- [Order lifecycle](/guides/order-lifecycle/): every status and reason to handle.
- [Receiving webhooks](/webhooks/): ordering, retries and deduplication.
- [Go-live checklist](/go-live/): what to check before you switch to production.