Skip to content

Operating reports

A connected assistant can read your reports: it can list every report Assemblified can answer, and run one over a period you name. Discovery and queries are read operations — no write access, no Enhanced plan, nothing to switch on.

This is the same engine the report pages in the app use, so a number an assistant quotes is the number the page would show for the same period.

  • What it takes
  • Asking for the catalogue first
  • Running a report
  • Periods, buckets and location scope
  • Filters, search and sorting
  • What comes back
  • Caveats an assistant must pass on
  • What it cannot do

Nothing beyond a working connection. Reports are read-only, so a read-scope key or a read-only web-chat connection is enough. See API keys.

The assistant starts with reporting.catalog(), which lists every report without reading report data. It then calls reporting.describe({ reportType }) for the selected report’s complete fields and options. Connection rate limits still apply. These are read-only calls. Together they provide:

  • The id to run it by, and its category — sales, bills of materials, manufacturing, or inventory.
  • A plain-English title, description and grain — what one row of that report actually is (“one material per period and location”, “one completed work order”).
  • Which basis it can count on — what left the store (sold) or what was used up (consumed). A report that offers both accepts a choice; a report that offers one ignores it.
  • Whether it has a location dimension at all — on a report that has none, naming locations changes nothing, and the catalogue says so up front.
  • Its columns, which of them can be sorted or filtered, and the figures it reports beside the rows.
  • How far back its history goes, and the maximum length of a period it will answer.
  • Whether it takes a period at all. The three On hand reports, in the inventory category, value the stock you hold right now, so an assistant runs them without one.
  • The note the report page shows above its table, when it has one. On the On hand reports it says what every value leaves out (tax, units reserved or held as safety stock, work in progress, which is counted separately), and a good assistant passes it on with any value it quotes.

Each catalog or selected detail fits the ordinary response limits when returned on its own. Combining many results can still shorten a response. The older reporting.list() remains available with its existing full-list format, which can be shortened when returned whole.

A capable assistant reads this before it runs anything, because it is how it picks the right report and knows which options that report accepts. If your assistant guesses a report name, it gets a clear “no such report” rather than an empty table.

Running one takes the report id and a period, and returns a page of rows plus the figures across the top:

“Run the material demand report for August and tell me the ten biggest movers.”

“Which finished goods sold last quarter that I have no bill of materials for?”

“How much did each completed work order cost me in September?”

  • The period is a pair of calendar days, start and end, both included, read in your store’s time zone. The assistant does not get to send a time zone — the store’s own is used, so a period cannot be quietly shifted by an offset.
  • A period longer than 366 days is refused, as is one that ends before it starts.
  • Buckets can split table rows by day, week or month. “None” covers the whole period. The summary reports and the three On hand reports always stay ungrouped, even if another bucket is sent. The selected detail distinguishes accepted options from effective grouping.
  • Locations narrow the rows. Leaving them out means every location. For a report with no location dimension, naming locations changes nothing — which the catalogue tells the assistant in advance.

The selected detail lists each field’s accepted operators and enum values. queryFilterable describes API filter acceptance on the selected basis; the older filterable flag describes what the app’s filter menu offers. An API can also filter some hidden IDs and summary figures. A report can be searched with its own free-text search and sorted by any sortable column. Paging is by page number, 25, 50 or 100 rows at a time.

Enum filters take a nonempty list of allowed values, ranges take a pair of numbers or calendar days, and boolean filters take true or false. Empty-value checks need no value. The detail also includes the query limits: at most 20 filters, 50 values in a list and 50 location IDs. These limits share a total query budget, so two lists that each fit their own limit may still be too large together.

One behaviour worth knowing: a filter or sort naming a column the report no longer has is dropped and reported, not refused. The page still comes back, with a note saying which conditions were ignored — so if an assistant reuses an old query after a report changed, you get the data and the warning rather than an error.

  • Rows — one object per row, keyed by column.
  • The totals — the same figures the report page shows in its strip across the top.
  • Paging information, so the assistant can walk a long report.
  • Notes, when there are any: which filters were dropped, how far back the data actually goes, and whether any figure in the answer is an estimate.

Two are important enough that a good assistant repeats them to you rather than quietly rounding them off:

  • Some answers are estimates. A period boundary that splits an order, or a historical row replayed against today’s BOM, makes a figure approximate. The answer says so; it should be reported as an estimate, not as an exact number.
  • History has a floor. Each report’s data starts on a date. A period reaching further back is empty for a reason, and the answer carries that date. For the sales reports the floor is the copy of your Shopify orders — if that looks short, see Operating the reporting sync.
  • It cannot export a file. Export exists so a person gets a spreadsheet; an assistant pages through the rows instead.
  • It cannot save a report view. Saved views are created in the app.
  • It cannot change a report. The report catalogue is fixed; nothing here writes anything.