Commerce infrastructure for AI agents

AI coding agents are good at greenfield code and bad at platforms. When we shipped the first Swell skill in May, we described why: an agent that doesn't know a platform's conventions either invents its own, which breaks at runtime, or asks you to spell out every constraint, which defeats the point of using an agent.

That was about writing code. The same failure gets worse when an agent acts on a live system. A commerce platform is not a repository an agent can read end to end. It is a running service with a schema, validations, and side effects. Everything the agent knows about it comes from documentation, and documentation drifts. The agent guesses, the guess is stale, and the write fails. Or worse, it succeeds wrongly. Guesswork is the bug.

We think the next generation of commerce systems will be built, and increasingly operated, by agents working alongside the people who own them. The platforms that win will be the ones an agent can discover, verify, and safely act on at runtime. That is an architectural property, not a feature you bolt on afterward. Today we published swell.is/ai to lay out how Swell is built for exactly this.

What an agent needs from a platform

Self-description at runtime. A Swell store can tell an agent its schema:

const { swell } = require('swell-node');
swell.init(storeId, secretKey);
const models = await swell.get('/:models');

One call returns the store's models: standard, merchant-customized, and app-installed alike, with field types, relationships, and over 750 field descriptions. This layer of the documentation cannot drift, because it is generated from the same definitions the platform enforces on every write. The endpoint is covered in our model customization guide.

Machine-readable feedback. When a write fails validation, the API returns an errors object keyed by field, each entry carrying a code:

{
  "errors": {
    "rating": {
      "code": "REQUIRED",
      "message": "Required"
    }
  }
}

Codes like REQUIRED, MINVAL, and MAXVAL name the exact field and the exact rule that failed, so an agent corrects its own payload instead of parsing prose or escalating to a human. Feedback a machine can act on is the difference between a loop that converges and one that stalls.

Tooling that never blocks. An agent driving a CLI hangs the moment a command waits for input. The Swell CLI is built to a written contract: every interactive prompt gets a flag equivalent, -y accepts defaults instead of waiting, and errors state what was wrong and list the valid options, usually with a correct invocation. Exit codes are part of the contract too (success, user error, system error), so a script can tell a retriable failure from a payload it needs to fix. We are still rolling the contract out command by command, and we will keep closing the gaps until every command holds to it.

Guardrails that make autonomy structural. Autonomy is only useful when the blast radius is bounded by architecture, not by policy. On Swell, swell app push deploys to a test environment; it cannot reach production. Deploying to a live store is a separate, explicit command, so the default loop an agent runs never touches production. Config files carry a published $schema, so editors and CI catch mistakes before push, and the platform validates again before anything applies. An app declares the permissions it needs in swell.json, and merchants control what it can touch. None of this depends on the agent behaving well. On top of that structural layer sits a human checkpoint: apps published to the Swell App Store are reviewed before they go out. "Safe to hand to an agent" is a property of the system, not a hope about the model.

The API is a JSON file

On Swell, most of what an agent builds is configuration, not code. Drop a file into your app's models/ directory:

{
  "$schema": "https://json.swell.store/model.json",
  "label": "Reviews",
  "fields": {
    "product_id": { "type": "objectid", "required": true },
    "product": { "type": "link", "model": "products", "key": "product_id" },
    "rating": { "type": "int", "required": true },
    "body": { "type": "string" }
  }
}

Deploy it and the platform generates the REST resource: endpoints, validation, relationships, and created/updated/deleted events, with no endpoint code to write. There is no scaffolding for an agent to get subtly wrong, because there is no scaffolding.

That $schema line points at a real, published URL. You can verify it in thirty seconds:

curl https://json.swell.store/model.json

This returns the JSON Schema (draft 2020-12) that every Swell model definition file validates against. One contract serves every consumer: your editor autocompletes against it, CI validates against it, humans review the file as a plain diff, and agents generate it. Conventions that live outside the schema (file layout, the CLI loop, the failure modes worth knowing) are packaged as versioned Swell skills, starting with apps; Backend API and storefront skills are rolling out.

What this is not

There is a separate, louder conversation happening about agentic checkout, protocols for agents that shop and pay on behalf of consumers. That layer is unsettled, and we are announcing nothing in it today. Our position is one line: merchants keep their checkout, and our job is to make the commerce system behind it legible to the agents that build and operate it. Credit where due: the teams working on agent payments are solving a real problem. It is not the problem this post is about.

The bet

Stated plainly: the default author of a commerce integration will soon be an agent with a human reviewing. Platforms designed around human memory — read the docs, retain the conventions, hope nothing changed — will fight that shift. Platforms that describe themselves at runtime, fail with machine-readable precision, and bound the blast radius structurally will compound with it. Swell is the second kind, and has been since before agents could take advantage of it.

Trying it takes a few minutes. Create a store, point your agent at it, and install the skill:

npx skills add swellstores/skills -y

Then ask your agent to build something. Where it knows the conventions, it will use them. Where it doesn't, it will ask the store.