Tool guide

What each tool is for, when to reach for it, and what it hands back. For the bare list, see the tools reference. For the REST equivalents, see Endpoints.

Start here

Three tools orient everything else.

get_store_context

Purpose. Reads the connection and the store before anything else: which cart drawer generation the store runs (v1 or v2), which template is live on v1, the subscription state, the connection's access level, the current settings revision, and whether the drawer has been set up.

When to use. First, before a change. A v2 drawer has no template choice and gets its look from a quick style, zone styles and a colour preset; that is how the assistant knows which tools apply.

Parameters. None.

get_setup_health

Purpose. Answers "is the drawer actually working?" Reports whether it is on, which template is live (v1), and a list of concrete problems with the fix for each.

When to use. Whenever the drawer, a reward bar or an upsell is "not showing".

Parameters. None.

Returns. normal (true when nothing is wrong), status, template, generation and issues. Each issue has a code, a severity, a message and fix steps.

Code	Severity	Meaning
APP_EMBED_DISABLED	Severe	The app embed is off in the live theme, so the drawer cannot load
THEME_NOT_OS2	Severe	The theme is not Online Store 2.0, so app embeds are unavailable
CART_DRAWER_DISABLED	Severe	The drawer is switched off in the app
NO_SETTINGS	Severe	The drawer's settings have never been saved; open the Cart Editor and save once
NO_TRANSLATION	Light	Drawer text has not been configured yet (optional)
NO_UPSELL_SETTINGS	Light	Upsell has not been set up yet (optional)

get_configuration_options

Purpose. Lists the choices that exist, with human labels: styles, block types, and the store's published languages. These are available options, not what is saved.

When to use. Before applying a style, preset or block. For quick styles and zone styles it also lists exactly which saved values applying one would overwrite (changesFromCurrent); for colour presets it lists customised colours that would be replaced.

Parameters.

Name	Notes
domain	styles, blockTypes, locales or markets
kind	With styles: quickStyle, zoneStyle, colorPreset or themeScheme
pageSize, offset	Paging

Reading the configuration

get_drawer_settings

Purpose. Reads how the drawer is set up: which features are on, the look, the reward tiers and their goals, the upsell rules and default slots, blocks, add-ons and validation.

When to use. Whenever the question is "what does my drawer do?", and before every change, to get the current revision and the stable ids that edits refer to.

Parameters.

Name	Notes
sections	Any of general, design, content, rewards, upsell, addons, validation. Omit for all
pageSize, offsets, cursor	Paging through tiers, rules, slots and blocks. A cursor alone continues what it was issued for
blockKey, htmlOffset	Read one imported block's HTML, in pieces if it is long
expectedRevision	Refuse the read if the settings changed since this revision. When you page, keep the revision from your first read

Returns. The sections asked for, plus the revision. Upsell rules are listed in the order they are checked: the first active rule whose conditions match the cart wins. Imported blocks include their HTML; when it will not fit, the result says so and gives its length.

get_translations

Purpose. Reads the wording shoppers see.

Parameters. locale (one language code, e.g. fr) and template (v1 only; defaults to the live one).

Returns. Two layers: text is the wording saved on the Design screen, which buyers see and which every untranslated language falls back to; translations holds per-language overrides.

Watch for. Several languages together can pass the 16,000 character cap. Ask for one locale.

get_all_templates

Purpose. Lists every template saved on the store and which is live. v1 drawers only.

Parameters. None.

get_plan_status

Purpose. Reads this store's subscription state and how many orders the app recorded as going through the drawer in the current 30-day cycle, with the reset date.

Parameters. None.

Analytics

get_analytics

Purpose. How the drawer is doing over a range: orders and revenue it drove, average order value, revenue by feature and the best-selling upsell products.

Parameters.

Name	Notes
start, end	YYYY-MM-DD, in the store's timezone. Default: the last 30 days. At most 400 days

Returns.

Field	Meaning
dateRange, currency	What was actually used
totalOrders	Orders in the range that went through the drawer
attributedRevenue	Sum of the features reported in revenueByFeature
aov	Average order value
abandonedCartRate	Share that did not convert, or null when there are too few checkout sessions (isAbandonedCartRateReliable is false and a note explains)
revenueByFeature	upsellProducts, giftWrap, shippingProtection, and rewardsBar only when the whole range is covered by reward-bar tracking
featureMetrics	Per feature: revenue, orders, change versus the previous period, attach rate
topUpsellProducts	Up to five products with order count and revenue
note	Anything the assistant should say alongside the numbers

Finding products, collections and discounts

These four tools exist so the assistant never guesses an identifier. Every write that takes a product resolves it live as well, so a wrong name is refused rather than saved.

Tool	Finds	Returns
search_products	Products by name (every word, case-insensitive; exact title first), handle, vendor or status. At least one is required; do not combine name and handle	Title, vendor, status, handle, product id
get_product_variants	One product's variants, by exactly one of name, handle or productId	SKU, option names and values, availability, variant ids
search_collections	Collections by name	Title, and whether the collection is published on the Online Store
search_discounts	Eligible Shopify code discounts by name	Discount titles for use as suggested discounts. Capped at 100, no continuation

search_products, get_product_variants and search_collections take pageSize and a cursor; a truncated response carries nextCursor. Two products with the same name need a vendor, a status or a handle to tell them apart.

Operations

get_operation_status

Purpose. After a write that did not finish cleanly, reads the state of that operation and the current storefront publication state.

Parameters. operationId, as returned by the write (optional).

retry_configuration_publication

