What the assistant can read
A connected assistant can read across your Assemblified data and your live Shopify catalog. With a read-only connection it cannot change anything — see Read-only by default. A write-scope connection reaches a much larger surface: bills, assembly BOMs and materials, but also work orders and build runs, stock restocking, bill versions, your catalogues, entity groups, the reporting sync and your store settings. The operating pages describe each one. This page lists the read surface so you know what you can ask about.
On this page
Section titled “On this page”- The data it can reach
- How it explores the API
- Reading locations
- Large answers
- Reading the documentation
- What’s not included
The data it can reach
Section titled “The data it can reach”The assistant can read across these areas, scoped to your single store:
| Area | What it can see |
|---|---|
| Bills of materials | Your finished goods and their full composition — component materials, nested assembly BOMsAssembly BOMThe BOM for an intermediate component you build and then use inside other bills — a lid, a wick assembly, a pre-wired harness. It keeps its own pre-assembled stock and can be a work order item in its own right.Read more →, quantities, settings, and per-row usage. Search, filter (used / unused, by vendor), and sort just like the app’s list. Every bill of one Shopify product can be looked up by the product’s id. |
| Selected product tags | Current Shopify product tags for 1–250 selected BOMs, alongside your saved tag catalogue. Missing BOMs can be omitted; unlinked or unavailable products are skipped, which differs from successfully reading a product with no tags. These tags belong to the whole product, including its other variants. See Operating material tags. |
| Buildable quantities | For any BOM, how many units you can build right now, per location — the same number the app’s Buildable column shows — including the sellable split and which components are the limiting factor. |
| Assembly BOMs | Your reusable assembly BOMsAssembly BOMThe BOM for an intermediate component you build and then use inside other bills — a lid, a wick assembly, a pre-wired harness. It keeps its own pre-assembled stock and can be a work order item in its own right.Read more → (the app’s newer name for subassemblies) and their hydrated component trees, with usage counts. |
| Per-location bill rules | What you have configured a bill to do at each location — the execution mode there, and the materials that are added, changed or removed at that location. Separately, the assistant can read the bill as seen from a location: the same BOM with that location’s rule already applied. |
| Bill history | The versions saved for a bill, newest first, what changed between any two of them, and how one compares with the BOM as it stands today. Reading history is open on every plan; saving and restoring need Enhanced. See Operating bill versions. |
| Materials | Every material — Shopify-linked and virtualVirtual materialA material tracked entirely inside Assemblified — not a Shopify variant. Useful for shop-floor consumables (glue, packaging, labour units) where you need quantity tracking but don't want a Shopify product on your storefront.Read more → — with its per-BOM and per-assembly BOM usage, vendor, SKU, and (optionally) the BOMs and assembly BOMs that reference it. |
| Material search | The same search, filters and sorting the Materials page uses, as a single call — plus the four counts above that table, and the names of the BOMs that consume any material. For up to five materials at a time it can also name the bills that use a material only through an assembly BOM, and which assembly BOMs lie in between (the base bill, without per-location changes). |
| Shopify catalog | Your live Shopify products and variants, searchable with Shopify’s own filter syntax, plus lookups by id — so the assistant can find the right variant before registering it as a material. |
| Shopify collections | Search collection identities and titles for a saved bulk builder rule, one page at a time. Similar or duplicate titles stay separate candidates. |
| Shopify orders | Find an accessible order by its exact name, or search with Shopify filter syntax, then read its existing BOM breakdown and variants. Results include identity, creation time and display statuses, with no customer/contact/address information in the finder. |
| Locations | Your Shopify locations, so the assistant can resolve location names and ids. |
| Inventory levels | Real per-location stock for any material — live Shopify levels for Shopify-linked materials, app-tracked levels for virtual ones. |
| Committed stock | How much of a material is already spoken for at each location: what open orders hold, and what your safety-stock reservations hold. Neither is available stock. |
| Order reservations | For one Shopify order, the stock it has reserved at each location: every reservation, open by default or closed ones too, with each component line’s reserved, consumed and released quantities and what it still owes. A held order whose give-back was never recorded is marked as a lower bound. |
| Allocated stock (shelf) | How much of a material is already built into finished items sitting on the shelf at each location, with the list of what those items are. |
| Allocated stock (work orders) | A different number: how many units of a material your open work orders have already picked and still have to pick, per location, with the work orders behind it. Demand from a work order with no location is reported separately. Neither figure may be subtracted from availability. |
| Stock history | A material’s movement history — what changed, when, and what caused it — for both Shopify-linked and virtual materials, newest first. |
| Material metafields | Every stored metafield value for a slice of materials in one read, including whether a value has been overridden locally. |
| Pre-assembled stock | Per-location pre-assembledPre-assembled stockStock of finished goods and subassemblies already built and on the shelf, counted per location. For Shopify-linked finished goods, these units are part of the applicable on-hand balance, not extra stock to add to it. A work order draws subassemblies from the shelf first, building fresh only if it runs short; an order consumes a finished good's shelf before its components.Read more → quantities for your finished goods and assembly BOMs. |
| Additional costs | Your catalogue of cost rates — labour and overhead rates — plus which factors each BOM and assembly BOM references, and at what per-unit quantity. |
| Your catalogues | The lists the rest of the app draws from: units and the conversions between them, material tags, metafield definitions, import templates and the four supported import field schemas, the assignees a work order can be assigned to, and the work-order export, QC and tag lists. |
| Groups | Your entity groups — the named sets of bills, assembly BOMs or materials — with their member counts and, for one group, its members. |
| Saved views | The named setups for finished goods, assembly BOMs, materials, work orders and tasks: list them or inspect one exact view. For the first four, read one current page of ordered matching record IDs, with total and paging details. Tasks support inspection only; report views are excluded. See Operating groups & saved views. |
| Order production | For one Shopify order, what each line allows: units its reserved components can still become, lines that can go into a normal work-order draft, and what blocks the rest, plus the work orders already linked to it and the confirmations already recorded for it. The preview needs Enhanced; the recorded confirmations read on every plan. See Operating work orders. |
| Bulk builder rules | The saved rules the bulk bill builder replays over a grid: what each one matches and what it puts in. |
| Cost breakdown | For any finished good or assembly BOM, what it costs right now against the figure stored on the record, with the additional-costs portion reported separately so the difference between the two can be explained rather than mistaken for an error. Up to 25 at a time. It reads; it never rewrites a cost. |
| Work orders | Your work ordersWork orderA planned production run: pick materials, build the items, do QC, and complete — all tracked together. Use work orders when you're building stock ahead of demand or running a multi-day project.Read more →: the list with its own filters and the counts beside them (including the work orders that build a given BOM or assembly BOM), one whole work order (its items, materials, the merged consumption plan, build runs, QC reviews, rework items, documents, conversation and activity), the material plan on its own, the build-run history, what a transition would allow, and the purchase-order view of what is missing. |
| Tasks | Your task list — title, status, priority, label, due date and quantity, plus the assembly flow or Shopify order a task came from, the work order linked to it (name, short ID, status and whether it is a material-list-only one), and whether the app raised it or a person did. Filter by status, priority or label and search by text, the same way the Tasks page does. |
| Your home dashboard | The same summary the app’s home page shows, in one call: how many finished goods, assembly BOMs and materials you have, how many bills are inactive or unlinked or thin on margin, your most recent runs, and how far through setup you are. |
| Search | The same search the app’s search field runs, across finished goods, assembly BOMs, materials, work orders, saved views and groups at once. Three characters minimum. This is how an assistant works out which thing you meant before it goes and reads it. |
| Execution history | Every run the app recorded — the orders and assembly flows it processed, whether each one succeeded, failed or is still pending, and for any single run the full picture: the bills it processed, the ones it skipped and why, the materials it moved and by how much, and where in the pipeline an error came from. Plus the over-consumption report, which lists orders whose components were drawn down more than the order allows. |
| Reports | The report catalogue — every report the app can answer, across sales, bills of materials, manufacturing and inventory — and the report itself: a page of rows over a period you name (or, for the three On hand reports, for right now), with its metric figures, optionally split by day, week or month and narrowed to locations. |
| Reporting freshness | How current the order history your sales reports are built on actually is, and whether its refresh is behind or has stopped. See Operating the reporting sync. |
| Your settings | Every setting of your store, and what each one does in plain language — the fallback location, whether order reservations hold stock, whether Logistified is connected, what the packing slip shows. This is how an assistant explains why a number looks the way it does instead of guessing. |
Product and variant searches return candidates. Shopify may ignore unsupported search filters. Assemblified includes this caveat in the assistant’s search result even when Shopify supplies no warning; no warning does not prove an exact or unique match. Ask the assistant to verify the returned product and variant details, including their IDs, before requesting changes.
How it explores the API
Section titled “How it explores the API”The assistant doesn’t have to guess what’s available, and it doesn’t have to load everything up front either. The API is a catalogue in three levels: topics (the 26 areas listed on the overview, each with a one-line summary), the methods in each topic, and the types those methods take and return. A read-only connection’s catalogue holds only read methods.
A capable assistant works through it in two steps:
searchthe catalogue for the methods that fit your question, for example everything about buildable quantities or committed stock.describe_apifor just those topics or methods, which returns their exact, typed definitions:describe_api({ namespaces: ['billOfMaterials', 'inventory'] }), or a list of individual methods.
That is how it figures out, on its own, how to answer a question like “which BOMs am I about to run out of components for?”
Ask for one area at a time. The full definition is very large, big enough to fill a chat model’s working memory on its own. Calling describe_api with no arguments returns short guidance on how to search, followed by that full definition, so a well-behaved assistant names what it needs instead. If an assistant keeps losing the thread of a long conversation, or claims it cannot find a method you know exists, telling it which area to look in usually fixes it.
To check which connection an assistant is using, ask it “Which store am I connected to?”. It answers with whoami: your store, whether the connection is read only or read and write, the kind of connection, its label and the API version.
Reading locations
Section titled “Reading locations”Ask the assistant to use shopify.listLocations to resolve your location names and IDs.
It includes active locations by default; includeInactive: true also includes inactive ones.
first means locations per page, from 1 to 50, default 50. It does not limit the total
returned: the read follows pages until the end, for up to 40 requests. There is no cursor
to pass for another page.
If more pages remain after request 40, the read fails with OUTPUT_TOO_LARGE instead of
returning a partial list. If a smaller first caused that limit, ask for a new read with
50 or the default. If it already used 50, contact support. An invalid or incomplete Shopify
response fails with UPSTREAM_SHOPIFY. Repeating the same limit failure unchanged will not
complete the list.
A successful read has reached the end, but a shortened answer can still leave locations out. Ask for the needed identity fields or the whole result within the connection’s size limits before treating it as a complete list. Locations can change between pages, so the result is not a snapshot taken at one instant.
Large answers
Section titled “Large answers”A long result is shortened at about 24,000 characters, with a clear marker saying what was left out, so the assistant can tell part of a list from the whole of it. IDs and paging details are kept. For candidate lists, the assistant must check what was left out and rerun the same starting cursor with a smaller page or return only the identity fields it needs before advancing. A shortened candidate list cannot establish that there is just one match. When it really needs everything at once, it can ask for the whole result on that one call. Results of a run that changed something are never shortened.
For an abbreviated product or variant search, ask the assistant to narrow the search or retry with a smaller page. When retrying the same search, it should start at the same place and keep any warnings and Assemblified’s caveat with the results. It must inspect the returned details and IDs before selecting an item for changes or moving past candidates that were left out.
Finding an order by name
Section titled “Finding an order by name”For “Open order #13226 and tell me what to build”, the assistant can use orders.lookupByName({ name: "#13226" }), then pass the selected digit-string order ID to the existing variants and BOM-breakdown reads. A bare number is treated as the order’s name, never as its resource ID. Leading/trailing whitespace and one leading hash are normalized; exact comparison remains case-sensitive. All candidate pages must be read before concluding there are no accessible matches or only one. An empty page can still have a next page. No accessible result does not prove an order does not exist: Shopify grants and the accessible order-history window still apply.
orders.search({ query, first, after }) and shopify.searchCollections({ query, first, after }) accept Shopify search syntax unchanged, up to 2000 characters. They do not add status or date filters. Each call reads one page of 1–100 results, default 20, with no total count. Optional warnings are bounded provider feedback; their absence does not validate every filter’s meaning. An exact-name lookup with provider warnings fails rather than returning a possibly incomplete answer. Unsupported special name syntax needs verification before relying on it.
Reading the documentation
Section titled “Reading the documentation”The assistant can also read this documentation site through two tools:
list_docs— the index of every documentation page.get_doc— the full text of one page.
This lets it ground its answers in how Assemblified actually works — what a BOMBill of materialsA bill of materials tells Assemblified how to build one unit of a finished good. When a customer orders the finished-good variant, Assemblified deducts the right component quantities from inventory automatically.Read more → is, how pre-assembled stockPre-assembled stockStock of finished goods and subassemblies already built and on the shelf, counted per location. For Shopify-linked finished goods, these units are part of the applicable on-hand balance, not extra stock to add to it. A work order draws subassemblies from the shelf first, building fresh only if it runs short; an order consumes a finished good's shelf before its components.Read more → works, what the buildable calculation includes — instead of guessing.
What’s not included
Section titled “What’s not included”- Writing without write access. A read-only connection can’t create or change anything, and the actions it isn’t allowed to take aren’t even visible to it. What a write-scope connection adds is covered on the operating pages.
- General Shopify catalog editing. Product and variant creation, prices and titles remain read-only. With write access, an assistant can request selected product-tag additions/removals through BOMs, or apply maintained default tags. Selected edits preserve unrelated tags and take effect asynchronously; a response is not proof the tags have changed. See Operating material tags.
- Running an assembly flow. Flows stay in the app. An assistant can see which flow a task or a work order came from, but it cannot run, create or edit one.
- Reaching another store. A connection is scoped to the single store it was created in.
See also
Section titled “See also”- AI / Agent access overview — how code mode works.
- Managing access & security — how access is scoped and revoked.