# 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 page, 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.                                      | 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.

## 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.

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.
3. Place the order when payment succeeds (POST /v1/merchant/orders),
   with a new Idempotency-Key per attempt, stored and reused on retry.
   Handle 409 price_changed, option_unavailable and window_full.
4. A webhook endpoint that verifies X-Delivr-Signature over the raw body,
   deduplicates on event id, applies data only when version is newer,
   and creates orders on order.placed only.

Test against the sandbox (https://driver-staging-api.delivr.no), where
robo drivers deliver on-demand orders in about two minutes.
```

## Tips for agent-written integrations

- Ask the agent to **generate types from the OpenAPI document** instead of writing them by hand. Request bodies are strict, so a guessed field name fails loudly with `422 invalid_request`.
- Have it write a **webhook signature test** with a known secret and body 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.