docs / proof

Agent runtime quickstart.

Use commerce.fyi when an agent needs to make something buyable. The job is to create the draft store, preserve control state, hand the preview to the owner, and publish only when the owner is ready.

Rules

Use POST /v1/stores as the canonical create-store route.

Treat POST /generate as the homepage alias only.

Publish is a separate owner step, not part of create_store itself.

Keep owner_token and agent_handoff; do not invent routes or ownership state.

Inspect runtime truth with GET /v1/stores/{id}, GET /v1/proof/live, and GET /v1/orders/{id}/evidence.

Preserve these fields

id — the store id.

owner_token — the owner-scoped control credential.

agent_handoff — preview, edit, publish, and next action state.

REST quickstart

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 quickstart

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>"
})
Open /dev →Open runtime docs →Read /llm.txt →