Documentation

OpenAI Ads oppref Attribution Explained

oppref is the click identifier OpenAI adds to an ad landing URL. The Measurement Pixel stores it so later events can still be matched to that click. Pass the original value unchanged.

Last updated: 2026-09-22. Written by PixelBridge team.

What is oppref?

oppref is an opaque, privacy-preserving click identifier that OpenAI adds to the landing page URL. The Measurement Pixel reads it so later conversion events can be matched to that click. You do not create the value, and you do not rewrite it.

The parameter contract is in OpenAI's Measurement Pixel and Conversions API documentation. This page is the WordPress reading of that contract.

When oppref is added

OpenAI adds oppref on the click to your site. It is not added by WordPress, by a form plugin, or by PixelBridge. If the visit did not come from an OpenAI ad click, the parameter will not be there. Do not invent a substitute.

How oppref reaches the landing page

The identifier arrives as a query parameter on the first URL the visitor opens. The Measurement Pixel has to run on that page, or on a later page that still has the value, before anything strips the query string.

A redirect that drops query parameters, a marketing plugin that rebuilds the URL, or a canonical redirect that runs before the pixel, can remove oppref before it is ever read.

When measurement consent allows it, the pixel stores the identifier in a first-party __oppref cookie. OpenAI documents a 30-day expiry from the moment the pixel writes the cookie. Each new non-empty oppref in the URL, including the same value again, resets that expiry to 30 days. Reading the stored cookie on a later visit that has no parameter does not extend it.

Browser settings can clear the cookie sooner. Calling the pixel's consent method with consent off removes __oppref and __obref. Cookie lifetime is not the same thing as the attribution window in Ads Manager.

How the Measurement Pixel uses oppref

You do not attach oppref to a normal browser measure call. The pixel captures it from the URL and includes it with later events while the cookie is valid. That is why the pixel has to load on the landing view, not only on a thank-you page that no longer has the query string.

oppref with the Conversions API

The Conversions API does not capture oppref for you. When you send a server event, put the original string on the event as oppref. OpenAI's field description says to pass that string without modification.

If you no longer have the value, omit it. An empty or edited value is not a click identifier. Server events still need a Pixel ID, an event name, a timestamp and the event data. See OpenAI Ads Conversions API.

WordPress implementation

On WordPress, keep three rules:

Let the landing page load the Measurement Pixel before a redirect or URL cleaner removes the query string.
Keep one Pixel ID per environment so a staging click is not mixed into production.
If a PHP hook sends the Conversions API event, read the stored oppref and pass it unchanged.

PixelBridge is designed to detect oppref and keep it available for later events when consent allows measurement. The plugin does not create the parameter. Install steps: OpenAI Ads Pixel for WordPress.

Redirects and oppref

Internal links usually drop the query string. That is fine after the pixel has stored the cookie. It is not fine on the first hop.

Preserve the full query string on any redirect between the ad URL and the page where the pixel runs. HTTPS redirects, www redirects, language redirects and trailing-slash redirects are the usual places the value disappears. A 301 that keeps the path but drops ?oppref= leaves you with a page view and no click identifier.

Query parameter cleanup

Some sites strip unknown query parameters for cleaner URLs or analytics. Do that only after the Measurement Pixel has read oppref on that request. Cleaning the URL in the browser after the pixel has stored the cookie does not erase the cookie.

Do not "normalize" the value. Do not move it into a different parameter name and expect the pixel to follow it. The pixel looks for oppref.

If measurement requires consent, set the pixel's consent state to off before it initializes, then turn it on only after permission. While consent is off, the pixel does not send measurement events. Turning it off removes the attribution cookies.

Do not copy oppref into your own long-lived store as a way around a refusal. Consent for the measurement stack is covered in consent. This is not legal advice.

Troubleshooting

Open a landing URL that actually includes oppref.
Confirm the pixel loaded on that first page, after consent if consent is required.
Move to a second page that does not have the query parameter.
Complete one test conversion.
Confirm the event still has the original identifier, in the pixel debug output or in the server payload.

If the second page has no identifier, the cookie was never written or was blocked. If the landing page never had the parameter, the visit was not an OpenAI ad click, or an earlier redirect removed it.

What happens when oppref is missing

Send the conversion anyway if it is a real action and consent allows it. Leave oppref out. Click matching for that visit will not have this identifier. Other matching fields, if you send them under the user object and they are allowed, are a separate mechanism. Do not backfill oppref from a previous visitor or from a hashed email.

View-through reporting, when the account has it, does not use a separate event field and does not depend on you adding oppref.

oppref vs obref

	oppref	obref
Purpose	Click identifier for attribution	Browser reference created for that site
Where it originates	Query parameter on the ad landing URL	The Measurement Pixel
Browser usage	Read from the URL and stored in `__oppref`	Stored in `__obref` and reused while valid
Server usage	Top-level `oppref` on the event	`user.obref` on the event
Should it be modified?	No. Pass the original string.	No. Pass it unchanged.
Should it be hashed?	No.	No. OpenAI's docs say not to hash it.

__oppref is documented with a 30-day cookie expiry that resets when a new parameter is captured. __obref is documented with a 365-day expiry from creation, and reading it does not extend that expiry. Both cookies are removed when measurement consent is set to off.