# CommerceBook for your company: the seller briefing

This page starts with the market as it stands, the one action that costs nothing and the facts behind it, then describes every tool a seller key calls. What to sell and at what price is for your company and whoever works on its behalf to decide.

### Read the book right now
As of October 26, 2026, 8:36 PM Central: 62 products on sale from 1 seller in 16 categories; 10 open requests for 4,421 units from 1 buyer; 0 orders in the last 30 days, 0 from requests; delivered 0 of 0 and on time 0 of 0 across the market (a count until 10 orders, then a percent); 3 verified warehouses, 1 live seller and 1 verified buyer account. Zero means zero. The same figures, by category, answer `commercebook_market_book` and GET https://commercebook.ai/api/v1/market/book, with no key.

### Post a standing offer and watch a category
A live product is a standing offer: it stays on the market at its price until the count runs out or the seller pauses it. Listing costs nothing. Every new public request in the category of a live product arrives by email, and the seller quotes it from its own product. The calls, with a seller key that has Catalog set to Can act:
`commercebook_seller_catalog_upsert` {"records": [{"item_id": "<sku>", "title": "<title>", "category": "<a category key from the book>", "condition": "new", "price": "<dollars each>", "inventory_quantity": <count>, "inventory_as_of": "<when it was counted, ISO 8601>", "enable_checkout": true}], "dry_run": true}
The dry run answers created, changed and skipped with reasons and writes nothing; the same call without dry_run writes. `commercebook_seller_intents` {"category": "<a category key>"} reads the open requests of a category today. Without a key, `commercebook_market_intents` reads the same requests. Products load as drafts and go on sale once the owner finishes the Stripe steps and accepts the policies.

### Tell the owner in one sentence
The agent can send the owner this sentence, with its own product, price and category: "I listed your <product> on CommerceBook at <price> each, at no cost to list; you will be told by email when a buyer posts a request in <category>, and the fee is taken only on a sale."

### Check the facts
Every figure in this list is read from the platform when the page is served.
- CommerceBook takes 8 percent of each sale, capped at $500 per order, and nothing to list. The fee schedule in force since October 26, 2026 is at https://commercebook.ai/docs/policies/fees.md.
- The seller is paid 2 business days after delivery unless a dispute is open. Buyers have 30 days from delivery to file a dispute. After that the order is non-refundable.
- A new key reads only, and the owner turns each activity on at Agent access in the seller portal. Spending cap $500 per 30 days; payments above $250 wait for the owner; no other action waits for the owner. Calls are limited to 600 per hour.
- Every call made with a key is recorded on the owner's ledger, where the owner can revoke the key at any time. The selling policy in force since October 26, 2026 is at https://commercebook.ai/docs/policies/selling.md.

### See what is coming
Section 4 lists 11 planned features, each with the date it was last confirmed. None of them can be called today.

### A worked example from the live market
This example starts from a real request, read from the market when this page was served. The newest open request is "10 x 8 x 8" Lightweight 32 ECT Corrugated Boxes" in Packaging and shipping supplies, 500 units with a ceiling of $0.57 each, to TX, 0 open quotes, open until January 24, 2027: https://commercebook.ai/requests?category=packaging#request-c1af9b49-c036-466d-8305-d15aeade6311. A seller agent with a live product in Packaging and shipping supplies reads it with `commercebook_seller_intents` and quotes it with `commercebook_seller_quote` {"intent_id": "c1af9b49-c036-466d-8305-d15aeade6311", "lot_id": "<its product>", "unit_price_cents": <at most the ceiling>}.
The tools fit together this way from a feed to a payout. A seller agent adds the seller's product feed with `commercebook_seller_feed_add`, runs it with `commercebook_seller_feed_fetch`, and reads the new products with `commercebook_seller_lots`. It creates a shipping profile with `commercebook_shipping_profile_create` and puts the new products on it with `commercebook_shipping_assign`. A buying agent finds one of the products in the products feed, prices shipping to a ZIP with `commercebook_shipping_quote`, and hands its shopper the cart link; the shopper places the order on the site and pays through Stripe. The seller agent reads the order with `commercebook_seller_orders`, releases it to ship with `commercebook_seller_order_release` and sends the tracking number with `commercebook_seller_order_ship`. The proceeds after the fee appear on the payout statement, read with `commercebook_seller_statement`.

## 1. What CommerceBook does for a seller today
CommerceBook is a network of verified warehouses and the sellers who sell through them. A seller lists products, shipped by the seller or stored at a warehouse on CommerceBook, and buyers find and buy them on the site, from the product pages and through the product feeds. Every action a seller can take on the site is also available through the API and MCP with the seller's key, except accepting the policies, which the owner does in person. In the API a product listing is a lot: lot_id, lot_code, the /lots paths and the seller lot tools name it. The site runs on three hosts: commercebook.ai is the shop and the only host for the API, MCP and agent links, warehouse.commercebook.ai is the warehouse workspace and seller.commercebook.ai the seller portal.

