Build with AI agents

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	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	An index of every guide, with a link to its Markdown, following llmstxt.org.	Letting an agent find the right page.
/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	A condensed version.	Smaller context windows.
/<page>.md	Any guide as Markdown, such as /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

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. 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 before wiring the endpoint up.
• Run the go-live checklist yourself. It covers what agents most often miss: idempotency keys reused across retries, version checks on webhooks, and handling failed orders.