Purpose. Re-publishes an already saved revision to the storefront. It never replays a settings change.

When to use. After a write returned publishPending. Read get_operation_status first and pass its current revision.

Parameters. expectedRevision (required): the current revision. If the settings have changed since, the retry is refused and you read them again first. requestId (optional).

Writing: how every change behaves

These apply to all 34 write tools. Read and write access is required.

• Read first. The assistant reads the current settings, takes the revision, and sends it back as expectedRevision. If the settings changed in the meantime, the write is refused with Cart drawer configuration changed from revision X to Y. Read it again before retrying. Nothing is overwritten.
• Repeat-safe. requestId lets a retried request be recognised, so a dropped connection does not apply the same change twice.
• Saved, then published. A committed change returns status: "saved" and the new revision. If publishing to the storefront fails, the result says publishPending: true and that the change is saved with publication queued for retry. Use get_operation_status and retry_configuration_publication.
• Confirmation for removals. remove_reward_tier, remove_upsell_rule and switch_template need confirm: true. A well-behaved assistant asks you first.
• Overwrites say so. set_quick_style, set_zone_style and apply_color_preset replace saved values. They point the assistant at get_configuration_options first so it can tell you which values change, and to wait for your answer.
• Drawer must be set up. If the drawer has never been saved, writes are refused with "Open Cart Editor, save its initial settings, then try again."
• One at a time. Writes are limited to 20 per minute per connection, and only one change to a store is saved at a time.

Features

Tool	Does
update_drawer_features	Turns the drawer, upsell, reward bar, announcement or shipping protection on or off. Other settings are kept. Takes a list of {feature, enabled} where feature is cart-drawer, upsell, reward-bar, announcement or shipping-protection. A request blocked by the store's plan is explained in the result

Rewards

Tool	Does
add_reward_tier	Appends a tier: rewardType (free shipping, order off, free gift), goalValue, optional title, icon, goalBySpecificCurrency. Order-off and free-gift tiers need an existing Shopify discount (discountCode or discountId). Returns a tierId
update_reward_tier	Changes fields on one tier, picked by tierId or tierName
remove_reward_tier	Removes one tier. Needs confirm: true
reorder_reward_tiers	Sets the full order from every tierId, each exactly once
update_reward_bar_settings	Reward-bar behaviour, market display, copy, layout and appearance. Several style fields apply to v2 drawers only

Upsells

Tool	Does
add_upsell_rule	Appends a rule. Triggers and recommended products are resolved live. Supply exactly one of triggerProducts or triggerConditions
update_upsell_rule	Changes selected fields of one rule by its id; other rules are untouched
remove_upsell_rule	Removes one rule. Needs confirm: true
reorder_upsell_rules	Sets the full order from every rule id, including drafts
update_upsell_default_slots	Replaces the ordered default slots and optionally their discount
update_upsell_settings	Presentation and behaviour: button action, auto-slide and its interval, hiding upsell-added products. upsellStyle 1 to 4 and the styled fields are for v2 only; v1 uses the legacy fields

Rule limits: name up to 60 characters; up to 20 trigger products; up to 5 recommended products; up to 5 conditions. status is active or draft. Discounts are a percentage, a fixed amount, or a fixed final price.

Add-ons

Tool	Does
update_gift_wrap_settings	Display, note and hide conditions. The configured gift product, variant and image are kept. A list of products or collections to hide it for replaces the saved list
update_shipping_protection_settings	Shopper copy, amount and selected image

Blocks

Tool	Does
update_block_settings	Turns a block on or off for the full or empty cart view. Imported blocks are identified by name
update_content_block_settings	Content and visibility fields for one block, such as the header or announcements
add_drawer_block	Adds a library block (blockType or name) or a custom HTML block (html, optional label), in a chosen view and zone. Exactly one of the three
update_imported_block	Replaces an imported block's html, or resetToOriginal: true
remove_drawer_block	Removes an imported block by blockKey or name
set_block_order	Reorders the visible blocks in one view and zone. Hidden and pinned blocks keep their place

Look

Tool	Drawer	Does
update_drawer_style	v1 and v2	Colour fields by hex value. Header, body and footer text, icon and line colours apply to v2 only
apply_color_preset	v1 and v2	Applies a colour preset. On v2 it overwrites drawer, reward-bar, upsell and validation colours, including custom ones
update_drawer_design	v1	Font family, header, product card and footer controls
switch_template	v1	Switches the live template, synchronises its upsell discount and publishes. Needs confirm: true. Open the Cart Editor first if the target template was never set up
update_zone_design	v2	Typography and geometry for header, product card and footer, and design toggles
set_quick_style	v2	Applies a quick style. Overwrites header, product-card and footer frame defaults; keeps colours
set_zone_style	v2	Applies one zone style. Overwrites that zone's frame values; footer style 3 hides the View cart button and Continue shopping link

Behaviour

Tool	Does
update_global_display_settings	displayMode (all, include or exclude), includeUrls, excludeUrls, disableCartPage. Each path matches exactly or as a path prefix; wildcards are refused
update_general_settings	Drawer behaviour, the Discount suggestions toggle and suggested codes (at most 4), and empty-cart content
update_cart_validation	The cart validation rule, its message, appearance and targets. Targets are named products, optionally narrowed to variants
update_sticky_cart	Sticky cart button visibility, layout, position, icon and colours

Wording

Tool	Does
update_wording	Base wording, the fallback every language uses. Plain text only
update_translation	Wording for one language, merged into what is there. Takes a standard locale code

Related

• Recipes
• Troubleshooting