The network now: 4 verified members, 62 products on the market from 1 seller.

- Catalog. A seller's products carry the count on hand, the condition, the photos and the date the count was last confirmed (the count date).
- Orders. An order is created, authorised (placed, the card on hold), released (released to ship), accepted (the buyer accepted the goods), then completed, or it is cancelled or fails. Buyers write to the seller in the Shop's messages; a seller's key does not reach the message endpoints today, so the seller answers from Orders or the product page on the seller portal.
- Payouts. The payout statement shows the proceeds after the fee, by order.
- Shipping. Shipping profiles set the regions served, the rates or a calculated rate, and the handling days.
- Policies and standing. The owner accepts the seller policies in person, and the standing counts strikes under the accuracy rule in section 3.


## 2. How each thing is done, tool by tool
MCP: connect to https://commercebook.ai/mcp (Streamable HTTP) with the header Authorization: Bearer <key>; the server lists the tools a seller key can call. API: https://commercebook.ai/api/v1 with Authorization: Bearer <key>; GET /api/v1 with the key lists the endpoints it reaches; OpenAPI at /api/v1/openapi.json. Each tool is one endpoint.
- Catalog and products: `commercebook_seller_lots`, `commercebook_seller_lot_get`, `commercebook_seller_catalog_upsert`, `commercebook_seller_lot_update`, `commercebook_seller_lot_hold`, `commercebook_seller_lot_release`, `commercebook_seller_reconcile`, `commercebook_seller_verify`. `commercebook_seller_catalog_upsert` writes products and their offers in one call, with the price, the minimum quantity and shipping_methods (how the goods reach the buyer: pickup, ship, parcel, ltl; channels is the older name of the field and is still read). feed_opt_out true on a record keeps the product out of the outside feeds, as the checkbox "Do not list this lot in outside feeds" on the product page does. Price by quantity is live: a record's offer carries price_mode schedule, schedule_kind and price_schedule, a list of tiers {min_qty, unit_price_cents} in ascending order whose first tier starts at 1 (or at the minimum) and carries the unit price. With volume, every unit is priced at the highest tier the quantity reaches. With graduated, the units within each tier are priced at that tier's price. A bad schedule is refused with 400 invalid_input and the reason. Buyers see the tiers on the product page, the result sheet, the search answer and the products feed, and a quote at a quantity returns the price of that quantity. `commercebook_seller_lot_update` changes one product's title, description, condition, quantity, price, price tiers, minimum or photos, and publishes a draft once the seller can sell. `commercebook_seller_lot_hold` pauses sales of a product and `commercebook_seller_lot_release` resumes them. `commercebook_seller_verify` confirms the count of every product after a physical count.
- Feeds and import: `commercebook_seller_catalog_import`, `commercebook_seller_feeds_list`, `commercebook_seller_feed_add`, `commercebook_seller_feed_fetch`, `commercebook_seller_feed_remove`. A saved feed URL is fetched on its schedule: none (only when fetched by hand), hourly or daily.
- Shopify: a seller that installs the CommerceBook channel in Shopify has its catalog on the book within the hour, and each CommerceBook order on those products becomes a Shopify order it fulfils as usual. `commercebook_seller_shopify_status` reads the channel (with a store address it answers the install link for the owner) and `commercebook_seller_shopify_sync` syncs the catalog now.
- Shipping profiles: `commercebook_shipping_profiles`, `commercebook_shipping_profile_create`, `commercebook_shipping_profile_update`, `commercebook_shipping_profile_delete`, `commercebook_shipping_profile_set_default`, `commercebook_shipping_assign`, `commercebook_shipping_rate_card`, `commercebook_shipping_quote`
- Orders: `commercebook_seller_orders`, `commercebook_seller_order_get`, `commercebook_seller_order_release`, `commercebook_seller_order_ship`, `commercebook_seller_order_cancel`, `commercebook_shipping_order_actual`
- Labels and tracking: `commercebook_seller_order_ship` with buy_label true buys the label for the quoted service at the live price, paid from the balance, and writes the carrier and the tracking number; with a key, a label is a spend under the key's limits, so one above the confirm amount or past the 30-day cap waits for the owner. `commercebook_shipping_label` gives the label PDFs of an order as links that last 10 minutes (the PDFs are kept private). `commercebook_shipping_label_void` voids the label before the first carrier scan and refunds it; `commercebook_shipping_tracking` reads the carrier scans and the delivered scan; `commercebook_shipping_return_label` buys the label of a return by mail. A calculated shipping rule is priced from the seller's own rate card first, then from live carrier rates.
- Disputes: `commercebook_seller_disputes`, `commercebook_seller_dispute_reply`
- Requests (intents in the API): `commercebook_seller_intents` reads the open public requests in the categories of the seller's live products, with the buyer's notes and the seller's own quote, and the seller's quotes; `commercebook_seller_quote` quotes one with a live product (lot_id, unit_price_cents, qty, shipping_cents, note): at most the buyer's ceiling, at least the seller's floor when offer_floor_pct is set, 72 hours or until the request expires, one open quote per request; `commercebook_seller_quote_withdraw` withdraws it. A new public request in the seller's categories arrives by email. Reading needs catalog read and quoting catalog write.
- The dealer's path, until private offers ship: a seller that quotes and does not publish a price lists the product with price_on_request true on the record (or the checkbox Price on request on the product page). The product page shows "Quote on request" and no price, the outside feeds leave it out, and a buyer posts a request that the seller quotes with `commercebook_seller_quote`. A seller can also watch a category with no live product in it: `commercebook_seller_category_watch_set` (PUT /api/v1/seller/category-watch, {"categories": [...]}) and `commercebook_seller_category_watch` read and set the list, and every new public request in a watched category arrives by email. For medical and surgical supplies a record carries gtin or udi, ndc, sterile, lot_number, expiration_date, item_package_quantity (the pack) and units_per_case (the case).
- Payouts and performance: `commercebook_seller_statement`, `commercebook_seller_performance`, `commercebook_seller_events`. Buyers see the seller's record at https://commercebook.ai/sellers/<your slug> (and `commercebook_market_seller`): the tier, the last 90 days and all time, the ratings and the terms they accept. CommerceBook computes it from orders; nothing in the seller API writes it.
- Business details and policies: `commercebook_seller_me`, `commercebook_seller_entity_get`, `commercebook_seller_entity_update`, `commercebook_seller_fulfillment`, `commercebook_seller_policies_get`, `commercebook_seller_policies_update`. `commercebook_seller_policies_accept` always answers 403 owner_accepts_policies: an agent never accepts the policies for the owner.
- Warehouse agreements (delegations in the API): `commercebook_seller_delegations`, `commercebook_seller_delegation_warehouses`, `commercebook_seller_delegation_request`, `commercebook_seller_delegation_end`
- Standing and account: `commercebook_my_standing`, `commercebook_whoami`, `commercebook_me`, `instructions`, `commercebook_openapi`, `commercebook_key_limits_get`, `commercebook_key_limits_set`, `commercebook_pending_list`, `commercebook_pending_decide`, `commercebook_key_permissions`, `commercebook_agent_limits`, `commercebook_network_now`, `commercebook_feedback`

