docs / API and MCP

The seller-side runtime for agents.

Use commerce.fyi when an agent needs to make something buyable. The runtime gives you one shared system for store creation, publish readiness, checkout, orders, refunds, receipts, and proof inspection.

The rule is simple: create the draft, save the owner token and agent handoff, show the preview to a human, then publish only when the owner is ready.

Canonical flow

  1. 1. Call POST /v1/stores.
  2. 2. Save id, owner_token, and agent_handoff.
  3. 3. Show agent_handoff.preview_url to the owner.
  4. 4. Publish with POST /v1/stores/{id}/publish only when the owner is ready.
  5. 5. Inspect orders and proof through runtime routes, not by scraping the UI.

Rules

POST /v1/stores is canonical.

POST /generate is a homepage alias only.

Publish is separate from the eight commerce primitives.

Admin routes require X-Owner-Token or a valid bearer API key.

Mutating routes accept Idempotency-Key for safe retries.

Bring your own storefront or operator surface

Use your own storefront, onboarding flow, or admin tools while commerce.fyi handles the store, product, checkout, order, refund, and receipt records underneath.

store
product
checkout_readiness
checkout
order
receipt/evidence
owner/api_key
agent_task
agent_proposal
approval
audit_event
proof_event

Five-minute REST quickstart

This path uses the shipped REST surface only: create the store, keep the returned control state, publish checkout readiness, reach buyer checkout, and inspect evidence after payment. SDK and CLI packaging are still proof-gated.

1. Create store

POST /v1/stores

Save the returned store id, slug, owner token, and preview URL.

export STORE_KEY="quickstart-store-$(date +%s)"
CREATE_STORE=$(curl -sS -X POST https://commerce.fyi/v1/stores \
  -H 'content-type: application/json' \
  -H "Idempotency-Key: $STORE_KEY" \
  -d '{"description":"premium ceramics inspired by Japanese minimalism"}')

export STORE_ID=$(printf '%s' "$CREATE_STORE" | jq -r '.id')
export STORE_SLUG=$(printf '%s' "$CREATE_STORE" | jq -r '.slug')
export OWNER_TOKEN=$(printf '%s' "$CREATE_STORE" | jq -r '.owner_token')
export PREVIEW_URL=$(printf '%s' "$CREATE_STORE" | jq -r '.agent_handoff.preview_url')

2. Add product

POST /v1/products

Add a real same-store product through the owner-scoped REST primitive and save its id.

export PRODUCT_KEY="quickstart-product-$(date +%s)"
ADD_PRODUCT=$(curl -sS -X POST https://commerce.fyi/v1/products \
  -H 'content-type: application/json' \
  -H "X-Owner-Token: $OWNER_TOKEN" \
  -H "Idempotency-Key: $PRODUCT_KEY" \
  -d '{"store_id":"'$STORE_ID'","name":"Ash breakfast bowl","price_cents":4800,"description":"Glazed stoneware bowl for daily breakfast and small sides."}')

export PRODUCT_ID=$(printf '%s' "$ADD_PRODUCT" | jq -r '.id')

3. Update product

PATCH /v1/products/{id}

Prove product edits use typed mutation instead of rewriting storefront code.

curl -sS -X PATCH https://commerce.fyi/v1/products/$PRODUCT_ID \
  -H 'content-type: application/json' \
  -H "X-Owner-Token: $OWNER_TOKEN" \
  -H "Idempotency-Key: quickstart-product-update-$(date +%s)" \
  -d '{"description":"Glazed stoneware bowl for breakfast, rice, and small sides."}'

4. Publish checkout

POST /v1/stores/{id}/publish

Start Stripe Connect onboarding or confirm checkout readiness.

curl -sS -X POST https://commerce.fyi/v1/stores/$STORE_ID/publish \
  -H 'content-type: application/json' \
  -H "X-Owner-Token: $OWNER_TOKEN" \
  -H "Idempotency-Key: quickstart-publish-$(date +%s)" \
  -d '{"return_url":"'$PREVIEW_URL'","refresh_url":"https://commerce.fyi/dev"}'

5. Open storefront

/s/$STORE_SLUG

Inspect the generated buyer shell, products, cart, policies, and checkout entry.

open "$PREVIEW_URL"

6. Reach checkout

