Skip to main content

Integration reference

Server-to-server postback

One request from your server when an order is confirmed. This is the method to choose: nothing in a browser can block it, delay it or fire it twice from a cache.

Keep the click id

A partner’s link brings the visitor through the tracking edge, which redirects them to your landing page and adds wo_click_id to the URL. That value is the whole of attribution: it is signed, and it carries the network, the offer and the partner inside the signature.

How your landing page is called
https://your-landing-page.example/?wo_click_id=<wo_click_id>
  • Store wo_click_id against the visit or the order as soon as the page loads. A thank-you page usually no longer has it in the URL.
  • You cannot construct one. A value the edge did not mint fails its signature check and the conversion is refused.
  • It is not a secret, and anyone who sees it can report a conversion against it. Send txn too, so that a sale can be found again and reconciled.

The request

A plain HTTP call with everything in the query string. Both GET and POST are accepted, on the hostname your network told you — the platform answers on its own name for a network that has not published one of its own.

A conversion, reported
GET https://tracking.wowmediametrics.pl/postback?click_id=<wo_click_id>&goal=signup&txn=ORDER-1&revenue=49.00
What the edge reads
ParameterRequiredWhat it is
click_idYesThe value we appended to your landing page. It is signed and carries the network, the offer and the partner inside it, so nothing has to be looked up to attribute the sale.
view_idOne of the twoThe same thing for a conversion earned by an impression nobody clicked. Only offers that credit views accept one; the rest refuse it rather than quietly treating it as a click.
goalNoWhich goal converted, as the wire key the network gave you. Leave it out on an offer with a single goal.
txnOn some goalsYour own order or transaction id. It is recorded with the conversion and is how either side finds this sale again later. It is not what stops a repeat being paid twice, except on a goal the network set to count every order, reported with a site key: there it is.
revenueNoWhat the sale was worth to you, as a decimal amount. The network prices the conversion from its own rule: on a percentage offer, what you are invoiced and what the partner is paid are each a percentage of this figure. It is stored as integer micros rather than as a float.
currencyNoThe three-letter code of the currency the order was paid in, read on every conversion call. It never chooses a currency: when a percentage rule is in another one, the conversion is recorded with no payout rather than converted. Leave it out and the value is taken to be in the currency of the rule that prices it. With a site key anything but three capital letters is refused; without one it is recorded with no payout instead.
ordered_atWith a site keyWith a site key only. When the order was placed, in unix milliseconds. It may be up to 5 minutes before the click or ahead of now, to allow for clocks that disagree, and at most 30 days old. The attribution window is judged from the click to this moment rather than to the moment the report arrives.
dry_runWith a site keyWith a site key only, and only the value 1. Runs every check and records nothing; see testing a connection below.

Connected shops: the site key

A shop connected to the network through the WordPress plugin reports with a site key, sent as a header: Authorization: Bearer wos_…. The key is issued in the advertiser panel when the shop is connected. It goes in the header and never in the query string, where every log between your server and ours would keep a copy.

Only the server-to-server postback reads it. The pixel and the SDK ignore it, because a key in a browser is a key anyone can read.

A conversion reported by a connected shop
POST https://tracking.wowmediametrics.pl/postback?click_id=<wo_click_id>&goal=signup&txn=ORDER-1&revenue=49.00&currency=EUR&ordered_at=1790000000000
Authorization: Bearer <your site key>
  • The address allowlist is skipped: the key says who is calling.
  • revenue must be a plain dot-decimal, up to twelve digits and six decimals, or the answer is 400. Without a key an unreadable amount is recorded as zero instead.
  • ordered_at is read. Without a key it is ignored.
  • dry_run is available for testing the connection.
  • The answer waits until the conversion is safely stored, so a 503 means the edge could not confirm it was: send the same report again.
  • A duplicate is remembered for 45 days rather than 48 hours, longer than any retry the plugin makes.
  • Goals set to count every order work, as described below.

Goals that count every order

A network may set a goal to count each order separately, so that a customer who buys twice after one click is two conversions. Reported with a site key, txn is then required on that goal, and a report without it is answered txn is required for this goal.

The event_id of such a conversion is the click id and the goal key, then :t, then the first 16 characters of the unpadded base64url SHA-256 of the exact bytes you sent as txn. It is a recipe, so you can compute it yourself.

