maxsuite Diagrams

Catalogue

Catalogue

Catalogue holds product records, whatever produced them: a scrape, an import, a supplier feed or a person. Each product keeps its title, brand, SKU, price, stock, variants and images, and the catalogue can be exported as a feed for a WooCommerce or Shopify importer (module catalog).

In the sidebar under Commerce → Catalogue.

The catalogue is separate from Scraper on purpose. It outlives the crawler that filled it, and it works on its own without one.

What you see

  • A list of products, ten at a time, with more loading as you scroll. Each row shows a small image, the title and brand, the SKU, the price in its own currency, the number of variants, the stock state and the platform the product came from.
  • Stock reads In stock, Out of stock, Pre-order, Backorder or Discontinued. When the source page never said, it reads "unknown", which is not the same as out of stock.
  • At the top, a count of the products loaded so far and their split by platform.
  • A search box for title, SKU or brand.
  • Open on each row goes to the product's own page on the store.

With nothing collected yet, the page says to add a source in Scraper and run it, or to send products to the catalogue's import endpoint.

What you can do

Fill the catalogue

  1. Open Commerce → Scraper, add a store and run it. When the run finishes, its products appear here.
  2. Or send products through the API (POST /catalog/ingest), up to 200 per call, for imports that do not come from a scrape.
  3. A product is known by its address. Sending a product whose address is already held updates it in place instead of adding a copy.

Find a product

  1. Type part of a title, SKU or brand in the search box.
  2. Choose Open to see the product on its store.

Export a feed

  1. Call GET /catalog/export/woocommerce or GET /catalog/export/shopify with an account that holds catalog:export.
  2. The WooCommerce feed writes a parent row for each product and one row per variant, so sizes and colours arrive as buyable variations. The Shopify feed uses Shopify's handle-keyed shape.

Exports have no button on the page. They are reached through the API.

Remove a product

Removing a product deletes it with its variants and images, and cannot be undone. It is done through the API or by an agent with catalog.remove.

How products drop out

When a scrape saw a whole store, products from that store it no longer found are marked gone. They are hidden from the list and the counts, but not deleted, so their history survives. A run that was capped, hit errors or rejected anything marks nothing gone, so a partial crawl cannot empty the catalogue.

Who can do what

PermissionLabelLets you
catalog:readView catalogue productsOpen Catalogue, search products and see one in full. Agents need it for catalog.search, catalog.get and catalog.stats.
catalog:writeAdd, edit and remove catalogue productsImport products and remove them. Agents need it for catalog.ingest and catalog.remove.
catalog:exportExport the catalogue as a feedDownload the WooCommerce or Shopify feed. It is separate because a file of every product and price is a bigger act than looking one up.

Roles and how permissions are granted are explained in People, roles and permissions.

What runs on its own

Nothing in this module runs on a schedule. Products arrive when a scrape finishes, which Scraper schedules, or when someone imports them.

When a stored product's price, stock or content changes, the module announces it (catalog.product.changed), naming the product and which fields moved.

For agents

An agent can search and read the catalogue, add or update products, and remove them.

Read:

  • catalog.search: find products by title, SKU or brand, with prices and stock but not full descriptions.
  • catalog.get: one product in full, with its variants and images.
  • catalog.stats: how many products are held and how they split by platform.

Change:

  • catalog.ingest: add products or update them by address, at most 200 per call. It answers how many were created, changed, unchanged and rejected, and why.
  • catalog.remove: delete a product with its variants and images. This is a destructive act and cannot be undone.

Whether an agent's change goes ahead or waits for a person follows its approval policy (Agents and approvals).

Over MCP the same tools are named catalog__search and so on (API keys and MCP access).