Working with AI agents

If your team works with a coding agent such as Claude Code or Codex, the agent can understand the merchant API itself and build integrations. Three machine-readable sources are available without a key.

Machine-readable sources

Source	Address	Use
OpenAPI spec	https://gateway.shirtee.cloud/public/merchant-api/openapi.json	The complete contract: all operations, parameters, examples, response codes and the required scopes (x-customer-scopes). Best source for generating a client.
llms.txt	/llms.txt	A short index of this documentation with links, meant for language models.
llms-full.txt	/llms-full.txt	All guides in one Markdown file. Fits into an agent’s context.

Tip

Give your agent llms-full.txt first for the concepts (authentication, preview, idempotency, errors) and the OpenAPI spec for the exact operations.

An instruction snippet for your repo

Put this section into your agent’s project instructions (AGENTS.md for Codex, CLAUDE.md for Claude Code):

## Shirtee merchant API

- Spec: https://gateway.shirtee.cloud/public/merchant-api/openapi.json
- Concepts: https://developers.shirtee.cloud/llms-full.txt
- Base URL: https://gateway.shirtee.cloud, authenticate with `Authorization: Bearer $SHIRTEE_API_KEY`.
- The token lives only in the environment variable. Never write it to code, logs, tests or output.
- There is no sandbox. Write calls go live. Use the `.../preview` endpoints before changes and
  create real orders only with explicit approval.
- Always send `Idempotency-Key` on `POST /api/orders` and retry only with the same key.
- Evaluate errors by `extra.error`, not `detail`. Retry only `429` and `5xx`,
  and on `429` wait at least `RateLimit-Reset` seconds.
- Ignore unknown fields in responses.

Letting an agent work safely

An agent acts fast and in loops. That needs guardrails:

• A separate key per agent, with the smallest necessary scopes. For development merchant_order:read and merchant_catalog:read are often enough. Add write permissions only when you need them, see Scopes.
• Short validity. A key for a development phase may expire after days, see API keys.
• No sandbox. Have the agent write tests against the preview endpoints and read operations. Creating real orders stays a deliberate act.
• Mind the rate limit. An agent loop reaches the budget quickly, see Rate limits.
• Never put the token in chat. Pass it via environment variable, not in the conversation.

And chat assistants?

For assistants such as Claude or ChatGPT that should do tasks in your account, set up a separate connection in the portal under KI-Assistent & API. It does not run through gateway.shirtee.cloud, see Overview.