Tool guide
Five tools. All read-only, none costs anything to call, and every one is scoped to the single store its token belongs to.
For the compact list, see the tools reference.
get_setup_status
Purpose: Report whether the bundle widget is actually live on the storefront, and if not, why.
When to use: First, whenever a bundle, a volume table or an upsell is described as "not showing". It reaches a conclusion rather than handing back raw data.
Parameters: none
Returns: the store's name, domain, plan and install date; the theme embed state; whether
settings have been saved; offer counts by type and status; and issues — a list of codes, in the
order worth acting on.
| Code | Means | Fix |
|---|---|---|
APP_EMBED_DISABLED | The app embed is off on the live theme, so nothing can render | Turn it on in the theme editor, on the live theme |
NO_BLOCK_ADDED | The theme supports app blocks, and none of ours is placed | Add the block where the widget should appear |
NO_ACTIVE_OFFERS | Nothing is currently active — every offer is draft, scheduled or expired | Activate one, or check its schedule |
THEME_NOT_OS2 | The live theme does not support app blocks | Switch to an Online Store 2.0 theme |
NO_SETTINGS | The store has no saved widget settings | Open and save the settings once |
The list is in priority order — fix the first one. The rest are usually noise until it is done.
A store with the embed off will often report several issues at once; only APP_EMBED_DISABLED
matters, because nothing renders at all until that is fixed.
NO_BLOCK_ADDED is only reported on themes that support app blocks. On a vintage theme there is no
block to add, and THEME_NOT_OS2 is the real reason — a bundle will not render there regardless of
what else is configured.
The offers.byType counts are worth reading alongside the issues. A store reporting
NO_ACTIVE_OFFERS with twelve offers has a scheduling problem, not an empty store.
get_offers
Purpose: List and search this store's offers.
When to use: For "what offers do I have", "which are live", or to find an offer's id before asking about it in detail.
Parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
query | string | No | Searches the offer name |
type | enum | No | One offer type — see below |
status | enum | No | active, scheduled, expired, draft, all |
limit | number | No | Defaults to 10 |
The six types, spelled as the tool expects them:
| Value | The offer you know as |
|---|---|
fbt | Frequently Bought Together |
volume-discount | Volume Discount |
mix-match-bundle | Mix & Match Bundle |
bundle-builder | Bundle Builder |
product-fixed-bundle | Product Fixed Bundle |
upsell | Product Recommendation |
Returns: each offer's id, name, type, status and discount, plus pagination.
The default limit is 10, not "all". On a store with fifty offers, "list my offers" answers with
ten of them and nothing in the wording says so. Ask for a higher limit, or narrow with type and
status, whenever a count matters.
status here is the offer's own state, not whether shoppers can see it. An active offer on a
store with the app embed switched off is active and invisible. get_setup_status is what answers
the second question.
get_offer_details
Purpose: Read the full configuration of one offer.
When to use: After get_offers, when the question is about how a specific offer is set up.
Parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
id | string | Yes | The id returned by get_offers |
Returns: name, type, status, discount type and value, start and end dates, and the products the offer applies to.
The id has to come from get_offers — it is not the offer's name and not anything visible in the
app's URL bar. An unknown id answers Offer not found rather than guessing.
get_analytics
Purpose: Bundle performance over a date range.
When to use: For revenue, order counts, attach rate, or which offers are earning.
Parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
start | YYYY-MM-DD | No | Defaults to 30 days ago |
end | YYYY-MM-DD | No | Defaults to today |
offer_id | string | No | Narrows the totals to one offer |
Returns:
| Field | What it is |
|---|---|
additional_revenue | Extra revenue attributed to bundles in the range |
bundle_orders | Orders that included a bundle |
total_orders | All orders in the range |
attach_rate | bundle_orders ÷ total_orders, as a decimal |
top_offers | The five offers that earned most, with their revenue and order counts |
currency | Always USD — see below |
Figures are in USD, whatever currency your store sells in. Orders are converted when they are
recorded, so a store selling in EUR gets USD totals here. An assistant that renders these under your
own currency symbol is mislabelling them — the currency field is in the result to prevent exactly
that, so it is worth asking which currency an answer is in.
Zero and "unavailable" are different answers. If the analytics warehouse cannot be queried, the
tool returns analytics_unavailable rather than zeros, precisely so that a temporary outage is
never reported to you as "you earned nothing". If an assistant says revenue is zero, it is worth
asking whether that was a real zero.
attach_rate is a decimal: 0.0842 is 8.42% of orders containing a bundle.
get_plan_status
Purpose: Report your plan and how much of it you have used this cycle.
When to use: For "what plan am I on", and — the more useful one — "why did bundles stop working part-way through the month".
Parameters: none
Returns:
| Field | What it is |
|---|---|
plan | The plan this store is on |
additional_revenue_used | Bundle-attributed revenue this billing cycle, in USD |
reset_date | When the cycle rolls over |
free_cap | The cap block, or null on plans with no cap |
When free_cap is present it carries cap, used, is_capped, near_limit and reset_date.
is_capped: true is the answer to "my bundles stopped mid-month". Once a capped plan reaches
its cap, running offers are switched off and cannot be activated again until the cycle resets on
reset_date. Nothing is broken — this tool is the fastest way to establish that, and it explains
an offer that reads as expired without anyone having touched its schedule.
near_limit turns true at 80% of the cap, which is the point at which it is still worth knowing.
This tool reports your own store's situation. It does not list plans or quote prices.
Related
- Tools reference — the compact list
- Recipes — these tools in sequence, on four real questions