Offertown integration docs
Everything you need to connect your store or app to an Offertown referral program: a no-code WooCommerce plugin, an embeddable lead-capture widget, and a REST API for full programmatic control.
Choose an integration path
| Path | Best for | Effort |
|---|---|---|
| WooCommerce plugin | WordPress/WooCommerce stores. Syncs sales, coupons, and leads automatically. | No code — install and paste your program ID |
| Embeddable widget | Any website. A branded referral form referred friends fill in on your site. | One iframe snippet |
| REST API | Custom checkouts, CRMs, and backends. Create referrals and report conversions server-to-server. | A few HTTP calls |
The paths compose: many partners embed the widget for lead capture and use the API or plugin to report conversions.
Core concepts
Programs and credentials
- A program defines your rewards: the referrer reward, an optional friend reward, and the confirmation (maturation) period.
- The program ID (
pub_…) is a public identifier used by the WooCommerce plugin, the widget, and the tracker script. - The API key (
oft_…) is a secret used only for the REST API. Keep it server-side; never ship it in browser code.
Both are available in your partner dashboard.
The referral lifecycle
| Status | Meaning |
|---|---|
clicked | A friend followed a referral link; no details captured yet. |
pending | The friend is identified (via the widget, the plugin, or the API) but hasn’t converted. |
converted | A qualifying purchase or action happened and was reported with its value. |
expired | The attribution window passed without a conversion. |
Attribution
Referral links set a 90-day, first-touch cookie: the first referral link a friend clicks is the one that counts, and later clicks don’t overwrite it. On your own domain, the optional tracker script stores the same attribution in a first-party cookie so purchases on your site can be credited.
Money flow
When you confirm a conversion and the program’s confirmation period elapses, Offertown charges your saved payment method for the reward plus commission (processed by Stripe) and credits the referrer’s wallet. Refunded or disputed purchases claw the reward back proportionally.
Environments and base URL
All endpoints in these docs are relative to the production base URL:
https://offertown.net/api
Need help?
Write to support@offertown.net — include your program ID (never your API key) and, for API issues, the requestId from the error response if you have one.