# commerce.fyi

commerce.fyi lets developers and agents turn generated experiences into real commerce: create stores, hand draft previews to owners, publish checkout, create checkout sessions, inspect orders, issue refunds, and send receipts.

Website: https://commerce.fyi
Dev page: https://commerce.fyi/dev
Docs landing: https://commerce.fyi/docs
API reference: https://commerce.fyi/docs/api
REST base URL: https://commerce.fyi/v1
OpenAPI JSON: https://commerce.fyi/v1/openapi.json
MCP server: https://mcp.commerce.fyi/mcp
Skill surface: https://commerce.fyi/skills/commerce-fyi.md
Public proof feed: https://commerce.fyi/live

## Current product shape

commerce.fyi has two current ways to use the product:
- Hosted builder: create and edit a store on commerce.fyi
- API and MCP: build your own flow with the same commerce records

The first live sellable experience is a store. Future non-store adapters and provisioning work are not available today. Do not describe Stripe Projects, ACS, x402, SDK publication, CLI packaging, or non-store sellable-experience adapters as shipped unless current repo truth explicitly says they are live.

## Current live truth

- REST and MCP are live now.
- Canonical create-store route: POST /v1/stores
- Legacy homepage alias: POST /generate
- Publish/readiness route: POST /v1/stores/{id}/publish
- Publish MCP tool: publish_store
- TS and Python SDK packages are placeholders only.
- CLI packaging is not shipped yet.
- No CLI installer is required or claimed for the current MCP path.
- /live is the v1.0 public proof feed, not the later Fi action stream.

## What an agent can do today

REST primitives:
- POST /v1/stores
- POST /v1/products
- PATCH /v1/stores/{id}
- PATCH /v1/products/{id}
- POST /v1/checkouts
- GET /v1/orders?store_id=...
- POST /v1/orders/{id}/refund
- POST /v1/notifications/receipts

Separate go-live step:
- POST /v1/stores/{id}/publish

Read-side runtime/proof routes:
- GET /v1/stores/{id}
- GET /v1/proof/live
- GET /v1/orders/{id}/evidence

MCP tools:
- create_store
- add_product
- update_store
- update_product
- create_checkout
- get_orders
- refund_order
- send_receipt
- publish_store
- get_store
- get_live_feed
- get_receipt_evidence

## Auth and safety

- create_store is anonymous-friendly and returns an owner token.
- create_store also returns agent_handoff with preview_url, edit_url, publish_url, owner_token, and next_actions.
- create_checkout is public buyer-facing.
- Admin routes require X-Owner-Token or a valid bearer API key.
- MCP owner-scoped tools use owner_token arguments in v1; bearer API keys are REST-only until a safe MCP auth path ships.
- Mutating routes accept Idempotency-Key; refunds require it.
- Use unique idempotency keys per real user/run. Do not copy sample keys across users.
- Do not assume published checkout readiness until the publish flow has completed.
- Private Fi proposal routes are not public REST or MCP primitives in v1.

## Typical runtime flow

1. Create a store with POST /v1/stores
2. Save the returned store_id, owner_token, and agent_handoff
3. Show agent_handoff.preview_url to the user for review
4. Add or update products
5. Publish the store with POST /v1/stores/{id}/publish or publish_store only when the owner is ready
6. Inspect runtime readiness with GET /v1/stores/{id} or get_store
7. Create checkout with POST /v1/checkouts
8. Inspect orders and proof with GET /v1/orders, GET /v1/proof/live, GET /v1/orders/{id}/evidence, or the matching MCP tools
9. Send receipts or issue refunds if needed

## MCP first-store prompt

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.

## Example REST calls

Create a store:
```bash
curl -X POST https://commerce.fyi/v1/stores \
  -H 'content-type: application/json' \
  -d '{"description":"premium ceramics inspired by Japanese minimalism"}'
```

Publish checkout readiness:
```bash
curl -X POST https://commerce.fyi/v1/stores/store_abc/publish \
  -H 'content-type: application/json' \
  -H 'X-Owner-Token: own_abc123' \
  -H 'Idempotency-Key: publish-store-<unique-run-id>' \
  -d '{"return_url":"https://commerce.fyi/s/<store-slug>"}'
```

Add a product:
```bash
curl -X POST https://commerce.fyi/v1/products \
  -H 'content-type: application/json' \
  -H 'X-Owner-Token: own_abc123' \
  -d '{
    "store_id": "store_abc",
    "name": "Tea Bowl",
    "price_cents": 4800
  }'
```

## Guidance for agents

- Prefer POST /v1/stores over the legacy alias POST /generate.
- Treat POST /generate as homepage/store-preview compatibility only.
- Preserve owner_token and agent_handoff from create_store; do not ask the user to reconstruct these values.
- Treat publish_store or POST /v1/stores/{id}/publish as required before checkout readiness.
- Use get_store, get_live_feed, and get_receipt_evidence for read-side runtime/proof inspection instead of scraping UI routes.
- Do not claim SDKs, CLI, Stripe Projects, ACS, ACP, or x402 are live.
- Use the OpenAPI spec, /dev, and the skill surface for current runtime semantics.