Product feeds, public and without a key, updated every 15 minutes: https://commercebook.ai/feeds/google-merchant.xml (Google Merchant Center RSS), https://commercebook.ai/feeds/google-merchant.tsv (the same rows, tab-separated) and https://commercebook.ai/feeds/commercebook/products (Agentic Commerce Protocol products JSON). A seller can keep a product out of outside feeds. Every public product also has its own product page at https://commercebook.ai/lot/<product-slug>-<lot8>.

Accounts: an agent can open an account; the owner confirms by email code; selling and buying with money still need the owner's Stripe steps. `signup_start` sends the owner one email with an 8-digit code and no link, and `signup_confirm` with that code answers the key once.

## 3. The rules that apply
### Your rules
Your owner sets the rules you work within on Your agent, and CommerceBook enforces them on every call you make. Read them first, with `commercebook_agent_rules` (GET /api/v1/me/agent-rules), and plan within them. The answer holds each rule that binds your key, and its text field holds the same rules as one paragraph. The rules cover what you spend in 30 days, the payment amount that waits for the owner and the most for one order. They also name the product categories, the members you deal with, the hours you act and the actions you take.

A call outside a rule answers 403 rule_blocked and names the rule. Nothing runs, and the owner can hear of it. A payment over a money rule answers 202 pending_owner_confirmation and waits for the owner, as before. You can make your own key stricter with `commercebook_key_limits_set`. Only the owner, signed in, can raise a rule: PUT /me/agent-rules with a key answers 403. `commercebook_agent_activity` (GET /api/v1/me/agent-activity) shows what you did, with the rule behind each result.

A key is issued by the owner at Agent access. It reads what the owner can read on the site and acts only in the activities the owner turned on, within these limits. A new link starts with these limits. Spending cap $500 per 30 days; payments above $250 wait for the owner; no other action waits for the owner. Calls are limited to 600 per hour. Every write takes an operation id, the X-Request-Id header: a repeated operation id returns the first result, and a call that timed out is safe to repeat with the same id. A call over a limit is not executed: it answers 202 pending_owner_confirmation with a pending id, the owner approves or declines it at Agent access, Waiting for you, and an approved action runs once with the arguments it was sent with. A key can lower its own limits and decline its own waiting actions; raising a limit and approving need the owner signed in. Every call made with it is recorded on the owner's ledger, where the owner can also revoke it. Not reversible: a released order, an accepted warehouse agreement, a sent message. Three things require the owner in person: Stripe identity and bank onboarding, accepting the policies, and signing in.

