Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Fetch Sitewide Analytics

post

Get Sitewide Conversion Funnel

Retrieve the sitewide conversion funnel as a Sankey graph: visitors flow from entry point → landing page → second page → cart → checkout → conversion. The step-1 entry-point nodes default to device type (Mobile / Desktop); set audience to pivot step 1 on traffic source, visitor type, or source site instead. Top-5 bucketing per step plus catch-all Other / Bounced rollups happen server-side; the wire format is already aggregated.

POST /v25-10-beta/analytics/sitewide/conversion-funnel

Request

Field
Required
Type
Notes

start

no

ISO 8601 datetime string

Beginning of the analysis window. Defaults to 30 days ago.

end

no

ISO 8601 datetime string

End of the analysis window. Defaults to now.

filters

no

filters object

Shared sitewide filters that narrow the underlying dataset — deviceType, visitorType, sourceSitesOrChannels, countryCodes, currencyCodes, onlyProductIds, landingPageFilters (preferred; landingPage is deprecated), landingPageTypes, etc. See the Filters Reference for the full list.

audience

no

string enum

Pivots the funnel's step-1 entry-point dimension — it controls which buckets are rendered at step 1, not which sessions are included. One of "device_type", "visitor_type", "source_channel", "source_site". Unrecognized values silently default to "device_type". See "Audience vs. filters" below.

conversionFunnel

no

conversionFunnel object

Funnel-specific filters. Stage flags + single landing/second page-type pins. See "Funnel-specific filters" below.

The conversionFunnel object

All funnel-specific filtering lives in a single optional conversionFunnel object. All fields are optional; combine any subset.

Stage flags (boolean) — narrow the funnel input to sessions that hit a behavioral stage:

  • addedToCart — sessions that added at least one item to cart

  • startedCheckout — sessions that started checkout

  • converted — sessions that converted

  • bounced — sessions that bounced (no second page)

  • abandonedCart — added to cart but did not convert

  • abandonedCheckout — started checkout but did not convert

  • exitedBeforeAtc — exited before adding to cart

  • viewedCollectionPage — viewed a collection page

  • viewedProductPage — viewed a product detail page

Page-type pins (landing-page enum) — pin the funnel to a single journey:

  • landingPageType — restrict to sessions whose landing page was this type

  • secondPageType — restrict to sessions whose second page was this type

Supported page-type values: "PDP", "Collection", "Content", "Blog", "Homepage", "Search", "Cart", "Other".

Funnel-specific vs. shared filters

