> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thrad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify

> Install the Thrad tag, connect your checkout pixel, and verify purchase tracking.

## 1. Install the storefront tag

Follow [Install](https://docs.thrad.ai/advertisers/attribution/tag/install.md), 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

1. Get the verified pixel code for your tag ID from Thrad.
2. 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.
3. **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:

```js theme={null}
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

> [accordion] 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](https://shopify.dev/docs/api/storefront/2026-07/mutations/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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.