Documentation

Getting started

OverviewQuickstartConnect ClaudeConnect ChatGPTConnect Cursor, Claude Code, VS Code

Core concepts

How it worksWhat gets collectedData freshnessMetrics and moneyGetting good answers

Reference

All tools37
Start here
get_cro_overviewget_opportunity_sizingget_anomalies
Funnel and conversion
get_funnel_analysisget_conversion_correlationsget_cart_analysisget_exit_analysisget_journey_patternsget_session_insights
Page and element diagnostics
get_top_issuesget_element_click_analysisget_page_dom_snapshotget_click_heatmapget_click_analysisget_page_vitalsget_page_performanceget_form_analyticsget_hover_analysisget_section_visibilityget_js_errorsget_page_templates
Products and discovery
get_product_performanceget_product_catalogget_product_changesget_search_analysisget_product_page_structure
Individual sessions
get_session_journeysget_session_summaries
Measuring a change
get_before_after
Custom events
get_custom_event_suggestionstest_custom_event_rulecreate_custom_event_rulelist_custom_event_rulesdelete_custom_event_ruleget_custom_event_definitionsget_custom_event_statsget_custom_events

Guides

Playbooks21Custom eventsPlans and limits

Support

TroubleshootingPrivacy and security

Custom events

The standard schema covers clicks, scroll, forms, errors and the whole commerce funnel. Custom events are for the thing specific to your store: a size chart, a subscription toggle, a configurator step, a video play.

Growth plan and above

Free stores drop custom events at ingestion, so a rule created there can be listed but never records anything. The standard schema and every core tool stay available on Free. See Plans and limits.

Three ways to fire one

Rules
Created through MCP. No theme edit at all. The tracker picks the rule up within about 60 seconds. Best default.
HTML attribute
Add data-cc-track="event_name" to an element in the theme. Fires on click. No JavaScript.
JavaScript
Call window.clickContext.track(name, props) from your own code, for anything the first two cannot express.

The workflow

Do it through your assistant. The three-step sequence exists because a selector that matches nothing produces a rule that silently never fires — and you will not notice for a week.

  1. Find out what is worth tracking

    get_custom_event_suggestions reads real click volume and returns untracked elements that people actually use, with a suggested event name and a selector for each.

    What should I be tracking that I am not?

  2. Test the selector before you commit

    test_custom_event_rule matches the selector against your stored DOM snapshots and reports how many elements it hits, on how many pages. This is the step that stops a broken rule reaching your storefront.

    Test whether ".size-chart-btn" matches anything on my product pages.

    Compound selectors work — form button.primary, .product-page .size-chart. Sibling, attribute and pseudo-class selectors cannot be tested against snapshots, though they may still work at runtime. The response tells you which case you are in.

  3. Create the rule

    create_custom_event_rule needs an event name, a trigger type and the selector. The tracker picks it up within about 60 seconds. No theme edit, no deploy.

    Create a click rule called size_chart_opened for ".size-chart-btn" on product pages.

  4. Confirm it is firing

    list_custom_event_rules shows fire counts and the last fired time. A rule sitting at zero after a day of normal traffic has a selector that does not match — go back to step two.

Trigger types

click
Fires when any element matching the selector is clicked.
submit
Fires when a matching form is submitted.
visible
Fires when a matching element scrolls into view.

A rule can be scoped to a subset of pages with pageUrlPattern, which is a SQL LIKE pattern — for example %/products/%.

The HTML attribute route

If you would rather keep tracking in the theme, add the attribute to the element. It fires on click, and the attribute value is the event name.

<button class="size-chart-btn" data-cc-track="size_chart_opened">
  Size chart
</button>

An element carrying data-cc-track with no value fires element_clicked.

The JavaScript route

For events that are not a click on a selector — a configurator reaching a step, a video finishing, a validation failing:

window.clickContext.track("configurator_completed", {
  steps: 4,
  finish: "matte",
});

Calls made before the tracker finishes initialising are queued and flushed, so you do not need to wait for a ready event.

Reading them back

  1. get_custom_event_definitions first — it lists every event name your store has ever fired, with the property keys observed. Use it to discover names rather than guessing.
  2. get_custom_event_stats for the metrics, including the conversion rate of sessions that fired the event.
  3. get_custom_events for raw events with their properties, when you are debugging what is actually being recorded.

Correlation, not causation

A high session_conversion_rate on an event means people who did the thing also bought. It does not mean the thing caused the purchase — high-intent visitors do more of everything. Confirm with get_conversion_correlations before redesigning around it.

Limits

Event name
1 to 100 characters. Letters, digits, underscore, hyphen, period and colon.
Static properties
At most 50 keys, and under 10KB total.
Rules per store
100.
Propagation
About 60 seconds, both for creating and for deleting.
Deleting a rule
Stops collection. Events already recorded are kept.

Naming

Use object_verb in the past tense — the convention the suggestion tool follows and the one that stays readable at fifty events: size_chart_opened, bundle_selected, warranty_expanded. Avoid names that describe your implementation rather than the shopper's action.