Every tool your AI can use in Vendor.

The first thing to call for "how did the store do".

Use it for "better or worse than last month".

Use it to pick products for a homepage block, or to answer "what sells".

Use it to triage: unpaid, stuck, or a date window.

The payload carries available_actions — every admin action with whether it is available, a reason when locked, and exactly one flagged primary (the recommended next step). Read that instead of reasoning about the lifecycle yourself.

Filters are POSITIVE only — there is no "missing brand" or "no image" filter, so to find gaps you must page through and inspect.

The API has no "missing X" filter, so this pages through and inspects — keep the sample modest on a large catalogue.

One variation is still required for a simple product — that is where the SKU, the price and the stock live. Set import.create_missing_brand or create_missing_attribute_options to let the backend fill gaps rather than failing.

Needs its own SKU, price and stock.

Shows a before/after diff before writing.

Each list replaces the previous one, so send the full set you want.

Build the structure before importing products, or every product lands uncategorised and has to be fixed afterwards.

Products reference it by id, so create brands before importing a catalogue that mentions them.

Attributes do double duty: they are the axes variations differ on and the filters shoppers use, so is_filterable is worth a thought.

Manual include and exclude lists override the rules.

Needed after bulk catalog changes or a new locale, otherwise search keeps serving the old data.

Use this instead of calling fix_product / set_seo row by row: the plan covers every row and the owner approves once. For the SAME value on many rows chosen by a filter, bulk_fix_products is cheaper. A job larger than 40 rows is several calls of this tool.

Use it when loading a catalogue: the plan lists every product and the owner approves once. Brands, categories and attributes must exist first (or pass create_missing_brand / create_missing_attribute_options per product).

Call this before bulk_fix_products: the filter keys are not guessable, and the negative ones (without_brand, without_category, without_media, without_description) are what turn an audit finding into one operation.

The backend dry-runs this for real, so the plan is an exact count rather than an estimate.

Pass status=low to answer "what is running out".

Filter tag=front-page to find the homepage (it is also the row with is_default=true).

template: "designed" plus a pageBuilder object with a content array means a Puck (v2) page; a bare array is a legacy v1 document and must not be edited in place.

Read this BEFORE authoring or editing any page document — the props are not guessable and a wrong key is silently dropped. Pass type to get one block in full: every field with its kind, its allowed option values, the fields of its list items, and its defaults.

Fetch one to see its full document before proposing it.

Destructive: it overwrites the current homepage document.

Replace a page’s builder document. Use for "rebuild my homepage" once you know what you want: author the content array from describe_page_blocks. Fetch the current document first with get_page_document so you do not discard sections by accident.

For a contact page, create the form first with create_contact_form and put its id in a Contact Form block.

Pass fields to override the default set.

Each is markdown carrying {{tokens}} that the storefront fills from store settings at render time.

The {{tokens}} in them resolve from your company and policy settings, so fill those first with configure_company_identity and configure_policies — otherwise the pages publish with holes in them.

Read this BEFORE writing a block template — anything not listed here will not render.

Writes nothing. Run it before save_block_version and fix every error.

The store’s custom page-builder blocks with their version summaries (draft / published / retired).

Pass version_id to also get that version’s template, snippets and schema — read it before proposing a change to it.

The key is permanent. Follow with save_block_version.

Save a block’s code as a DRAFT version: creates a new draft when given version, or updates an existing draft when given version_id. The source is checked locally first and refused if it has errors. A draft is not visible anywhere until published.

It becomes immutable and appears in the editor palette. It still shows nowhere on the storefront until it is placed on a page with write_page_document.

The store’s shared stylesheet for custom blocks: brand type, colour variables and utility classes that every custom block can use. Read it before writing a block so you reuse what is there instead of repeating it.

Replace the store’s shared stylesheet for custom blocks. Put here what several blocks share (CSS variables for brand colours, type classes, buttons) so each block’s own stylesheet stays small. It applies to every custom block on the store, and to nothing else.

The block must be published and created with "card" in enabled_on. Its template reads the product as product (see list_block_primitives → product_card).

The store’s custom header or footer, if it has one: its status and page-builder document. "built-in" means the store uses the storefront’s own header or footer.

Replace the store’s header or footer with a page-builder document, on EVERY page. It may contain ONLY custom blocks created with that region in enabled_on, at the top level: no Row and no built-in blocks. A store has ONE saved header and ONE saved footer (no separate draft beside a live one): when the current one is live, writing it changes what visitors see now unless publish is false, and publish: false takes the live one down (visitors see the built-in one) until it is published again. Read the current one with get_site_region first.

Export the store’s custom blocks as one portable JSON bundle: the latest published version of each block, plus (optionally) the shared block stylesheet and the custom header and footer. The bundle carries no ids, so import_blocks can load it into any store. Writes nothing.

A version the store already has is never overwritten; when the code differs, the incoming block gets the next free version. Every block is checked with the storefront’s Liquid engine first, and nothing is written if any of them fails.

The store’s whole shipping setup in one call: zones (where it delivers), delivery methods, and rates (what each costs and when), with the problems that stop shoppers from getting a price — a zone with no rate, a rate that can never be reached. Read this before any shipping change.

Set up shipping in one step, for a store that has none or is adding countries: a zone per country, a "Standard delivery" method, a flat price per order, and optionally free delivery above a cart total. Safe to run again — what already exists is kept. Use the single-piece tools afterwards for anything more specific.

A zone offers nothing until it has a rate: follow with create_shipping_rate.

A method is only offered where it has a rate that fits the cart.

