Skip to content

Tools

All 84 tools the MCP server exposes — store and theme tools, their arguments, guardrails, and which ability each one needs

Updated View as Markdown

The MCP server registers 84 tools: 47 for the store (20 that read, 27 that write) and 37 for themes (18 that read, 19 that write). The subscription tools are listed only for stores using Reload, the tax code tools only while Avalara or TaxJar is active, and the distributor catalog tools (search-distributor-catalog, import-distributor-products) only while the store has a distributor switched on. The cards below list the store tools first, then the theme tools. Every name on this page is the wire name — the exact string an agent puts in a tools/call, not a display label. Call them verbatim.

The whole set fits in a single tools/list page, so there is no cursor to follow.

What a connection sees

Every tool checks the connection’s abilities when the tool list is built, and a tool the connection may not use is absent rather than present-and-failing. A connection holding only themes:read sees the 18 theme read tools plus get-store-overview; themes:write adds the 19 theme write tools; each store ability adds its own tools. That is deliberate: an agent that cannot see a tool will not plan around it and then hit a wall halfway through.

screenshot-theme counts as a read tool: it renders and uploads a preview image but changes nothing in the store, so a view-only connection can call it. Screenshotting is how an agent checks its own work, so a view-only session can still run the full inspect-diff-report loop without ever being able to change a file.

See Permissions for which ability shows which tools.

Store tool conventions

  • IDs are the numbers shown in the dashboard: product, variant, order number, customer, subscription.
  • Money is a dollar string in results ("449.99") and a number in arguments. Dates use the store’s timezone; date-only inputs are whole days, inclusive.
  • Search results page with a cursor: pass a page’s next_cursor as cursor to get the next one.
  • Writes change one record per call, take the value the agent last read as expected_*, and accept dry_run to preview. A stale expected_* is refused as a conflict and nothing is saved. The bulk tools (set-product-tax-code, set-product-markup, import-distributor-products) change many records in one call instead: a dry_run reports how many, and applying needs that number as expected_count.
  • Images go through the media library. upload-media adds one (from a public https URL, a ChatGPT attachment, or a create-upload-link upload) and returns a media_id; list-media finds the ones already there. See Images and uploads.
  • Product content has a version. search-products with a product_id returns the description HTML, specifications and SEO fields with a content_version; update-product-content takes it back as expected_version, so an edit made after the agent read the product is never overwritten.

Theme tool conventions

  • theme accepts either identifier. The numeric row id or the theme_id UUID both resolve. Get them from list-themes.
  • Everything is scoped to the token’s store, before anything else runs. A theme belonging to another store is reported as not found, and there is no argument that widens the scope.
  • Paths are directory-scoped, with extensions: sections/hero.liquid, templates/index.json, assets/base.css, snippets/header-drawer.liquid.
  • Errors come back as MCP error results, not exceptions. They are written to be actionable — most name the tool you should have called first.

The two refusals on file writes

The file-write tools refuse two categories of change unless you opt in explicitly. Neither refusal is a permission problem, and retrying the same call with the flag set is the intended resolution — once you have established that it is the right call to make.

allow_active — writes to the active theme are blocked. All four file-write tools (update-theme-file, create-theme-file, delete-theme-file, restore-file-version) carry this flag. The active theme is the live storefront, so the safe pattern is duplicate-theme and work on the copy. Pass allow_active: true only when the user has explicitly asked to edit the live theme. set-collection-filters carries the same flag for the same reason: it writes a theme setting, and on the active theme a filter change is live on the next page load.

allow_chrome — writes to global page chrome are blocked. That means sections/header-group.liquid, sections/footer-group.liquid, and any section those groups render. Only the three tools that can change an existing file — update-theme-file, delete-theme-file and restore-file-version — take this flag; create-theme-file has no allow_chrome argument, because creating a file that does not yet exist cannot overwrite chrome that does. Chrome appears on every page, so the flag exists to separate two jobs the tool cannot tell apart:

  • Recreating a whole theme or homepage from a mockup: the mockup’s header and footer are the site’s header and footer. Retry with allow_chrome: true — shipping a custom body under stock chrome is a half-finished theme.
  • Building one secondary page: the chrome is not yours to change. If that page’s mockup shows different chrome, ask the user. Secondary-page mockups usually just abbreviate it, and matching them would strip the difference from the entire storefront.

The refusal text states both branches, because the correct answer depends on intent rather than on the file.

Saves are validated, versioned, and critiqued

Every write through the save pipeline does three things:

  1. Validates. Liquid, JSON and {% schema %} are parsed. A failure returns the parser error and nothing is written — fix and retry.
  2. Versions. The previous content is snapshotted first, so list-file-versions plus restore-file-version is always available as an undo.
  3. Warns. A save can succeed and return advisory warnings. These are the silent-failure detectors: a <header> in a body section that is not wired into header-group, a <nav> with no link_list setting, several page regions crammed into one section file, hand-drawn SVG artwork standing in for a photo, a hardcoded font-family, a hand-rolled page container that overrides the merchant’s Page width, an overlay written as an empty <div>, a custom header that cannot produce a hamburger or whose search icon reaches nothing, and a template using a plugin section whose plugin is not active.

Warnings do not block the write. Read them anyway — every one of them describes something that will look fine in a screenshot and be broken in production.

One warning is not a criticism but a report: if you send null for a setting the merchant has already chosen in the visual editor, the save keeps their value and tells you which ones it kept. read-theme-file returns the file, where an image_picker reads "image": null; the merchant’s actual choice lives in the theme’s settings and you cannot see it. A null you write back means “not specified”, never “clear it” — and sending "" to force it through deletes a photo you were never shown.

The tools

Store overview

get-store-overviewany connection
The connected store at a glance: its name, storefront URL, timezone, today's date there, what this connection may do, catalog counts, active plugins and collections. Call it first to learn which store you are working on.
Takes no arguments.

Search the FirearmCart docs

search-docsany connection
Search these docs for how FirearmCart works — store setup, products and collections, orders, FFL rules, shipping and taxes, payments, themes, integrations, billing and the API — and get the best-matching sections, each with a link to its heading. For how-to questions about the platform rather than the store's data.

Arguments

querystringrequired
What to look up, in plain words, e.g. "set up FFL transfers".
areastringoptional
guides = merchant how-tos, api = the developer API and MCP server, changelog = what's new. Default: all. One of: guides, api, changelog.
limitintegeroptional
Sections to return, 1-10. Defaults to 5.
Example argumentsjson
{ "query": "shipping rates for ammunition" }
Caveats
  • Each result has the page title, the section heading, a link straight to that heading, and an excerpt of about 1,500 characters.
  • Searches the docs that ship with the server, so answers match the version that is running.

Search products

search-productsproducts:read
Find products by name, SKU, barcode, manufacturer or brand, and filter by status, stock, collection, product type, sale, provider (the store's own stock or a distributor), missing shipping weight or missing tax code. Pass product_id for one product in full: variants, stock source, shipping weight, tax code, cost basis, MAP, FFL and shipping class, plus its description HTML, specifications and SEO fields with the content_version that update-product-content needs, and its images (image_id, position, alt text, the variants that show each) with the images_version that update-product-images needs.

Arguments

product_idstringoptional
A product ID as shown in the dashboard. Returns that product in full; other filters are ignored.
querystringoptional
Text to find in the name, SKU, barcode, manufacturer or brand.
statusstringoptional
active = published on the storefront, draft = hidden. One of: active, draft, any. Defaults to any.
stockstringoptional
in = 1 or more on hand, out = none, low = at or under low_stock_threshold. One of: in, out, low.
low_stock_thresholdintegeroptional
Units counted as low stock. Defaults to 5.
collectionstringoptional
Collection name.
product_typestringoptional
Product type, e.g. handguns, rifles, ammunition.
providerstringoptional
Who supplies the products, as the Products list's Provider filter: internal = the store's own stock (including products it also gets from a distributor), a distributor's slug such as rsr or lipseys, or lightspeed, fastbound or orchid-ebound.
on_salebooleanoptional
true = has a compare-at price above its price.
missing_weightbooleanoptional
true = would ship with no weight, which checkout can't rate; false = has a weight or doesn't ship.
missing_tax_codebooleanoptional
true = has no tax code, so a tax plugin taxes it as general merchandise; false = has one.
limitintegeroptional
Results per page, 1-50. Defaults to 20.
cursorstringoptional
next_cursor from the previous page.
Example argumentsjson
{ "query": "glock 19", "stock": "low" }
Caveats
  • A product counts as missing a weight when it, or any variant, would ship with none: a variant uses the product's weight unless it ships on its own (ships_on_product_weight false), and falls back to the product's when its own is blank. Products that don't ship (not physical, or event tickets) never count.
  • Each result carries its weight ({ value, unit } or null). One product's shipping block adds ships and missing_weight. Combine missing_weight with provider to work through one supplier's products.
  • Each result carries its tax_code, or null. The code matters only while a tax plugin (Avalara or TaxJar) is active: set it with set-product-tax-code.
  • Each result carries its manufacturer and brand, each null when the product has none. They come from its Manufacturer and Brand specs, so update-product-content changes them through those specs.
  • One product's sources list each supplier with the stock it can sell. The one marked selected is the supplier the product sells from under the store's supplier selection: it fills the product's orders, and the product's stock and cost basis are its.

Search distributor catalogs

search-distributor-catalogproducts:read
Search the catalogs of the distributors the store has switched on (RSR, Lipsey's, Chattanooga, Sports South and the others) for items to import: by name, SKU, UPC, manufacturer or part number, with manufacturer, category, stock and cost filters. Each item has its cost to the store, MAP, MSRP, stock and the store product it already is, if any. Listed only while the store has a distributor switched on.

Arguments

distributorstringoptional
One distributor, by its slug from the distributors block, e.g. rsr, lipseys or sports-south. Default: all of the store's distributors.
querystringoptional
Words to find in the name, SKU, UPC, manufacturer or manufacturer part number. Every word must match.
manufacturerstringoptional
Manufacturer name, or part of it.
categorystringoptional
The distributor's category, or part of it, e.g. handguns or optics.
in_stock_onlybooleanoptional
Only items the distributor has in stock.
not_importedbooleanoptional
Leave out items already in the store.
include_allocatedbooleanoptional
Also list allocated items, which the distributor releases to dealers in limited numbers.
include_non_dropshipbooleanoptional
Also list items the distributor won't drop ship to the store's customers, such as NFA items.
conditionstringoptional
Sports South only: which units to list. One of: new, refurbished, clearance, all. Defaults to new.
min_costnumberoptional
Lowest cost to the store, in dollars.
max_costnumberoptional
Highest cost to the store, in dollars.
markup_percentagenumberoptional
0-99: also give the price each item would sell at with this markup on its cost.
limitintegeroptional
Results per page, 1-50. Defaults to 20.
cursorstringoptional
next_cursor from the previous page.
Example argumentsjson
{ "distributor": "rsr", "query": "glock 19", "in_stock_only": true, "markup_percentage": 20 }
Caveats
  • Each item's cost is what the store pays the distributor: its drop-ship price where it has one, otherwise the dealer price. price_at_markup is that cost plus the markup, never under MAP, or the MAP itself when the store prices at MAP and the MAP is above the cost, which is how import-distributor-products prices a new product.
  • Like each distributor's page in the dashboard, it hides allocated items (RSR, Lipsey's, Chattanooga, 2nd Amendment Wholesale) and items the distributor won't drop ship until include_allocated or include_non_dropship asks for them, and lists Sports South's new units unless condition asks for others. The distributors block says what each one hides, whether its first catalog sync has finished, and links its page.
  • drop_ship is null for Zanders, MGE and Davidson's, whose catalogs don't say which items they drop ship.
  • imported_product_id is the store product an item already is, from an earlier import.

List collections

list-collectionsproducts:read
The store's collections with their IDs, storefront URLs and product counts, how many products are in no collection, and the collection types the store can still add. A product sits in at most one collection; to see a collection's products, use search-products with collection.
Takes no arguments.

Search orders

search-ordersorders:read
Find orders by order number (ours, or a GunBroker or Guns.com number), customer name or email, payment status, fulfillment status and date range, or list the orders that need the merchant. Pass order_number for one order in full: line items (with line_id, who ships each and what it can switch to), totals, shipping, the FFL dealer and whether it can still change, each payment attempt, refund and void with the gateway's own message (and a note on a payment approved while the gateway was in Test Mode), each fulfillment and its tracking, and the order note with its version.

Arguments

order_numberstringoptional
An order number. Returns that order in full; other filters are ignored.
needs_attentionbooleanoptional
Only orders that need the merchant: lines waiting to be sent, errors or holds, an FFL not on file, a failed delivery, or a paid order with lines never sent. Last 90 days, oldest first, test orders left out; each comes with its reasons.
test_ordersstringoptional
Test orders (test card, test customer or Sandbox payment). include by default, except with needs_attention. One of: include, exclude, only.
customerstringoptional
Customer name or email (partial match).
payment_statusstringoptional
pending = checkout not finished, nothing collected; completed = paid with no refund; refunded = fully refunded; declined = the payment failed or was declined (the order shows failed). One of: pending, completed, refunded, partially_refunded, chargeback, declined.
fulfillment_statusstringoptional
"No Shipment" = nothing sent yet; needs_processing = waiting on the store. One of: No Shipment, needs_processing, pending, processing, shipped, in_transit, out_for_delivery, on_hold, delivered, ready_for_pickup, picked_up, returned, cancelled, error.
rangestringoptional
Created in this period, in the store's timezone. One of: today, yesterday, last_7_days, last_30_days, this_month, last_month, this_year, last_year, all_time. Defaults to last_30_days.
start_datestringoptional
YYYY-MM-DD, inclusive. Overrides range.
end_datestringoptional
YYYY-MM-DD, inclusive.
limitintegeroptional
Results per page, 1-50. Defaults to 20.
cursorstringoptional
next_cursor from the previous page.
Example argumentsjson
{ "order_number": "4021" }
Caveats
  • In one order, each line's line_id, supplier (own_stock, outside, a distributor slug, split, or automatic while the store's settings will decide) and supplier_options are what change-order-supplier takes, each fulfillment_id is what fulfill-order takes, and note.version is what update-order-note needs to replace the note.
  • ffl_dealer.can_change says whether change-order-ffl can still change the dealer, with the reason when it can't.

Search customers

search-customerscustomers:read
Find customers by name, email or phone, with their paid order count and total spent (paid orders only, as the dashboard counts them). Pass customer_id for one customer with phone, addresses and recent orders.

Arguments

customer_idstringoptional
A customer ID as shown in the dashboard. Returns that customer in full.
querystringoptional
Name, email or phone (partial match).
limitintegeroptional
Results per page, 1-50. Defaults to 20.
cursorstringoptional
next_cursor from the previous page.
Caveats
  • Customer details are personal data: fetch only what the question needs.

Sales summary

get-sales-summaryanalytics:read
Sales for a period, counted the way the dashboard Sales report counts them (paid orders, with partly refunded ones at their full amount, test orders excluded): orders, gross revenue including tax and shipping, average order value, discounts, units sold, the change against the previous period of the same length, and the top products, collections and discount codes.

Arguments

rangestringoptional
The period, in the store's timezone. One of: today, yesterday, last_7_days, last_30_days, this_month, last_month, this_year, last_year. Defaults to last_30_days.
start_datestringoptional
YYYY-MM-DD, inclusive. Overrides range.
end_datestringoptional
YYYY-MM-DD, inclusive.
Example argumentsjson
{ "range": "this_month" }
Caveats
  • Limited to 30 calls a minute per store.

Traffic summary

get-traffic-summaryanalytics:read
Storefront traffic for a period, counted the way the dashboard Traffic report counts it: visits, unique visitors, pages viewed, average time on site, orders and the conversion rate, the change against the previous period, visits by day, and the top sources, landing pages and locations.

Arguments

rangestringoptional
The period, in the store's timezone. One of: today, yesterday, last_7_days, last_30_days, this_month, last_month, this_year, last_year. Defaults to last_30_days.
start_datestringoptional
YYYY-MM-DD, inclusive. Overrides range.
end_datestringoptional
YYYY-MM-DD, inclusive.
Example argumentsjson
{ "range": "last_7_days" }
Caveats
  • Conversion rate is orders counted as sales (paid, not test orders, as get-sales-summary counts them) divided by visits.
  • Only visits to the store's own domain are counted, and bots are left out. A visit is a session: pages viewed within 30 minutes of each other.
  • Landing pages, locations and referring sites cover the last 30 days; older visits keep their totals and UTM sources only.
  • Shares the report budget with get-sales-summary: 30 reports a minute per store.

List subscriptions

list-subscriptionssubscriptions:read
List the store's Reload subscriptions (repeat orders on a schedule), filtered by status or customer. Pass subscription_id for one subscription with its items and recent history. Only for stores using the Reload plugin.

Arguments

subscription_idstringoptional
A subscription ID as shown in the dashboard. Returns that subscription in full.
statusstringoptional
Only subscriptions in this status. One of: active, paused, past_due, cancelled.
customer_idstringoptional
Only this customer's subscriptions.
limitintegeroptional
Results per page, 1-50. Defaults to 20.
cursorstringoptional
next_cursor from the previous page.

List discount codes

list-discountsdiscounts:read
List the store's discount codes with their value, what they apply to, usage, minimum purchase, dates and status. Filter by status or find one by code.

Arguments

codestringoptional
Find one discount code (case-insensitive).
statusstringoptional
Only codes in this status. One of: Active, Scheduled, Expired, Inactive.
limitintegeroptional
Results, 1-50. Defaults to 20.

Find FFL dealers

search-ffl-dealersffl:read
Find federally licensed firearm dealers a firearm can be shipped to, by business name or license number, or near a ZIP code. Results come from the ATF FFL list FirearmCart keeps; the ZIP search geocodes the ZIP.

Arguments

namestringoptional
Business name or FFL license number.
zipstringoptional
5-digit ZIP code to search around.
radius_milesintegeroptional
Search radius around the ZIP, 5-100. Defaults to 25.
limitintegeroptional
Results, 1-25. Defaults to 10.
Example argumentsjson
{ "zip": "53147", "radius_miles": 15 }

Get store settings and payment gateways

get-store-settingssettings:read
Read the store's settings in one call: business details, branding, social links, the storefront's URL and lock screen, the store's own FFL, its payment gateways and its custom domains. settings_version is what update-store-settings needs.
Takes no arguments.
Resultjson
{
  "settings_version": "4be0c19a7d22",
  "business": { "store_name": "Alpha Arms", "email": "hello@alpha-arms.com", "phone": "262-555-0100", "address": "1825 Main St", "city": "Lake Geneva", "state": "WI", "zip_code": "53147", "country": "US" },
  "branding": { "logo_url": "https://cdn.firearmcart.com/media/10401/alpha-logo.png", "favicon_url": null, "checkout_logo_url": null },
  "social": { "facebook": null, "instagram": "https://instagram.com/alphaarms", "youtube": null, "tiktok": null, "twitter": null, "snapchat": null, "pinterest": null, "tumblr": null, "vimeo": null, "whatsapp": null },
  "storefront": { "url": "https://www.alpha-arms.com", "lock_screen_on": false, "locked_for_billing": false, "customer_accounts": true },
  "store_ffl": { "license_number": "1-54-059-01-8L-00695", "license_type": "01", "business_name": "Alpha Arms LLC", "expires": "2028-12-31", "show_at_checkout": true },
  "payments": [
    { "name": "Main card account", "provider": "Fortis", "kind": "card", "active": true, "mode": "live", "status": "ready", "surcharge_percent": 3 }
  ],
  "domains": [
    { "name": "www.alpha-arms.com", "primary": true, "enabled": true, "status": "connected", "dns_record": { "type": "CNAME", "host": "www.alpha-arms.com", "points_to": "stores.firearmcart.com" } }
  ]
}
Caveats
  • Payment gateways are read-only: provider, whether each is active, test or live, whether it can take payments (ready, awaiting Fortis approval, or needing a new NMI key) and its surcharge. Credentials are never returned.
  • Each domain comes with its status (connected, verifying, ssl_pending, failed or disconnected) and the CNAME record that connects it.

