Architecture brief
ChatGPT Ads for Shopify: build the conversion path that can be audited
The useful product is not another snippet injector. It is a traceable bridge from Shopify's customer events and orders to OpenAI's measurement endpoints, with consent, stable IDs, validation, retries, and reconciliation.
Recommended pattern: Shopify Web Pixel → app-controlled, CORS-enabled Cloudflare relay → OpenAI Conversions API. Add an order webhook as a purchase reconciliation path.
Why a direct browser snippet is fragile
Shopify App Pixels run in a strict web worker sandbox. They do not receive normal access to window or document. They can subscribe to Shopify customer events and use fetch, which makes an app-controlled, CORS-enabled relay the more dependable integration boundary.
A custom pixel has different constraints, but building the product around unrestricted page access creates a brittle promise. Treat browser measurement as one signal source and server delivery as the record you can monitor.
Event mapping for the first release
| Shopify standard event | OpenAI event | What to preserve |
|---|---|---|
page_viewed | page_viewed | Source URL and attribution context |
product_viewed | contents_viewed | Product identifiers and timestamp |
product_added_to_cart | items_added | Items, quantities, and cart value |
checkout_started | checkout_started | Checkout ID and value in minor units |
checkout_completed | order_created | Stable order ID, currency, amount |
The three records your dashboard should show
1. Captured
The event was received from Shopify with consent and required fields. This does not mean it was delivered.
2. Delivered
The relay submitted the event to OpenAI. Save the request timestamp, attempt count, response status, and a redacted validation result. Do not log access keys or unnecessary customer data.
3. Reconciled
The accepted purchase can be matched to the Shopify order using a stable event ID. A scheduled job can flag paid orders that have no accepted order_created record.
Important product limits
- A checkout-completed browser event can be missed if the completion page never loads. Order webhooks help reconcile this case.
- Do not promise recovery of attribution when the
opprefvalue was never captured. - OpenAI account capabilities and credential creation can vary. Ask the merchant to supply authorized measurement credentials.
- Refunds are not part of the currently documented supported-event list. Keep refund reporting separate unless the platform adds an official event.
Launch checklist
- Run the public Pixel Helper on the final landing URL.
- Configure consent-aware Shopify event subscriptions.
- Send a test payload with OpenAI CAPI validation enabled.
- Place one test order and compare Shopify, relay, and OpenAI records.
- Rotate credentials after any exposure and add an event-gap alert.
Primary references: Shopify Web Pixels, OpenAI Conversions API, and OpenAI supported events.