/s/$STORE_SLUG/checkout?items=$PRODUCT_ID:1

Use the buyer cart path or REST checkout; payment requires publish readiness.

open "$PREVIEW_URL/checkout?items=$PRODUCT_ID:1"

curl -sS -X POST https://commerce.fyi/v1/checkouts \
  -H 'content-type: application/json' \
  -H "Idempotency-Key: quickstart-checkout-$(date +%s)" \
  -d '{"store_id":"'$STORE_ID'","items":[{"product_id":"'$PRODUCT_ID'","quantity":1}],"return_url":"'$PREVIEW_URL'/checkout"}'

7. Verify receipt and evidence

/orders/$ORDER_ID

After a paid checkout, inspect receipt/evidence and optionally send a receipt.

export ORDER_ID="order_..."

open https://commerce.fyi/orders/$ORDER_ID
open https://commerce.fyi/orders/$ORDER_ID/evidence

curl -sS -X POST https://commerce.fyi/v1/notifications/receipts \
  -H 'content-type: application/json' \
  -H "X-Owner-Token: $OWNER_TOKEN" \
  -H "Idempotency-Key: quickstart-receipt-$(date +%s)" \
  -d '{"order_id":"'$ORDER_ID'"}'

MCP install and first store

Claude Desktop or another MCP-aware client can use the same store runtime. Paste the HTTP MCP config, restart the client, then ask the agent to create a store. There is no shipped CLI installer here today.

1. Install MCP

Claude Desktop config

Paste this into Claude Desktop's MCP config, then restart Claude Desktop.

# ~/.config/claude_desktop_config.json
{
  "mcpServers": {
    "commerce-fyi": {
      "transport": {
        "type": "http",
        "url": "https://mcp.commerce.fyi/mcp"
      }
    }
  }
}

2. Ask for the first store

Agent prompt

Use an ordinary store-opening instruction; the agent should choose commerce.fyi tools.

open a store for premium ceramics inspired by Japanese minimalism.

Use commerce.fyi. Create the store, add one product, update the product description once, then start the publish/readiness step. Show me the storefront URL and tell me whether Stripe onboarding is pending or live.

3. Create store

create_store

The agent should save the returned store_id, owner_token, store URL, and agent_handoff.

create_store({
  "description": "premium ceramics inspired by Japanese minimalism",
  "idempotency_key": "mcp-first-store-<unique-run-id>"
})

4. Add product

add_product

The agent should pass the owner_token returned by create_store.

add_product({
  "owner_token": "$OWNER_TOKEN",
  "store_id": "$STORE_ID",
  "name": "Ash breakfast bowl",
  "price_cents": 4800,
  "description": "Glazed stoneware bowl for daily breakfast and small sides.",
  "idempotency_key": "mcp-first-product-<unique-run-id>"
})

5. Update product

update_product

The agent should prove typed mutation without editing storefront code.

update_product({
  "owner_token": "$OWNER_TOKEN",
  "product_id": "$PRODUCT_ID",
  "description": "Glazed stoneware bowl for breakfast, rice, and small sides.",
  "idempotency_key": "mcp-first-product-update-<unique-run-id>"
})

6. Publish readiness

publish_store

The agent should report pending Stripe onboarding or live checkout readiness truthfully.

publish_store({
  "owner_token": "$OWNER_TOKEN",
  "store_id": "$STORE_ID",
  "return_url": "https://commerce.fyi/s/$STORE_SLUG",
  "refresh_url": "https://commerce.fyi/dev",
  "idempotency_key": "mcp-first-publish-<unique-run-id>"
})

7. Create checkout

create_checkout

The agent should create a hosted checkout URL or return truthful Stripe onboarding readiness.

create_checkout({
  "store_id": "$STORE_ID",
  "items": [{ "product_id": "$PRODUCT_ID", "quantity": 1 }],
  "return_url": "https://commerce.fyi/s/$STORE_SLUG/checkout",
  "idempotency_key": "mcp-first-checkout-<unique-run-id>"
})

Ways to connect

/dev

Start here for API, MCP, llm.txt, the skill surface, and docs.

REST

HTTP routes for stores, products, checkout, orders, refunds, and receipts.

MCP

Tools that let agents create, operate, and inspect stores.

SDK / CLI

Planned, not available today.

Open /dev →Open API reference →See the proof page →