Check payment gateways

check-gatewayssettings:read
Check whether the store can take payments. For each payment gateway: whether it is active, test or live and ready, its payments over the last 30 days, and the result of Test connection, which checks the credentials with Authorize.net, NMI or Fortis without moving money.

Arguments

test_connectionbooleanoptional
Run Test connection on each gateway that has one. connection_test is null for a gateway without one (Sandbox, Sezzle, Credova) or still awaiting Fortis approval. Defaults to true.
Resultjson
{
  "recent_days": 30,
  "gateways": [
    {
      "name": "Main card account", "provider": "NMI", "kind": "card", "active": true, "mode": "live", "status": "ready", "surcharge_percent": null,
      "recent_payments": {
        "approved": 0, "failed": 4, "last_approved_at": null,
        "latest_failures": [
          { "at": "2026-10-29T20:32:45-04:00", "order_number": "1004", "amount": "2.71", "gateway_message": "Invalid processor REFID:306191132" }
        ]
      },
      "connection_test": { "passed": false, "warning": false, "message": "NMI accepted the API security key but has no processor it can use. ..." }
    }
  ],
  "dashboard": "https://app.firearmcart.com/settings/payments"
}
Caveats
  • recent_payments counts approved and failed card payments over the last 30 days, gives the time of the last approval, and lists the five latest failures with the order number and the gateway's own message, such as a decline reason.
  • Test connection is the same check as the gateway's menu on Settings > Payments. It passes an Authorize.net account in Test Mode with warning: true, and fails an NMI account that refuses the gateway's Processor ID. A passing Fortis test doesn't refresh the surcharge settings here; the Payments page does.
  • Credentials are never returned.

Check why a domain is not connecting

check-domainsettings:read
Find out why a custom domain isn't serving the store, from the domain registry, two public DNS resolvers and Cloudflare, read live. Findings come most important first, each with a plain summary and the fix. For a domain the store hasn't connected, it says which way to connect it.

Arguments

domainstringoptional
The domain to check, such as yourstore.com. Omit it to check every domain on the store.
Example argumentsjson
{ "domain": "alpha-arms.com" }
Caveats
  • state is connected, waiting (nothing to change, it just needs time) or action_needed.
  • For FirearmCart-managed DNS the findings say whether the nameservers were never changed, changed to the wrong ones, are still propagating, or are blocked by DNSSEC. For the merchant's own DNS: whether the CNAME is missing, points elsewhere, was saved with the domain twice, or is an A record, and whether the domain uses Cloudflare DNS.
  • A domain the store hasn't connected returns a precheck: root or subdomain, registrar, nameservers, DNSSEC and the recommended dns for connect-domain.
  • It changes nothing. Retrying a failed domain is connect-domain called again.

Get setup progress

get-setup-progresssettings:read
How far the store is from launch, step by step as Getting Started and its Pre-Launch Checklist lay it out: store information, payment provider, shipping, taxes, products, theme, policies, custom domain, branded email, a test order and launch.
Takes no arguments.
Caveats
  • Each step says whether it is done and required, what is missing, and links the dashboard page and the docs. next_step is the first required step left, then the first optional one.
  • A test order counts once one is placed with a test card or through the Sandbox gateway. AI apps never place orders: the step links the Sandbox test cards and a product page instead.

List shipping zones

list-shipping-zonessettings:read
List the store's shipping zones with their states, whether each is on, their rates and the version save-shipping-zone needs, plus the carriers quoting live rates and the states no active zone covers.
Takes no arguments.
Caveats
  • Order-total ranges are in dollars and weight ranges in pounds. A product-type rate prices handguns, long guns, ammunition and accessories.
  • When a carrier quotes live rates at checkout, paid zone rates show only if no quote comes back; free zone rates show beside the quotes.
  • The ShipStation zone is managed by its plugin and comes back read_only.

List tax zones

list-tax-zonessettings:read
List the store's manual tax zones with their rate as a percent, states, whether each is on and the version save-tax-zone needs.
Takes no arguments.
Caveats
  • When a tax plugin such as Avalara is active, it calculates tax and the zones are used only when it can't be reached.
  • Lists the states more than one active zone covers: checkout would charge whichever it found first.

List marketplace plugins

list-marketplace-pluginssettings:read
List the plugins in the plugin marketplace (Plugins > Marketplace) that this store can add, each with what it does, whether it's on, its help page and where to set it up, plus the limits the store's plan puts on them: distributor slots in use, whether marketplace feeds are included and which tax plugin is on.

Arguments

searchstringoptional
Words in the plugin's name or description.
categorystringoptional
Only plugins of this kind. dropshipper means distributors. One of: analytics, enhancement, security, compliance, fulfillment, dropshipper, tax, marketplace, marketing, other.
statusstringoptional
Which plugins to list. One of: all, active, inactive. Defaults to all.
Example argumentsjson
{ "category": "dropshipper" }
Caveats
  • Read-only. Turning a plugin on and entering its account details happen in the dashboard, and no tool reads a plugin's credentials.
  • A distributor limit of null means unlimited. A plugin FirearmCart unlocked for the store skips the distributor limit and the marketplace feeds requirement. Only one tax plugin can be on at a time.

Search tax codes

search-tax-codesproducts:read
Look up the tax codes the store's tax plugin accepts on products, by code or by words in their description: Avalara's AvaTax System Tax Codes or TaxJar's product categories, which decide how each state taxes a product. Listed only while Avalara or TaxJar is active.

Arguments

querystringrequired
A code, or words its description contains.
limitintegeroptional
Results, 1-50. Defaults to 20.
Example argumentsjson
{ "query": "ammunition" }
Resultjson
{
  "provider": "Avalara",
  "tax_codes": [
    { "code": "PA3000100", "description": "Ammunition for firearms" }
  ],
  "total_matches": 1
}
Caveats
  • A code matches when it starts with the query; a description, when it contains every word of it. An exact code comes first.
  • The list is the plugin's own, the same one the product page offers, and is kept for a week. Codes the provider marks "do not use" are left out.

Create a product

create-productproducts:writemutates
Create one product in the catalog, as a draft unless status is active: price and cost, stock, shipping weight, collection, description, specifications, SEO, options with every variant they make, and up to 5 images. Its product type decides FFL requirements and, with a Hazmat specification, its shipping class, which the result reports.

Arguments

namestringrequired
The product name customers see.
product_typestringrequired
A FirearmCart product type by slug or name, such as handguns, rifles, shotguns, handgun-ammunition or holsters.
pricenumberrequired
Selling price in dollars.
compare_at_pricenumberoptional
Compare-at ("was") price in dollars.
cost_per_itemnumberoptional
What the store pays per unit.
skustringoptional
Must not be used by another product in the store.
barcodestringoptional
UPC or other barcode.
stock_quantityintegeroptional
Units on hand. Defaults to 0.
track_quantitybooleanoptional
Track stock. Defaults to true.
continue_sellingbooleanoptional
Keep selling when out of stock. Defaults to false.
weightnumberoptional
Shipping weight; needs weight_unit.
weight_unitstringoptional
Unit of weight. One of: lb, oz, kg, g.
is_shippablebooleanoptional
Ships to customers. Defaults to true.
collectionstringoptional
A collection ID or name from list-collections.
descriptionstringoptional
HTML, cleaned like update-product-content's.
specificationsarray<object>optional
{ name, value } pairs, standardized to the product page's spec names.
meta_titlestringoptional
SEO title, up to 70 characters.
meta_descriptionstringoptional
SEO description, up to 160 characters.
statusstringoptional
draft keeps it off the storefront; active publishes it. One of: draft, active. Defaults to draft.
optionsarray<object>optional
Up to 3 { name, values } options. Every combination becomes a variant at the product's price with no stock, up to 100.
imagesarray<object>optional
Up to 5 images, each with exactly one of media_id, url or upload_id, plus optional alt; the first is featured.
allow_below_costbooleanoptional
The merchant confirmed a price below cost.
allow_duplicate_namebooleanoptional
The merchant wants a second product with a name created in the last 10 minutes.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "name": "Federal 9mm 115gr FMJ 50rd", "product_type": "handgun-ammunition", "price": 18.99, "cost_per_item": 12.5, "sku": "FED-9-115", "stock_quantity": 40, "weight": 1.4, "weight_unit": "lb" }
Caveats
  • An unknown product type is refused with the closest ones FirearmCart knows. Events are created in the Events plugin instead.
  • The result reports whether the product needs an FFL, whether it is an NFA item, and its shipping class (handgun, long_gun, hazmat, ammunition or accessory), decided by the product type and, for hazmat, a Hazmat specification.
  • An SKU already used in the store is refused, as is a product with the same name created in the last 10 minutes (a retried call) unless allow_duplicate_name is set.
  • The store's plan limit on products applies.
  • Name, type, cost and SKU can't be changed through AI apps afterwards; prices, status, content and images can.
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Update product price or status

update-productproducts:writemutates
Change one product's (or one variant's) price or compare-at price, or publish or unpublish a product. Prices are saved the way the product page saves them, including markup and cost basis, and the storefront refreshes within a minute.

Arguments

product_idstringrequired
The product ID shown in the dashboard.
variant_idstringoptional
A variant ID from search-products, to price one variant instead of the product.
pricenumberoptional
New selling price in dollars.
expected_pricenumberoptional
The current price you read. Required with price.
compare_at_pricenumberoptional
New compare-at ("was") price in dollars; null removes it. The storefront shows a sale only when it is above the price.
statusstringoptional
active publishes the product on the storefront; draft hides it. Products only. One of: active, draft.
expected_statusstringoptional
The current status you read. Required with status. One of: active, draft.
allow_below_costbooleanoptional
The merchant confirmed selling below cost.
allow_large_changebooleanoptional
The merchant confirmed a price change past 2x or under half the current price.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "product_id": "1042", "price": 529.99, "expected_price": 549.99 }
Caveats
  • A price below MAP is always refused. At a store set to Price at MAP, a price above a product's MAP is saved with a warning that syncs move it back to the MAP.
  • A price below cost needs allow_below_cost, and a move past 2x or under half the current price needs allow_large_change; set them only after the merchant confirms that exact number.
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Update product description, specs or SEO

update-product-contentproducts:writemutates
Change one product's description, specifications, or SEO title and description, on any product, distributor (dropship) products included. The description is cleaned to the product editor's kinds of markup, spec names are matched the way marketplace feeds and storefront filters match them, and the storefront refreshes within a minute. The name, stock, cost and SKU are not changed here.

Arguments

product_idstringrequired
The product ID shown in the dashboard.
expected_versionstringrequired
The content_version search-products returned for this product.
descriptionstringoptional
The new description as HTML. Replaces the whole description; an empty string clears it.
meta_titlestringoptional
SEO title, up to 70 characters; the store name is added after it. An empty string clears it.
meta_descriptionstringoptional
SEO description, up to 160 characters. An empty string clears it.
specificationsarray<object>optional
Every spec as { name, value }, in order. Replaces the whole list; an empty list removes them all.
set_specificationsarray<object>optional
Specs as { name, value } to add, or to change by name. Other specs stay as they are.
remove_specificationsarray<string>optional
Names of specs to delete.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "product_id": "1042", "expected_version": "3f9a1c07b2de", "meta_title": "Glock 19 Gen 5 9mm Pistol", "set_specifications": [{ "name": "Barrel Length", "value": "4.02 in" }] }
Caveats
  • Descriptions keep paragraphs, headings, bold and italic, lists, quotes, links and simple tables. Scripts, styles, images, iframes and forms are removed, and plain text becomes paragraphs; the result lists what was removed.
  • The only Liquid allowed in a description is a plain product field such as {{ product.specifications }}, which prints the spec table. Filters and {% %} tags are refused.
  • Spec names are matched ignoring case and spacing, and saved under the product editor's standard name when one matches (barrel length becomes Barrel Length). Pass specifications for the whole list, or set_specifications and remove_specifications for smaller changes, not both.
  • Magazine capacity (Capacity, Magazine Capacity) and action type (Action Type, Action) decide state shipping restrictions and FFL transfers. A product that lacks one can have it added; one it already has can only be changed on the product page.
  • An empty meta_title or meta_description makes the storefront fall back to the product name and the start of the description.
  • FastBound replaces a FastBound-only product's specs whenever its FastBound record changes, so the result warns that a spec change there won't last.
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Update product images

update-product-imagesproducts:writemutates
Change one product's images in a single checked call: add images (from the media library, a public https url or an upload_id), remove them, reorder them or choose the featured (first) one, set alt text, and choose which image each variant shows.

Arguments

product_idstringrequired
The product ID shown in the dashboard.
expected_images_versionstringrequired
images_version from search-products for this product.
addarray<object>optional
Up to 5 images to add, each with exactly one of media_id, url or upload_id, plus optional alt, featured and variant_ids. They go after the existing images unless featured.
removearray<string>optional
image_ids to remove.
orderarray<string>optional
Every remaining image_id in the new order.
featured_image_idstringoptional
An existing image_id to make the featured (first) image. Use order or this, not both.
altarray<object>optional
{ image_id, alt } pairs; an empty alt clears it.
variant_imagesarray<object>optional
{ variant_id, image_id } pairs; image_id null shows no image for that variant.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "product_id": "1042", "expected_images_version": "9f3c2a1b7e40", "add": [{ "media_id": "9b2f6c3e-7d41-4a8e-9c55-1f0e2d3a4b5c", "alt": "Glock 19 Gen 5, left side", "featured": true, "variant_ids": ["2"] }] }
Resultjson
{
  "status": "applied",
  "record": {
    "product_id": "1042",
    "name": "Glock 19 Gen 5",
    "images": [
      {
        "image_id": "5d1c…",
        "position": 1,
        "featured": true,
        "url": "https://cdn.firearmcart.com/media/10450/glock-19-gen-5-left.jpg",
        "thumbnail_url": "https://cdn.firearmcart.com/media/10450/conversions/glock-19-gen-5-left-thumb.jpg",
        "alt": "Glock 19 Gen 5, left side",
        "width": 1600,
        "height": 1067,
        "variant_ids": ["2"]
      }
    ],
    "images_version": "4e0b9a17c2d3"
  },
  "changes": {
    "images": { "from": 2, "to": 3 },
    "image_order": { "from": ["…"], "to": ["new image", "…"] }
  },
  "warnings": [],
  "audit_id": 8813
}
Caveats
  • If the product's images changed after you read them, nothing is saved: read the product again.
  • An image from the media library is copied onto the product, so deleting it from the library never breaks the product.
  • A variant shows one image, so linking it to a new one unlinks the old.
  • Up to 5 images added per call and 50 per product.
  • Removing every image leaves the product with none; some distributor syncs add their own image back to products without one.
  • Changes reach the storefront within a minute, and an open product page refreshes its images.

Update product shipping weight

update-product-weightproducts:writemutates
Set the shipping weight checkout rates one product by, or one variant that ships on its own weight, distributor products included.

Arguments

product_idstringrequired
The product ID shown in the dashboard.
variant_idstringoptional
A variant ID from search-products whose ships_on_product_weight is false, to set that variant's own weight.
weightnumberrequired
The new shipping weight, more than 0.
weight_unitstringrequired
Unit of the new weight. One of: lb, oz, kg, g.
expected_weightnumberrequired
The current weight you read, in its own unit; 0 when it has none.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "product_id": "1042", "weight": 1.5, "weight_unit": "lb", "expected_weight": 0 }
Caveats
  • A distributor's weight is copied to the product once, at import, and distributor syncs never change it, so a correction stays.
  • A variant that ships on the product's weight is refused; leave variant_id out to set the product's.
  • The record's missing_weight says whether the product still has a line that would ship with no weight, such as another variant.
  • Use a weight the merchant gave or confirmed, never a guess. A product that doesn't ship is saved with a warning that checkout won't use the weight.
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Set product tax codes

set-product-tax-codeproducts:writemutates
Set the tax code the store's tax plugin (Avalara or TaxJar) taxes a product under, on one product or on many at once by product IDs, product type or collection, or remove it. Listed only while Avalara or TaxJar is active.

Arguments

tax_codestringoptional
The code to set, from search-tax-codes.
remove_tax_codebooleanoptional
Remove the code instead of setting one.
product_idstringoptional
One product, by the ID shown in the dashboard.
expected_tax_codestringoptional
With product_id: the tax_code you read from search-products, null when it has none.
product_idsarray<string>optional
Several products by ID, up to 200.
product_typestringoptional
Every product of this type, e.g. handgun-ammunition.
collectionstringoptional
Every product in this collection, by name.
only_missingbooleanoptional
With product_ids, product_type or collection: only the products that have no tax code yet.
expected_countintegeroptional
With product_ids, product_type or collection: how many products the dry run said would change. Required to apply.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "product_type": "handgun-ammunition", "tax_code": "PA3000100", "only_missing": true, "expected_count": 41 }
Caveats
  • Pass tax_code or remove_tax_code, and exactly one of product_id, product_ids, product_type or collection.
  • The code must be one of the plugin's (search-tax-codes) and is saved as the plugin writes it. A product without a code is taxed as general merchandise.
  • One product is compared against expected_tax_code like the other writes. A change to many is previewed with dry_run, which reports how many products match and how many would change, lists the first 25, and warns when it replaces codes products already have. Applying it needs that count as expected_count; if the products changed meanwhile it is refused and previewed again.
  • Product pages open on the changed products show the new code, and the audit log keeps every product a change to many touched.
  • New orders use the new code. Orders already placed keep the code they were taxed under, so refunds of them still match.
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Set product markup

set-product-markupproducts:writemutates
Set the markup on many products at once, like Reprice on the Products list: each product's price becomes its cost plus the markup, never under MAP. Pick the products by ID, or by provider, product type and collection together, up to 500.

Arguments

markup_percentagenumberrequired
The markup on each product's cost, 0-99, as the merchant chose it.
product_idsarray<string>optional
Products by the IDs shown in the dashboard, up to 200.
providerstringoptional
Products from this provider, as search-products' provider filter: a distributor's slug such as rsr or lipseys, or internal for the store's own stock.
product_typestringoptional
Products of this type, e.g. handguns.
collectionstringoptional
Products in this collection, by name.
allow_large_changebooleanoptional
Allow new prices over twice or under half the current ones. Only after the merchant confirms them.
expected_countintegeroptional
How many products the dry run said would change. Required to apply.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "provider": "rsr", "product_type": "handguns", "markup_percentage": 15, "expected_count": 214 }
Caveats
  • Pass product_ids, or any of provider, product_type and collection; they can't be mixed.
  • Each product is priced from the cost its selected supplier syncs it from, floored at the highest MAP of its switched-on distributors. At a store set to Price at MAP, a product whose MAP is above that cost is priced at the MAP. The stored markup is the one the new price works out to, so a price held up by MAP keeps a higher markup. Variants keep their own prices.
  • Products with no supplier or no cost to price from are skipped and listed. The dry run lists the first 25 products with their old and new prices and warns about prices set by hand that this replaces, products held at MAP, products Price at MAP prices under the markup, and products with Auto-update price on cost change switched off.
  • Applying needs the dry run's count as expected_count, and allow_large_change when a new price is over twice or under half the current one. It's refused while a Reprice from the Products list is running. More than 500 products go through that Reprice instead.
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Import distributor products

import-distributor-productsproducts:writemutates
Import items from one of the store's distributor catalogs at a markup on cost, the same import as the Import button on the distributor's page: by SKU, or every item matching a search that isn't in the store yet, up to 500. Listed only while the store has a distributor switched on.

Arguments