Two distinct layers of filtering, and they behave differently:

  • filters.landingPageTypes (plural, array, inside the shared filters object) — narrows the underlying dataset to sessions starting on any of the selected page types. Same as the other /sitewide/* endpoints.

  • conversionFunnel.landingPageType / conversionFunnel.secondPageType (singular) — pin the funnel itself to a specific journey, so a caller can see how the PDP → 2nd-page-PDP path converted in isolation.

  • conversionFunnel stage flags (addedToCart, converted, etc.) — narrow the input population to sessions that hit a specific behavioral stage. Equivalent to the clickable node filters in the Intelligems dashboard.

conversionFunnel reuses the same schema the Intelligems dashboard sends internally, so the external contract matches the dashboard's funnel filtering exactly.

Audience vs. filters

audience and the shared filters look related but do completely different things. The simplest way to keep them straight:

filters change which sessions are included in the funnel. audience changes which buckets are shown at step 1. They don't filter the same way — in fact, audience doesn't filter at all.

Concrete contrast:

  • filters.deviceType: "mobile" → the funnel is computed over only mobile sessions. Every step in the response reflects mobile-only counts. Desktop sessions are gone from the dataset entirely.

  • audience: "device_type" → the full dataset (mobile + desktop) is funneled, but step 1 of the Sankey is split into "Mobile" and "Desktop" nodes so you can see how each device cohort flows down. Nothing is filtered out.

Two questions, two different answers:

Question
Use

"How does the funnel look for mobile traffic specifically?"

filters: { deviceType: "mobile" }

"How does the funnel split between Mobile and Desktop visitors at the entry point?"

audience: "device_type"

"How does the funnel split by channel, restricted to mobile US traffic?"

both: audience: "source_channel" + filters: …

They compose without conflict — audience controls the rendering of step 1, filters controls what data feeds into the funnel in the first place.

Supported audience values

audience value

Step-1 nodes

"device_type"

"Mobile", "Desktop"

"visitor_type"

"New", "Returning"

"source_channel"

Channel buckets: "Paid Social", "Paid Search", "Direct", "Organic Social", "Email", "Other", …

"source_site"

Referrer host buckets ("google.com", "facebook.com", …) with top-5 + "Other" rollup

These four mirror the Customer Journey chart's audience selector exactly. The shared AnalyticsAudienceType enum also has country_code and landing_page_full_path values, but the funnel intentionally excludes those — they're not surfaced in the dashboard's funnel view, so the external API and MCP do not expose them either.

Fallback on unrecognized values

If audience is set to any string outside the four supported values (e.g., "country_code", "channel", "new_vs_returning", a typo), the request does not 400 — the value silently falls back to "device_type" and a warning is logged server-side. This is deliberate so that LLM-driven callers that guess slightly-wrong dimension names still get a sensible funnel back instead of an opaque validation error.

When audience is omitted entirely, the funnel uses its built-in default step-1 split (the same default the dashboard's Customer Journey chart starts on).

Response

Abbreviated example (one path through all six steps). Note every node referenced by a link appears in nodes, and step numbers are contiguous — a real response has more nodes/links per step:

Every node a link references is present in nodes, steps run 1→6 with no gaps, and each link.step equals its source node's step. pct values are all fractions of the step-1 total (10,000 here).

  • nodes — one entry per labeled state at each step. Ordered by (step ascending, value descending).

    • name — node label (e.g. "Mobile", "Landing: PDP", "Bounced", "Added to Cart").

    • step — 1-indexed step position in the funnel.

    • value — visitor count at this node.

    • pct — share of step-1 visitors that reached this node, as a fraction in [0, 1] (not a percent).

  • links — one entry per transition between adjacent step nodes. Ordered by (step ascending, value descending).

    • source / target — node names on either end of the transition.

    • step — step of the source node.

    • value — visitor count traversing this link.

Server-side bucketing

At each step the server keeps the top 5 entries by traffic and rolls everything else into "Other". Two special node names are reserved:

  • "Bounced" — sessions that ended before reaching a second page.

  • "Landing: Other" / "2nd Page: Other" — catch-all buckets for low-volume landing or second-page types.

This is the same shape the Intelligems dashboard renders; there is no "unbucketed" mode.

Rate limits

Same rate limit as the other /analytics/sitewide/* endpoints. Aggregated, cacheable data — see the Rate Limiting Reference.

Body
startstring · date-timeOptional

Start of analysis period as an ISO 8601 datetime string (e.g. '2025-01-01T00:00:00.000-05:00'). Defaults to 30 days ago.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
endstring · date-timeOptional

End of analysis period as an ISO 8601 datetime string. Defaults to now.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
audiencestring · enumOptional

Optional dimension that pivots the funnel's step-1 entry-point nodes. This does NOT filter the dataset — it only changes which buckets are rendered at step 1 (Mobile vs. Desktop, New vs. Returning, channel breakdown, source-site breakdown). To narrow the dataset to a single segment, use the filters object instead. Supported values: 'device_type' (Mobile vs Desktop), 'visitor_type' (New vs Returning), 'source_channel' (Paid Social, Paid Search, Direct, ...), 'source_site' (referrer host buckets). Any other value (typo, unsupported dimension, wrong type) silently falls back to 'device_type'. Mirrors the Customer Journey chart's audience selector in the Intelligems dashboard.

Default: device_typePossible values:
Responses
200

OK

application/json
post/v25-10-beta/analytics/sitewide/conversion-funnel
200

OK

post

Retrieve order value distribution data and unit mix breakdowns for a time window.

The response returns orderValueDistribution.kernel_density_estimate and orderValueDistribution.cumulative_distribution_function, plus orderBreakdown.

Body
startstring · date-timeOptional

Start of analysis period as an ISO 8601 datetime string (e.g. '2025-01-01T00:00:00.000-05:00'). Defaults to 30 days ago.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
endstring · date-timeOptional

End of analysis period as an ISO 8601 datetime string. Defaults to now.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
Responses
200

OK

application/json
post/v25-10-beta/analytics/sitewide/order-distribution
200

OK

post

Retrieve sitewide snapshot metrics for a time window.

The optional feature parameter is an object, not a string enum.

Use { "name": "performance" } for the core KPI subset, { "name": "audience", "audience": "device_type" } for audience snapshots, { "name": "order" } for order-focused snapshot metrics, or { "name": "conversion" } for conversion funnel snapshot metrics. Omitting feature entirely returns the full sitewide metric set.

Response Structure

The response is a JSON object keyed by segment name, not a flat object with top-level metric fields.

When no audience feature is specified (or feature.name is "performance", "order", or "conversion"), the response contains a single "All" key:

{
  "All": {
    "currency": "USD",
    "n_visitors": { "value": 52763, "pct_change": 0.12 },
    "conversion_rate": { "value": 0.034, "pct_change": -0.05 },
    ...
  }
}

When feature.name is "audience", the response contains one key per audience segment plus a "__total" key:

{
  "Desktop": { "currency": "USD", "n_visitors": { "value": 30000, "pct_change": 0.08 }, ... },
  "Mobile": { "currency": "USD", "n_visitors": { "value": 22763, "pct_change": 0.18 }, ... },
  "__total": { "currency": "USD", "n_visitors": { "value": 52763, "pct_change": 0.12 }, ... }
}

Each segment object contains currency (string), the COGS metadata fields cogs_configured (boolean) and cogs_coverage_pct (number), and metric fields. The two cogs_* fields are present for the performance, order, and audience features but omitted for conversion. Each metric field is an object with value (number) and pct_change (number) representing the percent change versus the comparison period. In audience view, per-segment metrics also include pct_impact_to_total_change (number), and the __total segment additionally includes impact_from_visitor_mix_shift (number).

Alongside currency, every segment also includes two scalar COGS-status fields (not { value, pct_change } objects): cogs_configured (boolean — whether cost-of-goods data is configured for the store) and cogs_coverage_pct (number, a fraction in [0, 1] for the share of revenue with COGS data).

COGS-dependent profit metrics — gross_profit, gross_profit_per_visitor, and gross_margin_pct — are returned as a bare null (not a { value, pct_change } object) when cogs_configured is false. Clients must null-check these fields before reading .value/.pct_change.

Metric Availability by Feature

  • performance returns this KPI subset: n_visitors, conversion_rate, n_orders, aov, net_revenue, gross_profit, gross_profit_per_visitor, net_revenue_per_visitor, gross_margin_pct, average_discount, pct_revenue_with_cogs.

  • order returns this subset: aov, n_visitors, n_orders, median_order_value, average_units_per_order, pct_orders_with_free_shipping, net_shipping_revenue_per_order.

  • conversion returns this subset: viewed_collection_page_rate, viewed_product_page_rate, add_to_cart_rate, checkout_begin_rate, conversion_rate, bounce_rate, abandoned_cart_rate, abandoned_checkout_rate.

  • audience returns per-segment metrics plus a __total key: n_sessions, n_visitors, n_orders, gross_revenue, net_revenue, order_cogs, conversion_rate, aov, net_revenue_per_visitor, shipping_cost, transaction_fees, tax, gross_profit, gross_profit_per_visitor, oli_net_product_revenue_with_cogs, oli_net_product_revenue, pct_revenue_with_cogs.

Body
startstring · date-timeOptional

Start of analysis period as an ISO 8601 datetime string (e.g. '2025-01-01T00:00:00.000-05:00'). Defaults to 30 days ago.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
endstring · date-timeOptional

End of analysis period as an ISO 8601 datetime string. Defaults to now.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
featureone ofOptional

Optional feature selector object. Omit it or use { "name": "performance" } for sitewide KPI snapshots, { "name": "audience", "audience": "device_type" } for audience segment snapshots, { "name": "order" } for order-focused metrics, or { "name": "conversion" } for conversion funnel metrics.

or
or
or
Responses
200

OK

application/json
post/v25-10-beta/analytics/sitewide/snapshot
200

OK

post

Returns sitewide KPI time-series data with configurable granularity and optional audience segmentation.

Parameters

  • granularity — optional time bucketing: day, week (default), or month

  • feature — optional feature selector object:

    • { "name": "performance" } for the core KPI subset in an "All" segment

    • omit feature entirely for the full sitewide metric set in an "All" segment

    • { "name": "audience", "audience": "device_type" } for per-segment audience timeseries

    • { "name": "order" } for order-focused timeseries

    • { "name": "conversion" } for conversion funnel timeseries

dt Field Format

dt is returned as a formatted date string (not Unix epoch). Format is "YYYY-MM-DDTHH:mm:ss" for all granularities (day, week, and month).

Response Notes

  • Each data point contains dt plus one or more numeric KPI fields (for example: n_visitors, conversion_rate, n_orders, aov, net_revenue, gross_profit).

  • Each segment can include a summary object with aggregate totals in addition to the data array.

Body
startstring · date-timeOptional

Start of analysis period as an ISO 8601 datetime string (e.g. '2025-01-01T00:00:00.000-05:00'). Defaults to 30 days ago.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
endstring · date-timeOptional

End of analysis period as an ISO 8601 datetime string. Defaults to now.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
featureone ofOptional
or
or
or
granularitystring · enumOptional

Time bucket granularity. Supported values: day, week, month. Defaults to week.

Default: weekPossible values:
Responses
200

OK

application/json
post/v25-10-beta/analytics/sitewide/timeseries
200

OK

PreviousPerform Experience ActionNext07 Get Experience Export

Last updated

Was this helpful?