Skip to content

Track checkout.started in the VTEX checkout funnel#1

Merged
rockwellll merged 1 commit into
masterfrom
checkout-started-event
Apr 15, 2026
Merged

Track checkout.started in the VTEX checkout funnel#1
rockwellll merged 1 commit into
masterfrom
checkout-started-event

Conversation

@rockwellll
Copy link
Copy Markdown
Contributor

Summary

This PR adds checkout.started tracking to the VTEX checkout funnel so we can capture checkout entry in the environment where the storefront pixel cannot run.

The new event is triggered from the initial getOrderForm() load and subsequent orderFormUpdated.vtex updates, but it is deduped once per orderFormId per browser session. That gives us Shopify-like checkout entry semantics without relying on a VTEX hook that only fires on the first modifying request.

This change also keeps the event attribution safe and retryable:

  • checkout.started always carries the current checkout-shaped user payload, even when email or phone are not available yet, so the event does not inherit a stale remembered Hellotext identity from cookies
  • the dedupe marker is only stored after Hellotext.track(...) succeeds, and in-flight sends for the same orderFormId are suppressed so concurrent updates do not double-send the event

What Changed

Added a checkout-specific helper in src/checkout.js that tracks checkout.started, dedupes by orderFormId in sessionStorage, suppresses duplicate in-flight sends, and only marks the event as delivered after a successful Hellotext response.

Updated the checkout funnel entrypoint in src/funnel.js so the initial getOrderForm() load and orderFormUpdated.vtex both feed a shared order-form handler. The funnel still identifies the shopper when email or phone is available, and now also emits checkout.started with the normalized VTEX order and user payloads.

Expanded the funnel test coverage to verify the initial event, same-order dedupe, new-order retracking, pending-request suppression, retry-after-unsuccessful-response, and the anonymous-checkout case where we still send the current checkout user payload. The README and built dist/funnel.js bundle were updated to reflect the new behavior.

Why This Matters

Without this event, the VTEX SDK only captured shopper identification updates and the final order.placed event. We were missing the actual point where a shopper enters checkout, which is the key signal needed for abandoned-checkout attribution and parity with the Shopify pixel's checkout.started flow.

This PR adds that signal while keeping the VTEX implementation safe for real traffic. It avoids stale identity leakage from remembered Hellotext cookies, does not burn the dedupe key on failed requests, and prevents rapid VTEX updates from producing duplicate checkout.started events for the same order form.

Verification

  • yarn test
  • yarn build

@rockwellll rockwellll merged commit a982c69 into master Apr 15, 2026
2 checks passed
@rockwellll rockwellll deleted the checkout-started-event branch April 15, 2026 06:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant