Developer documentation

GWP puts a free gift from a partner brand in front of a shopper at the basket. The shopper picks one, claims it after checkout, and the retailer earns a share of the commission when the gift converts. There are exactly two integrations. Pick yours.

Retailer A retailer's developer

You put one script tag on the storefront and tell us how a script on the page can read the basket total. Everything else is configuration we hold for you.

Install the tag →

On Shopify? Start with the Shopify guide.

Advertiser A partner brand giving the gift

You capture a click id from the claim link and post it back from your server when the shopper converts. One authenticated POST, fired once per order.

Conversion API →

No SDK, no JavaScript, no inbound calls from us.

Evaluating Working out how much work this is

The moving parts explained once: the tag, basket-page detection, cart adapters, the claim moment, the click id and how commission is attributed.

How the integration works →

Read this first if any of the above is new.

The one-minute version

Retailer side

One tag, loaded async, on your basket template, or site-wide if you have a slide-out mini-cart or a single-page storefront:

<script async src="https://cdn.gwpingenuity.com/w.js" data-site="YOUR_SITE_KEY"></script>

Everything else is configuration held on your GWP account, not code you write. That covers which URLs are basket pages, where the block renders, how the cart total is read, branding and caps, and it can all be changed without you redeploying anything.

The tag never changes basket items or prices, is fail-silent by contract, and loads nothing from a third party: every request it makes goes either to cdn.gwpingenuity.com or to your own store's origin.

Advertiser side

We mint a click id when a shopper picks your gift and carry it on the claim link. When that click converts, you POST it back from your server:

POST https://cdn.gwpingenuity.com/v1/conversion

{
  "advertiser_key": "YOUR_ADVERTISER_KEY",
  "secret": "sk_…",
  "gwp_clid": "clk_4f8c1d2b3a90f1e7c6d5b4a39281706f",
  "advertiser_order_id": "ORDER-10231",
  "order_value": 42.50,
  "currency": "GBP"
}

order_value is required whenever your offer pays a percentage of the order; it is optional for flat-fee offers. The secret is server-side only. It must never appear in browser code, in a tag manager, or in a page a shopper can view.

Platform support

Platform	How the cart is read	Where the shopper claims	Status
Shopify (cart page and cart drawer)	DOM selector (proven), or `dataLayer`	Your own order-confirmation email: the tag stages `gwp_*` cart attributes and a Liquid snippet renders the claim block. Shopify's thank-you page is part of checkout and never loads your theme	Running in production
Custom / headless / in-house	`dataLayer`, a `window` global, or a DOM selector	Your confirmation page, or your own transactional email via the platform-neutral `gwp:selection` hook	Running in production
BigCommerce, Magento / Adobe Commerce, WooCommerce, Salesforce Commerce Cloud	Expected to work through the same three adapters (nothing in the tag is platform-specific)	Confirmation page, or your own email via the generic hook	We have not done one yet. Talk to us first

If you are on a platform in the last row, nothing about the tag is unusual — but we would rather scope it with you than let you find the gaps. Bring three things to that conversation: the URL patterns of your basket and confirmation pages, how a script on the page can read the current cart total, and where you want the claim to happen (confirmation page, or your own email). The platform guides set out what we would confirm for each.

Before you start

The code is small. The dependency on us is the part worth planning around, so here it is plainly.

What we hold versus what you build:

Thing	Who does it
Create the account, issue the site key	GWP only. Ask us
Decide which gift offers are live for your store	GWP, with you. Nothing renders until at least one is assigned
Registered domains (the `Origin` allow-list)	You, dashboard → Settings → Allowed domains (or ask us)
Basket / confirmation URL patterns, eligibility rules, cart-adapter type, mount points, cart-drawer selectors, consent mode, the Shopify order-email channel	You, dashboard → Install (or ask us)
Cart-adapter config: the `dom` total selector, an `orderIdSelector`	GWP only. There is no dashboard field for it today; send us the selector
Branding and on-widget copy	GWP only. The dashboard previews it; tell us what you want changed
Put the tag on the storefront, add mount points, wire the claim moment into your order email	You, in your own code. This is the whole of the engineering work

None of the middle rows are a redeploy: they are stored on your account and take effect on the next config fetch, bounded by our edge cache (see the install guide).

Also true before you write anything:

You need a site key. It is public and identifies your store to the config endpoint. It is not a secret and is safe in page source.
Your domains must be registered with us. The tag's POST endpoints check the browser Origin against your registered domains and refuse anything else, so a staging, preview or local hostname needs adding before it will work. Subdomains of a registered domain are covered automatically, which is also the tidiest way to develop locally (local development).
Check your CSP. One host covers all three fetch directives: https://cdn.gwpingenuity.com in script-src (or script-src-elem), connect-src and img-src. One caveat: the widget styles itself with inline style attributes plus a single <style> element inside its own shadow root, so a policy that restricts style-src without 'unsafe-inline' will render it unstyled. Tell us if that is your policy and we will scope it with you. Details in the install guide.
Nothing here is a secret except the advertiser postback secret. Site keys, click ids and claim URLs all live in the shopper's browser by design.

Reference

How the integration works. The moving parts, once: the tag, basket detection, cart adapters, gift selection, the claim moment, the click id, attribution.
Install the tag. The generic, platform-agnostic guide: snippet, page registration, all three cart adapters, the claim moment, browser verification, troubleshooting, CSP, device storage.
Platform guides: Shopify end to end (cart page, cart drawer, the order-email claim path), custom & headless, and what we would confirm on the platforms we have not shipped yet.
Conversion API: endpoint, auth, parameters, responses, idempotency, attribution window, reversals, worked examples.

Talk to a person

We would rather answer a question than have you guess at a parameter, and rather scope an unproven platform with you than have you find the gaps mid-sprint.

Email support@gwpingenuity.com with [INTEGRATION] in the subject line. The prefix matters: the same mailbox answers shoppers asking about a gift they claimed, and it tells us to put yours in front of an engineer instead of treating it as one of those. It is a monitored mailbox; we aim to reply within two working days.

Put these in the first email (usually the difference between one reply and four):

Your site key (retailer) or advertiser key (partner brand). Never your postback secret or pixel signing key. We never need them and cannot help faster for having them.
Every domain you serve from, including staging and any local dev hostname.
Your platform / stack, and whether the tag is going in directly or through a tag manager.
The exact URL you are testing on, what you expected, and what happened.
What you already tried — plus, if the widget is involved, the [GWP debug] console output and the /v1/config response body (how to get both).

Two things this mailbox is not. It is not a 24/7 incident line. If you need the gift block off your storefront immediately, removing the script tag is your own lever and it is instant; see switching it off for what we can and cannot do centrally. And /support is the shopper help page ("I didn't receive my gift") — send your customers there, not your developers.