Skip to main content

Integration reference

The WooCommerce plugin

For a shop on WordPress and WooCommerce: a plugin that remembers which partner click brought a visitor and reports each paid order from the shop’s own server. Nothing to paste into a theme, and nothing a browser can block.

What the plugin does

When a visitor arrives from a partner link, the landing page address carries wo_click_id. The plugin keeps that value in a first-party cookie for as long as the offer’s attribution window, and when the visitor’s order is paid it reports the conversion to the network, retrying for up to seven days if the network cannot be reached.

What it sends is the server-to-server postback described on the previous page, authenticated with the shop’s site key. Everything that page says about duplicates, goals and the answers the network gives applies to it.

What the plugin needs
SoftwareAt leastTested up to
WordPress6.57.1
WooCommerce8.511.1
PHP7.4
  • WooCommerce must be installed and active: WordPress will not activate the plugin without it.
  • Your server must be able to make outbound HTTPS requests to the network’s API and tracking addresses.
  • Scheduled tasks must run, either through WP-Cron or through a real cron job that triggers it. Reports are sent in the background.

Getting the plugin

The plugin is downloaded only after signing in to the advertiser portal: open Set up tracking, choose WordPress, and the download is on the first step, with its version and its SHA-256 checksum.

Sign in to download the plugin

It is not in the WordPress.org plugin directory and it is not published anywhere else. If you have no advertiser login, your network’s staff can download it for you from their own panel.

Installing it

  • In WordPress, open Plugins, choose Add New Plugin, then Upload Plugin, choose the file you downloaded, press Install Now and then Activate.
  • The panel shows the file’s SHA-256. Computing it on your own computer and comparing tells you the file arrived intact. It is a checksum, not a signature.

Connecting the shop

  • In the advertiser portal, the second step of the WordPress setup creates a site key for your shop. It is shown once and cannot be shown again; if it is lost, rotate it.
  • In WordPress, open WooCommerce and then WOWOFFER, paste the key and choose a consent mode. The plugin will not connect until a mode is chosen.
  • Connecting changes what the network accepts for that offer: from then on the image pixel, the JavaScript SDK and any postback without the shop’s key are refused, and a refused postback is answered with this offer accepts conversions only from its connected site. Remove the other methods from your shop when you connect, so that each order is reported once.

Consent

  • You choose one of two modes when connecting: capture partner clicks only after the visitor consents to marketing cookies, or capture them without asking. Which one your shop needs is a legal question for you, not a technical one.
  • A cookie banner that supports the WP Consent API is always respected, whichever mode you chose: clicks are then captured only after marketing consent.
  • Consent given on a later page does not recover the click. The partner’s click arrives on the landing page, and if consent is not given there, that click is lost.

Testing the connection

  • Check connection asks the network whether it recognises the shop’s key. A new key can take about half a minute to be recognised everywhere.
  • Check this browser shows what the shop captured in your browser and what the network would do with it, without recording anything. Open a tracking link your network generated for this offer first, so there is a click to look at; ask your network for one.
  • Last conversion received shows the most recent conversion the network recorded for this shop.

When an order counts

  • An order counts when WooCommerce considers it paid, which by default is Processing or Completed.
  • Cash on delivery counts only when the order is Completed, because WooCommerce marks such an order Processing before any money has been collected.
  • Either rule can be chosen per payment method in the plugin’s settings.
  • Orders placed by shop staff and orders with a total of zero are not reported by default. Both can be switched on.
  • A customer who orders again after the same partner click is reported again. Whether the second order is paid depends on the goal: most goals count one conversion per click, and some count every order. Your network sets which.

What is sent

  • For each order: the partner click identifier, the order number, the order value, its currency and the time of the order. The value is taken on the basis your network set for the offer, by default products after discounts, without tax, shipping or fees.
  • On an offer priced as a percentage, you are invoiced the percentage agreed with your network of each order’s value as sent, not the order value itself. The partner’s share is between the partner and the network and is not shown to you.
  • No name, e-mail address, postal address or IP address is sent.
  • The click identifier and the order number are pseudonymous identifiers: together they link the order to the network’s record of the click, which holds the visitor’s IP address and browser details until retention removes them.
  • Anonymising or erasing an order in WooCommerce removes the plugin’s data from your shop. It cannot reach the network’s copy; ask the network to handle an erasure request for its records.
  • The network receives this data to attribute and pay for sales. Your agreement with the network, including a data processing agreement where one is needed, governs what it may do with it.

Refunds, cancellations and re-payments