The event id of the order in the example above
<wo_click_id>:signup:twdBag3h21oiSzJeB
  • The same order sent again is a duplicate; a different order from the same click is a new conversion.
  • Without a site key the same goal is still counted once per click.
  • An unusually large number of orders from one click, or one order reported from two clicks, are still recorded, and are flagged for the network to review.

Testing a connection

dry_run=1 with a site key runs every check a real report would pass and changes nothing: no duplicate is claimed, no budget is spent and no event is recorded. The answer says what the real report would be answered.

A test of one conversion
GET https://tracking.wowmediametrics.pl/postback?click_id=<wo_click_id>&goal=signup&dry_run=1
Authorization: Bearer <your site key>
What the test answers
{"status":"dry_run","would_be":"accepted","event_id":"<wo_click_id>:signup","duplicate":false,"goal_match":"matched","unpriced":false,"currency":"EUR","reason":""}
The same test with no click id: the key alone
{"status":"dry_run","site":"recognised","site_id":"…","offers":[1012]}

Without a key it is refused with dry_run requires a site key rather than ignored, because ignoring it would record, and bill, a conversion you meant as a test.

Goal keys

What you put in goal is a WIRE KEY, not the name anybody reads on a screen. A goal has a label the network can rename freely and one or more keys that never change unless somebody decides they should. Ask your network for the keys, and use them exactly.

  • A key the offer defines is priced by that goal’s own rule.
  • A key the offer does not define is recorded and paid nothing. The answer says so, and so does a header (X-Wo-Goal: unknown). The sale is not lost — the network can add the key as an alias and settle the difference — but nobody is paid for it until they do.
  • An offer that models no goals at all accepts anything and prices every conversion by its one blanket rule. Many offers are like this and nothing about them needs a key.
  • Leaving goal out is ordinary, not an error, and is recorded as such.
What an unknown key answers
{"status":"accepted","event_id":"<wo_click_id>:sale","reason":"this offer does not define the goal key \"sale\"; the conversion was recorded with no payout","unpriced":true}

A key is letters, digits, a dot, an underscore or a hyphen, up to 64 characters (/^[A-Za-z0-9._-]{1,64}$/). The network chooses them; you cannot create one by sending it.

What it answers

JSON, never cached. The sentences below are the exact bytes the edge writes, so you can match your own logs against them character for character.

