@ptengine/cart-attribution

Part of the Ptengine web packages monorepo. Which package do I need? Want full storefront analytics events too? Use @ptengine/hydrogen (Hydrogen framework) or @ptengine/hydrogen-react (Next.js etc.) — both already include everything this package does. Do not install this package alongside them.

Order attribution only. Zero dependencies. No analytics events. No framework required.

For headless merchants who run their own Ptengine instrumentation and only need Shopify orders attributed to Ptengine visitor sessions: this package keeps the five __pt_* identity fields written into your cart attributes, so the server-side checkout_completed events (generated by the Ptengine Shopify App from order webhooks) link to the right visitor. It never sends any analytics event — its only network calls are cart reads/writes against your own store's Storefront API.

Theme stores (Online Store) don't need this package — attribution there is automatic via the Ptengine App's theme extension.

Prerequisites

1. Ptengine tag installed on your storefront (this package reads the identity the Ptengine SDK stores; it does not load the SDK);
2. Ptengine Shopify App installed (registers the order webhooks that produce checkout_completed);
3. A public Storefront API token — the same one your headless storefront already uses for cart operations. Needs the unauthenticated_write_checkouts scope (cart mutations). To create a fresh one: Shopify admin → the Headless sales channel, or a custom app with Storefront API integration enabled. Public Storefront tokens are designed to be exposed in the browser — shipping it client-side is standard Shopify practice.

Install & use (any stack: Hydrogen, Next.js, Vue, plain JS)

npm install @ptengine/cart-attribution

import {initPtAttribution} from '@ptengine/cart-attribution';

initPtAttribution({
  ptengineId: 'YOUR_PTENGINE_ID',        // the {id} in js.ptengine.com/{id}.js
  storefrontToken: 'YOUR_PUBLIC_STOREFRONT_TOKEN',
});

Call it once on the client (React: a useEffect in your root component; plain sites: any module/script that runs in the browser). Returns a destroy function. SSR-safe — calling on the server is a no-op.

Everything else is auto-discovered:

| What | How it's found | Override | | --- | --- | --- | | Store domain | checkout links on the page / the clicked checkout link | storeDomain | | API version | pinned default (DEFAULT_SF_API_VERSION) | storefrontApiVersion | | Cart id | Hydrogen cart cookie → hydrogen-react localStorage | getCartId: () => id |

If auto-discovery can't resolve the cart id in your stack, pass getCartId — you know where your cart id lives.

Custom checkout domains are supported by auto-discovery. Checkout can only be served by a Shopify-managed domain, and Shopify-managed domains also serve the Storefront API (verified against production custom-domain stores) — so the hostname of a checkout link is a valid endpoint. Trust rules: a clicked checkout link is trusted on any domain (the visitor is navigating there with the full cart URL anyway); the DOM-scan (non-click) path only trusts checkout-shaped links on the current page's own hostname or *.myshopify.com, so injected foreign links can never receive your cart id. If your setup falls outside these rules (e.g. storefront on one domain, checkout on another, and you need the initial sync rather than the checkout-time guard), pass storeDomain explicitly.

How it works

• Initial sync: once identity + cart id + domain are available, it reads your cart's attributes, compares with the current Ptengine identity, and writes the five __pt_* fields if stale (your own cart attributes are always preserved — the package only manages __pt_* keys);
• Pre-checkout guard: clicking a checkout link re-checks the values and, if stale, briefly holds navigation (≤1.5s hard cap), writes, then continues. It never blocks checkout: your own click handlers always win (bubble-phase listener + defaultPrevented respect), modifier-key / new-tab / download clicks pass through untouched, one failed write disables interception for the session, and any exception restores native navigation immediately. Disable entirely with preCheckoutSync: false.

Options

| option | default | description | | --- | --- | --- | | ptengineId | required | Ptengine profile ID | | storefrontToken | required | your store's public Storefront API token | | storeDomain | auto | e.g. your-shop.myshopify.com | | storefrontApiVersion | pinned | Storefront API version | | getCartId | auto | function returning your cart id (gid or bare token) | | preCheckoutSync | true | pre-checkout guard on/off | | retryMs / maxTries | 1000 / 30 | initial-sync retry pacing | | debug | false | console logs + window.__ptAttribution |

CSP note

The package only calls https://{your-store}.myshopify.com/api/.... If your storefront ships a strict Content-Security-Policy (e.g. Hydrogen), allow your own *.myshopify.com in connect-src. No Ptengine domains are contacted.

GDPR note

No identity exists until your Ptengine tag runs (which you gate behind consent yourself) — without identity this package does nothing and sends nothing.