distributorstringrequired
The distributor to import from, by its slug from search-distributor-catalog, e.g. rsr.
skusarray<string>optional
The items to import, by the SKUs search-distributor-catalog returned, up to 500.
querystringoptional
Instead of skus: words every matching item's name, SKU, UPC, manufacturer or part number contains.
manufacturerstringoptional
Instead of skus: items from this manufacturer.
categorystringoptional
Instead of skus: items in this distributor category.
in_stock_onlybooleanoptional
With search filters: only items the distributor has in stock.
include_allocatedbooleanoptional
With search filters: also import allocated items.
include_non_dropshipbooleanoptional
With search filters: also import items the distributor won't drop ship.
conditionstringoptional
With search filters, Sports South only: which units to import. One of: new, refurbished, clearance, all. Defaults to new.
min_costnumberoptional
With search filters: lowest cost to the store, in dollars.
max_costnumberoptional
With search filters: highest cost to the store, in dollars.
markup_percentagenumberrequired
The markup on each item's cost, 0-99, as the merchant chose it.
publishbooleanoptional
Put the new products live on the storefront. Only when the merchant asked; otherwise they arrive as drafts. Defaults to false.
expected_countintegeroptional
How many items the dry run said would be imported. Required to import.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "distributor": "rsr", "skus": ["GLPA1950203", "GLPA1750203"], "markup_percentage": 20, "expected_count": 2 }
Caveats
  • Each new product is priced at its cost plus the markup, never under MAP, or at its MAP when the store prices at MAP and the MAP is above the cost, and arrives as a draft unless publish is set. Always ask the merchant for the markup; the dashboard suggests 20%.
  • The dry run sorts the items: new products, products the store deleted that come back as they were (old price and status), items that join an existing listing with the same UPC as another supplier (not priced at the markup), and items already in the store, which are skipped. It lists the first 25 with their cost, MAP and price, and warns about allocated items and items the distributor won't drop ship.
  • Applying needs the dry run's count as expected_count. It's refused until the distributor's first catalog sync has finished, while another import from it is running, or when the plan's product limit has no room for the new products.
  • Up to 5 items import straight away and the result lists the products. More run as a background import, as on the distributor's page: the dashboard's bell says when it finishes. A search matching more than 500 items is refused; import those with Select all on the distributor's page.
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Adjust inventory

adjust-inventoryinventory:writemutates
Set or adjust the stock the store holds itself for one product or variant. Distributor stock, and stock synced from Lightspeed, FastBound or Orchid eBound, updates from its source and is refused. A pack variant sells the product's units, so the product is adjusted instead.

Arguments

product_idstringrequired
The product ID shown in the dashboard.
variant_idstringoptional
A variant ID from search-products, to change that variant's stock.
modestringrequired
set = make it exactly quantity; adjust = add quantity (negative removes). One of: set, adjust.
quantityintegerrequired
Units to set, or to add (negative to remove).
expected_quantityintegerrequired
The current own stock you read.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "product_id": "1042", "mode": "adjust", "quantity": -2, "expected_quantity": 7 }
Caveats
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Add tracking to an order

fulfill-orderorders:writemutates
Record tracking for a parcel the merchant shipped: up to 10 tracking numbers on one of the order's fulfillments. The customer gets one tracking email, and a fulfillment waiting to be sent is marked complete so it never goes to a supplier.

Arguments

order_numberstringrequired
The order number.
fulfillment_idstringoptional
The fulfillment the parcel belongs to, from search-orders. Optional when the order has one open fulfillment.
trackingarray<object>required
1 to 10 { number, carrier } entries. The carrier (UPS, FedEx, USPS, DHL or Other) is read from the number when left out, and required when the number doesn't show it.
expected_statusstringoptional
The fulfillment status you read, such as pending or processing.
notify_customerbooleanoptional
Email the customer their tracking. Default: only when the fulfillment had no tracking yet.
mark_completebooleanoptional
Take a fulfillment waiting to be sent off the queue. Defaults to true.
dry_runbooleanoptional
Check and preview without recording anything.
Example argumentsjson
{ "order_number": "4021", "fulfillment_id": "9a3c4d1e-2b7f-4c1a-8e5d-6f0a1b2c3d4e", "tracking": [{ "number": "1Z999AA10123456784" }], "expected_status": "processing" }
Caveats
  • Works on lines the store ships itself (own stock, ShipStation, an outside source) and on lines a supplier is already handling. A distributor line that was never sent is refused, since the distributor would ship it too: change its supplier to own_stock first.
  • Cancelled, failed, held, delivered and returned fulfillments, and local pickups, are refused.
  • Numbers already on the fulfillment are skipped. A fulfillment already in transit or delivered keeps its status.
  • FastBound and Orchid eBound dispositions and the tracking.assigned webhook run whether or not the customer is emailed; GunBroker orders get their tracking pushed.
  • Read the order with search-orders first, tell the merchant the exact change and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: read the order again and ask again.
  • Every attempt is recorded in the store's AI audit log. An order page that is open shows the change.

Send an order to its suppliers

process-orderorders:writemutates
Send an order's waiting lines to whoever ships them, as Process Fulfillments does on the order page. This places real purchase orders with distributors and pushes own-stock lines to ShipStation. A dry run returns the plan and its version; the send names that version.

Arguments

order_numberstringrequired
The order number.
expected_plan_versionstringoptional
The plan_version a dry run returned. Required to send.
allow_short_stockbooleanoptional
The merchant confirmed sending lines the plan shows as short on stock.
dry_runbooleanoptional
Return the plan without sending anything. Always do this first.
Example argumentsjson
{ "order_number": "4021", "dry_run": true }
Resultjson
{
  "status": "dry_run",
  "record": {
    "order_number": "4021",
    "plan_version": "5c0e9a7d21b4f3a8",
    "shipments": [
      {
        "fulfillment_id": "9a3c4d1e-2b7f-4c1a-8e5d-6f0a1b2c3d4e",
        "route": "rsr",
        "supplier": "RSR Group",
        "places_purchase_order": true,
        "ships_to": "ffl",
        "ffl_dealer": { "license_number": "1-54-059-01-8L-00695", "business_name": "Valley Arms LLC" },
        "lines": [{ "line_id": "88213", "name": "Glock 19 Gen 5", "sku": "PA195S201", "quantity": 1 }],
        "estimated_cost": 489.5,
        "problem": null
      }
    ],
    "stock_shortages": [],
    "left_alone": []
  },
  "changes": { "shipments_sent": { "from": 0, "to": 1 } },
  "warnings": ["Sending places 1 purchase order(s) with RSR Group. That can't be undone from here."],
  "audit_id": 9104,
  "store": { "name": "Alpha Arms", "timezone": "America/Chicago", "currency": "USD" }
}
Caveats
  • Always preview first and show the merchant the plan: each shipment, who sends it, where it goes, its lines, estimated cost, stock shortages and anything blocking it. Send only the plan they approved; if the order changed since, the send is refused.
  • Never use it for a parcel the merchant already shipped: that is fulfill-order.
  • Test orders, local pickups, and unpaid, refunded, voided or charged-back orders are refused.
  • Each line is sent once, even if the order page sends it at the same moment. A line that has to reach an FFL waits until the order has one, and a line whose distributor isn't connected and active waits too.
  • Read the order with search-orders first, tell the merchant the exact change and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: read the order again and ask again.
  • Every attempt is recorded in the store's AI audit log. An order page that is open shows the change.

Change who ships an order line

change-order-supplierorders:writemutates
Change who ships one order line before it is sent: the store's own stock, an outside source the merchant buys from, or one of the line's distributors. Stock moves with it as on the order page.

Arguments

order_numberstringrequired
The order number.
line_idstringrequired
The line_id from search-orders.
supplierstringrequired
own_stock, outside, or a distributor slug from the line's supplier_options.
expected_supplierstringrequired
The line's supplier as you read it: automatic when it had none yet.
allow_short_stockbooleanoptional
The merchant confirmed a source showing less stock than the line needs.
dry_runbooleanoptional
Check and preview without changing anything.
Example argumentsjson
{ "order_number": "4021", "line_id": "88213", "supplier": "own_stock", "expected_supplier": "rsr" }
Caveats
  • Only while the line is waiting (supplier_can_change in search-orders). The whole line moves; splitting it between sources is done on the order page.
  • A line with no fulfillment yet gets one, waiting to be sent, so the choice is saved. Nothing is ordered until process-order.
  • A firearm can't go to a general-merchandise supplier, and an accessory that has to reach an FFL can't go to a distributor that ships accessories to customers only.
  • Read the order with search-orders first, tell the merchant the exact change and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: read the order again and ask again.
  • Every attempt is recorded in the store's AI audit log. An order page that is open shows the change.

Update an order note

update-order-noteorders:writemutates
Add to an order's internal note, signed with who added it and when, or replace the whole note. The note is for the store's staff; the customer never sees it.

Arguments

order_numberstringrequired
The order number.
textstringrequired
The text to add, or the whole new note. Up to 5,000 characters.
modestringoptional
append adds to the end; replace sets the whole note. One of: append, replace. Defaults to append.
expected_note_versionstringoptional
The note version from search-orders. Required to replace.
dry_runbooleanoptional
Preview without saving.
Example argumentsjson
{ "order_number": "4021", "text": "Customer asked to hold until Friday." }
Caveats
  • Text the note already holds isn't added again, so a retried call leaves one copy.
  • ShipStation receives the note when the order is sent to it, so a later change doesn't reach ShipStation.
  • Read the order with search-orders first, tell the merchant the exact change and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: read the order again and ask again.
  • Every attempt is recorded in the store's AI audit log. An order page that is open shows the change.

Change an order's receiving FFL

change-order-fflorders:writemutates
Change the FFL dealer an order's firearms ship to, by license number. Fulfillments not yet sent follow the new dealer.

Arguments

order_numberstringrequired
The order number.
license_numberstringrequired
The new dealer's FFL license number, with or without dashes. search-ffl-dealers finds dealers.
expected_license_numberstringrequired
The order's current dealer license as you read it, or none.
set_as_customer_defaultbooleanoptional
Also make it the customer's default FFL for future orders.
allow_no_sotbooleanoptional
The merchant confirmed sending an NFA item to a dealer not on file as SOT.
allow_non_dealer_licensebooleanoptional
The merchant confirmed a license type other than 01, 02 or 07.
dry_runbooleanoptional
Check and preview without changing anything.
Example argumentsjson
{ "order_number": "4021", "license_number": "1-54-059-01-8L-00695", "expected_license_number": "none" }
Caveats
  • Only while no firearm line has gone to a distributor or carrier (ffl_dealer.can_change in search-orders).
  • Expired licenses and licenses no longer on the ATF list are refused, as are local pickups.
  • The result warns when no copy of the dealer's license is on file, since some distributors need one, and when the order came from a marketplace.
  • Read the order with search-orders first, tell the merchant the exact change and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: read the order again and ask again.
  • Every attempt is recorded in the store's AI audit log. An order page that is open shows the change.

Update store settings

update-store-settingssettings:writemutates
Change the store's business details, social links, whether its own FFL shows in storefront FFL pickers, and its logo, favicon or checkout logo.

Arguments

expected_settings_versionstringrequired
settings_version from get-store-settings.
store_namestringoptional
The store name customers see.
emailstringoptional
The store's contact email.
phonestringoptional
Customer service phone; null clears it.
addressstringoptional
Street address.
citystringoptional
City.
statestringoptional
State.
zip_codestringoptional
ZIP code.
socialobjectoptional
Profile URLs by network (facebook, instagram, youtube, tiktok, twitter, snapchat, pinterest, tumblr, vimeo, whatsapp); null removes one.
show_ffl_at_checkoutbooleanoptional
Whether the store's own FFL is offered in storefront FFL pickers.
logoobjectoptional
The new logo: exactly one of media_id, url or upload_id. PNG, JPG or GIF up to 1 MB.
remove_logobooleanoptional
Remove the store logo.
faviconobjectoptional
The new favicon: exactly one of media_id, url or upload_id. PNG or JPG up to 1 MB.
remove_faviconbooleanoptional
Remove the favicon.
checkout_logoobjectoptional
The logo for the always-light checkout. PNG, JPG or GIF up to 1 MB.
remove_checkout_logobooleanoptional
Remove the checkout logo, so checkout uses the store logo.
dry_runbooleanoptional
Check and preview without saving.
Example argumentsjson
{ "expected_settings_version": "4be0c19a7d22", "phone": "262-555-0100", "social": { "instagram": "https://instagram.com/alphaarms" } }
Caveats
  • Changes reach the storefront and checkout at once, so the assistant tells the merchant exactly what changes and gets a yes first. If the settings changed since they were read, nothing is saved.
  • Turning show_ffl_at_checkout off hides the store's license from the FFL picker on every FirearmCart store; local pickups still transfer through it.
  • The lock screen, custom scripts, customer accounts and payment gateways stay in the dashboard. The store's FFL is set from a copy of its license, never a typed number.
  • Every attempt is recorded in the store's AI audit log.

Set the store's FFL

set-store-fflsettings:writemutates
Set the store's own FFL, which local firearm pickups transfer through, from a copy of its license. The license number is read off the copy and matched to the ATF list, as Settings > General does; it is never typed.

Arguments

urlstringoptional
A public https URL of the license copy.
fileobjectoptional
A license copy the merchant attached in ChatGPT: { download_url, file_id, mime_type?, file_name? }, passed by ChatGPT itself.
upload_idstringoptional
An upload_id from a create-upload-link link made with purpose license.
expected_license_numberstringrequired
The store FFL's license number from get-store-settings, or none.
dry_runbooleanoptional
Read the copy and show the license without setting it.
Example argumentsjson
{ "upload_id": "01k7f3x2c9d8b6a5e4r3t2y1u0", "expected_license_number": "none", "dry_run": true }
Caveats
  • Give exactly one copy: url, file or upload_id. PDF, JPG or PNG.
  • Preview first: the dry run shows which license the copy holds. Confirm it with the merchant, then call again with the same copy. A copy is read once every 15 minutes, so the confirming call doesn't read it again, and a store can have 10 copies read a day.
  • The copy is kept privately as the record of the proof, as on the settings page. Removing the store's FFL stays in Settings > General.

Connect a custom domain

connect-domainsettings:writemutates
Connect a custom domain to the storefront, or re-check one the store already has. With FirearmCart-managed DNS it returns the nameservers the merchant sets at their registrar; with the merchant's own DNS, the CNAME record they add at their DNS provider.

Arguments

domainstringrequired
The domain or subdomain, such as yourstore.com or www.yourstore.com. A pasted URL is fine.
dnsstringoptional
managed: FirearmCart hosts the domain's DNS and the merchant changes its nameservers once (root domains). external: the merchant adds one CNAME at their own DNS provider (subdomains, or DNS already on Cloudflare). Omitted, it is managed for a root domain and external otherwise. One of: managed, external.
dry_runbooleanoptional
Check the domain without connecting it.
Example argumentsjson
{ "domain": "alpha-arms.com", "dns": "managed" }
Caveats
  • A domain another store uses, and FirearmCart's own addresses, are refused.
  • Managed: the result's name_servers are the two the merchant sets at their registrar, replacing the old ones, with DNSSEC turned off first. The domain's existing records, such as email, are copied over before the switch, and www redirects to the root. The domain serves the store once the nameservers change (usually within an hour, up to 24) and its SSL certificate is issued, and branded email turns on by itself.
  • External: the domain serves the store once its CNAME points at FirearmCart and the SSL certificate is issued, usually 5-30 minutes. If the DNS is on Cloudflare, the record must be DNS only (grey cloud).
  • Calling it again for the same domain re-checks it, and asks Cloudflare to verify one that failed again. When a domain isn't connecting, check-domain says why.

Save a shipping zone

save-shipping-zonesettings:writemutates
Create a shipping zone, or change one's name, states, on switch and rates. Rates are added or changed one by one; rates left out stay as they are.

Arguments

zone_idstringoptional
The zone to change. Leave out to create one.
expected_versionstringoptional
The zone's version from list-shipping-zones. Required with zone_id.
namestringoptional
The zone name. Required to create.
statesarray<string>optional
Every state the zone covers, as two-letter codes. Replaces the list. Required to create.
activebooleanoptional
Whether the zone is on. New zones are on.
ratesarray<object>optional
Rates to add (no rate_id) or change (rate_id): name, description, condition_type (price, weight or product_type), price, min_value, max_value, product_type_prices.
dry_runbooleanoptional
Check without saving.
Example argumentsjson
{ "name": "Lower 48", "states": ["TX", "OK"], "rates": [{ "name": "Ground", "condition_type": "price", "price": 9.99, "min_value": 0, "max_value": 499.99 }, { "name": "Free over $500", "condition_type": "price", "price": 0, "min_value": 500 }] }
Caveats
  • Rates follow the zone editor's rules: the first paid range of a kind starts at 0, ranges of a kind can't overlap, a $0 rate is free shipping and can start anywhere, and a product-type rate needs all four prices. A rate that breaks them undoes the whole call.
  • The ShipStation zone is refused. Deleting a zone or a rate stays in Settings > Shipping.
  • Changes reach checkout at once.

Save a tax zone

save-tax-zonesettings:writemutates
Create a manual tax zone, or change one's name, rate, states or on switch.

Arguments

zone_idstringoptional
The zone to change. Leave out to create one.
expected_versionstringoptional
The zone's version from list-tax-zones. Required with zone_id.
namestringoptional
The zone name. Required to create.
rate_percentnumberoptional
The tax rate as a percent, 0-100, such as 5.5. Required to create.
statesarray<string>optional
Every state the zone covers, as two-letter codes. Replaces the list. Required to create.
activebooleanoptional
Whether the zone is on. New zones are on.
dry_runbooleanoptional
Check without saving.
Example argumentsjson
{ "name": "Wisconsin", "rate_percent": 5, "states": ["WI"] }
Caveats
  • A state can be in one active zone only; a zone that would overlap another is refused.
  • FirearmCart doesn't know local tax rates: the merchant decides the rate. Deleting a zone stays in Settings > Taxation.

Upload an image to the media library

upload-mediaproducts:writemutates
Add an image to the store's media library (the Files page) and get its media_id, for the product, collection and article image tools, and its CDN url, for themes. Works with products:write or themes:write.

Arguments

urlstringoptional
A public https URL of the image. The server downloads it.
fileobjectoptional
An image the merchant attached in ChatGPT: { download_url, file_id, mime_type?, file_name? }, passed by ChatGPT itself.
upload_idstringoptional
An upload_id from a file sent to a create-upload-link link.
namestringoptional
A name for the library, also the image's default alt text. Defaults to the file name.
dry_runbooleanoptional
Check the source without downloading or saving anything.
Example argumentsjson
{ "url": "https://images.example.com/glock-19-gen-5-left.jpg", "name": "Glock 19 Gen 5 left" }
Resultjson
{
  "status": "applied",
  "record": {
    "media_id": "9b2f6c3e-7d41-4a8e-9c55-1f0e2d3a4b5c",
    "name": "Glock 19 Gen 5 left",
    "url": "https://cdn.firearmcart.com/media/10442/glock-19-gen-5-left.jpg",
    "thumbnail_url": "https://cdn.firearmcart.com/media/10442/conversions/glock-19-gen-5-left-web_thumb.jpg",
    "width": 1600,
    "height": 1067,
    "size": 284113,
    "mime_type": "image/jpeg"
  },
  "changes": { "media": { "from": null, "to": "Glock 19 Gen 5 left" } },
  "warnings": [],
  "audit_id": 8812,
  "store": { "name": "Alpha Arms", "timezone": "America/Chicago", "currency": "USD" }
}
Caveats
  • Give exactly one source: url, file or upload_id.
  • JPG, PNG, GIF or WebP up to 10 MB and 40 megapixels. SVG, HEIC, AVIF and animated WebP are refused; the type is read from the file, never its name. Location data is removed from photos.
  • Downloads only reach public internet addresses over https, and every redirect is checked the same way.
  • The same image uploaded again returns already_applied with the existing media_id.
  • An upload_id can be used once; a used one says which media it became.
  • Only add images the merchant owns or may use. Uploads are recorded in the AI audit log; a ChatGPT download link is never logged.