Every answer the conversion endpoints give
AnswerWhat it saysWhat it is
200 acceptedRecorded, priced and paid according to the offer’s rule.
200 acceptedAlready seen: the same click id and goal key arrived before, or, on a goal that counts every order, the same order. The body also says so, and nothing is recorded a second time. Stop retrying.
200 acceptedthe conversion was recorded with no payoutRecorded, worth nothing. The goal key is not one this offer defines; the body quotes the key back and carries an explicit flag for a machine to branch on.
400 rejectedclick_id is requiredNeither a click id nor a view id was in the query string.
400 rejectedinvalid click_idThe id failed its signature check, or it is dated in the future. Which of the two is deliberately not said, because saying would help somebody forging one.
400 rejectedgoal must be at most 64 bytes and txn at most 128 bytes of UTF-8 text without control charactersThe goal key or the order id cannot be stored: the goal key is longer than 64 bytes, the order id longer than 128, or either holds a control character or bytes that are not UTF-8. Nothing is recorded, and sending the same report again gets the same answer. Every goal key a network can define fits.
200 rejectedunknown offerThe id is genuine but the offer behind it is not configured on the tracking server: archived before the tracking server began keeping archived offers for the conversions they owe, or longer ago than the longer of its click and view windows plus 30 days; an offer of a suspended or closed network; or an id from another environment. It cannot be priced, so it is not recorded. An offer archived more recently still records the conversions it owes, its connected shop’s included.
403 rejectedsource address not permittedThe address is not on the offer’s postback allowlist. The same answer whatever else the request contained.
403 rejectedthis offer accepts conversions only from its connected siteThe offer is connected to the advertiser’s WordPress shop, and only that shop reports its conversions. A postback or SDK call from anywhere else is refused, and so is an image pixel, whose answer carries this status in its header.
200 rejectedthis offer credits clicks onlyA view id arrived for an offer that credits clicks only. Refused rather than quietly credited as a click, which would pay for traffic nobody agreed to buy.
200 rejectedoutside attribution windowThe click is older than the offer’s window. Nothing is recorded and nothing is owed.
200 rejectedcap reachedA ceiling on this offer has been reached; the answer names which one and its period. Later conversions are refused until the period turns over.
503 retrydeduplication unavailableWe cannot currently tell whether this is a repeat, so nothing is recorded. This is the one answer that is our fault, and it is safe to retry.
503 retrycap check unavailableWe cannot currently tell whether this is within budget, so nothing is recorded. Safe to retry.
503 retryoffer configuration not loadedThis tracking server has not loaded the current configuration for this offer: it has just started, or the control plane is unreachable and the saved copy it serves meanwhile does not include the offer. Nothing is recorded. Safe to retry.
400 rejecteddry_run must be 1A test was asked for with a value other than 1. Nothing is recorded.
400 rejecteddry_run requires a site keyA test was asked for without a site key. Refused rather than ignored, because ignoring it would record and bill a real conversion.
200 acceptedcurrency mismatch: orderRecorded, worth nothing: the goal is paid a percentage in one currency and the order was paid in another. The full reason names both codes. Nothing is converted.
200 acceptedcurrency must be a three-letter code; the conversion was recorded with no payoutRecorded, worth nothing: the goal is paid a percentage and the currency sent was not three letters, so the order could not be read. Only a call without a site key gets this; with one the same currency is refused.
What only a call with a site key is answered
AnswerWhat it saysWhat it is
401 rejectedmalformed site keyThe header names a site key but it is not one: wrong length or wrong characters. Copy the key again from the advertiser panel.
401 rejectedsite key revokedThe key was revoked or replaced by a newer one. It will not work again; stop and connect the shop again.
503 retrysite key not yet knownThe key is not known to the tracking edge yet, usually because it was created seconds ago, or it is held while the advertiser’s account is paused. Nothing is recorded; retry after the 30 seconds the answer asks for.
403 rejectedoffer not connected to this siteThe key is genuine but the click belongs to an offer this shop is not connected to.
400 rejectedrevenue must be a non-negative dot-decimalThe amount is not a plain dot-decimal: no sign, no comma, no exponent, at most twelve digits and six decimals.
400 rejectedcurrency must be a three-letter codeThe currency is not three capital letters.
400 rejectedordered_at must be unix millisecondsThe order time is not a whole number of milliseconds.
400 rejectedordered_at is before the clickThe order time is more than 5 minutes before the click it is reported against.
400 rejectedordered_at is in the futureThe order time is more than 5 minutes ahead of our clock.
400 rejectedordered_at is more than 30 days agoThe order was placed more than 30 days ago, which is older than the edge will attribute.
400 rejectedtxn is required for this goalThe goal counts every order and the report named none. Send the order id and report it again.
503 retryevent stream unavailableThe edge could not confirm the conversion was stored safely. Send the same report again.
200 dry_runA test was evaluated. The body says what the real report would be answered and whether it would be a duplicate; nothing was recorded.
200 dry_runA test with a key and no click id: the key is valid, and the body lists the offers connected to it.
  • Retry only an answer whose status is retry. Anything else is settled, and retrying it changes nothing.
  • An accepted answer recorded with no payout because the currencies differ also carries X-Wo-Currency: mismatch, and one recorded with no payout because the currency was not a three-letter code carries X-Wo-Currency: invalid.
  • A conversion is unique per click id and goal key. The same pair sent again is accepted and ignored, which makes a retry safe — and means two separate purchases from one click against the same key are one conversion here, unless the network set that goal to count every order and you report with a site key; then txn tells them apart.
  • An accepted answer carries event_id: the click id and the goal key, joined by a colon. On a goal that counts every order, :t and 16 characters derived from txn follow. A duplicate answer carries the click id on its own.

Where postbacks may come from

A network can pin the addresses an advertiser’s postbacks arrive from. With none pinned, any address is accepted; with a list, anything else is refused with source address not permitted, and the refusal is the same whatever the rest of the request said. The address compared is the one that connected to the edge: a forwarding header such as X-Forwarded-For sent with the postback is not believed.

The window, and views

A conversion has to arrive while the click is still eligible. How long that is belongs to the offer, not to the request: there is no parameter that extends it, because that would let whoever fires the postback claim clicks of any age.

  • Too late is not an error on your side — it is answered as a rejection with a reason, and the sale simply earns nothing.
  • An offer that credits impressions mints a view id instead, reported back as view_id. Nothing puts it on the landing URL, and it is returned only in a response header of the impression pixel, which the page showing the ad cannot read, so there is no supported way yet for a view to reach a conversion. Its window is much shorter than a click’s, and an offer that credits clicks only refuses a view rather than counting it as one.