Embeddable widget

A branded lead-capture form you embed on your own site with one iframe. Referred friends fill in their details without leaving your page, and the referral is attributed automatically.

Embed the widget

Add the iframe wherever the form should appear:

HTML

<iframe
  src="https://offertown.net/widget/pub_YOUR_PROGRAM_ID?ref_code={REFERRAL_CODE}"
  style="border: none; width: 100%; height: 480px;"
  title="Refer a friend"
></iframe>

Parameter	Required	Description
`pub_…` (path)	Yes	Your program ID, from the partner dashboard.
`ref_code`	No	The 8-character referral code of the referrer, if known (for example, taken from the `ref_code` query parameter of the page the friend landed on). Pre-fills attribution.
`lang`	No	Two-letter language code for the form’s UI text.

Allowed origins

The widget (and its submission endpoint) only accepts requests from origins registered for your program. If you use the WooCommerce plugin, your site is registered automatically when you save the settings page; otherwise ask us to add your domains. Unregistered origins receive a 404 — by design, the API doesn’t reveal whether a program exists.

Which fields appear

The form always asks for the friend’s name and email. You can enable extra fields (phone, address, post code, city) per program in your widget configuration; consent is timestamped on submission.

Submitting programmatically

If you’d rather build your own form, POST directly to the widget’s endpoint from your page. The same origin allow-list and rate limits apply; no API key is used (this endpoint is meant for browsers, so it must never carry secrets).

POSThttps://offertown.net/api/widget/referrals

Request body

{
  "referralCode": "a1b2c3d4",        // required, 8 chars [a-z0-9]
  "friendEmail": "ana@example.com",  // required
  "friendName": "Ana",               // required
  "friendPhone": "+30 69…",          // optional
  "friendPostCode": "…",             // optional
  "friendAddress": "…",              // optional
  "friendCity": "…",                 // optional
  "sourceUrl": "https://your-site/…" // optional, page the form was on
}

Response — 201 Created (200 on idempotent resubmission)

{
  "ok": true,
  "referralId": "…",
  "idempotent": false
}

Idempotency: resubmitting the same referral code + friend email returns the original referral with idempotent: true instead of creating a duplicate.
Rate limiting: submissions are rate limited per program and per IP; a 429 response includes a Retry-After header.
Errors use the same shape as the REST API: { "error": { "code", "message", "fields?" } }.

What happens after submission

A pending referral is created and attributed to the referrer. The friend gets a confirmation message in the widget. When the friend later converts — reported by your store integration or the REST API — the referral flips to converted and the reward flow begins.