Create a collection

create-collectionproducts:writemutates
Add a collection from the platform's collection types (list-collections shows the ones still available). It takes the type's name and storefront URL, a store has one collection per type, and it starts empty.

Arguments

typestringrequired
A collection type from list-collections available_types, by name, e.g. Handguns.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "type": "Handguns" }
Caveats
  • Asking for a type the store already has returns already_applied with that collection.
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Update a collection

update-collectionproducts:writemutates
Change one collection: move products into or out of it, change its type (which renames it and moves it to a new storefront URL), or set or remove its cover image. A product sits in at most one collection, so adding a product takes it out of the one it was in; removing one leaves it in no collection.

Arguments

collection_idstringrequired
A collection ID from list-collections.
add_product_idsarray<string>optional
Product IDs to move into this collection, up to 50.
remove_product_idsarray<string>optional
Product IDs to take out of this collection, up to 50.
typestringoptional
A collection type from list-collections available_types. Renames the collection and changes its URL.
expected_namestringoptional
The collection's current name, as you read it. Required with type.
allow_url_changebooleanoptional
The merchant agreed that the collection's old URL stops working. Required with type.
cover_imageobjectoptional
A new cover: exactly one of { media_id, url, upload_id }. Replaces the current cover.
remove_coverbooleanoptional
Remove the cover image.
expected_cover_idstringoptional
The current cover's image_id from list-collections, or none. Required with cover_image or remove_cover.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "collection_id": "12", "add_product_ids": ["1042", "1043"] }
Caveats
  • A product ID that isn't in the store refuses the whole call. Event products aren't placed in collections.
  • Products listed in remove_product_ids that aren't in this collection are left alone, with a warning.
  • A new type that another collection already has is refused; move the products into that collection instead.
  • Moving products changes which collection pages, filters and collection discount codes they fall under. The dry run lists each product's current collection.
  • A new cover is a copy of the image, so deleting it from the media library never breaks the cover. The old cover stays until the new one is fully saved.
  • Collections are deleted only on the Collections page.
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Pause, resume or skip a subscription

update-subscriptionsubscriptions:writemutates
Pause, resume, or skip the next charge of one Reload subscription. Resuming turns recurring charges back on.

Arguments

subscription_idstringrequired
The subscription ID shown in the dashboard.
actionstringrequired
What to do. One of: pause, resume, skip.
expected_statusstringrequired
The status you read. One of: active, paused, past_due.
expected_next_charge_onstringoptional
YYYY-MM-DD in the store's timezone. Required for skip.
pause_untilstringoptional
YYYY-MM-DD to resume automatically. Leave out to pause until resumed.
dry_runbooleanoptional
Check and preview the change without saving it.
Caveats
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Cancel a subscription

cancel-subscriptionsubscriptions:writemutates
Cancel one Reload subscription so the customer is never charged for it again. A cancelled subscription can't be resumed here.

Arguments

subscription_idstringrequired
The subscription ID shown in the dashboard.
reasonstringrequired
Why it is being cancelled, as the merchant said.
expected_statusstringrequired
The status you read. One of: active, paused, past_due.
dry_runbooleanoptional
Check and preview the change without saving it.
Caveats
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Create a discount code

create-discountdiscounts:writemutates
Create a discount code: a percentage or fixed dollar amount off the whole store, chosen products, collections or customers, with optional free shipping (or free shipping alone, with value 0), minimum purchase, usage limit and dates. Codes are unique per store; leave code out to generate one.

Arguments

codestringoptional
The code shoppers enter. Leave out to generate one.
titlestringrequired
Internal name, e.g. "Black Friday 10%".
typestringrequired
Percentage or fixed dollar amount off. One of: percentage, fixed.
valuenumberrequired
Percent off (0-100) or dollars off. 0 with free_shipping makes a free-shipping-only code; 0 without it is refused.
applies_tostringoptional
What the code applies to. One of: store_wide, product, collection, customer. Defaults to store_wide.
product_idsarray<string>optional
Product IDs, when applies_to is product.
collection_idsarray<string>optional
Collection IDs, when applies_to is collection.
customer_idsarray<string>optional
Customer IDs, when applies_to is customer.
free_shippingbooleanoptional
Also give free shipping.
minimum_purchasenumberoptional
Minimum order subtotal in dollars.
usage_limitintegeroptional
Total times the code can be used.
starts_onstringoptional
YYYY-MM-DD. Leave out to start now.
ends_onstringoptional
YYYY-MM-DD. Leave out for no end date.
is_activebooleanoptional
Whether the code works once created. Defaults to true.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "title": "Black Friday 10%", "code": "BF10", "type": "percentage", "value": 10, "ends_on": "2026-11-30" }
Caveats
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

Update a discount code

update-discountdiscounts:writemutates
Turn a discount code on or off, or change its dates, usage limit, minimum purchase or name. Its value and what it applies to are changed in the dashboard.

Arguments

codestringrequired
The discount code to change.
is_activebooleanoptional
false turns the code off.
titlestringoptional
New internal name.
starts_onstringoptional
YYYY-MM-DD; null removes the start date.
ends_onstringoptional
YYYY-MM-DD; null removes the end date.
usage_limitintegeroptional
null removes the limit.
minimum_purchasenumberoptional
Dollars; null removes the minimum.
dry_runbooleanoptional
Check and preview the change without saving it.
Example argumentsjson
{ "code": "BF10", "is_active": false }
Caveats
  • Read the record first, tell the merchant the exact change (record, field, current → new) and get a clear yes.
  • A stale expected_* value is refused as a conflict and nothing is saved: re-read and ask again.
  • Every attempt is recorded in the store's AI audit log.

List themes

list-themesthemes:read
Lists every theme in the authenticated team's library. The row with active=true is the published storefront; the rest are inactive library copies you can safely edit. This is the entry point for the whole server — every other theme tool needs an id from here.
Takes no arguments.
Resultjson
{
  "themes": [
    {
      "theme_id": "9f1c0b2e-7d44-4a1e-9a52-3b8c6d0f1a77",
      "name": "Arsenal",
      "active": true,
      "template_source": "arsenal",
      "base_version": "1.4.0",
      "is_customized": true,
      "dev_mode": false,
      "screenshot_url": "https://cdn.firearmcart.com/theme-screenshots/412.jpg",
      "updated_at": "2026-02-11T18:04:22+00:00"
    },
    {
      "theme_id": "2ad7f6c1-55b0-4f3d-8e19-c0a4b7e2d904",
      "name": "Arsenal (working copy)",
      "active": false,
      "template_source": "arsenal",
      "base_version": "1.4.0",
      "is_customized": false,
      "dev_mode": false,
      "screenshot_url": null,
      "updated_at": "2026-02-14T09:31:07+00:00"
    }
  ]
}
Caveats
  • Takes no arguments — the store is the token itself, so there is nothing to scope by.
  • Rows are ordered active-first, then by name, so themes[0] is the live theme whenever the team has one.
  • theme_id is the identifier every later tool's `theme` argument takes, and it is stable: it survives an export/import round trip.
  • template_source is the theme-store slug the theme was created from (it matches list-theme-store.slug), and base_version is the catalogue version it was copied at — neither changes when the merchant edits files.
  • screenshot_url is the library thumbnail written by a background job (GenerateThemeScreenshot), so it is frequently null on a freshly duplicated theme and can lag the current files. It is unrelated to the URLs screenshot-theme returns; do not use it to check your own edits.
  • Never build against the active theme. Duplicate it first (duplicate-theme) or pick an inactive copy — file-write tools refuse an active theme unless allow_active=true.

List theme store catalog

list-theme-storethemes:read
Lists the active themes in the FirearmCart theme store, each annotated with whether this team has purchased it and whether a copy is already in their library. Use it to find the slug that add-theme-from-store installs.
Takes no arguments.
Resultjson
{
  "store": [
    {
      "slug": "arsenal",
      "name": "Arsenal",
      "version": "1.4.0",
      "price_cents": 0,
      "is_free": true,
      "purchased": false,
      "cover_photo": "https://cdn.firearmcart.com/themes/arsenal/cover.jpg",
      "in_library": true
    },
    {
      "slug": "tactix",
      "name": "Tactix",
      "version": "2.0.1",
      "price_cents": 18000,
      "is_free": false,
      "purchased": true,
      "cover_photo": "https://cdn.firearmcart.com/themes/tactix/cover.jpg",
      "in_library": false
    }
  ]
}
Caveats
  • Takes no arguments.
  • The catalog is the `config('themes')` file, not a database table. Only entries flagged active are returned, and a slug with several active versions yields one row per version — so slug alone is not a unique key here.
  • price_cents is an integer in cents and is 0 for free themes. Nothing on this server can purchase a theme; a paid theme the team has not bought (purchased: false) must be bought in the dashboard first.
  • in_library is derived by matching the slug against the template_source of themes already in the library, so it is true for any copy — including one the merchant has since renamed or heavily customized.

List theme files

list-theme-filesthemes:read
Lists a theme's files as theme paths, grouped by type (layout/, templates/, sections/, snippets/, blocks/, assets/). Run it before writing anything: it is the only way to confirm a snippet or asset you want to {% render %} actually exists.

Arguments

themestringrequired
The theme to inspect — the theme_id returned by list-themes. Omitting it fails with “Missing theme argument. Call list-themes first.”
typestringoptional
Return only one group. Omit for every group at once. One of: layout, template, section, snippet, block, asset.
Example argumentsjson
{
  "theme": "418",
  "type": "section"
}
Resultjson
{
  "files": {
    "section": [
      {
        "path": "sections/header.liquid",
        "is_customized": true,
        "user_created": false,
        "size": 18422
      },
      {
        "path": "sections/hero-banner.liquid",
        "is_customized": false,
        "user_created": true,
        "size": 3140
      }
    ],
    "asset": [
      {
        "path": "assets/base.css",
        "file_size": 96114,
        "mime_type": "text/css",
        "editable": true
      },
      {
        "path": "assets/logo-mark.png",
        "file_size": 12880,
        "mime_type": "image/png",
        "editable": false
      }
    ]
  }
}
Caveats
  • files is an object keyed by type, not a flat array, and a key is simply absent when that type has no files. Iterate the keys rather than indexing them.
  • Template rows and asset rows have different shapes: templates carry is_customized / user_created / size, assets carry file_size / mime_type / editable.
  • user_created: true means the file has no base-theme original (original_content IS NULL). Those are exactly the files delete-theme-file will accept — base theme files cannot be deleted, only overwritten.
  • editable: false marks a binary asset (png, jpg, webp, fonts). read-theme-file refuses it and no write tool can produce one, because every tool on this server is text-only. Reference it by URL instead.
  • Only active assets are listed. Assets superseded by a re-upload stay in the database but never appear here.
  • Plugin sections (fc-product-reviews, fc-events-list, fc-reload-options, …) are NOT theme files — they live in the application, so they never appear in this listing however active the plugin is. Discover them with list-plugins or get-section-schema.
  • Themes are resolved inside the authenticated team only. A theme id belonging to another team is indistinguishable from a non-existent one: both return “Theme not found for this team. Call list-themes first.”

Read a theme file

read-theme-filethemes:read
Returns the contents of one theme file addressed by its theme path, optionally at a historical version number. The response is plain text, not JSON.

Arguments

themestringrequired
The theme to inspect — the theme_id returned by list-themes. Omitting it fails with “Missing theme argument. Call list-themes first.”
pathstringrequired
Theme path exactly as list-theme-files reports it, e.g. sections/hero.liquid, templates/index.json, assets/base.css.
versionintegeroptional
Read a historical version instead of live content. Pass a version_number from list-file-versions (minimum 1).
Example argumentsjson
{
  "theme": "418",
  "path": "sections/hero-banner.liquid",
  "version": 3
}
Resulttext
# sections/hero-banner.liquid @ v3

<div class="section section--{{ section.settings.section_width }}">
  <h2>{{ section.settings.heading }}</h2>
</div>

{% schema %}
{ "name": "Hero banner", "settings": [] }
{% endschema %}
Caveats
  • The first line is a header — `# {path} @ {version}` — followed by a blank line, then the raw file. Strip those two lines before treating the payload as Liquid or JSON.
  • The version label reads `v12 (current)` when the file has version history and plain `current` when it has none. Requesting an explicit version labels it `v3` with no suffix.
  • Binary assets are refused with “Binary asset cannot be inlined. Use public_url: …”, which includes the URL. Readable assets are css, js, json and svg, plus *.css.liquid and *.js.liquid.
  • A missing path errors with “File not found: {path}” and a bad version with “Version {n} not found for {path}.” Neither is a partial success — nothing is returned alongside the error.
  • This returns the FILE, not the merchant's settings. An image_picker reads "image": null here even when the merchant has chosen a photo, because their choice lives in the theme's settings — read those with get-theme-settings, and never write that null back as "" or "none" to “clear” it.
  • Themes are resolved inside the authenticated team only. A theme id belonging to another team is indistinguishable from a non-existent one: both return “Theme not found for this team. Call list-themes first.”

Search theme files

grep-themethemes:read
Searches template contents — and optionally text assets — for a string or regex, returning path, line number and the matching line. The fastest way to find which section renders a snippet or defines a CSS class.

Arguments

themestringrequired
The theme to inspect — the theme_id returned by list-themes. Omitting it fails with “Missing theme argument. Call list-themes first.”
querystringrequired
The string to find, or a PCRE pattern when regex is true. Must be at least one character.
regexbooleanoptional
Treat query as a regular expression rather than a literal substring. Defaults to false.
case_sensitivebooleanoptional
Match case exactly. Both literal and regex searches are case-insensitive by default. Defaults to false.
typestringoptional
Restrict the search to one template type. Assets are governed by include_assets, not by this filter. One of: layout, template, section, snippet, block.
include_assetsbooleanoptional
Also search css/js/json/svg assets. Slower — each one is fetched from object storage. Defaults to false.
max_resultsintegeroptional
Stop after this many matches (1–200). Defaults to 50.
Example argumentsjson
{
  "theme": "418",
  "query": "render 'header-drawer'",
  "include_assets": false,
  "max_results": 20
}
Resultjson
{
  "matches": [
    {
      "path": "sections/header.liquid",
      "line": 142,
      "text": "      {% render 'header-drawer', linklist: section.settings.menu %}"
    }
  ],
  "count": 1,
  "truncated": false
}
Caveats
  • Matching is line-based and line numbers are 1-indexed, so a pattern spanning two lines never matches.
  • The regex delimiter is `~` and the tool escapes any `~` in your pattern before compiling with the `u` (and, unless case_sensitive, `i`) modifier. An uncompilable pattern returns “Invalid regex pattern.” rather than falling back to a literal search.
  • max_results caps the whole run, not each file — templates are scanned first and the cap can be reached before assets are touched. truncated: true means matches were dropped, so narrow the query rather than paging.
  • include_assets only reaches text assets; binaries are skipped, and any asset that fails to download is skipped silently rather than erroring the call.
  • The type filter has no `asset` value on purpose. Passing an unlisted type is a validation error, not an empty result.
  • Themes are resolved inside the authenticated team only. A theme id belonging to another team is indistinguishable from a non-existent one: both return “Theme not found for this team. Call list-themes first.”

Get section schema

get-section-schemathemes:read
Returns a section's parsed {% schema %} — its settings, blocks and presets — or, with `section` omitted, a summary of every section in the theme. It also covers plugin-provided sections (fc-*), which are not theme files but can be referenced by type from a page template.

Arguments

themestringrequired
The theme to inspect — the theme_id returned by list-themes. Omitting it fails with “Missing theme argument. Call list-themes first.”
sectionstringoptional
A section name (hero-banner), a filename (hero-banner.liquid), a full path (sections/hero-banner.liquid) or a plugin section type (fc-product-reviews). Omit for the summary of all sections.
Example argumentsjson
{
  "theme": "418",
  "section": "sections/hero-banner.liquid"
}
Resultjson
{
  "path": "sections/hero-banner.liquid",
  "schema": {
    "name": "Hero banner",
    "settings": [
      { "type": "image_picker", "id": "image", "label": "Background" },
      { "type": "text", "id": "heading", "label": "Heading", "default": "Shop rifles" }
    ],
    "blocks": [{ "type": "cta", "name": "Button", "settings": [] }],
    "presets": [{ "name": "Hero banner" }]
  },
  "has_presets": true,
  "picker_excluded": false,
  "picker_visible": true
}
Caveats
  • Three different response shapes. With a theme section: path + schema + has_presets + picker_excluded + picker_visible. With a plugin section: type, plugin_slug, plugin_active, template_only, block_types, schema and a ready-made `usage` snippet. With `section` omitted: a `sections` summary array (path, name, preset_count, block_types, picker_visible) plus a `plugin_sections` array.
  • Plugin names are resolved BEFORE theme files, so a theme file named fc-*.liquid can never be read through this tool.
  • picker_visible is the merchant-facing fact: it is true only when the section has at least one preset AND is not picker-excluded. Excluded are header, footer, header-group, footer-group, _blocks, any name starting with `_`, and anything prefixed main-, password-, predictive-search or section-rendering. A section with no preset exists but can never be added from the Visual Editor.
  • A plugin section whose plugin is inactive comes back with plugin_active: false and a `warning` telling you not to build the feature — its drops are empty and its endpoints reject. Confirm activation with list-plugins first.
  • template_only plugin sections (fc-reload-options is the usual one) are absent from the editor's picker entirely, so wiring them into a template JSON is the only way a merchant gets them.
  • An unknown section errors with “Section not found: {ref}”. Only files of type `section` resolve — passing a snippet or template path is a not-found, not a wrong-type error.
  • The summary form parses every section's schema on the fly, so it is the more expensive of the two calls on a large theme.

Get theme settings

get-theme-settingsthemes:read
Reads a theme's configuration in one of three scopes: the settings_schema definition, the merchant's saved global values, or the effective JSON for one page template. Theme settings are read-only over MCP, with one exception: the collection filter allowlist, which set-collection-filters writes.

Arguments

themestringrequired
The theme to inspect — the theme_id returned by list-themes. Omitting it fails with “Missing theme argument. Call list-themes first.”
scopestringrequired
Which slice to read: `schema` for the settings_schema definition, `values` for the merchant's saved global values, `page_template` for one template's effective section JSON. One of: schema, values, page_template.
templatestringoptional
The template name for scope=page_template, e.g. index, product, page.about. A .json or .liquid suffix is stripped. Required for that scope, ignored otherwise.
Example argumentsjson
{
  "theme": "418",
  "scope": "page_template",
  "template": "index"
}
Resultjson
{
  "template": "index",
  "source": "themes.settings",
  "data": {
    "sections": {
      "hero": {
        "type": "hero-banner",
        "settings": { "heading": "Shop rifles", "image": null }
      }
    },
    "order": ["hero"]
  }
}
Caveats
  • scope=page_template answers the question read-theme-file cannot: `source` is “themes.settings” when the merchant has edited the page in the Visual Editor and “theme_templates” when it is still the file on disk. The settings copy WINS at render, so templates/index.json can look nothing like the live page.
  • scope=values returns global values only — every key prefixed `templates.` or `pages.` is stripped out, because those are per-page overrides. Read one of those with scope=page_template.
  • scope=values includes collection_filters, the list of specification groups the theme shows as filters on collection pages and search results (an empty list means every group shows). It is the one setting with a write tool: use list-collection-filters to judge the groups and set-collection-filters to change it, rather than reading this raw list.
  • scope=values is also where merchant-chosen images live. A file read shows "image": null while the value here is set; that mismatch is expected, not a bug to correct.
  • The store logo is NOT a theme setting: it comes from the team's Settings › General and is force-applied at render, so a section-level logo picker never shows anything. Headers must emit the global settings.logo.
  • Errors are scope-specific: “No settings_schema found for this theme.”, “template is required when scope=page_template.”, “Page template not found: {name}”.
  • A JSON template's leading comment header is stripped before parsing. If the body still fails to decode, `data` comes back as the raw string instead of an object.

