Shopify

1. Install the storefront tag

Follow Install, using the same tag ID for your storefront and checkout.

Shopify theme: paste the tag before </head> in layout/theme.liquid.
Headless storefront: install the tag in your storefront app and add the checkout hook below.

2. Connect your checkout pixel

Get the verified pixel code for your tag ID from Thrad.
In Shopify admin → Settings → Customer events, open your existing Thrad pixel and replace its code. Create one only if you don’t already have one.
Save and Connect. Keep one active Thrad purchase pixel.

Keep your existing cart bridge until the replacement is verified. Check with Thrad before changing a working server integration.

3. Check a test purchase

Confirm that an authorized test order appears once in capture reporting with the correct amount, currency and traffic source. Ask Thrad to verify provider delivery separately.

Headless checkout hook

Add this to your existing checkout handler after the tag has loaded and been configured:

async function checkoutAttributedCart(request, tag, cart) {
  if (typeof tag?.checkoutShopifyCart === "function") {
    return tag.checkoutShopifyCart({
      request, cartId: cart.id, checkoutUrl: cart.checkoutUrl,
    });
  }
  window.location.assign(cart.checkoutUrl);
  return { status: "failed" };
}

// Call from your existing checkout button with the actual Storefront API cart.
await checkoutAttributedCart(storefrontRequest, window.thradTag, cart);

Use your existing Storefront client and cart:

request(query, { variables }) returns the parsed { data, errors } response.
cart contains the full id and checkoutUrl from that client.
Wait for other cart writes first, use fresh cart reads, and keep the client’s network timeout.
Keep private Storefront tokens out of browser code.

The helper saves attribution and opens checkout. Confirm saved on a test cart before replacing your working bridge. A saved cart is not a purchase receipt.

Reference and troubleshooting

How checkout handoff works

The helper preserves merchant attributes and replaces older attribution with the current signed Thrad, OpenAI-only or mixed context. It retries a request failure once and limits the checkout wait to three seconds. saved confirms the cart write; no_context means no new attribution; failed means an unconfirmed handoff. Checkout can still proceed after a failed write.Repeated helper calls on the same cart are serialized. A late write must finish before a newer write can start. Other tabs and merchant cart writers are outside this queue. A hung request can block later writes, so keep your client’s network timeout.Theme carts use Shopify’s AJAX cart. Headless carts use Storefront cartAttributesUpdate. Updating one does not update the other. Existing cartAttributes() integrations remain compatible.Cookies are a conditional recovery path: they may not reach a different checkout domain. Use the cart hook until your exact setup is verified. A complete cart snapshot takes priority over older cookies. An app installation does not add this hook to a headless storefront.Cart persistence is verified against the live Storefront API. Native pixel purchase receipt and deduplication checks are separate.

Pixel updates and fallback

The pixel loads https://cdn.thrad.ai/shopify/current.js, which Thrad can update centrally. If loading or initialization fails within three seconds, its bundled fallback handles purchases. A late script cannot create a second subscription.The fallback stays pinned to your installed code and still needs the collector. A critical fallback change may require another pixel update. Migrate to an app pixel only after its purchase receipt and shared order identity are verified.

Check attribution and troubleshoot

Test signed-only, OpenAI-only and mixed purchases, and reuse a cart after changing sources. Verify current attribution, preserved merchant attributes and one receipt. To test fallback, block the hosted runtime on a fresh authorized checkout and confirm mode: fallback.

Diagnostic	What to check
`runtime_ready`	Initialization only; check mode and versions.
`runtime_load_failed` / `runtime_timeout`	The fallback should report `runtime_ready`.
`missing_context`	Check the actual cart handoff. OpenAI traffic can have no signed cookie.
`missing_order` / `invalid_purchase`	Check the finalized order ID, amount, currency and timestamp.
`invalid` / `suppressed`	Ask Thrad to check validation, measurement configuration and existing privacy permissions.
`transient_failure`	Reconcile the order with Thrad before replaying it.
`queued` / `stored` / `duplicate`	Confirm the original order appears once with correct context.

A receipt does not prove provider acceptance or conversion credit. Don’t share raw checkout payloads, customer data, cart buyer keys, signed attributes or referral tokens in support logs.

Attribution fields

Keep incoming parameters unchanged through landing redirects. The tag captures signed Thrad and OpenAI context independently; a missing signed cookie does not establish organic traffic.

Source	Landing context	Checkout attributes
Signed Thrad	`thrad_click_id`, `exp`, `sig`, optional `thrad_bid_id`	`thrad_click_id`, `thrad_exp`, `thrad_sig`, optional `thrad_bid_id`
OpenAI reference	`oppref`	`thrad_oppref`, `thrad_oppref_exp`
Additional OpenAI context	`oppcref`, `__obref`	`thrad_server_context_v1`

Use all helper-returned attributes, including empty values that clear an older source. Don’t invent signatures, extend expiry or place customer data in attribution fields.

Getting Started

Attribution

Feeds

Advertiser API

API Reference

1. Install the storefront tag

2. Connect your checkout pixel

3. Check a test purchase

Headless checkout hook

Reference and troubleshooting

​1. Install the storefront tag

​2. Connect your checkout pixel

​3. Check a test purchase

​Headless checkout hook

​Reference and troubleshooting

1. Install the storefront tag

2. Connect your checkout pixel

3. Check a test purchase

Headless checkout hook

Reference and troubleshooting