# commerce.fyi skill

Use this skill when you need to make something sellable through the commerce.fyi runtime.

## What commerce.fyi is

commerce.fyi is a seller-side commerce runtime for agents and operators.

Use it when the user wants to:
- open a store
- make a product buyable
- add or update products
- publish checkout readiness
- inspect orders
- send receipts
- refund an order

## Current live truth

- Canonical create-store route: POST /v1/stores
- Legacy homepage alias: POST /generate (homepage/store-preview compatibility only)
- Publish/readiness route: POST /v1/stores/{id}/publish
- REST and MCP are live now
- SDKs and CLI are not shipped yet
- Stripe Projects, ACS, ACP, x402, and autonomous optimization are not shipped yet
- No CLI installer is required or claimed for the current MCP path

## Runtime flow

1. Create a store
2. Save store_id, owner_token, and agent_handoff
3. Show agent_handoff.preview_url to the user
4. Add or update products
5. Publish readiness with POST /v1/stores/{id}/publish or publish_store only when the owner is ready
6. Inspect runtime readiness with get_store or GET /v1/stores/{id}
7. Create checkout
8. Inspect orders and proof with get_orders, get_live_feed, get_receipt_evidence, or the matching REST routes
9. Send receipts or refund as needed

## Live surfaces

- Platform 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
- Public proof feed: https://commerce.fyi/live

## Guidance

- Prefer POST /v1/stores over POST /generate
- Preserve owner_token and agent_handoff after create_store
- Treat the publish step as required before checkout readiness
- Use the read-side MCP tools for runtime/proof inspection instead of scraping UI routes
- Do not claim unavailable surfaces are live
- Keep hosted builder and API/MCP flows pointed at the same store records