List file versions

list-file-versionsthemes:read
Lists the version history of one theme file, newest first, with who saved it and whether each version still matches the live content. Pair it with restore-file-version to undo a change that made things worse.

Arguments

themestringrequired
The theme to inspect — the theme_id returned by list-themes. Omitting it fails with “Missing theme argument. Call list-themes first.”
pathstringrequired
Theme path of the file whose history you want, e.g. sections/hero-banner.liquid.
Example argumentsjson
{
  "theme": "418",
  "path": "sections/hero-banner.liquid"
}
Resultjson
{
  "path": "sections/hero-banner.liquid",
  "versions": [
    {
      "version_number": 4,
      "label": "MCP update",
      "user": null,
      "created_at": "2026-02-14T09:31:07+00:00",
      "content_hash": "5f2b…a91c",
      "is_current": true
    },
    {
      "version_number": 3,
      "label": "MCP update",
      "user": "Dana Reyes",
      "created_at": "2026-02-13T22:12:44+00:00",
      "content_hash": "c07d…8e33",
      "is_current": false
    }
  ]
}
Caveats
  • Ordered by version_number descending, so versions[0] is the most recent save.
  • is_current is a sha256 comparison against live content, not a pointer. If an edit was reverted by hand, two versions can both report is_current: true — and a file saved outside the version pipeline can leave every version false.
  • user is null when the save came from a team API token (which is every MCP write), because a token has no user behind it. The label is what identifies the writer.
  • This returns metadata only. Fetch the content of a version with read-theme-file and its `version` argument.
  • A missing path errors with “File not found: {path}”. A file that has never been saved through the editor or MCP returns an empty versions array — there is no synthetic version 1 for the base theme content.
  • Themes are resolved inside the authenticated team only. A theme id belonging to another team is indistinguishable from a non-existent one: both return “Theme not found for this team. Call list-themes first.”

List available fonts

list-fontsthemes:read
Lists every web font a theme can load, with the exact font_picker handle for each family and weight. FirearmCart hosts no font library of its own — fonts come from Google Fonts and only these families resolve. Call it before choosing a typeface from a mockup.
Takes no arguments.
Resultjson
{
  "fonts": [
    {
      "family": "Inter",
      "weights": [
        { "handle": "inter_n4", "weight": 400, "label": "Regular" },
        { "handle": "inter_n7", "weight": 700, "label": "Bold" }
      ]
    },
    {
      "family": "Playfair Display",
      "weights": [{ "handle": "playfair_display_n7", "weight": 700, "label": "Bold" }]
    }
  ],
  "handle_format": "{family_lowercased_with_underscores}_{style}{weight}: `n` = normal, `i` = italic, digit x 100 = weight. Inter 400 is `inter_n4`; Playfair Display 700 is `playfair_display_n7`.",
  "rules": {
    "no_hosted_font_library": "…",
    "never_hardcode_a_family": "…",
    "mockup_typefaces": "…",
    "usage": "…"
  }
}
Caveats
  • Takes no arguments. The catalogue is global (App\Support\GoogleFonts, 25 families) and identical for every team and theme.
  • The failure mode this tool exists to prevent is silent: an unknown family 400s at Google, a 400 yields an EMPTY @font-face rule, and the browser falls back with no error logged anywhere. The page just renders in the wrong typeface.
  • Never write a literal font-family into a section's CSS. Typography is a merchant setting: use the theme's tokens (var(--font-heading--family)) or declare your own {"type":"font_picker","id":"heading_font","default":"inter_n7"} and render it with the font_face / font_url filters. Saves are warned when a hardcoded family is detected.
  • The handle format is fixed, but the family spellings are canonical and case-sensitive — PT Sans, DM Sans and JetBrains Mono cannot be reconstructed by title-casing their handles, which is why the handle string from this response is the only safe value to use.
  • A mockup's typeface is often not in the list. Pick the closest family and tell the user what you substituted rather than hardcoding the original name.

List media

list-mediathemes:read
List the images in the store's media library (the Files page), newest first: each image's media_id for the product, collection and article image tools, and its CDN url for themes. upload-media adds images.

Arguments

searchstringoptional
Case-insensitive substring filter on the media name or filename. Max 255 characters.
media_idstringoptional
One image by its media_id.
sincestringoptional
Only images added on or after this date (YYYY-MM-DD, store timezone), such as ones the merchant just uploaded on the Files page.
limitintegeroptional
Max results, 1–200. Defaults to 50.
offsetintegeroptional
Skip this many results. Defaults to 0.
Example argumentsjson
{
  "search": "hero",
  "limit": 20
}
Resultjson
{
  "media": [
    {
      "media_id": "9b2f6c3e-7d41-4a8e-9c55-1f0e2d3a4b5c",
      "name": "optics-hero",
      "file_name": "optics-hero.jpg",
      "url": "https://cdn.firearmcart.com/media/9812/optics-hero.jpg",
      "thumbnail_url": "https://cdn.firearmcart.com/media/9812/conversions/optics-hero-web_thumb.jpg",
      "mime_type": "image/jpeg",
      "size": 418322,
      "width": 1600,
      "height": 900,
      "source": "ai",
      "added_at": "2026-10-12T09:14:02-05:00"
    }
  ],
  "total": 64,
  "offset": 0,
  "limit": 50,
  "returned": 1,
  "files_page_url": "https://app.firearmcart.com/store/files",
  "usage": "Pass media_id to the product, collection and article image tools. In themes, use `url` verbatim…"
}
Caveats
  • Listed for any product or theme ability, since images serve both the catalog and the storefront.
  • Use `url` verbatim — as an `image_picker` value in `templates/*.json`, or in Liquid via `{{ "<url>" | image_url: width: 1200 }}`. Never invent an asset filename or hotlink a third-party URL.
  • Only the merchant's `web_assets` collection is listed. Product and collection photography is not here; reach it through the catalog image drops instead.
  • `returned` can be lower than `limit` even mid-list: an item whose CDN URL cannot be resolved is dropped from `media` but still counted in `total`. Page with `offset` on `total`, and treat a short page as normal.
  • To add an image, call upload-media with an image the merchant gives you, or ask them to upload it on the Files page (`files_page_url`) and find it here with `since`. Never draw a missing photo as SVG.

List menus

list-menusthemes:read
List the merchant's navigation menus: each one's handle, whether it's the main menu, its items in the form `create-menu` and `update-menu` take, its version, and the links a theme loops over. Storefront navigation is merchant-managed data, not theme content — bind a `link_list` setting to a handle instead of hardcoding links in Liquid.

Arguments

handlestringoptional
Return only this menu. `main-menu` and `main` return the main menu, unless a menu has that handle itself. Omit for every menu.
Example argumentsjson
{
  "handle": "main-menu"
}
Resultjson
{
  "menus": [
    {
      "handle": "main-menu",
      "name": "Main menu",
      "is_active": true,
      "version": "3f9c1a7d2b04",
      "items": [
        { "type": "collection", "label": "Shop", "collection_slug": "all", "url": "/collections/all" },
        {
          "type": "dropdown",
          "label": "Firearms",
          "items": [
            { "type": "product_type", "label": "Handguns", "product_type": "handguns", "url": "/collections/all?filter.p.product_type=handguns" },
            { "type": "collection", "label": "Rifles", "collection_slug": "rifles", "url": "/collections/rifles" }
          ]
        }
      ],
      "links": [
        { "title": "Shop", "url": "/collections/all" },
        {
          "title": "Firearms",
          "url": "#",
          "links": [
            { "title": "Handguns", "url": "/collections/all?filter.p.product_type=handguns" },
            { "title": "Rifles", "url": "/collections/rifles" }
          ]
        }
      ]
    }
  ],
  "generating": null,
  "aliases": {
    "main-menu": "Always resolves to the ACTIVE menu. Use this as the default for a header link_list setting.",
    "main": "Alias of main-menu."
  },
  "usage": "… how to declare a link_list setting and loop section.settings.menu.links …"
}
Caveats
  • `main-menu` (and its alias `main`) always resolves to the ACTIVE menu, which makes it the right `default` for a header `link_list` setting.
  • Declare `{"type": "link_list", "id": "menu", "label": "Menu", "default": "main-menu"}` in the section schema, then loop `section.settings.menu.links` — each link has `title`, `url`, and `links` when it has children. A dropdown's `url` is `#`, and a mega menu's columns are a level of `links` of their own, each holding its links.
  • The stored value is a handle string that the render layer swaps for a menu object, so `linklists[section.settings.menu]` double-resolves and yields nothing. Use the setting directly.
  • `items` is the editable form (see `create-menu`), each link with the `url` it leads to. An item that can't be named that way, such as an old link without a type or an article inside a dropdown, shows as a `link` to its URL. Pass `version` to `update-menu` as `expected_version`.
  • `generating` shows a menu being generated with AI, by `generate-menu` or on the Navigation screen: its name and when it started. It is `null` otherwise.
  • Never copy nav labels out of a mockup screenshot. The merchant owns this list: change it with `update-menu` only when they ask.

List collection filters

list-collection-filtersthemes:read
Lists every specification group the store's catalog can show as a filter on collection pages and search results, with the evidence for choosing which belong in the theme's collection filter allowlist: how many products carry each group, how many checkbox values it renders, its most common values, and the product types it concentrates in. Pair it with set-collection-filters.

Arguments

themestringrequired
theme_id from list-themes. The allowlist is stored per theme, so a library copy and the live theme each carry their own.
searchstringoptional
Only return groups whose name contains this text, case-insensitively. Applied before limit and offset.
limitintegeroptional
Maximum groups to return (1–400). Defaults to 100.
offsetintegeroptional
Skip this many groups, to page past limit. Defaults to 0.
Example argumentsjson
{
  "theme": "9f1c0b2e-7d44-4a1e-9a52-3b8c6d0f1a77"
}
Resultjson
{
  "theme": {
    "theme_id": "9f1c0b2e-7d44-4a1e-9a52-3b8c6d0f1a77",
    "name": "Arsenal",
    "active": true
  },
  "allowlist": {
    "filters": [],
    "state": "No allowlist: every group with renders: true is shown on collection pages and search results.",
    "not_in_catalog": []
  },
  "always_shown": [
    "Availability",
    "Price",
    "Sale",
    "Product type (when a page spans 2+ product types)",
    "In Store (when the catalog uses that spec)"
  ],
  "catalog": {
    "storefront_products": 18412,
    "groups_total": 212,
    "groups_shown_now": 164,
    "groups_matching": 212,
    "offset": 0,
    "returned": 100
  },
  "groups": [
    {
      "name": "Manufacturer",
      "products": 18412,
      "values": 150,
      "values_capped": true,
      "renders": true,
      "shown_now": true,
      "top_values": [
        { "value": "Hornady", "count": 612 },
        { "value": "Federal", "count": 540 },
        { "value": "Magpul", "count": 377 },
        { "value": "SIG SAUER", "count": 301 }
      ],
      "top_product_types": [
        { "type": "ammunition", "products": 2210 },
        { "type": "rifles", "products": 1984 },
        { "type": "handguns", "products": 1102 }
      ]
    },
    {
      "name": "Caliber / Gauge",
      "products": 7630,
      "values": 118,
      "values_capped": false,
      "renders": true,
      "shown_now": true,
      "top_values": [
        { "value": "9mm Luger", "count": 1204 },
        { "value": "5.56 NATO", "count": 688 }
      ],
      "top_product_types": [
        { "type": "ammunition", "products": 2140 },
        { "type": "rifles", "products": 1911 },
        { "type": "handguns", "products": 1086 }
      ]
    },
    {
      "name": "FFL Required",
      "products": 3322,
      "values": 1,
      "values_capped": false,
      "renders": false,
      "shown_now": false,
      "top_values": [{ "value": "Yes", "count": 3322 }],
      "top_product_types": [{ "type": "rifles", "products": 1984 }]
    }
  ],
  "fields": { "products": "…", "values": "…", "values_capped": "…", "renders": "…", "shown_now": "…", "top_values": "…", "top_product_types": "…" },
  "how_to_choose": ["…"]
}
Caveats
  • Group names are exactly what set-collection-filters accepts. Every caliber-type spec — Caliber, Gauge, Caliber/Gauge, Chambering, Cartridge — is merged into the single “Caliber / Gauge” group, just as the storefront merges them into one filter.
  • Groups are sorted by products, most widely carried first, then by name. Category-specific groups (Tube Diameter, Blade Length) therefore sit well below feed plumbing that every product carries: page through with offset, or use search, before concluding a useful group is missing.
  • values is the number of checkboxes the filter renders, read from the same cached aggregation the storefront uses. Calibers are merged into canonical cartridges, but every other spelling counts separately — 1x and 1X are two values because they render as two checkboxes.
  • The aggregation keeps at most 150 values per group, so values_capped: true means “at least 150”. For most groups that marks free text rather than a filter; a brand group on a large catalog is the normal exception.
  • renders: false means the group has fewer than 2 values. It never appears on the storefront, allowlisted or not — flags such as FFL Required are the usual case. shown_now applies the current allowlist on top of that.
  • On the storefront, groups other than Manufacturer and Caliber / Gauge show at most their 50 most common values.
  • Counts cover storefront-visible products across the whole catalog: active, not deleted, and not event listings. They are not per collection. A group only appears on a collection page or search whose products carry it, which is what top_product_types lets you predict.
  • allowlist.not_in_catalog lists saved names that no longer match any group — the spec was renamed, or the products carrying it were removed. Those entries render nothing.
  • Base filters (always_shown) are not part of the allowlist. Nothing on this server can hide them.
  • The per-type breakdown is a catalog-wide aggregation that takes a few seconds on a catalog of tens of thousands of products. It is cached for an hour and evicted whenever products change, so a repeat call is fast.
  • The response carries a how_to_choose checklist written for the agent: what shoppers narrow by per category, how to spot identifiers, free text and feed plumbing, and why to read top_values before choosing.
  • Themes are resolved inside the authenticated team only. A theme id belonging to another team is indistinguishable from a non-existent one: both return “Theme not found for this team. Call list-themes first.”

List pages

list-pagesthemes:read
List the merchant's content pages (about, contact, …) and which template actually renders each one. Call it before editing a secondary page: a page gets its own look from templates/page.{slug}.json, never from editing the shared page.json or the header and footer.

Arguments

themestringrequired
`theme_id` from `list-themes`. Required because the answer depends on which templates that theme actually has.
Example argumentsjson
{
  "theme": "b8d2f0c4-7a91-4f3e-9c65-1d0e2a4b7f88"
}
Resultjson
{
  "pages": [
    {
      "slug": "about",
      "title": "About Us",
      "status": "published",
      "url": "/pages/about",
      "type": "page.about",
      "renders_with": "templates/page.about.json",
      "uses_shared_template": false,
      "template_to_create": null
    },
    {
      "slug": "contact",
      "title": "Contact",
      "status": "published",
      "url": "/pages/contact",
      "type": "page.contact",
      "renders_with": "templates/page.json",
      "uses_shared_template": true,
      "template_to_create": "templates/page.contact.json"
    }
  ],
  "rules": "… five guidance strings on template selection and page chrome, abbreviated …"
}
Caveats
  • A page's template is chosen by its `type` column, NOT its slug. `/pages/{slug}` renders `templates/{type}.json` when that template exists and silently falls back to the shared `templates/page.json` when it does not — which is why `renders_with` is the field to trust, not `type`.
  • `template_to_create` is the whole point of the tool: it names the file to pass to `create-theme-file` for a page that currently borrows the shared template. Creating `templates/page.about.json` while the page's `type` is something else has no effect at all.
  • `templates/page.json` is the fallback for EVERY page without its own template. Restyling one page by editing it changes contact, FAQ and the rest.
  • The `rules` block returned by this tool still claims “MCP cannot edit a page's `type`”. That is stale — `update-page` sets exactly that. Follow the tool, not the note.

List policies

list-policiesthemes:read
List the store policies (privacy, terms, refund, shipping, …) that feed the `shop.policies` drop. Bodies can be long, so this returns a preview by default — pass `policy` to get one policy in full.

Arguments

policystringoptional
Slug of a single policy. Returns its full `content` instead of a preview. Omit to list them all.
Example argumentsjson
{}
Resultjson
{
  "policies": [
    {
      "name": "Privacy Policy",
      "slug": "privacy-policy",
      "url": "/policies/privacy-policy",
      "published": true,
      "content_length": 8421,
      "preview": "We collect only the information needed to fulfil your order and to meet our record…"
    },
    {
      "name": "Shipping Policy",
      "slug": "shipping-policy",
      "url": "/policies/shipping-policy",
      "published": false,
      "content_length": 2140,
      "preview": "All firearms ship to a licensed FFL dealer of your choosing…"
    }
  ],
  "rules": "… four guidance strings: shop.policies, the footer block, 404-on-unpublish, slug stability …"
}
Caveats
  • Two shapes, one tool. Listing returns `content_length` plus a 160-character `preview` of the tag-stripped body; naming a `policy` swaps both for the full `content`.
  • Policies are store data, like menus and pages. Themes read them through the `shop.policies` drop (`title`, `url`, `handle`, `body`) and the stock footer already lists them via its `footer-policy-list` block — never hardcode policy text or links into a section.
  • `published: false` is a draft, not a soft-hide: the policy disappears from `shop.policies` AND `/policies/{slug}` returns 404.
  • A named policy that does not exist is refused with “Policy '…' not found for this team. Call list-policies with no arguments to see them all.”

List plugins and their Liquid surface

list-pluginsthemes:read
Lists the plugins that open theme/Liquid surface — their sections, drops and form endpoints — and whether each is active for this team. Plugin features (reviews, events, subscriptions, back-in-stock) are only buildable when the plugin is ACTIVE, so call this before implementing any of them.

Arguments

liquid_onlybooleanoptional
Keep to the plugins that expose theme surface. Pass false to also list the team's other active plugins, which have nothing to build against. Defaults to true.
Example argumentsjson
{
  "liquid_only": true
}
Resultjson
{
  "plugins": [
    {
      "slug": "product-reviews",
      "name": "Product Reviews",
      "active": true,
      "sections": [
        { "type": "fc-product-reviews", "name": "Product Reviews", "template_only": false }
      ],
      "drops": [
        "product.metafields.reviews.rating.value.rating (float) + .scale_max",
        "product.rating / product.rating_full (pre-rendered star HTML; empty string when no reviews)"
      ],
      "endpoints": ["POST /api/reviews (plain <form>, NOT {% form %}); rejects when the plugin is inactive"],
      "guide": "plugin-liquid → Product Reviews",
      "note": null
    },
    {
      "slug": "events",
      "name": "Events & Classes",
      "active": false,
      "sections": [{ "type": "fc-events-list", "name": "Events", "template_only": false }],
      "drops": ["events (global; up to 24 upcoming — EMPTY ARRAY when the plugin is inactive)"],
      "endpoints": ["POST /events/{handle}/register (plain <form>)"],
      "guide": "plugin-liquid → Events",
      "note": "NOT ACTIVE for this team. Do not build this feature — its data drops return empty and its form endpoints reject. Tell the user to activate 'events' in the plugin marketplace first."
    }
  ],
  "active_slugs": ["product-reviews", "klaviyo"],
  "how_to_use": { "sections": "…", "template_only": "…", "inactive": "…", "recipes": "…" }
}
Caveats
  • Four plugins currently open Liquid surface: product-reviews, events, reload (Subscribe & Save) and klaviyo (back in stock). All four are always returned — read the `active` flag, do not infer activation from presence.
  • An inactive plugin carries a populated `note`; an active one has note: null. active_slugs is the flat list of everything active on the team, including plugins with no theme surface.
  • liquid_only: false appends the team's other active plugins as bare rows (slug, active, sections, note) with no drops/endpoints/guide keys — do not expect a uniform row shape across that response.
  • Plugin sections are not theme files: they are invisible to list-theme-files and must never be created or edited. Reference one by `type` from a page template, exactly like a theme section, and read its settings with get-section-schema.
  • There is no Liquid-visible activation flag (no shop.plugins drop), which is the reason this tool exists. The closest in-theme proxy is events.size > 0, and only for the events plugin.
  • Building a feature whose plugin is inactive ships a widget with no data — the section still renders, its drops are empty and its endpoints reject. Read the `plugin-liquid` resource for the per-feature Liquid recipes.

