Getting Started with Agents

A coding agent needs three things to build on Storelayer: judgment (the skill), concepts and worked workflows (these Markdown docs), and exact contracts (OpenAPI). For live operations it also needs a project API key, used either over plain HTTP or through the Storelayer MCP server.

Install the skill

npx skills add storelayer/skills

The canonical source is skills/storelayer/SKILL.md. Edit it in that repository; this docs site does not keep a second copy. For manual installation, download the raw skill into your agent’s skill directory as storelayer/SKILL.md.

How an agent finds information

Read /llms.txt — one line per page with a specific description.
Fetch only the relevant pages as Markdown by appending .md, e.g. /guides/loyalty-program.md.
For exact request/response shapes, select the needed paths from /openapi.json (it is large — filter with jq, don’t load it whole):
Terminal window
```
curl -s https://api.storelayer.io/openapi.json \
  | jq '.paths["/projects/{projectId}/users/{userId}/wallet/earn"]'
```
Implement, then verify against live state (balances, workflow runs, promotion evaluation).

Option A: plain HTTP

Give the agent STORE_LAYER_API_KEY (and the project ID for /projects/{projectId}/… paths) as environment variables and let it call https://api.storelayer.io with Authorization: Bearer $STORE_LAYER_API_KEY. See authentication.

Option B: the Storelayer MCP server

@storelayer/mcp-server (npm) exposes the Storelayer tool catalog as MCP tools over stdio for Claude Code, Claude Desktop, Cursor, and other MCP clients.

Variable	Required	Default	Purpose
`STORE_LAYER_API_KEY`	yes	—	Project API key; also selects the project
`STORE_LAYER_API_URL`	no	`https://api.storelayer.io`	API base URL

There is no project-ID variable: the project is whatever project the key belongs to. Use a separate key (and server entry) per project.

Claude Code:

claude mcp add storelayer -e STORE_LAYER_API_KEY=sk_your_key_here -- npx -y @storelayer/mcp-server

Generic MCP client config:

{
  "mcpServers": {
    "storelayer": {
      "command": "npx",
      "args": ["-y", "@storelayer/mcp-server"],
      "env": { "STORE_LAYER_API_KEY": "sk_your_key_here" }
    }
  }
}

On start the server loads the tool list from the API, so it always matches the deployed catalog; restart it to pick up new tools. Tool names replace dots with underscores: wallet.earn becomes wallet_earn, promotions.evaluate_cart becomes promotions_evaluate_cart.

Give the agent a concrete task

Use Storelayer to award 100 points when a customer’s purchase total reaches $50. Our purchase payload uses integer cents (payload.amount). Inspect existing rules first and test the threshold before enabling the rule.

Build a draft 10% basket promotion. Evaluate a qualifying and a non-qualifying cart (prices in cents) and show the per-item discounts.

Pitfalls

Write tools change real state (wallets, rules, promotions). Point agents at a test project’s key while developing.
Ingested events are processed asynchronously; agents should check the workflow run before concluding a rule did or didn’t fire.
Keys in agent configs are secrets — keep them out of committed files.