# Store locations

> Register the stores and warehouses your goods are picked up from.

Source: https://docs.delivr.no/guides/locations/

A location is a store or warehouse a driver picks your goods up from. Every quote and order names one.

## Add a store

[`POST /v1/merchant/locations`](/api/operations/createlocation/):

```bash title="Request"
curl https://driver-staging-api.delivr.no/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,
    "readyDeadlineMinutes": 60,
    "readySignal": "assumed",
    "pickupInstructions": "Staff entrance in the back yard. Ring the bell marked Delivr."
  }'
```

`name`, `street`, `postalCode`, `city`, `contactName` and `contactPhone` are required. The answer is `201` with the location and its `id`. Another store of yours with the same `externalStoreId` answers `409 conflict`.

| Field                         | Default          | Meaning                                                                                                          |
| ----------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `externalStoreId`             | none             | Your own id for the store, unique among your stores. Use it instead of `id` in quotes and orders.                |
| `contactName`, `contactPhone` | required         | Who the driver asks for at the store. The phone is stored as E.164.                                              |
| `prepMinutes`                 | `0`              | How long packing takes, used when `readySignal` is `assumed`.                                                    |
| `readyDeadlineMinutes`        | `60`             | When the goods are due, counted from the order, if the order has no `readyBy`. At least `prepMinutes`.           |
| `readySignal`                 | `assumed`        | Whether Delivr assumes the goods are ready, or waits for you. See [Goods ready signals](/guides/ready-signals/). |
| `defaultParcel`               | none             | A size (`lengthCm`, `widthCm`, `heightCm`) for parcels you declare by weight only.                               |
| `pickupInstructions`          | `""`             | Standing instructions for drivers at this store, such as the entrance or counter.                                |
| `latitude`, `longitude`       | from the address | Send both or neither.                                                                                            |

### Where the store is

Without coordinates, Delivr places the store from its address in the national address register. If the address is not found, you get `422 invalid_address`; send `latitude` and `longitude` then.

### Who sees the instructions

`pickupInstructions` reach the driver only. You can read them back, but they never appear on the recipient's tracking page, in SMS or in webhooks.

## Change a store

[`PATCH /v1/merchant/locations/{id}`](/api/operations/updatelocation/) changes only the fields you send.

- `""` clears `externalStoreId` or `pickupInstructions`, and `"defaultParcel": null` drops the default size.
- A new street, postal code or city places the store again from its address, unless you send coordinates too.
- Orders already placed keep their pickup. New quotes and orders use the change.

## Read your stores

[`GET /v1/merchant/locations`](/api/operations/listlocations/) lists your stores, and [`GET /v1/merchant/locations/{id}`](/api/operations/getlocation/) reads one. Reading needs scope `quotes`; adding and changing need scope `orders` and an `Idempotency-Key`.

Locations cannot be removed yet. Change one to reuse it.