List blogs

list-blogsthemes:read
List the merchant's storefront blogs with handles and article counts. In Liquid the global `blogs` map is keyed by HANDLE, so these handles are exactly what a theme references. Use `list-articles` for a blog's posts.
Takes no arguments.
Example argumentsjson
{}
Resultjson
{
  "blogs": [
    {
      "title": "News",
      "handle": "news",
      "url": "/blogs/news",
      "is_active": true,
      "articles": 12,
      "published_articles": 9,
      "liquid": "blogs['news']"
    }
  ],
  "liquid": "… four notes: the handle-keyed global, blog/article templates, the double-resolve trap, no global articles map …",
  "note": null
}
Caveats
  • `blogs` is a map keyed by handle: `{% assign blog = blogs['news'] %}`, then `blog.title` / `blog.url` / `blog.articles` / `blog.articles_count`.
  • There is no global `articles` map. Articles are reachable only nested under a blog (`blogs['news'].articles`) or as the page-level `article` drop.
  • The double-resolve trap: a `blog` section setting is already resolved to a blog OBJECT at render, so `blogs[section.settings.blog]` yields nothing. Use `section.settings.blog` directly, or index `blogs` with a literal handle string.
  • `/blogs/{handle}` renders `templates/blog.json` (with `blog.articles` paginated) and `/blogs/{handle}/{article}` renders `templates/article.json`.
  • A team with no blogs gets an empty list plus a `note` saying so. `create-blog` makes one, and `create-article` auto-creates a “News” blog when the team has none.

List articles

list-articlesthemes:read
List blog articles (posts) for the team, newest first. Article bodies are omitted — only the excerpt and metadata come back.

Arguments

blogstringoptional
Blog handle. Omit for every blog in the team.
statusstringoptional
Return only articles in this state. One of: draft, published, scheduled.
limitintegeroptional
Max results, 1–100. Defaults to 50.
Example argumentsjson
{
  "blog": "news",
  "status": "published",
  "limit": 20
}
Resultjson
{
  "articles": [
    {
      "blog": "news",
      "title": "Choosing your first optic",
      "handle": "choosing-your-first-optic",
      "url": "/blogs/news/choosing-your-first-optic",
      "status": "published",
      "published_at": "2026-07-28T14:02:11+00:00",
      "excerpt": "Magnification, reticle and eye relief, without the jargon.",
      "featured_image": "https://cdn.firearmcart.com/media/9812/optics-hero.jpg",
      "author_name": "Dana Whitfield",
      "live": true
    }
  ],
  "note": "Only `published` articles render on the storefront. `scheduled` flips to published by cron once its date passes."
}
Caveats
  • There is no way to read an article's body over MCP. The server's own advertised description tells clients to “use read-article”, but no such tool is registered — `excerpt` is all you get.
  • Only `published` articles render on the storefront; `live` restates that per row. A `scheduled` article flips to published by cron once its date passes.
  • Ordering is `published_at DESC, id DESC`, so drafts and scheduled posts (no publish date) sort to the top.
  • An unknown blog handle is refused with “Blog '…' not found for this team. Call list-blogs.” A team with no blogs at all returns an empty list and a `note` instead of an error.

Screenshot a theme

screenshot-themethemes:read
Screenshot a theme preview template at one or more viewports (desktop/tablet/mobile). Captures the FULL scrollable page by default. Runs synchronously (multi-viewport is slow). Returns inline JPEG images plus CDN URLs that expire after ~7 days. Prefer only the viewports needed per iteration.

Arguments

themestringrequired
theme_id from list-themes.
templatestringoptional
Page template name, with or without its extension — index, product, collection, page, page.contact, blog, article, cart, search, 404, … Validated against this theme's own template rows; an unknown name returns the valid list. Defaults to "index".
pagestringoptional
Page slug (e.g. about-us) for a page template. REQUIRED to see real content on the shared `page` template — without it that template previews as an empty stub. Slugs come from list-pages.
productstringoptional
Product slug or id for the product template. Without it the preview picks a RANDOM product, or placeholder data on an empty catalog.
collectionstringoptional
Collection slug or id for the collection template. Without it the preview picks a random collection.
blogstringoptional
Blog handle for the blog or article template. Defaults to the first blog. Handles come from list-blogs.
articlestringoptional
Article handle for the article template. Defaults to the newest article. Handles come from list-articles.
viewportsarray<string>optional
Viewports to capture, at most three. desktop is 1440×900, tablet 768×1024 at 2× DPR, mobile 390×844 at 3× DPR. Duplicates are collapsed. One of: desktop, tablet, mobile. Defaults to ["desktop"].
full_pagebooleanoptional
Capture the whole scrollable page. Set false for just the above-the-fold viewport — faster, but you cannot diff the rest of the page against a mockup. Defaults to true.
delay_msintegeroptional
Extra wait after network idle, in milliseconds. Accepted range 0–15000. Defaults to 2000.
Example argumentsjson
{
  "theme": "c40b9e18-77a5-4f36-8d21-2a9f0be4c153",
  "template": "index",
  "viewports": ["desktop", "mobile"],
  "full_page": true
}
Resulttext
[image/jpeg, image/jpeg, then a text block:]

{
  "screenshots": [
    {
      "viewport": "desktop",
      "width": 1440,
      "height": 900,
      "actual_width": 1440,
      "actual_height": 6820,
      "url": "https://cdn.firearmcart.com/mcp-previews/c40b9e18…/index-desktop-1770000000.jpg"
    },
    {
      "viewport": "mobile",
      "width": 390,
      "height": 844,
      "actual_width": 1170,
      "actual_height": 28440,
      "url": "https://cdn.firearmcart.com/mcp-previews/c40b9e18…/index-mobile-1770000000.jpg",
      "inline_omitted": true,
      "inline_omitted_reason": "Full-page image exceeds 1.5MB so it could not be returned inline — you cannot see it. Retry this viewport with full_page: false to get an inline above-the-fold capture, or open the url."
    }
  ],
  "preview_url": "https://firearmcart.com/themes/preview/c40b9e18…?screenshot=true",
  "note": "Screenshot CDN URLs expire after ~7 days. Dimensions include logical viewport and actual image size."
}
Caveats
  • **The only tool in this group a `themes:read` token can call.** It does not check write ability and is always registered — but note it is annotated idempotent rather than read-only, unlike the other read tools on this server, because each call re-renders and uploads a fresh capture.
  • **The inline JPEG is the point.** MCP hands the image to the model as base64, which is how it sees the render. A bare preview URL is invisible to a model, so the mockup-diff loop depends on the inline image landing.
  • An image over 1.5 MB is dropped from the inline payload and the entry says so — retry that viewport with `full_page: false` for an above-the-fold capture you can actually see. Mobile is most at risk, since it is captured at 3× DPR.
  • Subjects are team-scoped and a bad handle **fails loudly** (`Page 'x' not found for this team. See list-pages.`) rather than silently falling back to a random one, which would have you reviewing the wrong page and thinking it passed.
  • A subject argument that does not apply to the chosen template is an error, not a no-op: ``product`` on a `page` template returns *`product` does not apply to the 'page' template.*
  • Two soft warnings ride along in the response instead of failing: the shared `page` template rendered with no `page` slug previews as an EMPTY stub (which reads as a broken theme but is not), and a `product` template with no `product` uses a random one.
  • `page.{slug}`-style templates derive their subject from the suffix, so they need no argument.
  • If every requested viewport fails, the error still carries `preview_url` plus a note that screenshot rendering is broken on the host, not necessarily the theme — keep editing and open the URL in a browser rather than hunting for a Liquid error. A partial failure returns the captures that worked plus a `failures` list.
  • Captures land in `mcp-previews/{theme_uuid}/` on the CDN; URLs expire after roughly 7 days and old shots are pruned, so do not treat them as durable links.
  • Library (inactive) themes preview by UUID without being published, which is what makes the duplicate-then-screenshot loop safe.

Update theme file

update-theme-filethemes:writemutates
Update an existing theme file. To change part of a file, prefer edits: find-and-replace pairs whose find text you copy exactly from read-theme-file. Use content only to rewrite the whole file. The new content is validated (Liquid/JSON/schema), versioned, and cache-invalidated. Use restore-file-version to revert. Refuses the active (published) theme unless allow_active=true.

Arguments

themestringrequired
theme_id from list-themes.
pathstringrequired
Theme path to an existing file, e.g. templates/index.json. Unknown paths return `File not found: {path}`.
contentstringoptional
The whole new file, for a full rewrite. Send `content` or `edits`, not both. An empty string is accepted for most files but is refused on a JSON page template.
editsarray<object>optional
{ find, replace } pairs, applied in order to the file's current content: the way to change part of an existing file without sending all of it. Copy each `find` exactly from read-theme-file, whitespace and indentation included; it must match exactly one place. An empty `replace` deletes the text.
allow_activebooleanoptional
Set true ONLY if the user explicitly asked to edit the live (active) theme. Otherwise duplicate-theme and edit the copy. Defaults to false.
allow_chromebooleanoptional
Allow writing GLOBAL chrome (header-group/footer-group and the sections they render — these appear on EVERY page). True when recreating a whole theme or homepage from a mockup, or when the user asked to change the site-wide header/footer. Building ONE secondary page whose mockup shows different chrome: do not set it, ask the user first. Defaults to false.
Example argumentsjson
{
  "theme": "8f3c1a72-4d90-4e51-9b2e-6c0a55d1e7bb",
  "path": "templates/index.json",
  "edits": [
    { "find": "\"heading\": \"Shop rifles\"", "replace": "\"heading\": \"Shop pistols\"" },
    { "find": "\"collection\": \"new-arrivals\"", "replace": "\"collection\": \"pistols\"" }
  ]
}
Resultjson
{
  "saved": true,
  "path": "templates/index.json",
  "version_number": 7,
  "warnings": [
    "Kept 2 setting(s) you sent as null, because the merchant has set them in the visual editor: hero.image, featured.background_image. A null in a theme file means \"not specified\", not \"clear it\" …"
  ],
  "note": "Use restore-file-version to revert if needed."
}
Caveats
  • **Send `content` or `edits`, not both.** `content` replaces the whole file. `edits` changes part of it: each `find` is replaced by its `replace`, in order, on the file as the edits before it leave it, and must match exactly one place. A `find` that matches nowhere or more than once refuses the whole call — *Edit 2 of 3: its find text was not found in sections/hero.liquid. Nothing was saved. …* or *Edit 1 of 1: its find text was found 3 times in sections/hero.liquid, but it must match exactly one place. …* — so fix that edit and send them all again. The edited file then goes through the same validation, versioning and guards as `content`.
  • Saves are validated before anything is written. Liquid goes through the theme renderer, JSON page templates are decoded after the leading `/* … */` comment header is stripped, and a section or block carrying a `{% schema %}` must have schema JSON that parses. A failure returns *Validation failed, file NOT saved: {parser error}* and the file is untouched — fix and retry.
  • Every successful save records a version (label `MCP save`) and returns its `version_number`. `restore-file-version` takes you back.
  • Writes to the ACTIVE (published) theme are refused unless `allow_active: true`.
  • **Global chrome is gated, not forbidden.** The guard only fires for `sections/*` paths that `header-group` or `footer-group` actually renders. The refusal states both branches and makes you choose: recreating a whole theme or homepage — retry the same call with `allow_chrome: true`, do NOT respond by skipping the header/footer; building one secondary page — stop and ask the user, because this changes every page to match one page's mockup.
  • Only text assets are updatable: `css`, `js`, `json`, `svg`, plus `.css.liquid` / `.js.liquid`. Anything else returns *Only text assets (css/js/json/.css.liquid/.js.liquid) can be updated via MCP.*
  • A JSON page template's identity is inferred from its **content**, because `template_name` carries no extension. Saving Liquid (or nothing) into `templates/x.json` would silently retype it to `templates/x.liquid` and stop the theme rendering its sections, so that save is refused outright.
  • **A `null` you send never erases a merchant's setting.** `read-theme-file` returns the FILE, where an `image_picker` reads `"image": null`, while the merchant's picked value lives in the theme settings. The merge treats `null` as "not specified" and keeps what they set, then tells you which keys it kept. Do not try to force the null through with `""` or `"none"` — you would be deleting a photo you cannot see.
  • `warnings` are non-blocking and worth reading: duplicate header/footer, a section that fights `header-group`/`footer-group`, hardcoded nav with no `link_list` setting, a whole page crammed into one section, hand-drawn SVG artwork, a missing mobile hamburger, dead search, a footer that dropped `powered_by_link`, a hardcoded page container, or a font family outside the Google catalogue.
  • After a successful save the tool recompiles affected CSS/JS bundles, folds JSON page templates into the theme's live settings, and invalidates theme and preview caches. Failures in those post-save steps surface as `warnings`, not as a failed save.
  • Registered only for tokens that hold `themes:write`.

Create theme file

create-theme-filethemes:writemutates
Create a new theme file at a theme path. Directory whitelist is enforced server-side. Optional content is validated on create. Refuses the active (published) theme unless allow_active=true.

Arguments

themestringrequired
theme_id from list-themes.
pathstringrequired
Theme path, e.g. sections/hero-banner.liquid. The first segment must be one of layout, layouts, templates, sections, snippets, blocks or assets.
contentstringoptional
Initial file content. Omit it to create an empty file; when present it is validated before the row is created. Defaults to "".
allow_activebooleanoptional
Set true ONLY if the user explicitly asked to edit the live (active) theme. Otherwise duplicate-theme and edit the copy. Defaults to false.
Example argumentsjson
{
  "theme": "8f3c1a72-4d90-4e51-9b2e-6c0a55d1e7bb",
  "path": "sections/hero-banner.liquid",
  "content": "<section class=\"section section--{{ section.settings.section_width }}\">\n  <h1>{{ section.settings.heading }}</h1>\n</section>\n\n{% schema %}\n{\n  \"name\": \"Hero banner\",\n  \"settings\": [\n    { \"type\": \"text\", \"id\": \"heading\", \"label\": \"Heading\", \"default\": \"Shop rifles\" },\n    { \"type\": \"select\", \"id\": \"section_width\", \"label\": \"Width\", \"options\": [{ \"value\": \"page-width\", \"label\": \"Page\" }, { \"value\": \"full-width\", \"label\": \"Full\" }], \"default\": \"page-width\" }\n  ],\n  \"presets\": [{ \"name\": \"Hero banner\" }]\n}\n{% endschema %}"
}
Resultjson
{
  "created": true,
  "path": "sections/hero-banner.liquid"
}
Caveats
  • Only the whitelisted top-level directories resolve: `layout/` (`layouts/` is accepted as an alias), `templates/`, `sections/`, `snippets/`, `blocks/`, `assets/`. Anything else — or a path containing `..` — returns *Invalid path. Use theme paths like sections/hero.liquid or templates/index.json.*
  • Nesting is allowed only under `templates/` (e.g. `templates/customers/account.json`). A nested section, snippet, block or layout is refused, and `assets/` may never be nested.
  • Each path segment must match `[a-zA-Z0-9_-]` plus periods. Templates must end `.liquid` or `.json`; assets must end `.css`, `.css.liquid`, `.js`, `.js.liquid`, `.json` or `.svg`.
  • **Raster images cannot be created.** `content` is a string, so `assets/hero.png` is rejected before any write: *Binary assets (png/jpg/webp/fonts) must be uploaded through the theme import or media library, not the file editor.* SVG is the one image format authorable here — and only for icons; name them `icon-*.svg` or the save warns.
  • `assets/*.css.liquid` and `assets/*.js.liquid` are stored with `asset_type` css and js respectively, so they compile like their plain counterparts.
  • A file that already exists in that category is refused (*A file with this name already exists in this category.* / *An asset with this name already exists.*) — use update-theme-file instead.
  • Content is validated before the row is inserted, and if the save fails afterwards the row is deleted, so a failed create never leaves an orphan you must clean up before retrying.
  • The first version snapshot is labelled `Baseline` and holds the content **as created**, not the empty row it was inserted as — so restoring to version 1 returns the file to what you first wrote rather than blanking it.
  • Writes to the ACTIVE (published) theme are refused unless `allow_active: true`; the error tells you to call duplicate-theme and edit the copy.
  • **No `allow_chrome` argument.** Unlike update / delete / restore, this tool does not run the global-chrome gate — creating `sections/header-group.liquid` on a theme that lacks one is not speed-bumped. THEME_MCP.md claims all four file-write tools gate chrome; only three do.
  • `warnings` is omitted from the response when empty (the payload is `array_filter`ed). When present it carries the same non-blocking structural warnings as update-theme-file.
  • Registered only for tokens that hold `themes:write`. A read-only token does not see this tool in `tools/list` at all.

Delete theme file

delete-theme-filethemes:writemutates
Delete a user-created theme file. Base theme files (original_content set / is_base_theme assets) cannot be deleted. Refuses the active (published) theme unless allow_active=true.

Arguments

themestringrequired
theme_id from list-themes.
pathstringrequired
Theme path to an existing file. Unknown paths return `File not found: {path}`.
allow_activebooleanoptional
Set true ONLY if the user explicitly asked to edit the live (active) theme. Otherwise duplicate-theme and edit the copy. Defaults to false.
allow_chromebooleanoptional
Allow deleting GLOBAL chrome (header-group/footer-group and the sections they render — these appear on EVERY page). True only when rebuilding the site-wide header/footer; false when working on one page. Defaults to false.
Example argumentsjson
{
  "theme": "8f3c1a72-4d90-4e51-9b2e-6c0a55d1e7bb",
  "path": "sections/hero-banner-old.liquid"
}
Resultjson
{
  "deleted": true,
  "path": "sections/hero-banner-old.liquid"
}
Caveats
  • The only tool on this server annotated destructive, so an MCP client may prompt before running it.
  • **Base theme files cannot be deleted.** A template that still carries `original_content` returns *Cannot delete base theme files. You can only delete files you created (original_content is null).*, and an asset with `is_base_theme` returns the asset equivalent. Only files you or the merchant created are removable.
  • Deletion also removes the file's entire version history, so there is nothing left to restore-file-version afterwards. Prefer emptying or superseding a file you are unsure about.
  • Writes to the ACTIVE (published) theme are refused unless `allow_active: true`, and the same global-chrome gate as update-theme-file applies to `sections/*` paths a group renders.
  • For assets the stored file is deleted first, but a storage failure does not abort the delete — the row and its versions still go, and the response is still `deleted: true`.
  • Theme caches are invalidated after the delete; a failure there is swallowed rather than reported.
  • Registered only for tokens that hold `themes:write`.

Restore a file version

restore-file-versionthemes:writemutates
Restore a file to a previous version_number. Commits immediately (snapshots current content first). Validation still applies. Refuses the active (published) theme unless allow_active=true.

Arguments

