Instructions for AI agents

This page is written for AI coding agents, and readable by the people who direct them. Point an agent at its Markdown version, https://docs.kentro.io/docs/ai-agent-instructions.md, add it to the agent's rules, or install the agent skills, which carry the same rules.

Instructions for AI agents building on Kentro

You are writing software that talks to Kentro. Follow these instructions unless the user explicitly asks for something else, and tell the user when a request conflicts with them.

1. Use the current APIs

• Use only the APIs in this table, at the hosts it lists, and only the endpoints their references document. Do not call, generate code for, or recommend any other Kentro URL. When existing code calls a Kentro URL that is not in this reference, stop and ask the user before changing it.
• Authenticate as Channel API authentication and Store API authentication describe.
• There is no Kentro SDK package, CLI or agent plugin. Call the HTTPS APIs with the language's standard HTTP client. Do not invent packages such as @kentro/sdk or commands such as kentro login. The only script Kentro serves is the Kentro Pixel browser SDK, loaded with a script tag.
• Look up every endpoint, field and enum in the API Reference before you use it: the .md pages listed in https://docs.kentro.io/llms.txt. Never guess field names. The Channel API refuses unknown fields with 400 validation_failed, and most Store API operations refuse them with 400 VALIDATION.
• Kentro MCP serves the user's AI client, not integrations. Never build an integration on Kentro MCP and never ask the user for a Kentro MCP token.

2. Credentials and scopes

• A Kentro admin creates API keys in Kentro OS under Users > API keys: https://kentro.cc for the sandbox, https://kentro.app for production. Ask the user for a key. Never ask for their Kentro password, and never ask them to paste a secret into the chat: ask them to put it in environment variables.
• Ask for the least privilege the job needs: channel:read for read-only work; the per-resource write scopes (customers:write, products:write, orders:write, fulfillment:write, shipments:write, invoices:write, payments:write, purchase-orders:write) for one job; channel:write only for a full channel integration; storefront:serve for a storefront server. Never request admin for an integration.
• Ask the user to bind a Channel API key to the sales channels the integration serves.
• Never derive, send or accept a tenant id. The key's tenant is the tenant of every call, and nothing in a request selects a tenant.
• Keep secrets in environment variables or a secrets store. Never commit them, log them, put them in a URL or ship them in client-side code.
• Channel API requests send kentro-key and kentro-secret, or Authorization: Bearer <accessToken> from POST https://apis.kentro.live/auth/login/api-key (15-minute token; the refresh token rotates at POST /auth/refresh). Store API requests send X-API-Key and X-Storefront-Host, plus X-Storefront-Buyer or X-Storefront-Guest for the buyer; the Store API does not read Authorization.
• Build and test against the sandbox with a sandbox key. A production key does not work in the sandbox. Switch to production only when the user asks.

3. Channel API writes

• Send an Idempotency-Key header on every POST, PUT, PATCH and DELETE: 7 to 50 characters, derived from the source system's identity for the change (shop-1001-create, a webhook delivery id), identical on every retry of that change. A new key means a new change.
• Send externalId, the source system's id, on every create, and address documents as ext:<channelId>:<externalId>.
• Keep onDuplicate: update (the default) so a replayed feed updates instead of duplicating. Use skip to never overwrite, and error when a duplicate must surface, such as a retailer purchase order received twice.
• Send version on a PATCH when overwriting a concurrent change would be wrong, and handle 409 version_conflict by reading the document again.
• Order lines name the sellable variant (sku, barcode, externalId or id), never the parent product group.
• Validate a write without storing anything with X-Dry-Run: true. Load history with X-Import-Mode: historical, which skips confirmation emails, packing slips, accounting exports and EDI documents. Send large batches to POST /v1/orders/import or POST /v1/products/import and poll GET /v1/operations/:id.

4. Store API calls

