Technical guide

ChatGPT Ads conversion tracking for Shopify

A conversion setup is complete only when an ad click can be associated with a valid event that OpenAI accepts. This guide separates the attribution token, browser measurement, server delivery, and deduplication responsibilities.

1. Preserve the oppref parameter

OpenAI documents oppref as the click-attribution parameter used by its measurement tooling. Your landing page, redirects, locale selector, and storefront routing should not discard it before it can be captured.

https://store.example/products/item?oppref=example_click_reference

redirect check:
input URL  →  locale redirect  →  final product URL
oppref     →  must remain      →  must remain

The free EventProof checker adds a harmless test value and reports the final redirect URL.

2. Initialize browser measurement only with consent

The OpenAI Measurement Pixel supports setting consent before initialization. Your consent-management platform should decide whether measurement is allowed under the laws and policies that apply to the visitor.

oaiq("consent", false);
oaiq("init", { pixelId: "YOUR_PIXEL_ID" });

// After a valid consent signal:
oaiq("consent", true);

Do not place real identifiers in public repositories. If you use a Content Security Policy, allow only the exact OpenAI script and network origins listed in the current official pixel documentation.

3. Relay Shopify events server-side

A Shopify App Pixel can subscribe to standard customer events and send a minimal, consent-appropriate payload to your Cloudflare endpoint. Validate the store installation and payload on the server before translating the event.

import { register } from "@shopify/web-pixels-extension";

register(({ analytics }) => {
  analytics.subscribe("checkout_completed", async (shopifyEvent) => {
    const checkout = shopifyEvent.data.checkout;
    const attribution = await loadConsentApprovedAttribution(shopifyEvent.clientId);
    await fetch("https://your-relay.example/v1/shopify/events", {
      method: "POST",
      keepalive: true,
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        eventName: "checkout_completed",
        shopifyEventId: shopifyEvent.id,
        orderId: checkout.order?.id,
        clientId: shopifyEvent.clientId,
        occurredAt: shopifyEvent.timestamp,
        sourceUrl: shopifyEvent.context.document.location.href,
        oppref: attribution.oppref,
        obref: attribution.obref,
        currencyCode: checkout.currencyCode,
        totalAmount: checkout.totalPrice?.amount
      })
    });
  });
});

This is an illustrative shape, not copy-paste production code: loadConsentApprovedAttribution represents your own consent-aware lookup, not a Shopify API. The strict App Pixel sandbox cannot read a normal page cookie. Capture oppref and, for a hybrid Pixel/CAPI setup, the Pixel's __obref value in an allowed browser context, then associate them with a pseudonymous app record only when consent permits. The relay must handle the pixel sandbox's cross-origin request correctly and convert Shopify's decimal money value to the currency's integer minor unit. A production app also needs authenticated installation context, strict validation, rate control, retries, and Shopify's mandatory privacy webhooks.

4. Build the OpenAI CAPI request

OpenAI documents a POST endpoint under https://bzr.openai.com/v1/events, with the pixel ID in the query and an API key in the Authorization header. Batches can contain up to 1,000 events. For web events, include the source URL. Send monetary amounts in minor units.

const requestBody = {
  "validate_only": true,
  "integration_source": "eventproof_shopify",
  "events": [{
    "id": "stable-shopify-order-id",
    "type": "order_created",
    "timestamp_ms": Date.now(),
    "oppref": "original-opaque-value-if-available",
    "action_source": "web",
    "source_url": "https://store.example/thank-you",
    "user": {
      "obref": "original-browser-reference-if-consented"
    },
    "data": {
      "type": "contents",
      "amount": 2599,
      "currency": "USD"
    }
  }]
};

Start with validate_only. Ensure timestamps are within the accepted window in the current docs. CAPI does not capture oppref for you, so pass the original event-level value when available. In a consented hybrid integration, pass the unchanged __obref cookie value as events[].user.obref. Omit either optional field when unavailable; never fabricate one. For browser and server versions of the same conversion, reuse the same Pixel ID, event name, and event ID so the platform can deduplicate them. Custom events must also keep the same custom event name.

5. Verify a test order at every hop

6. Protect the data path

• Keep CAPI keys in Cloudflare secrets and never ship them to storefront JavaScript.
• Collect only identifiers the official API accepts and your consent basis permits.
• Bound payload sizes, reject unknown keys, and redact logs.
• Delete installation data after Shopify sends a valid shop-redact request.
• Use a queue or durable retry record for transient OpenAI failures. Never retry permanent validation errors forever.