WooCommerce server-side tracking: a setup guide

WooCommerce server-side tracking sends each paid order from your shop's order data to Meta, TikTok and other ad platforms, instead of relying only on a pixel in the shopper's browser. The purchase is reported even when an ad blocker stops the pixel or the shopper never reaches the thank-you page.

This guide covers why WooCommerce stores lose conversions, the order data WooCommerce gives you, and the two ways to connect ROASaurus: the WordPress plugin or webhooks. Then matching, consent, setup and testing. For the general idea, read what server-side tracking is.

Why do WooCommerce stores lose conversions?

A browser pixel reports a purchase only when the pixel script loads, the shopper reaches the thank-you page and the browser sends the event. Each step can fail. The order itself is still in your database, because WooCommerce saves it on the server.

Missing purchases do two kinds of damage. The ad platform optimizes on fewer conversions, and your reports show a lower return than you really get. Here is the second effect in numbers, for an example store with a break-even ROAS of 2.2:

What WooCommerce gives you: orders, webhooks and the REST API

Which order statuses count as paid?

WooCommerce describes processing as payment received, with the order waiting to be fulfilled. ROASaurus sends orders with the status processing or completed and skips pending payment, on hold, failed, cancelled and refunded orders. Two payment methods need attention:

• Cash on delivery. WooCommerce sets these orders to processing until the payment is collected, so ROASaurus sends them when they are placed. Orders with a downloadable product are the exception: they go on hold. See tracking cash on delivery orders for what that means for returns and refusals.
• Bank transfer. WooCommerce puts these orders on hold while you verify the payment. ROASaurus sends them when you move them to processing.

Webhooks

A webhook is a message WooCommerce sends to another system when something changes. You create it under WooCommerce › Settings › Advanced › Webhooks. For an order topic, the payload is the same order object the REST API returns. Each delivery carries an X-WC-Webhook-Signature header: a base64 HMAC-SHA256 hash of the payload, made with the secret you choose. ROASaurus checks that signature before it accepts an order.

Two details matter in practice. WooCommerce delivers webhooks in the background, with WP-Cron by default, so a delivery can be delayed when that queue runs late. And WooCommerce disables a webhook after more than five failed deliveries in a row.

REST API

The REST API lets ROASaurus ask for orders itself. With a read-only API key, ROASaurus asks every 5 minutes for processing and completed orders changed since its last check, with 30 minutes of overlap. Orders it already has are ignored. This catches any order a webhook missed.

Plugin or webhooks: two ways to connect

Both connections send every paid order. They differ in how well each order is linked to the ad click that brought the shopper in.

You can use both at once. The plugin saves the visitor id on the order as order meta data, and the webhook payload carries it along. ROASaurus stores each order once, by its WooCommerce order id, so the plugin and the webhook never create two purchases. The plugin also declares support for WooCommerce's High-Performance Order Storage.

How is a WooCommerce order matched to the ad click?

An ad platform can only credit a purchase to an ad when it can connect the two. ROASaurus does this by linking the order to the visitor who clicked the ad, and that visitor carries the click ids (such as fbclid and ttclid) and UTM parameters from the landing. It tries these methods in order and stops at the first one that works:

1. The visitor id saved on the order. Only with the plugin. This is an exact link.
2. The browser purchase on the thank-you page, which carries the same order id. Only with the plugin.
3. A hashed email the visitor gave earlier on your site, for example in a Klaviyo, Attentive or Wisepops popup form, or through an Identify call.
4. The same IP address and browser, seen from 3 hours before to 15 minutes after the order, but only when exactly one visitor fits. On shared networks, such as offices and mobile carriers, several visitors often share one IP address, and then ROASaurus does not guess.

ROASaurus waits briefly before it sends each purchase, so the thank-you page event can arrive first. If the order is still unmatched, it tries again at send time. The Orders page shows the result per order in the Matched by column. Orders linked by the plugin's visitor id show cart, the same label Shopify orders get.

Those click identifiers raise Meta's match rate for the event. Event Match Quality explains how Meta scores them.

Consent on WooCommerce

Each store in ROASaurus has the setting Respect visitor consent, which is on by default. On WooCommerce, the ROASaurus script reads the visitor's choice from the WP Consent API, which consent plugins such as Complianz and CookieYes fill in. It also reads Cookiebot, OneTrust, IAB TCF banners and Google consent mode. Until the visitor accepts marketing cookies, the script sets no visitor id and loads no browser pixels.

When a visitor declines, the script sets no visitor id, keeps no click ids and fires no browser pixels, and the plugin stores no tracking cookies on the order. The paid order is still sent from the server to your connected ad platforms with hashed customer data from the order and the order's IP address and browser. If your legal advice says purchase events also need prior consent, contact ROASaurus before you switch on server-side purchases. The consent help page has the details, and the post on Consent Mode v2 and GDPR covers the legal background.