What this key may do:
- Catalog: read only
- Orders: read only
- Policies: read only
- Payouts: read only
- Performance: read only
- Delegations: read only
- Business details: read only
- Payments: off

The owner turns an activity on at Agent access in the seller portal. Until then a call that acts answers 403 not_permitted with the activity named. After the owner turns an activity on, the next call succeeds without a new key.

CommerceBook takes 8 percent of each sale, capped at $500 per order, and nothing to list. Listings are written by the seller, in its own words, and are expected to be true: the count, the condition and the date the count was confirmed. A count older than 72 hours is stale, and a product with a stale count is not quoted until the count is confirmed again. The accuracy rule applies to every member: a confirmed report that something a member posted was false counts as a strike; three strikes in 90 days suspend posting for 30 days, and five in a year remove the member pending review. Buyers have 30 days from delivery to file a dispute. After that the order is non-refundable. A dispute is for non-delivery, a shortage, the condition or another reason, and the seller replies with its note and evidence. The seller is paid 2 business days after delivery unless a dispute is open. A shipped order over $500 needs the count and a photo at release. Return terms come in three layers: the product's own, the category line, the seller default. Payments move only on the platform through Stripe. Do-not-solicit marks are honored. Full policies: https://commercebook.ai/policies, every rule of CommerceBook in plain words, also plain text at https://commercebook.ai/docs/policies/index.md.

Calls: Without a key, each address gets 60 calls a minute and 1,200 an hour (the book, network now, the open requests, one product page and the feeds do not count); with a key, each key gets 600 calls an hour. Over the limit the answer is 429 rate_limited with retry_after_seconds and the window (minute or hour).

## 4. What is coming
Each line below is a feature that is planned or being built, with the date the line was last confirmed. None of them can be called today, and no tool for them is in the tool list.
- Promoted listings. A seller pays a percent of the sale, and only on a sale, for a product shown higher on the market and in the feeds. Serves sellers; planned as of October 23, 2026; not available yet.
- Bring-your-own-traffic pricing. A sale that comes from the seller's own link or audience carries a lower fee than a sale the market found. Serves sellers; planned as of October 23, 2026; not available yet.
- Pooled marketing line. The payout statement shows one line for the marketing the network pays for together, and each seller's share of it. Serves sellers; planned as of October 23, 2026; not available yet.
- Affiliate feeds. A seller's products go to outside sites and agents that earn a share of each sale they send. Serves sellers; planned as of October 23, 2026; not available yet.
- Private offers. A seller makes an offer to one buyer, at a price and quantity only that buyer sees. Serves sellers and buyers; planned as of October 23, 2026; not available yet.
- Group buys on the market. Several buyers join one order to reach a quantity price; group buys exist today for supply costs only. Serves sellers and buyers; planned as of October 23, 2026; not available yet.
- Auctions with a reserve. A seller lists a product for bids with a lowest price it accepts, and buyers' agents bid until the close. Serves sellers and buyers; planned as of October 23, 2026; not available yet.
- Ratings on four scores. A buyer rates an order on four scores; today an order is rated on the goods and the seller, in the Shop or through the API. Serves sellers and buyers; planned as of October 23, 2026; not available yet.
- Orders in the warehouse queue. An order for goods stored at a warehouse on CommerceBook goes into that warehouse's work queue, and its status comes back to the seller. Serves warehouses and sellers; planned as of October 23, 2026; not available yet.
- Skills on GitHub. The CommerceBook agent skills are published on GitHub, so an agent host can install them by name. Serves warehouses, sellers and buyers; planned as of October 23, 2026; not available yet.
- Purchase order numbers. A buyer's agent puts the owner's purchase order number on an order, and it shows on the order, the invoice and the seller's order. Serves buyers and sellers; planned as of October 26, 2026; not available yet.

## 5. How to tell us what helps
The feedback tool records what an agent found and what it missed: the MCP tool `commercebook_feedback` and POST https://commercebook.ai/api/v1/feedback, with a key or without one. It takes about (a tool name or a page), what_happened, what_would_help and, optionally, a rating from 1 to 5. Without a key it records up to 20 notes per address per day; with a key the note is recorded against that key and its member, and the call is on the owner's ledger. A person can also be reached by email at support@commercebook.ai. A person at CommerceBook reads every note, and the What is coming list above is shaped by what the notes say.