Tool guide
What to ask, and which of the eleven tools answers it. You never name a tool yourself — Claude picks. This page is here so you can tell whether the answer you got came from the right place.
The words the tools use
The app has exactly four offer types, called placements. The tools take and return them by their admin names, so you can ask in your own words:
| Placement | Where it appears |
|---|---|
| Post-purchase upsell | After checkout, before the thank you page |
| Thank you page upsell | On the thank you page |
| Coupon offer | A discount code on the thank you page |
| Order status page upsell | On the order status page |
An offer is Active, Scheduled, or Expired — there is no other state. If you ask about drafts or archived offers, Claude will tell you those do not exist here rather than guess.
Question to tool
About your offers
| Ask | Tool |
|---|---|
| Show my post-purchase offers · Find my Spring Sale offer | search_offers |
| Which offer shows first? · What's my display order? | list_offers_by_priority |
| How many active offers do I have? | count_offers |
| Who sees this offer, and when does it run? | get_offer_detail |
| What does this offer actually sell? | get_offer_stages |
About your results
| Ask | Tool |
|---|---|
| How much extra revenue did I make last week? · What's my AOV lift? | get_offer_summary |
| How did each placement do? | get_offer_stats |
| Which offer converts best? · Which earned least? | get_top_offers |
| What are my all-time totals? | get_shop_lifetime_stats |
| Which offer types am I missing? | get_offer_coverage |
About what to sell
| Ask | Tool |
|---|---|
| What should I upsell with this offer? · What gets bought together with X? | recommend_products |
Four distinctions worth knowing
These are the places where a reasonable-sounding question has two different answers, and knowing which one you asked for saves confusion.
Display order is not performance. list_offers_by_priority tells you which offer shows first inside one placement. It says nothing about which earns most — that is get_top_offers. Priority restarts per placement, so there is no shop-wide "first offer"; if you ask without naming a placement, Claude will ask which one.
Setup is split in two. get_offer_detail answers who sees this and when — status, schedule, trigger conditions. get_offer_stages answers what it sells — products, discounts, bundle tiers, A/B variants. Trigger products are not upsell products, and the split exists so the two never get confused.
A ranking only contains offers that earned. get_top_offers is built from claim history, so an offer that made nothing in the period is absent from the ranking entirely — not ranked last. To see those, ask for offers sorted by lowest revenue instead. The same history is why a top earner can be an offer you have already deleted.
Period numbers and all-time numbers are different things. get_shop_lifetime_stats is all-time and matches the Home Statistics card. get_offer_summary is a date range and matches the Analytics dashboard. They are never subtracted from each other.
get_offer_stats are separate measurements, not parts of a total. Post-purchase counts views and claims on its first upsell only, while its revenue spans every slot — the columns do not share a denominator, so adding the rows up produces a number that means nothing. For a shop-wide roll-up, ask for the summary instead.Dates
- If you do not name a period, tools default to the last 30 days.
- A range cannot exceed 90 days. Ask for a year and the call is refused rather than silently trimmed.
- Days are counted on your store's timezone, the same as the Analytics dashboard, so "today" means your today.
- Dates are inclusive — to cover all of 14 April, the range ends on
2026-04-14.
Two things the numbers will not show
Coupon offers never accrue upsold revenue. A Coupon offer rewards a future order, which the app cannot attribute back, so revenue is omitted for that placement rather than reported as $0. Zero would read as a problem; absent is the truth.
Success rate and conversion rate are different rates. In the shop-wide summary, success rate is upsold orders divided by every order your store took in the period — the same tile the Analytics dashboard shows. It is a share of all orders, not an offer conversion rate. For conversion measured against views, use the all-time conversion rate in lifetime stats, or a single offer's acceptance rate in the top-offers ranking.
Starter questions
Copy any of these:
How much extra revenue did my post-purchase offers make last week?
Compare this month's AOV lift to last month's.
Which offers earn the most, and what's their accept rate?
Which offer types have nothing active right now?The app keeps the same list under Settings → AOV MCP → What you can ask.
Related
- Tool reference — every input and every returned field
- Troubleshooting