# Requests and responses

> Formats, headers and conventions shared by every endpoint.

Source: https://docs.delivr.no/conventions/

## Format

- HTTPS only. Every route lives under `/v1/merchant/`.
- Request and response bodies are JSON (`Content-Type: application/json`), with `camelCase` field names.
- **Bodies are strict.** An unknown field answers `422 invalid_request`, with `param` naming the field. This catches typos like `externalref` before they become silent bugs.
- Optional fields are omitted from answers when they do not apply. Treat a missing field and `null` the same.

## Money

Amounts are integers in **minor units**, VAT included:

```json
{ "amountMinor": 14900, "vatMinor": 2980, "exVatMinor": 11920, "currency": "NOK" }
```

is NOK 149.00, of which NOK 29.80 VAT. Never use floating point for money.

## Times

Times are RFC 3339. You may send any offset; answers are in UTC. `timeZone` names the market's IANA zone (`Europe/Oslo`) for showing times to people. Window option keys use the market's local offset, such as `window:2026-11-03T17:00:00+01:00/2026-11-03T19:00:00+01:00`.

## Identifiers

| Id                               | Example        | Notes                                              |
| -------------------------------- | -------------- | -------------------------------------------------- |
| Order `id`                       | `3f0e9a52-…`   | A UUID. Equals the `quoteId` it was placed on.     |
| `reference`                      | `DD-482913`    | Short and human. Paths accept it in place of `id`. |
| `externalRef`                    | `order-1001`   | Yours. Unique among your live orders.              |
| Location `id`, `externalStoreId` | `oslo-sentrum` | Either names a store in a quote or order.          |

## Headers

| Header                                    | Direction | Meaning                                                                                                                                               |
| ----------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization: Bearer dmk_…`             | request   | Your [API key](/authentication/).                                                                                                                     |
| `Idempotency-Key`                         | request   | A UUID that makes a write safe to retry. See [Idempotency](/conventions/idempotency/).                                                                |
| `X-Request-Id`                            | both      | The request's id. Send your own (up to 64 characters of `A-Za-z0-9._-`) to correlate with your logs; otherwise Delivr makes one. Quote it to support. |
| `Delivr-Api-Version`                      | response  | The API version that answered. See [Versioning](/conventions/versioning/).                                                                            |
| `Idempotent-Replayed: true`               | response  | The answer is a replay of an earlier request.                                                                                                         |
| `RateLimit-Limit`, `-Remaining`, `-Reset` | response  | Your [rate limit](/conventions/rate-limits/).                                                                                                         |

## Pagination

List endpoints answer `{ "items": [...], "nextCursor": "…" }`. Pass `cursor=<nextCursor>` for the next page, and stop when `nextCursor` is absent. Cursors are opaque; do not build or parse them.