After a paid order has been reported, the plugin also reports what happens to it next, from your shop’s server and with the shop’s key. The network applies each report according to where the conversion stands, or leaves it to its staff.

  • An order refunded in full is reported as a refund. An order that is cancelled, or whose payment fails after it was reported, is reported as a cancellation.
  • A partial refund is reported as a partial refund, with the amount refunded.
  • When partial refunds together reach the order’s total, the refund that reaches it is reported as a full refund.
  • When a cancelled or refunded order is paid again, the plugin reports a re-payment.
  • Nothing is reported for an order whose conversion was never sent. An order cancelled or refunded before its conversion was first sent is not reported at all, and neither is its conversion.
What the network does with each report
ReportThe conversion isWhat happens
Full refund or cancellationPending, within every limit belowRejected at once, as a chargeback. The network’s staff see every automatic rejection and can undo it.
Full refund or cancellationPending, outside a limitSent to the network’s staff to decide. Nothing changes until they do.
Full refund or cancellationApprovedSent to the network’s staff to decide. If the conversion is in a payout or on an invoice that has not gone out yet, rejecting it holds that payout or invoice back until it is rebuilt.
Full refund or cancellationApproved, and already paid to the partner or invoicedSent to the network’s staff to decide. Money already paid out or invoiced is recovered with a separate adjustment.
Full refund or cancellationAlready rejectedRecorded, and nothing changes.
Partial refundPending or approvedAlways sent to the network’s staff, who settle it by hand with an adjustment. The conversion’s amount is not changed.
Partial refundAlready rejectedRecorded, and nothing changes.
Re-paymentRejected by this shop’s refund or cancellation, and approved before itApproved again at once, unless an adjustment has been recorded on the conversion since it was rejected, or the order number in the report does not match the conversion’s. Either of those goes to the network’s staff to decide.
Re-paymentRejected in any other waySent to the network’s staff to decide. Nothing changes until they do.
Re-paymentPending or approvedRecorded, and nothing changes.

A refund or a cancellation is applied at once only when every one of these limits holds. Anything else goes to the network’s staff.

The limits on an automatic rejection
LimitValue
Oldest conversion that can be rejected automatically, in days60
Most a shop’s automatic rejections may reach, as a share of its pending conversions, in per cent20
The period that share is counted over, in hours24
How long a report that matches no conversion yet is retried, in days7
  • A full refund must carry its WooCommerce refund number.
  • The offer must accept conversions only from this shop.
  • The conversion must carry the same order number as the report.
  • If any conversion of the order has to be reviewed, none of them is changed automatically.

Nothing a report changes is hidden: every automatic change appears in the conversion’s history as made by the shop integration. A conversion never goes back to pending, so undoing an automatic rejection approves the conversion.

A report can arrive before the conversion it is about, for example when an order is refunded while its conversion is still being sent. The network keeps trying to match it for the number of days in the table above, and then closes it as unmatched.

Updates

  • Updates come only from the network’s own servers, and only to shops that are connected. An unconnected shop is offered none.
  • Every update is signed, and the plugin checks the signature before WordPress installs it. An update that fails the check is refused and the shop stays on its current version.
  • View details on the Plugins screen shows what changed: in Polish when your WordPress profile’s language is Polish, in English otherwise. Your profile uses the site’s language unless you chose another one.
  • Automatic updates follow WordPress’s own per-plugin switch on the Plugins screen. The plugin adds no setting of its own.

When something does not work

  • A page cache or a CDN must not strip wo_click_id from the landing page address: without it there is no click to keep. And purge the cache after connecting.
  • If WP-Cron is switched off and your only queue runner is wp action-scheduler run limited to one group, run wp action-scheduler migrate once first. Until WooCommerce’s Action Scheduler has finished moving to its own tables, such runs stop with The group "wowoffer" does not exist. and send nothing.
  • With DISABLE_WP_CRON set, nothing is sent unless a real cron job runs WordPress’s scheduled tasks every few minutes.
  • With WP_HTTP_BLOCK_EXTERNAL set, WordPress blocks outbound requests, and the network’s addresses have to be allowed for the plugin to report anything.
  • A security plugin that blocks anonymous requests to the REST API also blocks /wp-json/wowoffer/v1/touch, which the plugin uses on pages a cache served. Allow that one route.
What the network may answer the shop, and what to do
What it saysWhat to do
site key revokedThe key was revoked in the panel. Reports wait in the shop until it is connected again with a new key; an order more than 30 days old by then is refused.
site key not yet knownThe key is new and has not reached the tracking servers yet. Wait about 30 seconds; the plugin retries on its own.
offer not connected to this siteThe offer is not connected to this shop’s key. Connect it in the panel, or ask your network to.

Removing the plugin

Deleting the plugin, whose folder is wowoffer-woocommerce, removes its settings, its stored key and its scheduled tasks. The tracking details stored on orders stay, as part of your order records.