The list REPLACES the zone’s current one. A zone with no methods chosen falls back to the store’s default methods.

Leave zone_id out for a rate that applies everywhere. Order matters: rates on the same method and zone are tried lowest priority number first and the first that fits wins, so "free above 3000" needs a LOWER number than the flat rate it sits beside.

Nothing is deleted through the assistant — switching off is how a zone, method or rate is retired.

Images and files already in the store’s media library, newest first: id, address, size and alt text. Use it to find the id of a photo or logo before placing it on a product, a page or a setting.

Bring up to 10 images or PDFs into the store’s media library from public web addresses — product photos, a logo, a banner. Each is fetched and stored by the store, which returns its id and its new address. Use the id on products (thumbnail_media_id, media_gallery) and the new address in settings and page blocks; never keep pointing at the original address. Only upload what the owner has the right to use.

For up to 10 files this returns a one-time upload address and the exact command that sends each file there. Run the commands if you have a shell; otherwise give them to the owner to run. Then call finish_file_upload with the tickets. The addresses stop working after 15 minutes. Without a shell and without an owner willing to run a command, the file has to be uploaded in the dashboard.

Call it once the upload commands have run. A ticket whose file did not arrive is reported, and the others still register.

The key is immutable once created: it is baked into entry URLs, cache keys and SDK filters.

The storefront ANDs across axes and ORs within one.

A term keeps one identity across locales and translates its fields, so do not create one per language.

Entries are per-locale rows, so a translation is a separate entry joined by translation_group_id.

Start every translation job here — it is the difference between translating what is missing and re-translating everything.

You do the translating — this only persists it. Keep brand names, SKUs, sizes and units untranslated.

The whole object is replaced, so include every key you want kept.

Call this first in a session: it says which capabilities the plan unlocks, so you never offer something the store cannot do.

Use it to answer "is my store ready to launch" and "what is still missing".

The store’s whole configuration in one call: every reserved setting with its label, current value, type and allowed options, grouped by area. Read this before configuring anything — it is the difference between setting a value and guessing a key.

Read it before writing any setting — a typo in a key silently creates a setting nothing reads.

Nothing else in the store behaves correctly until these are set.

These fill the store-identity readiness step and are substituted into the legal policy templates, so getting them right once fixes the footer, invoices and policy pages together.

These are the values the legal policy templates interpolate, so a shop with blank fields publishes policy pages with holes in them.

Call get_store_config first — store_operational_flow_preset is an enum and its options are the only legal values.

Catalog mode turns a shop into a brochure — say so plainly before switching it on.

Enum values come from get_store_config — invented ones are refused rather than silently stored.

This is the single biggest lever on how a catalogue feels to shop.

Check get_settings_schema first: an unrecognised key is stored but read by nothing, which looks like a setting that does not work.

Stock lives per location, so a store needs at least one before inventory means anything — this is the default_location readiness gate.

Products resolve their rate through the class, so the class matters more than the number — this is the tax readiness gate.

Credentials go in secrets and are stored encrypted — they are never echoed back, and this tool never prints them. Without at least one method a store can reach checkout and go no further.

The store’s navigation menus. Pass a location for one menu with its items; omit it to list them all.

Create a menu, or replace an existing one’s items wholesale. Items link to real entities by reference_type + reference_id rather than hardcoded URLs, so they survive a slug change. Replacing is destructive — the previous item tree is gone.

Fast way to a sane primary nav on a fresh store — and destructive, since it replaces whatever is in that menu.

The store’s custom domains and their current status.

Nothing works until those records exist at the registrar, so hand them over and expect to wait.

Re-poll Cloudflare for a domain’s hostname and SSL status. Use it after the DNS records have been published; it is a read, so call it as often as needed.

Until this verifies, order confirmations go out from the platform default rather than the store’s own domain.

A read, safe to repeat.

The contract for migrating a store from the old Vendor platform (v1): the order of work, every import step and its options, the field-by-field mapping, the settings mapping, the known faults and how to check for each, and the verification that ends a migration. Read the overview before the first import; read a section again before you act on it.

Read from the old (v1) store: how many taxes, brands, categories, attributes, products, coupons, customers and orders it holds, or one page of a v1 resource (its settings, shipping methods, a sample of products). Read-only on both sides. The counts are what a finished migration is checked against.

What is new or changed in the old (v1) store since it was last imported, for one kind of record: which v1 rows are not here yet, which were edited in v1 after their import, which failed to import, and which source pages they sit on — so the next import can be limited to exactly those pages. Read-only on both sides. This is the first step of every re-sync; read get_v1_migration_contract section delta_sync for what to do with the answer.

After an import: the old store’s counts next to the new store’s, entity by entity, with the failed rows of the latest v1 run. This is the check that ends a migration — do not call it done on the run status alone.

Steps run in a fixed order: taxes, brands, categories, attributes, products, price_sync, stock_sync, coupons, customers, orders, pages, menus, seed_defaults. Long-running; it writes into the live catalogue, pages and menus. Read get_v1_migration_contract first — it says which steps to run together and what to check after each.

Long-running and hard to undo — it writes into the live catalog.

Poll this after queueing an import instead of assuming it finished.

Use it to see whether something is still running before starting another, and to find the run a migration should be resumed from.

Filter by status "failed" after a migration — each failed row carries the source record and an _error.

After a migration, customers exist in the store but cannot sign in; this creates their accounts silently — no email is sent — and each customer sets a password the first time they try to log in. Safe to repeat: run it after every customer import or re-sync, and only the customers still without a login are touched.