Tool guide
Six tools. All read-only, none costs anything to call, and every one is scoped to the single store its key belongs to.
For the compact list, see the tools reference.
get_setup_health
Purpose: Report whether the cart drawer is actually working on this store.
When to use: First, whenever the drawer, a reward bar, or an upsell is described as "not showing". It reaches a conclusion rather than handing back raw data.
Parameters: none
Returns: normal (true when there is nothing wrong), the drawer's on/off status, the live
template, total impressions, and issues — each with a code and the fix for it.
| Code | Means |
|---|---|
APP_EMBED_DISABLED | The app embed is off on the live theme, so nothing can render |
THEME_NOT_OS2 | The live theme does not support app blocks |
CART_DRAWER_DISABLED | The drawer is switched off in the app |
APP_BLOCK_CART_MISSING | The app block is missing from the cart template |
APP_BLOCK_PRODUCT_MISSING | The app block is missing from the product template |
NO_SETTINGS | The store has no saved drawer settings |
NO_UPSELL_SETTINGS | Upsell is on but nothing is configured for it |
NO_TRANSLATION | No storefront wording has been saved |
NO_IMPRESSIONS | The drawer has never been shown to a shopper |
NO_IMPRESSIONS is the one worth reading carefully. Everything can be configured correctly and
still produce it — it means shoppers have not reached the drawer yet, which points at traffic or at
where the drawer is set to appear, not at a broken setup.
get_drawer_settings
Purpose: Read how the drawer is configured — which features are on, and how each is set up.
When to use: For "what does my drawer currently do", or before changing anything, to establish what is already there.
Parameters: none
Returns: whether the drawer itself is enabled, a flag per feature, the live template, primary colour, font and the store's currency — then a detail block for each feature:
| Block | What it carries |
|---|---|
rewardBar | The goal type, and each tier's reward, title and threshold |
upsell | Display settings, and the default rule slot by slot |
giftWrap | Price, product name and title |
shippingProtection | Price and title |
The upsell default rule
upsell.defaultRule lists the slots in the order the merchant arranged them in the Cart Editor,
with a count per source:
{
"slotCount": 6,
"slotsBySource": {"smart-pairing": 2, "specific-product": 2, "best-sellers": 1},
"slots": [
{"position": 1, "source": "best-sellers", "label": "Best sellers"},
{"position": 5, "source": "specific-product", "label": "Specific product",
"product": {"title": "Wool beanie", "handle": "wool-beanie",
"variantSelection": "all"}}
]
}Each slot carries both a source to match on and the label shown on the merchant's screen, because
the two are not the same word — what the Cart Editor calls Smart pairing is smart-pairing
internally.
Only a specific-product slot names a product. The other three sources pick their products at render time from the shopper's own cart, so there is nothing saved to list — an empty product list on those slots is correct, not missing data.
variantSelection: "all" means every variant is offered. It is not zero variants.
A specific-product slot reports the title and handle recorded when the merchant picked it, not a live Shopify lookup. A product renamed or deleted since still shows its original name here.
A store that has never been saved through the current Cart Editor comes back with slotCount: 0 and
a note saying so. That is not the same as having no upsell.
get_analytics
Purpose: Cart drawer performance over a date range.
When to use: For revenue, orders, AOV, or which upsell products are working.
Parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
start | YYYY-MM-DD | No | Store timezone. Defaults to 30 days ago |
end | YYYY-MM-DD | No | Store timezone. Defaults to today |
Returns: the date range actually used, the store's currency, total orders, revenue attributed to the drawer, average order value, abandoned cart rate, a revenue breakdown per feature — reward bar, upsell products, gift wrap, shipping protection — and the top upsell products.
The per-feature breakdown is the useful part. "The drawer made money" is not actionable; "the reward bar made most of it and gift wrap made none" tells you what to change.
Dates are in the store's own timezone, and both are optional — omit them for the last 30 days.
get_all_templates
Purpose: List every cart drawer template saved on this store, and which one is live.
When to use: For "what templates do I have", or to compare setups before switching.
Parameters: none
Returns: the saved templates and a marker for the live one.
get_translations
Purpose: Read the storefront wording the drawer shows buyers.
When to use: For "what text do my customers see in the drawer", or to check a translation.
Parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
template | string | No | Defaults to the template currently live |
locale | string | No | One language code, e.g. fr. Omit for all |
Returns: the template, which locales it has wording for, and two layers of wording:
| Field | What it is | Edited on |
|---|---|---|
text | The wording saved on the Design screen | Design |
translations | Per-language overrides | Translations |
text is what buyers see, and the fallback for every language with no translation of its own.
A store's own primary language usually has nothing in translations — there was nothing to
translate it from — which does not mean buyers see nothing.
On a store with several languages the full result can exceed the size limit. template cannot
narrow it any further — the payload is already one template — so language is the axis that
matters. Ask for one locale when a result comes back cut off.
get_plan_status
Purpose: Report the store's own subscription state and drawer usage.
When to use: For "which subscription is this store on", or "how many orders has the drawer handled".
Parameters: none
Returns: whether the subscription is paid, the pricing version, when the app was installed, and
ordersAttributedToDrawer.
ordersAttributedToDrawer counts orders this app recorded as going through the cart drawer,
since install. It is not the store's total order count, and it is not a figure to compare against
Shopify's own order numbers.
This tool reports your own store's situation. It does not list plans or quote prices.
Related
- Tools reference — the compact list, and the matching REST endpoints
- Recipes — these tools in sequence, on three real questions