How to set up WooCommerce server-side tracking

These are the steps for the plugin route:

1. Add the store

   In ROASaurus, go to Add a store, pick WooCommerce and enter the domain your customers visit.

2. Create an API key

   Open Store settings and, under Orders API, click Create API key. Copy the key right away: it is shown only once, next to your store key. The endpoint is the address in front of /api/v1/orders on that page.

3. Install the plugin

   Download the plugin and upload the zip in WordPress under Plugins › Add New Plugin › Upload Plugin, then activate it.

4. Enter the keys

   Under WooCommerce › ROASaurus, enter the endpoint, the store key and the API key, and save.

5. Connect your ad platforms

   On Tracking & platforms, use Connect with Facebook or Add pixel for Meta, TikTok and the others. Tick the option to also load the browser pixel, so the thank-you page purchase is deduplicated with the server event.

6. Set up consent and test

   Block the script in your consent tool until the visitor accepts marketing cookies, then place a test order.

Without the plugin, add the script tag from Tracking & platforms to every page, then create the webhook. The Connection tab of your store shows your webhook URL. Keep it private: anyone with the URL can send orders to your store.

WooCommerce › Settings › Advanced › Webhooks › Add webhook

Status        Active
Topic         Order updated
Delivery URL  (your webhook URL from the Connection tab)
Secret        (a secret of your choice; paste the same one in ROASaurus)
API version   WP REST API Integration v3

For the backup, create a key under WooCommerce › Settings › Advanced › REST API with read access. Paste the consumer key and secret on the Connection tab, save, and press Test connection. Fetch orders now pulls recent paid orders straight away. The WooCommerce integration page lists every option in one place.

How do you test WooCommerce server-side tracking?

Test the browser side first, then place an order and follow it to the ad platforms.

• Open your shop with ?roasaurus=connected in the address. An alert confirms that the script runs. With ?roasaurus=debug, the script logs what it sends to the browser console.
• In the Event log, under Collected events, page views should show a visitor id.
• Place a test order. Cash on delivery is the quickest, because the order is processing straight away.
• On the Connection tab, Last order received shows the time of the latest order.
• In the Event log, under Server deliveries, each connected platform gets a line with the status sent and the platform's response.

To see the event in Meta, paste the code from Events Manager › Test events into the Test event code field of your Meta pixel in ROASaurus. Remove it when you are done, because the code is meant for testing only. If the plugin cannot deliver an order, it adds an order note in WooCommerce that starts with "ROASaurus: order not sent", followed by the error.

Mistakes to avoid

• Using the topic Order created. Orders paid by redirect are created as pending payment. ROASaurus ignores unpaid orders, and no second "created" message follows when the payment arrives. Use Order updated.
• A secret that does not match. ROASaurus rejects a delivery whose signature does not match the secret it has. After more than five failures in a row, WooCommerce disables the webhook. Fix the secret, set the webhook back to Active and add the REST API key, so orders from the gap are fetched.
• Two tools sending the same pixel. If another plugin also sends your Meta or TikTok pixel, it uses its own event ids and the platform counts each sale twice. Switch it off for that pixel. See preventing double counting and duplicate purchase events.
• Expecting add-to-cart events. On WooCommerce the script tracks page views by itself. Product views and adds to cart are detected automatically on Shopify only. A developer can send them with a tlq track call.
• Expecting Google Ads conversions. ROASaurus sends Google Ads purchase conversions from the Shopify checkout only. From WooCommerce it sends purchases to Meta, TikTok, Snapchat, Pinterest, Reddit, X, Microsoft Ads, Taboola, LinkedIn and the other ad platforms you connect.
• Late bank transfers. Meta accepts server events up to 7 days after the event time. The plugin sends the order with the date it was created, so Meta rejects a transfer confirmed more than 7 days after checkout. Orders that arrive by webhook or the REST API use the paid date instead. Also note that the thank-you page fires the browser purchase at checkout, before the transfer is paid. If the payment is confirmed more than 48 hours later, Meta and TikTok cannot merge the browser and server copies, and a transfer that is never paid keeps its browser purchase.

Once orders flow, the attribution reports show which campaigns and ads they came from.

Sources

1. WooCommerce: Webhooks Documentation
2. WooCommerce REST API Documentation - WP REST API v3
3. WooCommerce: Order Statuses Documentation
4. WooCommerce: Cash on Delivery Documentation
5. Meta for Developers: Server Event Parameters

In ROASaurus

• WooCommerce integration
• Help: WooCommerce and custom websites
• Server-side tracking

Keep reading