# Webround: a guide for AI agents Read this first. It tells you what Webround is, which door to use for the task you were given, how to authenticate, and where the rest is documented. This file is generated from the documentation at https://docs.webround.com: when the docs change, it does. ## What Webround is Webround builds, publishes and runs websites and online stores. It has two parts that work together or on their own: - **Webround Sites.** A site is a **draft**: a React + Vite + Tailwind project in which **the code is the source of truth**. People change it in a visual editor, in code (VS Code in the browser) or through an AI. The editor is a guardrailed, fast way to change the same files you can change by hand. Published sites go to a CDN, on a `webround.net` address or on the customer's domain. - **Webround Commerce.** A **store**: a headless engine for products, variants, prices, taxes, stock, shipping, promotions, orders, customers, returns and reviews, with an API for everything. Payments go through the merchant's own Stripe account (Standard mode), and any other gateway can be connected through the public APIs. A draft and its store share the same ID. The store does not depend on the site: it can serve a mobile app, a point of sale or any other front-end. ## Pick the door for your task | If you have to… | Use | Start here | |---|---|---| | Read or change store data: products, orders, promotions, shipping, taxes, settings | **Commerce MCP** (269 tools in 31 groups, loaded by toolset) or the **Commerce API** | https://docs.webround.com/mcp/commerce/ | | Change a site: pages, sections, texts in every language, SEO, theme, styles, files | **Editor MCP** (one server for each draft); the layout of the project and the rules of its components are in the **Project guide** | https://docs.webround.com/mcp/editor/ and https://docs.webround.com/mcp/project-guide/ | | Work inside a draft's project (you were started in its container) | The files of the project and the `wr` command; read `CLAUDE.md` in the project root (the same text as the Project guide) | the project's own `CLAUDE.md`, and https://docs.webround.com/mcp/wr-command/ for `wr` | | Build a custom storefront or app on a store | **SDK** `@webround/commerce` (logic) and `@webround/commerce-react` (hooks), over the Catalog and Checkout APIs | https://docs.webround.com/sdk/overview/ | | Be told when something happens (new order…) | **Webhooks** (signed) | https://docs.webround.com/webhooks/introduction/ | | Change how checkout works (cart, discounts, shipping, validation) | **Checkout hooks** (your server joins the checkout) | https://docs.webround.com/integrations/checkout-hooks/ | ## Authentication Everything uses an **API key** created in the Webround dashboard, with only the permissions (scopes) it needs: ``` Authorization: Bearer ``` - The **Commerce MCP** and the **Commerce API** also need the headers `store-id` (the store, which is the draft's ID) and `user-id` (the store's owner or one of its collaborators). - The **Editor MCP** needs a key with the **`site:update`** scope, even for tools that only read. It has no other headers. - If the key lacks a permission the API answers with an error: tell the user which scope is missing, do not look for another way in. - Keys are for servers and tools. **Never put a key in code that runs in a browser** and never commit one. ## Rules that save you mistakes - **Read before you write.** Ask the user before anything that deletes or replaces: the MCP servers mark destructive tools so you can. - **The server is the truth.** Totals, prices, taxes and stock come from the store: show them, do not calculate them. Do not validate requests against your own assumptions; send them and read the error (`code` and `issues` say what is wrong). - **Languages.** Text fields have a default-language value and a `translations` object keyed by locale (`en`, `it`…). The default language goes outside `translations`. - **Links between entities are replaced as a whole.** Setting the tags, options or shipping methods of a product sends the full list (see the Commerce API introduction). - **Files hosted by Webround** are uploaded and deleted through the Core API, never only through the Commerce API. - **In a draft's project, the code is the truth.** Use the editor's components and the `wr` commands, keep ids literal and unique, use the theme's semantic colors. The project's `CLAUDE.md` has the rules. ## Endpoints | API | Base URL | Operations | What it is | |---|---|---|---| | Commerce API | `https://commerce-api.webround.com` | 310 | Back-office of the store: catalog, orders, customers, promotions, settings. Scoped by `store-id`. | | Catalog API | `https://catalog-api.webround.com` | 8 | Read-only catalog for front-ends: products and collections, by language and currency, with enrichment on demand. | | Checkout API | `https://checkout-api.webround.com` | 3 | Turns a cart into a Stripe Checkout Session and an order. | | Core API | `https://core-api.webround.com` | 18 | Drafts and the files stored for them (images, videos). | OpenAPI 3 documents, for tools that read them: [Commerce API](https://docs.webround.com/openapi/commerce-api.json), [Catalog API](https://docs.webround.com/openapi/catalog-api.json), [Checkout API](https://docs.webround.com/openapi/checkout-api.json), [Core API](https://docs.webround.com/openapi/core-api.json) ## Documentation map ### Start - [What is Webround](https://docs.webround.com/intro/): Webround builds, publishes and runs websites and online stores. ### Concepts - [API Keys](https://docs.webround.com/concepts/api-keys/): Give a script, an app or Claude access to a store, with only the permissions it needs. - [Domains and SSL](https://docs.webround.com/concepts/domains/): Publish on a free webround.net address or on your own domain, with SSL. - [Sites](https://docs.webround.com/concepts/sites/): A site is a draft you edit, publish on a domain and optimize for search engines. - [Store](https://docs.webround.com/concepts/stores/): A store holds your catalog, orders and customers, with an API for everything. ### Quickstart - [Create your site](https://docs.webround.com/quickstart/draft/): From a template to a published site in a few steps. - [Create your store](https://docs.webround.com/quickstart/ecommerce/): Turn your site into a shop and get ready to sell. ### MCP - [Connect an AI to Webround](https://docs.webround.com/mcp/overview/): Use any AI assistant with your Webround store and your site through MCP. - [Commerce tools](https://docs.webround.com/mcp/commerce-tools/): Every tool of the Webround Commerce MCP server, by toolset. - [Webround Commerce MCP](https://docs.webround.com/mcp/commerce/): Manage your store with Claude, from products and orders to promotions, shipping and settings. - [Editor tools](https://docs.webround.com/mcp/editor-tools/): Every tool of a draft's MCP server, what it does and the parameters it takes. - [Webround Editor MCP](https://docs.webround.com/mcp/editor/): Build and change your site with Claude, from pages and texts to SEO, theme and styles. - [Project guide](https://docs.webround.com/mcp/project-guide/): How a draft's project is laid out and the rules that keep the editor able to read it, for an AI that works on a site. - [The wr command](https://docs.webround.com/mcp/wr-command/): The command to look at a draft's site and check it from the terminal: its syntax and every command. ### SDK - [SDK](https://docs.webround.com/sdk/overview/): The libraries that connect your own front-end to a Webround store. - [@webround/commerce](https://docs.webround.com/sdk/commerce/): Catalog, customers, cart and checkout of a Webround store, without a framework. - [@webround/commerce-react](https://docs.webround.com/sdk/react/): React 19 hooks for the shop, the customer, the cart and the checkout. ### API - [Introduction to Catalog APIs](https://docs.webround.com/api/introduction-catalog-apis/) - [Introduction to Checkout APIs](https://docs.webround.com/api/introduction-checkout-apis/) - [Introduction to Commerce APIs](https://docs.webround.com/api/introduction-commerce-apis/) - [Introduction to Core APIs](https://docs.webround.com/api/introduction-core-apis/) ### Commerce entities - [Products and variants](https://docs.webround.com/commerce-entities/introduction/): A product is the template, a variant is what the customer buys. - [Collections and filters](https://docs.webround.com/commerce-entities/collection/): Conditions, filters and collections decide which products a visitor sees. - [Orders](https://docs.webround.com/commerce-entities/order/): An order records a sale, with who bought, what, at which prices, and what happened to the payment and the shipment. - [Promotions](https://docs.webround.com/commerce-entities/promotion/): Coupons need a code, catalog promotions change prices. - [Shipping and taxes](https://docs.webround.com/commerce-entities/shipping-and-tax/): Where you can sell, what shipping costs and which VAT applies. - [Customers](https://docs.webround.com/commerce-entities/store-customer/): The people who buy from you, how they sign in, and what they can do. - [Subscriptions](https://docs.webround.com/commerce-entities/subscription/): Recurring payments are billed by Stripe and recorded in Webround. - [Tags and attributes](https://docs.webround.com/commerce-entities/tag/): Tags describe what is shared between products, attributes what is unique to one. - [Stock](https://docs.webround.com/commerce-entities/warehouse/): Warehouses hold the quantity of each variant. - [Create a Product](https://docs.webround.com/commerce-examples/products/) ### Integrations - [Integrations](https://docs.webround.com/integrations/overview/): How Webround connects to your tools, with native providers and with your own code. - [Apps](https://docs.webround.com/integrations/apps/): Put your own applications inside your Webround dashboard. - [Checkout hooks](https://docs.webround.com/integrations/checkout-hooks/): Change the cart, apply discounts, choose shipping or block an order during checkout, with your own server. - [Email providers](https://docs.webround.com/integrations/email/): Set up Webround Email or an external provider for your forms and transactional emails. - [Product feeds](https://docs.webround.com/integrations/feeds/): Export your products as XML, CSV or JSON for marketplaces and price comparison sites. - [Page hooks](https://docs.webround.com/integrations/hooks/): Call your own server while a page of your site loads, and inject the answer into the page. - [Stripe](https://docs.webround.com/integrations/stripe/): Connect your own Stripe account to take payments in your store. ### Webhooks - [Webhooks](https://docs.webround.com/webhooks/introduction/): Webround tells your systems when something happens in your store. - [Order events](https://docs.webround.com/webhooks/orders/): The events of orders and of their items. - [Variant events](https://docs.webround.com/webhooks/product-variant/): The events of variants, with their prices and stock. - [Product events](https://docs.webround.com/webhooks/product/): The events of products and of what is linked to them. - [Return request events](https://docs.webround.com/webhooks/return-request/): The events of return requests. - [Customer events](https://docs.webround.com/webhooks/store-customer/): The events of customers, their addresses and the emails that concern them. - [Subscription events](https://docs.webround.com/webhooks/subscription/): The events of subscriptions. ### Plans - [Plans](https://docs.webround.com/pricing/overview/): Webround Sites and Webround Commerce each have their own subscription.