get_funnel_analysis
The full session-based purchase funnel — sessions, product viewed, added to cart, checkout started, address, shipping, payment, order — split by any dimension you choose.
When to use it
Whenever you need to know where visitors drop out. This is the most important tool on the server, and segmentBy is the most important parameter on it.
Ask for it like this
You do not name the tool. These are questions that make an assistant reach for it:
Show me the funnel split by device.
Which traffic source has the worst checkout completion?
Is one device silently broken?
How to read the result
- Always run segmentBy: 'device' before concluding anything. A store at 1.3% overall was 2.0% on mobile and 0.0% across 1,145 desktop sessions — and the leak was at the top of the desktop funnel, not at checkout.
- Every step counts sessions, not events. A session that adds to cart four times counts once, so step-to-step ratios are true drop-off rates.
- biggestDrop names the single largest leak in each segment. sessionConversion carries a 95% Wilson interval and a sample-adequacy verdict.
- vsRestOfStore is a two-proportion z-test, so you can tell a real gap from noise without doing the arithmetic yourself.
- When a segment has zero orders, upperBoundIfZero gives the rule-of-three 95% ceiling on its true rate. That is how you prove a dead segment is genuinely dead rather than just small.
What will make you wrong
Caveats
- Address and shipping steps are not strictly nested — Shopify skips them for express and returning-customer checkouts — so a later step can exceed an earlier one. The response flags this rather than treating it as a bug.
- segmentBy: 'theme' is observational. It diagnoses why an A/B variant loses; it never decides which variant wins.
- segmentBy: 'country' only has data from 31 July 2026 onward. Earlier sessions fall into an unrecoverable unknown bucket.
Parameters
segmentBy
Split the funnel by this dimension. Start with device. entry_type buckets the landing page as home, product, collection, blog, page, cart or search.
deviceutm_sourceutm_mediumvisitor_typeentry_typecountrythememinSessions
Drop segments below this many sessions as uninterpretable. The response reports how many were suppressed.
Shared parameters it accepts
Documented in full on the tool reference index.
Date window — defaults to the last 30 days.
dateFrom
Start of the window, YYYY-MM-DD. Inclusive.
dateTo
End of the window, YYYY-MM-DD. Inclusive.
Every tool also accepts merchantId, which resolves from your connection. You never pass it.
What comes back
JSON. These are the top-level keys; date-scoped tools additionally carry a _meta block with the server date and the data coverage envelope.
storeWide
The unsegmented funnel, for reference.
segments
One funnel per segment, each with step counts, drop-off, biggestDrop, sessionConversion and vsRestOfStore.
countingBasis
Always "sessions" — a reminder that these are not event counts.
suppressedSegments
How many segments fell below minSessions, when any did.
segmentCaveat
Present for theme splits, explaining why the split cannot decide an A/B test.
dataQuality
The share of funnel events carrying a session id.