themestringrequired
theme_id from list-themes.
pathstringrequired
Theme path to an existing file. Unknown paths return `File not found: {path}`.
version_numberintegerrequired
Version to restore, minimum 1. Get the list from list-file-versions; a number the file does not have returns `Version {n} not found.`
allow_activebooleanoptional
Set true ONLY if the user explicitly asked to edit the live (active) theme. Otherwise duplicate-theme and edit the copy. Defaults to false.
allow_chromebooleanoptional
Allow restoring GLOBAL chrome (header-group/footer-group and the sections they render — these appear on EVERY page). True when rolling back a site-wide header/footer you are rebuilding; false when working on one page. Defaults to false.
Example argumentsjson
{
  "theme": "8f3c1a72-4d90-4e51-9b2e-6c0a55d1e7bb",
  "path": "sections/hero-banner.liquid",
  "version_number": 3
}
Resultjson
{
  "restored": true,
  "path": "sections/hero-banner.liquid",
  "restored_from_version": 3,
  "version_number": 9,
  "warnings": []
}
Caveats
  • There is no preview or confirmation step — the restore commits on the call.
  • It runs through the same save pipeline as update-theme-file (label `MCP restore`), so the current content is snapshotted as a **new** version first. The restore is therefore itself undoable: the response returns both `restored_from_version` and the new `version_number`.
  • Validation still applies. If the old content no longer parses against the current theme, the response is *Restore validation failed, file NOT changed: {parser error}* and nothing moves.
  • Version 1 is the `Baseline` — for a file created through create-theme-file that is the content as first written, not an empty file.
  • Writes to the ACTIVE (published) theme are refused unless `allow_active: true`, and the same global-chrome gate as update-theme-file applies to `sections/*` paths a group renders.
  • `warnings` behaves as on a normal save: restoring old content can re-introduce a structural warning that was fixed since.
  • Registered only for tokens that hold `themes:write`.

Create page

create-pagethemes:writemutates
Create a content page (about, FAQ, …) served at /pages/{slug}. The page's `template` names the theme template that renders it, so create that template too or the page falls back to the shared page.json.

Arguments

titlestringrequired
Page title. 3–255 characters.
slugstringoptional
URL slug, slugified before use. Defaults to a slug of the title.
templatestringoptional
Template that renders this page, e.g. `page.about`. Use `page` for the shared default layout. Defaults to page.{slug}.
contentstringoptional
Page body (HTML). Defaults to "" (empty).
statusstringoptional
Whether the page is live on the storefront. One of: published, draft. Defaults to published.
seo_titlestringoptional
SEO title. Max 255 characters.
seo_descriptionstringoptional
SEO meta description. Max 500 characters.
Example argumentsjson
{
  "title": "About Us",
  "slug": "about",
  "template": "page.about",
  "content": "<p>Family owned since 1998.</p>",
  "status": "published"
}
Resultjson
{
  "created": true,
  "page": {
    "slug": "about",
    "title": "About Us",
    "status": "published",
    "url": "/pages/about",
    "template": "page.about"
  },
  "next_step": "Now create templates/page.about.json with create-theme-file. Until it exists, this page renders with the shared templates/page.json."
}
Caveats
  • Creating the page is only half the job. The response's `next_step` names the template file to create with `create-theme-file`; until it exists the page renders with the shared `templates/page.json`.
  • Slugs are unique per team. An existing slug is refused with “A page with slug '…' already exists. Use update-page to change it.”
  • A title that slugifies to nothing (and no explicit `slug`) is refused with “Could not derive a slug from the title. Pass an explicit slug.”
  • Store data, not theme content: there is no `allow_active` guard here. The write hits the live storefront immediately, even when you are building inside an inactive draft theme.
  • Requires `themes:write`. A token without it never sees this tool in `tools/list` (`shouldRegister()`), and a direct call is refused with “This token lacks themes:write.”

Update page

update-pagethemes:writemutates
Update a content page — most importantly, point it at a different template. A page renders with templates/{template}.json, so a page stuck on the shared `page` template needs its template changed here before a dedicated layout takes effect.

Arguments

slugstringrequired
Slug of the page to update, from `list-pages`. Slugified before lookup.
themestringoptional
Theme id or UUID. Optional, but pass it: it is the only way the tool can check the target template exists and warn you when it does not.
templatestringoptional
Template that renders this page, e.g. `page.about`. Use `page` for the shared default.
titlestringoptional
New title. 3–255 characters.
contentstringoptional
New page body (HTML). Replaces the existing body.
statusstringoptional
Whether the page is live on the storefront. One of: published, draft.
seo_titlestringoptional
SEO title. Max 255 characters.
seo_descriptionstringoptional
SEO meta description. Max 500 characters.
Example argumentsjson
{
  "slug": "contact",
  "theme": "b8d2f0c4-7a91-4f3e-9c65-1d0e2a4b7f88",
  "template": "page.contact"
}
Resultjson
{
  "updated": true,
  "page": {
    "slug": "contact",
    "title": "Contact",
    "status": "published",
    "url": "/pages/contact",
    "template": "page.contact"
  },
  "warnings": [
    "templates/page.contact.json does not exist in this theme yet, so the page still renders with the shared templates/page.json. Create it with create-theme-file."
  ]
}
Caveats
  • This is the only way to move a page off the shared `page` template. Writing `templates/page.{slug}.json` alone does nothing — the template is picked by the page's `type`.
  • Pass `theme` to get the guardrail. With it, a template that does not exist in that theme yet returns a `warnings` entry rather than letting you believe the new layout is live; without it, the retarget is applied blind.
  • A call that carries no updatable field is refused with “Nothing to update. Pass at least one of: template, title, content, status, seo_title, seo_description.”
  • An unknown slug is refused with “Page '…' not found for this team. Call list-pages.”
  • Not versioned. `list-file-versions` and `restore-file-version` only cover theme files, so this overwrite has no undo.
  • Requires `themes:write`. A token without it never sees this tool in `tools/list` (`shouldRegister()`), and a direct call is refused with “This token lacks themes:write.”

Create policy

create-policythemes:writemutates
Create a store policy (privacy, terms, refund, shipping, …) served at /policies/{slug} and exposed to themes as `shop.policies`. The slug is derived from the name and is permanent — renaming later will not change it.

Arguments

namestringrequired
Policy name, e.g. “Privacy Policy”. Becomes the slug and the link text in the footer. 3–255 characters.
contentstringrequired
Policy body (HTML).
slugstringoptional
URL slug override, slugified before use. Defaults to a slug of the name, de-duplicated within the team.
publishedbooleanoptional
`true` = live at /policies/{slug} and listed in `shop.policies`. `false` = draft: the URL 404s and it is hidden from the footer. Defaults to true.
Example argumentsjson
{
  "name": "Shipping Policy",
  "content": "<h2>Shipping</h2><p>All firearms ship to a licensed FFL dealer of your choosing.</p>",
  "published": true
}
Resultjson
{
  "created": true,
  "policy": {
    "name": "Shipping Policy",
    "slug": "shipping-policy",
    "url": "/policies/shipping-policy",
    "published": true
  },
  "note": "Themes reach this through the `shop.policies` drop, and the stock footer already lists it via its `footer-policy-list` block. Do not add a hardcoded link to it in a section."
}
Caveats
  • The slug is set once, at creation, and never regenerated on update. Pick it deliberately — a later rename keeps the original URL.
  • An explicit `slug` already taken by this team is refused with “A policy with slug '…' already exists for this team. Use update-policy to change it.” An auto-derived slug is de-duplicated instead, gaining a `-2` suffix.
  • An explicit `slug` that slugifies to nothing is refused with “The slug given does not reduce to anything usable. Omit it to derive one from the name.”
  • Store data, not theme content: there is no `allow_active` guard here. The write hits the live storefront immediately, even when you are building inside an inactive draft theme.
  • Requires `themes:write`. A token without it never sees this tool in `tools/list` (`shouldRegister()`), and a direct call is refused with “This token lacks themes:write.”

Update policy

update-policythemes:writemutates
Update a store policy: rewrite its body, rename it, or publish and unpublish it. The slug never changes, so /policies/{slug} keeps working after a rename.

Arguments

policystringrequired
Slug of the policy to update, from `list-policies`.
namestringoptional
New name. Does NOT change the slug — the URL stays as it was. 3–255 characters.
contentstringoptional
New body (HTML). Replaces the existing body outright.
publishedbooleanoptional
`true` = live at /policies/{slug} and listed in `shop.policies`. `false` = draft: the URL 404s and it is hidden from the footer.
Example argumentsjson
{
  "policy": "privacy-policy",
  "name": "Privacy Notice"
}
Resultjson
{
  "updated": true,
  "policy": {
    "name": "Privacy Notice",
    "slug": "privacy-policy",
    "url": "/policies/privacy-policy",
    "published": true
  },
  "warnings": [
    "Renamed, but the slug is unchanged by design: this policy still lives at /policies/privacy-policy. Existing links keep working."
  ]
}
Caveats
  • Read the `warnings` array. A rename returns one stating the URL did not move, and unpublishing returns one stating that `/policies/{slug}` now 404s and the policy has left `shop.policies`, so the footer no longer links it.
  • `content` replaces the body outright — there is no patch or append mode. Fetch the current text with `list-policies` first if you mean to edit rather than replace.
  • A call that carries no updatable field is refused with “Nothing to update. Pass at least one of: name, content, published.”
  • An unknown slug is refused with “Policy '…' not found for this team. Call list-policies.”
  • Not versioned. `list-file-versions` and `restore-file-version` only cover theme files, so this overwrite has no undo.
  • Requires `themes:write`. A token without it never sees this tool in `tools/list` (`shouldRegister()`), and a direct call is refused with “This token lacks themes:write.”

Create blog

create-blogthemes:writemutates
Create a storefront blog — a container for articles — at /blogs/{handle}. Most stores need only one, so check `list-blogs` first. In Liquid it is reachable as blogs['{handle}'].

Arguments

titlestringrequired
Blog title, e.g. “News”. 2–255 characters.
handlestringoptional
URL handle, max 100 characters. Defaults to a slug of the title; de-duplicated within the team.
Example argumentsjson
{
  "title": "News",
  "handle": "news"
}
Resultjson
{
  "created": true,
  "blog": {
    "title": "News",
    "handle": "news",
    "url": "/blogs/news"
  },
  "liquid": "blogs['news']",
  "next_step": "Add articles with create-article. The theme renders /blogs/{handle} via templates/blog.json and each post via templates/article.json."
}
Caveats
  • Handles are de-duplicated inside the team, including one you pass explicitly — a collision quietly becomes `news-2` rather than erroring, so read the `handle` in the response instead of assuming the one you asked for.
  • A title that slugifies to nothing is refused with “Could not derive a handle from that title. Pass an explicit `handle`.”
  • Blogs are created active. There is no tool to rename, deactivate or delete one — that is dashboard-only.
  • Store data, not theme content: there is no `allow_active` guard here. The write hits the live storefront immediately, even when you are building inside an inactive draft theme.
  • Requires `themes:write`. A token without it never sees this tool in `tools/list` (`shouldRegister()`), and a direct call is refused with “This token lacks themes:write.”

Create article

create-articlethemes:writemutates
Create a blog article (post). `content` is HTML and is required. Only status=published renders on the storefront; scheduled needs a future `scheduled_at`.

Arguments

titlestringrequired
Article title. Max 255 characters.
contentstringrequired
Article body (HTML). Required — an article cannot be created without it.
blogstringoptional
Blog handle. Defaults to the team's only blog, or creates a “News” blog when the team has none.
handlestringoptional
URL handle, max 100 characters. Defaults to a slug of the title; de-duplicated within the blog.
excerptstringoptional
Short summary. Max 500 characters.
statusstringoptional
Publication state. Only `published` renders on the storefront. One of: draft, published, scheduled. Defaults to draft.
scheduled_atstringoptional
ISO-8601 datetime (UTC). Required, and must be in the future, when `status` is `scheduled`.
author_namestringoptional
Byline. Max 255 characters.
tagsarray<string>optional
Tag NAMES, not ids. Each name is resolved to a team-scoped tag, created if missing.
featured_image_media_idstringoptional
A `media_id` from `list-media` or `upload-media` for the featured image.
featured_imagestringoptional
Or the image URL taken verbatim from `list-media`. Must be one of the team's own uploads.
featured_image_altstringoptional
Alt text for the featured image. Max 255 characters.
meta_titlestringoptional
SEO title. Max 70 characters.
meta_descriptionstringoptional
SEO description. Max 160 characters.
Example argumentsjson
{
  "blog": "news",
  "title": "Range bag essentials",
  "content": "<p>Six things worth carrying, and two that are not.</p>",
  "excerpt": "Six things worth carrying, and two that are not.",
  "status": "published",
  "author_name": "Dana Whitfield",
  "tags": ["gear", "beginners"],
  "featured_image": "https://cdn.firearmcart.com/media/9812/optics-hero.jpg"
}
Resultjson
{
  "created": true,
  "article": {
    "blog": "news",
    "title": "Range bag essentials",
    "handle": "range-bag-essentials",
    "url": "/blogs/news/range-bag-essentials",
    "status": "published",
    "published_at": "2026-08-11T09:15:00+00:00"
  },
  "live": true,
  "note": null
}
Caveats
  • Omitting `blog` is only safe when the team has exactly one. With several, the call is refused with “This team has several blogs (…). Pass `blog` to say which one.” With none, a “News” blog is created silently, mirroring the dashboard.
  • The default status is `draft`, so a bare create publishes nothing. The response says so in `note`: “This article is NOT on the storefront yet — only status=published renders.”
  • `status: "scheduled"` requires `scheduled_at`, and it must parse as ISO-8601 and be in the future — a past date is refused with “`scheduled_at` must be in the future. To publish now, use status “published”.” A cron flips scheduled articles to published once the date passes.
  • Publishing always stamps a date. `published_at` is nullable but the blog listing orders by `published_at DESC`, and the database sorts NULLs first — an undated published article would pin itself to the top of the blog forever.
  • `tags` takes tag NAMES, not ids. Missing tags are created, and every tag is resolved inside the authenticated team (the dashboard syncs raw ids without an ownership check; this path deliberately does not).
  • `featured_image` must be a URL returned verbatim by `list-media`. Any other URL is refused — the column is a plain string, so an unchecked value would let an article hotlink anything. MCP cannot upload images.
  • A title that slugifies to nothing is refused with “Could not derive a handle from that title. Pass an explicit `handle`.”
  • Store data, not theme content: there is no `allow_active` guard here. The write hits the live storefront immediately, even when you are building inside an inactive draft theme.
  • Requires `themes:write`. A token without it never sees this tool in `tools/list` (`shouldRegister()`), and a direct call is refused with “This token lacks themes:write.”

Update article

update-articlethemes:writemutates
Update a blog article: edit its body, change or remove its featured image, or publish, unpublish and schedule it. Publishing always stamps a date, because an undated published article would pin itself to the top of the blog.

Arguments

articlestringrequired
Article handle, from `list-articles`.
blogstringoptional
Blog handle. Required only when the same article handle exists in more than one of the team's blogs.
titlestringoptional
New title. Does NOT change the handle. Max 255 characters.
contentstringoptional
New body (HTML). Replaces the existing body.
excerptstringoptional
Short summary. Max 500 characters.
statusstringoptional
Publication state. Only `published` renders on the storefront. One of: draft, published, scheduled.
scheduled_atstringoptional
ISO-8601 datetime (UTC). Required, and must be in the future, when `status` is `scheduled`.
author_namestringoptional
Byline. Max 255 characters.
tagsarray<string>optional
Tag NAMES. Replaces the existing set outright — an empty array clears every tag.
featured_image_media_idstringoptional
A `media_id` from `list-media` or `upload-media` for the featured image.
featured_imagestringoptional
Or the image URL taken verbatim from `list-media`. `null` or `""` removes the featured image.
featured_image_altstringoptional
Alt text. Max 255 characters. `null` or `""` clears it.
meta_titlestringoptional
SEO title. Max 70 characters.
meta_descriptionstringoptional
SEO description. Max 160 characters.
Example argumentsjson
{
  "article": "range-bag-essentials",
  "blog": "news",
  "status": "published"
}
Resultjson
{
  "updated": true,
  "article": {
    "blog": "news",
    "title": "Range bag essentials",
    "handle": "range-bag-essentials",
    "url": "/blogs/news/range-bag-essentials",
    "status": "published",
    "published_at": "2026-08-11T09:15:00+00:00"
  },
  "live": true
}
Caveats
  • Re-publishing preserves the original `published_at` rather than stamping a new one, so toggling an old post back to published does not jump it to the top of the blog.
  • An article whose stored `published_at` is in the future cannot be published directly — the call is refused and tells you to use `status: "scheduled"` instead.
  • The article is looked up across every blog in the team. A handle that exists in several is refused with “Several blogs have an article '…' (…). Pass `blog` to disambiguate.”
  • Changing `title` never changes the handle, so the URL is stable. There is no tool to re-handle or delete an article.
  • Saved changes, the featured image included, reach the storefront within a minute.
  • `status: "scheduled"` requires `scheduled_at`, and it must parse as ISO-8601 and be in the future — a past date is refused with “`scheduled_at` must be in the future. To publish now, use status “published”.” A cron flips scheduled articles to published once the date passes.
  • Publishing always stamps a date. `published_at` is nullable but the blog listing orders by `published_at DESC`, and the database sorts NULLs first — an undated published article would pin itself to the top of the blog forever.
  • `tags` takes tag NAMES, not ids. Missing tags are created, and every tag is resolved inside the authenticated team (the dashboard syncs raw ids without an ownership check; this path deliberately does not).
  • `featured_image` must be a URL returned verbatim by `list-media`. Any other URL is refused — the column is a plain string, so an unchecked value would let an article hotlink anything. MCP cannot upload images.
  • A call that carries no updatable field (and no `tags`) is refused with “Nothing to update. Pass at least one field.”
  • Not versioned. `list-file-versions` and `restore-file-version` only cover theme files, so this overwrite has no undo.
  • Requires `themes:write`. A token without it never sees this tool in `tools/list` (`shouldRegister()`), and a direct call is refused with “This token lacks themes:write.”

Create a menu

create-menuthemes:writemutates
Create a navigation menu in Store > Navigation. Each item names what it links to — a collection, product type, specification filter, product, page, policy, blog, article or event of the store — and the tool builds the URL, so a link can't lead anywhere that doesn't exist. The storefront doesn't change unless `set_active` makes it the main menu.

Arguments

