# Build with AI agents

> Give your coding agent everything it needs to integrate the Delivr Merchant API.

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

These docs are written to be read by people and by AI coding agents such as Claude Code, Cursor, Codex and Copilot. Point your agent at the right file and it can write most of an integration for you.

## Machine-readable files

| File                                 | What it is                                                                                          | Use it for                                                                     |
| ------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [`/openapi.yaml`](/openapi.yaml)     | The OpenAPI 3.1 contract: every route, schema, error code and webhook.                              | Generating clients and types, and as the agent's ground truth for field names. |
| [`/llms.txt`](/llms.txt)             | An index of every guide, with a link to its Markdown, following [llmstxt.org](https://llmstxt.org). | Letting an agent find the right page.                                          |
| [`/llms-full.txt`](/llms-full.txt)   | Every guide in one Markdown file, in reading order.                                                 | Loading all the docs into an agent's context at once.                          |
| [`/llms-small.txt`](/llms-small.txt) | A condensed version.                                                                                | Smaller context windows.                                                       |
| `/<page>.md`                         | Any guide as Markdown, such as [`/quickstart.md`](/quickstart.md).                                  | Quoting one page.                                                              |

Every guide page also has **Copy page**, **View as Markdown**, **Open in Claude** and **Open in ChatGPT** buttons under its title. The API reference pages have no Markdown version: use `/openapi.yaml` for them.

## A prompt to start from

```text
Integrate the Delivr Merchant API into this codebase.

Read https://docs.delivr.no/llms-full.txt for the guides and
https://docs.delivr.no/openapi.yaml for the exact contract. Prefer the
OpenAPI document for field names and types, and generate types from it.

Build:
1. A server-side Delivr client with the API key from the environment
   (DELIVR_API_KEY), base URL from DELIVR_API_URL. Never expose the key
   to the browser.
2. Quote at checkout (POST /v1/merchant/quotes) and show the options.
   Name the store by pickupExternalStoreId or pickupLocationId, never both.
3. Place the order when payment succeeds (POST /v1/merchant/orders).
   Use one Idempotency-Key per logical action: generate it once, save it
   with the order before the first attempt, and reuse it on every retry
   of that action. Retry network errors, 429, 500 and 503 and
   409 idempotency_key_in_flight with the same key.
   Handle 409 price_changed, option_unavailable and window_full.
4. A webhook endpoint that verifies X-Delivr-Signature over the raw body
   (HMAC-SHA256 keyed with the whole whsec_ secret, not decoded), answers
   2xx fast for every verified event including unknown types,
   deduplicates on event id, applies data only when version is newer,
   and creates orders on order.placed only.
5. Handling for failed orders: with a fallback policy, wait for
   order.successor_created (follow successorId) or
   order.fallback_cancelled before telling the shopper.
6. A test for the signature check using the test vector at
   https://docs.delivr.no/webhooks/signatures/#test-vector.

Test against the sandbox (https://driver-staging-api.delivr.no), where
robo drivers deliver on-demand orders in about two minutes. Call
POST /v1/merchant/orders/{id}/ready after placing so the search starts
at once.
```

## Tips for agent-written integrations

- Ask the agent to **generate types from the OpenAPI document** instead of writing them by hand; see [Client libraries](/client-libraries/). Request bodies are strict, so a guessed field name fails loudly with `422 invalid_request`.
- Have it write a **webhook signature test** with the [test vector](/webhooks/signatures/#test-vector) before wiring the endpoint up.
- Run the [go-live checklist](/go-live/) yourself. It covers what agents most often miss: idempotency keys reused across retries, version checks on webhooks, and handling `failed` orders.