OpenAI Ads Conversions API: WordPress Setup Guide

Set up the OpenAI Ads Conversions API on WordPress: server-side events, pixel comparison, event IDs, deduplication, WooCommerce, forms and debugging.

Last updated: 3 September 2026. Written by PixelBridge team.

On WordPress, that usually means sending an event after a form, booking or order is confirmed, instead of relying only on a script in the browser. The API does not read oppref from the landing URL for you. Pass the original value when you still have it. PixelBridge can send these server events and keep them aligned with the browser pixel.

What the Conversions API is

The Conversions API is a server-to-server path. WordPress, or another backend, sends a supported conversion event after it already knows the action succeeded. The browser does not have to be the only messenger.

It is not a second advertising account, and it is not a replacement for campaign setup. It is a delivery method for measurement events. Official request fields, authentication and supported event types belong in OpenAI's developer documentation. Confirm those details before you build a custom client.

PixelBridge is independent from OpenAI. Using the Conversions API through the plugin does not create an official partnership.

Why server-side measurement matters

Browser pixels fail in ordinary conditions:

• The visitor refuses measurement cookies
• A browser or extension blocks the script
• Content Security Policy blocks the SDK domain
• The customer closes the thank-you page before the pixel runs
• A page builder or cache plugin reorders scripts

A server event can still record the conversion after WordPress has stored the form, booking or order. That resilience is the reason to add the Conversions API. It is not a reason to ignore the pixel. Page views and landing-page context still come from the browser.

Server-side delivery does not bypass consent. If measurement permission is required, keep the server event behind the same permission. See consent.

Pixel vs Conversions API

You can start with the pixel only. Add the Conversions API when browser delivery is not enough, or when purchases and bookings need a confirmed backend signal. Using both is a resilience choice, not a ranking tactic.

The pixel install guide is OpenAI Ads Pixel for WordPress. Product docs: Conversions API.

Deduplication

When the same conversion is sent from the browser and the server, measurement needs a way to treat them as one action. That mechanism is deduplication.

Without it, a successful checkout can become two purchases. With it, both payloads carry the same event ID and the advertising measurement system can collapse the pair.

Deduplication is only relevant when both layers send the same conversion. A server-only lead has nothing to merge. A browser-only page view should not invent a server twin.

Event IDs

An event ID is the shared key for a single customer action.

The intended WordPress pattern:

1. At the success hook, create or reuse one event ID.
2. Send the browser event with that ID, if the pixel is allowed to run.
3. Send the server event with the same ID, if the Conversions API is enabled and consent allows it.
4. Store enough of the ID in logs or diagnostics to debug a mismatch later.

If the browser event uses one ID and the server event uses another, you get duplicates. If you retry a failed server call with a new ID while the original browser event already succeeded, you can also get duplicates. Keep the ID stable for that conversion.

PixelBridge is designed to generate or reuse that ID so the pair can be deduplicated.

WordPress implementation

A WordPress Conversions API setup is a backend job:

1. Store API credentials in plugin settings or environment configuration, not in a public JavaScript file.
2. Listen to confirmed WordPress hooks, not to button clicks.
3. Build a payload that matches the current official event spec.
4. Include the event ID used by the browser event.
5. Respect consent before the request leaves the server.
6. Record success and failure instead of retrying blindly.

Typical sources:

• A confirmed form submission hook
• A booking confirmation hook
• A WooCommerce order status that means the purchase is real

Do not send server events from wp_footer on every page. That recreates the worst parts of a pixel with none of the page-view value.

WordPress documentation covers hooks and plugin architecture. It does not define OpenAI event fields.

WooCommerce

WooCommerce is a natural Conversions API source because the order exists on the server even if the customer never sees the thank-you pixel.

The event should:

• Fire on the order status you treat as a conversion
• Include an order identifier
• Include a conversion value where allowed
• Share an event ID with the browser order_created event

PixelBridge can send that WooCommerce event. You can also map the WooCommerce order hook yourself. Store setup stays in WooCommerce's documentation. The event notes are on the WooCommerce integration page.

Form submissions

Forms are the other common server-side source. A PHP success hook can send lead_created after the message is stored, which is more reliable than a JavaScript listener on the submit button.

PixelBridge connects Elementor Forms, Contact Form 7 and WPForms. Gravity Forms and Fluent Forms are not connected yet. A custom implementation should still fire once per successful submission and skip validation failures.

If the form also triggers a browser event, use the same event ID on both.

Debugging

Debug browser and server as a pair.

1. Confirm the pixel path still works. A broken pixel plus a broken API looks like "CAPI is down" when the real issue is consent or a Pixel ID mismatch.
2. Trigger one conversion.
3. Check whether a browser event was sent.
4. Check whether a server event was sent.
5. Compare event IDs.
6. Inspect the server response. Keep failures visible.

PixelBridge diagnostics are designed to show Conversions API connection status and recent event send status. A planned warning is "browser event was sent but server event failed". That check is planned, not claimed as shipped. See diagnostics and troubleshooting.

Common errors

Event names and required fields can change. When a payload is rejected, check official OpenAI documentation before changing WordPress hooks.

PixelBridge setup

PixelBridge can send Conversions API events from WordPress and keep them aligned with browser events.

1. Enter the Pixel ID and confirm browser measurement first.
2. Add Conversions API credentials in plugin settings.
3. Enable only the conversions you already trust in the browser, or that exist only on the server.
4. Confirm diagnostics show a connection and a single send per test action.

Product details are on PixelBridge for WordPress. For the wider measurement model, continue with OpenAI Ads conversion tracking.