namestringrequired
The menu's name in Store > Navigation. Refused when another menu already has it, in any letter case.
itemsarray<object>optional
The menu's items, in order. See the notes for each type's fields. Leave out for an empty menu.
set_activebooleanoptional
Make it the main menu, shown in the storefront's header in place of the current one. Refused for a menu with no items.
dry_runbooleanoptional
Check the items and return the menu as it would be saved, without saving it.
Example argumentsjson
{
  "name": "Holiday menu",
  "items": [
    { "type": "collection", "label": "Gift Ideas", "collection_slug": "accessories" },
    {
      "type": "mega_menu",
      "label": "Ammunition",
      "categories": [
        {
          "name": "Handgun",
          "items": [
            { "type": "specification", "label": "9mm", "spec_name": "Caliber", "spec_value": "9mm", "spec_collection_slug": "ammunition" },
            { "type": "specification", "label": ".45 ACP", "spec_name": "Caliber", "spec_value": "45 ACP", "spec_collection_slug": "ammunition" }
          ]
        },
        {
          "name": "Rifle",
          "items": [
            { "type": "specification", "label": "5.56 NATO", "spec_name": "Caliber", "spec_value": "5.56 NATO", "spec_collection_slug": "ammunition" }
          ]
        }
      ]
    },
    { "type": "page", "label": "Contact", "page_slug": "contact" }
  ]
}
Resulttext
{
  "status": "created",
  "menu": {
    "handle": "holiday-menu",
    "name": "Holiday menu",
    "is_active": false,
    "version": "8d21e4c0b97a",
    "items": [
      { "type": "collection", "label": "Gift Ideas", "collection_slug": "accessories", "url": "/collections/accessories" },
      {
        "type": "mega_menu",
        "label": "Ammunition",
        "categories": [
          {
            "name": "Handgun",
            "items": [
              { "type": "specification", "label": "9mm", "spec_name": "Caliber", "spec_value": "9mm Luger", "spec_collection_slug": "ammunition", "url": "/collections/ammunition?filter.p.m.custom.caliber=9mm+Luger" },
              { "type": "specification", "label": ".45 ACP", "spec_name": "Caliber", "spec_value": ".45 ACP", "spec_collection_slug": "ammunition", "url": "/collections/ammunition?filter.p.m.custom.caliber=.45+ACP" }
            ]
          },
          { "name": "Rifle", "items": [ … ] }
        ]
      },
      { "type": "page", "label": "Contact", "page_slug": "contact", "url": "/pages/contact" }
    ]
  },
  "warnings": [
    "items[1].categories[1].items[0]: no active product in collection \"ammunition\" has Caliber \"5.56x45mm NATO\", so shoppers see an empty page."
  ],
  "next_step": "Shoppers don't see it yet. update-menu with set_active makes it the main menu, or a theme section can show it through a link_list setting set to its handle."
}
Caveats
  • Each item has a `type` and a `label` (plain text: tags are stripped), plus what it links to. `link`: `url`, a `/path` on the store, `https://`, `#`, `mailto:` or `tel:` (anything else, such as `javascript:`, is refused). `collection`: `collection_slug` (`all` for every product), or `collection_id` from `list-collections`. `product_type`: `product_type`. `specification`: `spec_name`, `spec_value` and optionally `spec_collection_slug`. `product`: `product_slug`, or `product_id` from `search-products`. `page`: `page_slug`. `policy`: `policy_slug`. `blog`: `blog_handle` (`all` for every blog). `article`: `blog_handle` and `article_handle`. `event`: `event_handle` (`all` for every event). The tool builds every URL but a `link`'s, exactly as the Navigation screen does.
  • A top-level `dropdown` holds its links in `items`, and a `mega_menu` holds columns in `categories`, each `{ "name": …, "items": […] }`. Inside a dropdown or column, a link can be any type but `article`, `dropdown` and `mega_menu` (the types the Navigation screen edits there), so make an article a `link` to its URL. Menus go two levels deep. Limits: 50 top-level items, 12 columns, 200 links in a dropdown or column, 1,000 items in all.
  • Every item is checked before anything is saved. One that doesn't resolve (a slug the store doesn't have, an unpublished policy, a specification no active product has) refuses the whole call with every problem and where it is, such as `items[1].categories[0].items[2]: …`. One that resolves but leads nowhere useful yet (a collection with no active products, a draft page or product, a filter value no active product has) is saved and listed in `warnings`.
  • Specification values are saved in the form the storefront's filters use, so `9mm` is saved as `9mm Luger` and the link ticks the matching box in the Caliber / Gauge filter.
  • The handle is made from the name and never changes, even when the menu is renamed. A store's first menu becomes its main menu, as it does on the Navigation screen.
  • Menus are store data shared by every theme, so a change to the main menu shows in the storefront's header at once, and a Navigation page open in the dashboard reloads to show it. Not versioned: there is no undo, so `dry_run` first and get the merchant's yes.
  • Requires `themes:write`. A token without it never sees this tool in `tools/list` (`shouldRegister()`), and a direct call is refused with “This token lacks themes:write.”

Update a menu

update-menuthemes:writemutates
Rename a navigation menu, replace its items, or make it the main menu shown in the storefront's header. Pass the `handle` and `version` from `list-menus`. `items` replaces the whole list.

Arguments

handlestringrequired
The menu's handle from `list-menus`. `main-menu` and `main` name the main menu, unless a menu has that handle itself.
expected_versionstringrequired
The menu's `version` from `list-menus`. A menu that changed since then is refused.
namestringoptional
A new name. The handle stays, so theme sections showing the menu keep showing it. Refused when another menu has the name.
itemsarray<object>optional
Every item the menu should have, in order, in the form `list-menus` returns. Replaces the current items; leave out to keep them.
set_activebooleanoptional
`true` makes it the main menu and takes the current one out of the header. `false` on the main menu is refused: set another menu active instead.
dry_runbooleanoptional
Check the change and return the menu as it would be, without saving.
Example argumentsjson
{
  "handle": "main-menu",
  "expected_version": "3f9c1a7d2b04",
  "items": [
    { "type": "collection", "label": "Shop", "collection_slug": "all" },
    {
      "type": "dropdown",
      "label": "Firearms",
      "items": [
        { "type": "product_type", "label": "Handguns", "product_type": "handguns" },
        { "type": "collection", "label": "Rifles", "collection_slug": "rifles" },
        { "type": "collection", "label": "Shotguns", "collection_slug": "shotguns" }
      ]
    },
    { "type": "page", "label": "Contact", "page_slug": "contact" }
  ]
}
Resulttext
{
  "status": "updated",
  "changed": ["items"],
  "menu": {
    "handle": "main-menu",
    "name": "Main menu",
    "is_active": true,
    "version": "c47e0b9a1d58",
    "items": [ … every item as saved, each with the url it leads to … ]
  },
  "warnings": []
}
Caveats
  • `items` replaces the whole list. To change one item, take `items` from `list-menus`, change that item and send them all back. Each item's `url` there is only for reference: every type but `link` rebuilds its own.
  • Items take the same form as in `create-menu`; see its notes for each type's fields, nesting, checks and limits.
  • Refused when the menu changed since `list-menus` (“This menu changed since it was read. Call list-menus again and confirm the change with the merchant.”), when no `name`, `items` or `set_active` is passed, and when the main menu would be left with no items.
  • A call that changes nothing returns `status: "unchanged"`; `changed` lists what a change touched (`name`, `is_active`, `items`, and `main_menu` when the main menu moved).
  • Menus are store data shared by every theme, so a change to the main menu shows in the storefront's header at once, and a Navigation page open in the dashboard reloads to show it. Not versioned: there is no undo, so `dry_run` first and get the merchant's yes.
  • Requires `themes:write`. A token without it never sees this tool in `tools/list` (`shouldRegister()`), and a direct call is refused with “This token lacks themes:write.”

Delete a menu

delete-menuthemes:writemutates
Delete a navigation menu from Store > Navigation. Call it with `dry_run` first, show the merchant which menu will go, then delete with the `confirmation` the dry run returned. The main menu and any menu the storefront shows can't be deleted.

Arguments

handlestringrequired
The menu's handle from `list-menus`.
expected_confirmationstringoptional
The `confirmation` a dry run returned. Required to delete; without it the call is refused.
dry_runbooleanoptional
Return the menu that would be deleted and its `confirmation`, without deleting it.
Example argumentsjson
{
  "handle": "holiday-menu",
  "dry_run": true
}
Resulttext
{
  "status": "dry_run",
  "menu": {
    "handle": "holiday-menu",
    "name": "Holiday menu",
    "is_active": false,
    "version": "8d21e4c0b97a",
    "items": [ … the menu's items … ]
  },
  "confirmation": "b3e1f09a6c2d4875",
  "next_step": "Nothing was deleted. Tell the merchant \"Holiday menu\" and its 3 top-level items will be deleted for good, and once they say yes, call delete-menu again with expected_confirmation."
}
Caveats
  • Two calls: `dry_run` returns the menu and a `confirmation`; after the merchant says yes, call again with it as `expected_confirmation`. Only a dry run gives out the confirmation, and it stops working when the menu changes (“This menu changed since the dry run…”), so a delete always follows a preview of the menu as it is.
  • Refused for the main menu (make another menu the main menu with `update-menu` and `set_active` first), and for a menu the storefront shows: picked in a section or block of the published theme, such as a header or footer menu setting, or chosen as the checkout footer menu under Settings > Checkout. The refusal names each place.
  • It can't be undone: there is no version history and no tool to restore a menu. A successful call returns `status: "deleted"` with the menu's handle and name.
  • Requires `themes:write`. A token without it never sees this tool in `tools/list` (`shouldRegister()`), and a direct call is refused with “This token lacks themes:write.”

Generate a menu with AI

generate-menuthemes:writemutates
Have AI design a navigation menu from the store's catalog, as Generate from catalog does in Store > Navigation. It runs in the background and saves a new menu that isn't shown on the storefront.

Arguments

namestringoptional
A name for the new menu. Leave out to let the AI name it. A name another menu has gets a number after it.
Example argumentsjson
{
  "name": "AI menu"
}
Resultjson
{
  "status": "generating",
  "name": "AI menu",
  "next_step": "It takes a minute or two, longer for a very large catalog. Call list-menus: `generating` shows while it runs, and the new menu appears in `menus`, not as the main menu, when it's done…"
}
Caveats
  • The AI builds sections from the store's product types, groups ammunition by caliber in a mega menu, adds a sale link when items are on sale, and includes useful pages, blogs with published articles and published events. Every link is built from the real catalog.
  • It takes a minute or two, longer for a very large catalog. Call `list-menus` to follow it: `generating` shows the name and start time while it runs, and the new menu appears in `menus` when it's done. If `generating` clears and no new menu appeared, generation failed and can be tried again.
  • The new menu is never the main menu. Review it with the merchant, adjust it with `update-menu`, and make it the main menu with `update-menu` and `set_active`.
  • One generation runs at a time per store, whether started here or on the Navigation screen, and a call while one runs is refused. A store can start up to 10 a day over MCP.
  • Requires `themes:write`. A token without it never sees this tool in `tools/list` (`shouldRegister()`), and a direct call is refused with “This token lacks themes:write.”

Set collection filters

set-collection-filtersthemes:writemutates
Sets which specification groups render as filters on collection pages and search results, replacing the theme's current allowlist, or clears it so every group renders again. Names are validated against the catalog before anything is written, and the change is live on the next page load.

Arguments

themestringrequired
theme_id from list-themes. The allowlist is stored per theme, so a library copy and the live theme each carry their own.
filtersarray<string>optional
Group names from list-collection-filters. Replaces the whole allowlist. Pass this or clear, not both.
clearbooleanoptional
Drop the allowlist so every group with 2+ values renders again. Pass this or filters, not both. Defaults to false.
allow_activebooleanoptional
Set true ONLY if the user explicitly asked to change the filters on the live (active) theme. Defaults to false.
Example argumentsjson
{
  "theme": "9f1c0b2e-7d44-4a1e-9a52-3b8c6d0f1a77",
  "filters": ["Manufacturer", "caliber", "Action", "Capacity", "Barrel Length", "Finish", "Bullet Type", "Rounds Per Box"],
  "allow_active": true
}
Resultjson
{
  "saved": true,
  "theme": {
    "theme_id": "9f1c0b2e-7d44-4a1e-9a52-3b8c6d0f1a77",
    "name": "Arsenal",
    "active": true
  },
  "filters": ["Manufacturer", "Caliber / Gauge", "Action", "Capacity", "Barrel Length", "Finish", "Bullet Type", "Rounds Per Box"],
  "previous_filters": [],
  "warnings": [],
  "note": "Collection pages now show only these groups, plus Availability, Price, Sale, Product type and In Store. Storefront caches were cleared. To undo, call set-collection-filters with previous_filters, or clear: true if previous_filters is empty."
}
Caveats
  • Requires `themes:write`. A token without it never sees this tool in `tools/list`, and a direct call is refused with “This token lacks themes:write.”
  • It REPLACES the list. There is no add or remove: send the complete set every time, or you will silently drop the groups you left out.
  • Names match case-insensitively and are stored as the catalog spells them, so “manufacturer” saves as “Manufacturer”. When a catalog carries several capitalizations of one name, every one of them is selected. Any caliber-type spelling — Caliber, Gauge, Caliber/Gauge — selects the merged “Caliber / Gauge” filter.
  • One unknown name fails the whole call, and the valid names beside it are not saved either: “Nothing saved. Not a specification group in this catalog: 'Brand' (did you mean: Brand Fit, Sub Brand?). Call list-collection-filters (with search) for the exact names.”
  • Exactly one of filters or clear is required. Both, or neither, is refused with “Pass either filters (one or more group names from list-collection-filters) or clear: true, not both and not neither.”
  • The active theme is refused unless allow_active: true, with the same message the file-write tools use. Unlike a page or policy write, this is a theme setting, so working on an inactive copy and publishing it later is a real option.
  • Not versioned — list-file-versions and restore-file-version do not cover settings. previous_filters in the response is the undo: send it back, or clear: true when it is empty.
  • A group with fewer than 2 values is saved but reported in warnings, because it never renders.
  • Re-sending the same set, in any order, returns saved: false and writes nothing. Order is never significant: the storefront lists filter groups alphabetically.
  • The save goes through the same path as a Visual Editor Save: the theme's settings are updated, its compiled assets and page and section caches are invalidated, and a cache warm with a Cloudflare purge is queued. The purge is asynchronous, so edge-cached pages can show the old filters for a short window.
  • This writes the same value as the Visual Editor's Theme settings → Collection Filters picker. A merchant editing that picker afterwards will see your selection, and can overwrite it.
  • Themes are resolved inside the authenticated team only. A theme id belonging to another team is indistinguishable from a non-existent one: both return “Theme not found for this team. Call list-themes first.”

Add theme from store

add-theme-from-storethemes:writemutates
Installs a theme from the FirearmCart theme store catalog into the team's library as a new inactive copy. Paid themes must already have been purchased in the dashboard. The call is synchronous and slow: it copies every template, uploads the base theme's assets to object storage, and compiles CSS and JS before returning.

Arguments

slugstringrequired
The catalog slug, exactly as list-theme-store returns it in each entry's slug field (for example arsenal, horizon, tactix). This is the store slug, not a theme name and not a theme_id.
Example argumentsjson
{
  "slug": "arsenal"
}
Resultjson
{
  "added": true,
  "theme_id": "6f5a1c2e-9d47-4b0a-8f31-2c7e5b90ad14",
  "name": "Arsenal",
  "active": false,
  "template_source": "arsenal",
  "note": "Theme added as an inactive library copy. Use publish-theme when ready to make it live."
}
Caveats
  • Only catalog entries flagged active are installable. An unknown slug, or one whose catalog entry is inactive, is refused with "Theme store slug not found or inactive: {slug}". Call list-theme-store first — it lists only active entries, so anything it returns is installable.
  • Paid themes cannot be bought over MCP. If the entry is not free and the team has no matching purchase record, the tool refuses with "This is a paid theme the team has not purchased. Purchases must be made in the dashboard at /store/themes/store." list-theme-store tells you this in advance through its is_free and purchased flags.
  • Nothing dedupes by catalog slug. Calling this twice with the same slug produces two separate library themes with the same template_source, both named the same. list-theme-store's in_library flag is the only signal that you already have one; check it before installing.
  • The new theme is always inactive — this tool never touches the live storefront. Call publish-theme when the merchant is ready.
  • Expect this call to take tens of seconds. Asset upload, CSS/JS compilation and .css.liquid / .js.liquid processing all happen inline before the response is written, so a short MCP client timeout can fire while the install is still running and succeeding. Re-issuing after a timeout adds a second copy (see above) — call list-themes to check before retrying.
  • On a purchased PAID theme the created theme is named "{Slug} Theme" (for example "Reformation Theme") with base_version 1.0.0, not the catalog's name and version. The install re-reads the catalog without the paid flag, so the metadata lookup comes back empty and the fallback names are used. Rename it in the dashboard, or via the Themes index, if it matters.
  • Any failure returns "Failed to add theme: {message}" and the exception is reported to error tracking. The database work is transactional and rolls back, but files already uploaded to object storage are not removed, so a failed install can leave orphaned asset objects behind.
  • A cache warm is queued for the new theme on the default queue connection. Nothing about the storefront changes, since the theme is not active.

Duplicate theme

duplicate-themethemes:writemutates
Clones a theme into a new inactive library copy — the safe workspace every editing session should start from. Copies templates, theme settings rows, locales and assets, isolating each asset file into the copy's own storage folder so edits can never reach the original. Never publishes.

Arguments

themestringrequired
The source theme's theme_id, from list-themes.
namestringoptional
Name for the copy. Trimmed, and limited to 255 characters — a longer value is a validation error. Defaults to "{source name} (Copy)".
Example argumentsjson
{
  "theme": "6f5a1c2e-9d47-4b0a-8f31-2c7e5b90ad14",
  "name": "Arsenal — homepage rebuild"
}
Resultjson
{
  "duplicated": true,
  "source": {
    "theme_id": "6f5a1c2e-9d47-4b0a-8f31-2c7e5b90ad14",
    "name": "Arsenal",
    "active": true
  },
  "theme": {
    "theme_id": "b3d90f77-1a54-42c8-9e6b-70f1c8a4d221",
    "name": "Arsenal — homepage rebuild",
    "active": false,
    "template_source": "arsenal",
    "base_version": "15.4.1"
  },
  "note": "Inactive library copy created. Edit this theme freely; publish-theme when ready to make it the live storefront."
}
Caveats
  • Duplicating the ACTIVE published theme is allowed, and is the intended way to get a workspace. The active-theme refusal applies to the file-write tools, not to this one: duplicate first, edit the copy, then publish it.
  • The copy is always created inactive, whatever the source's state.
  • theme is resolved against the authenticated team only. An id belonging to another team reads as missing and returns "Theme not found for this team. Call list-themes first."; an empty value returns "Missing theme argument. Call list-themes first." Values are matched against theme_id.
  • A blank or whitespace-only name is treated as absent and falls back to "{source name} (Copy)". Names are not unique — duplicating twice without a name yields two themes with identical names, distinguishable only by id.
  • Asset copying is best-effort. If an asset's file is missing from object storage, the copy's asset row keeps the ORIGINAL storage_path and public_url instead of an isolated one, so that asset is then shared with the source theme. The failure is reported to error tracking, not returned to you.
  • Media re-homing runs after the transaction commits and is also best-effort: if it fails, the duplicate still succeeds and the response says nothing about it.
  • Carried over: template_source, base_version, is_customized and the theme settings blob. Reset: active, and all dev-mode state.
  • Not idempotent. Every call creates another theme, so a retry after a client timeout leaves you with two copies — check list-themes before retrying.
  • A cache warm is queued for the copy, so its preview URL is usable shortly after the call returns.

Publish theme

publish-themethemes:writemutates
Makes a library theme the live storefront. A team can have only one published theme, so the previously active one is deactivated in the same transaction. Storefront caches are cleared and a cache warm with a Cloudflare purge is queued. Identical to Themes → Publish in the dashboard.

Arguments

themestringrequired
The theme_id of the theme to publish, from list-themes.
Example argumentsjson
{
  "theme": "b3d90f77-1a54-42c8-9e6b-70f1c8a4d221"
}
Resultjson
{
  "published": true,
  "already_active": false,
  "theme": {
    "theme_id": "b3d90f77-1a54-42c8-9e6b-70f1c8a4d221",
    "name": "Arsenal — homepage rebuild",
    "active": true
  },
  "previous_theme": {
    "theme_id": "6f5a1c2e-9d47-4b0a-8f31-2c7e5b90ad14",
    "name": "Arsenal",
    "active": false
  },
  "note": "Theme is now the live storefront. The previous active theme (if any) was deactivated automatically."
}
Caveats
  • Publishing a theme that is already active is a no-op: the response carries already_active: true, previous_theme: null and "Theme was already the published storefront; no changes made." No caches are cleared and no warm is queued, so this is not a way to force a cache refresh.
  • previous_theme is the theme this call deactivated, captured before the switch. It is null when the team had no active theme, and when the target was already active.
  • There is no unpublish tool. The only way to change the live storefront is to publish a different theme; you cannot leave a team with no active theme over MCP.
  • Nothing validates the theme before it goes live. Publish does not render a page, check for missing snippets or run the save-time Liquid checks — a theme that has never been screenshotted can be published broken. Run screenshot-theme at desktop, tablet and mobile first.
  • Cache clearing happens after the transaction commits, and covers the team's UUID storefront plus every active custom domain. The Cloudflare purge rides on a queued cache-warm job (redis-long connection, theme-cache queue), so it is asynchronous: for a short window after this returns, edge-cached HTML from the old theme can still be served.
  • theme is resolved against the authenticated team only, exactly as in duplicate-theme, and returns the same "Theme not found for this team." and "Missing theme argument." errors.
  • If the publish itself throws, the tool returns "Failed to publish theme: {message}" and reports the exception. The activation is transactional, so a failure leaves the previously active theme live.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close