Documentation
Shopify revenue attribution
In Settings → Revenue, select Shopify and copy the site's /api/webhooks/shopify/SITE_ID URL. In Shopify Settings → Notifications → Webhooks create JSON webhooks for Order payment (orders/paid) and Refund create (refunds/create). Save the signing key displayed in that store's Webhooks settings in AnalyticFast. For subscriptions created by an app through the API, save the app client secret instead. These credentials are different; do not paste a Storefront/Admin API access token. Use a separate store/app secret per analytics site. An app shared across stores shares a signing credential, so HMAC alone cannot separate those stores: use separate app credentials for this manual integration.
X-Shopify-Hmac-Sha256 is base64 HMAC-SHA256 over the exact request body. Shopify signs no timestamp. Financial IDs, scoped to site and provider, prevent duplicate revenue on retries and resends. Headers such as topic are routing hints, not signed data; resource shapes and financial status are also checked. Verification, admin-created webhooks, topics and examples.
Pass visitor IDs through the cart
Install the tracker first. Add this snippet in the theme, after it can load. It runs after deferred scripts on DOMContentLoaded and again when the visitor returns to the page. Call the same function after an AJAX cart is created if your theme creates carts lazily. Await its returned promise in your custom checkout handler before navigating to checkout; a quick checkout click can otherwise beat the asynchronous update. Do not block a customer's checkout if analytics fails.
<script>
async function saveAnalyticFastCartAttribution() {
try {
const ids = window.analyticfast?.attribution?.();
if (!ids?.ml_visitor_id) return;
const attributes = { ml_visitor_id: ids.ml_visitor_id };
if (ids.ml_session_id) attributes.ml_session_id = ids.ml_session_id;
await fetch((window.Shopify?.routes?.root || '/') + 'cart/update.js', {
method: 'POST', credentials: 'same-origin',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ attributes }), signal: AbortSignal.timeout(1500)
});
} catch (_) { /* Analytics must never break checkout. */ }
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', saveAnalyticFastCartAttribution, { once: true });
} else saveAnalyticFastCartAttribution();
window.addEventListener('pageshow', saveAnalyticFastCartAttribution);
</script>
The Ajax Cart API accepts { "attributes": { "key": "value" } } at the locale-aware POST /{locale}/cart/update.js. These cart attributes become order note_attributes, an array of {name,value}. Accelerated buy-now flows which bypass the cart need their own checkout integration; confirm the IDs arrive on a real paid order. Cart IDs are attribution hints, not authentication credentials. Respect your consent requirements.
Amounts, refunds and subscriptions
Paid orders use total_price_set.presentment_money when supplied, otherwise total_price with currency. Decimal money is converted exactly to integer minor units, including JPY and three-decimal currencies; currencies remain separate. The order's original total includes discounts, tax and shipping. Order edits/additional captures after the original paid notification are not incremental revenue in this order-based adapter; reconcile those on your server. Large Shopify integer IDs retain all digits.
Refund resources can be restocks without returned funds. Only transactions with kind=refund and status=success subtract money, once per transaction ID, linked to order_id. Pending/failed/suggested refunds do not subtract. A pending refund that later succeeds needs reconciliation if Shopify does not send another refund notification. Refund currencies must match their original; no implicit conversion occurs. Refund resource, transaction currency.
Each paid subscription order has its own order ID. The order payload has no reliable renewal flag; repeat-customer attribution recognizes later purchases through the customer ID. It cannot distinguish a repeat one-time purchase from a renewal. Customer IDs are parsed; webhook emails do not identify a visitor or get persisted as consented PII. Optional product filters use product IDs and include a whole order when any line matches.
Send test event is a deterministic local preview and writes no revenue. Use Shopify's signed delivery test plus a paid test order and refund in a dedicated analytics site for end-to-end validation. Official references reviewed 2026-11-12.