• Every operation is POST /<family>.<operation> with a JSON body, {} when it takes no fields.
• Call the Store API only from the storefront's server: server components, route handlers, server actions, API routes or a backend. Never call it from browser code; it answers with no CORS headers for tenant origins.
• Never place X-API-Key, buyer tokens or guest tokens in a browser bundle, a NEXT_PUBLIC_ variable, local storage, a readable cookie or a URL. Keep them on the server, keyed by your own httpOnly session cookie.
• Set X-Storefront-Host from configuration (the published storefront's host: lower case, no scheme, no path), or from an allowlist that maps your own domains to storefront hosts. Never take it from user input.
• Send X-Storefront-Client-Ip with the buyer's IP address and X-Expected-Buyer with the buyer id your session maps to.
• Send expectedRevision and ownershipVersion from the last cart answer on every cart mutation. On 409 CONFLICT, read cart.get again and let the buyer act; never retry with a bumped revision.
• Send idempotencyKey in the body of checkout.start, cart.addMany, cart claims, invoice payments, saved payment methods, subscriptions and applications: 7 to 50 characters from A-Z a-z 0-9 _ -.
• Check out in this order: cart.get { "quote": true }, then checkout.start with quoteFingerprint, expectedRevision and idempotencyKey, then follow state with checkout.status and checkout.confirm. Never start a second checkout while one is pending. Recover a lost answer with checkout.status { idempotencyKey, quoteFingerprint }.
• Do not cache Store API answers across requests; every answer is Cache-Control: no-store.

5. Money, dates and ids

• Channel API money is a decimal string in currency units with a currency: "unitPrice": "12.50", "currency": "USD". Never send cents, and do arithmetic with decimal types, not floats. Totals must add up, or the write is 422 totals_mismatch.
• Store API money is an integer in the currency's minor unit: 1250 is 12.50 USD. Format amounts for display on your side with the store's currency.
• Kentro Pixel money is an integer in minor units; floating-point money is rejected.
• Timestamps are ISO-8601 in UTC. Date-only fields take YYYY-MM-DD.

6. Reading and syncing

• Channel API lists are cursor based: limit 1 to 200 (default 50), follow nextCursor until it is null, no totals, newest first.
• Sync incrementally with updatedSince set to the latest updatedAt already processed, and walk every page before you advance the watermark.
• Store API lists are page based: page, hasNextPage, total and totalIsCapped.

7. Errors and retries

• Channel API errors are { "error": { "code", "message", "details", "requestId" } }. For 400 validation_failed, fix the field named in details[].path. For 403 forbidden, report the missing scope the message names. For 404 not_found and 422 unresolved_reference, create or fix the referenced document. For 409 duplicate, state_conflict and version_conflict, read the document again and decide. 422 idempotency_key_reused means a bug in your keys: one key was sent with two different bodies.
• Failures at Kentro's gateway use another shape: { "error": "INVALID_CREDENTIALS", "message": "..." }, TOKEN_EXPIRED (refresh the bearer token) or TENANT_INACTIVE.
• Store API errors are { "code", "message", "fieldErrors" }. The message is written for the buyer and can be shown as is. A declined payment is not an error: checkout.* answers 200 with state: "declined".
• Retry only 429, 409 in_progress, 500, 503 and network failures, with exponential backoff and jitter, at most five attempts, and never sooner than Retry-After when it is present. Retry Channel API writes with the same Idempotency-Key. A Store API write that answered 503 was not applied unless a later read shows it.
• The Channel API allows 1,200 writes and 6,000 reads per minute per tenant by default. Watch X-RateLimit-Remaining and slow down before 429.
• Log requestId (or the X-Request-Id header) with every failure. Kentro support is [email protected].

8. Before you report done

• Run the integration against the sandbox and show the user each request and response, with secrets redacted.
• Prove idempotency: send one Channel API write twice with the same Idempotency-Key and confirm the second answer carries Idempotent-Replayed: true.
• Prove that no key or token reaches client-side code: search the built client assets for the key value and for X-API-Key.
• List what you did not build or could not test.

Related

• Prompt library
• Agent skills
• Errors and limits
• Security