OfferTown

Quick Start Integration Guide

Integration Overview

OfferTown helps you track referrals from lead generation to paying customer. This guide shows how to install the WordPress plugin, use our API to fetch new leads hourly, and report conversions when leads become paying customers.

Step 1: Get Your API Credentials

Login to OfferTown Dashboard
```
https://www.offertown.net/auth/sign-in
```
Generate API Keys
- Navigate to: Settings → API Keys
- Click "Generate New Key"
- Choose Key Type:
  WordPress Plugin Key (trp_)
  For WordPress plugin integration only
  Example: trp_67759518e0eb2de0900bfd47dfc76e5e553581522...
  API Integration Key (tlp_)
  For API calls and external integrations
  Example: tlp_a8f5c2d1b9e7f3a2c8d4e9f1a2b3c4d5e6f7a8b9...
- Copy and save securely:
  - API Key: Full 64-character key (auto-copied to clipboard)
  - Note: Tenant ID is not needed separately - it's embedded in your API key
Important: Generate separate keys for different purposes. Use trp_ keys exclusively for WordPress, and tlp_ keys for API integrations.

Step 2: WordPress Plugin Setup

Install Offertown Plugin
Download v1.0.7 (Latest)View all downloads
- Upload the tenant-referral-program folder to /wp-content/plugins/
- Activate the plugin from WordPress admin panel
Configure Plugin Settings
Go to Settings → Offertown in WordPress admin:
```
API Key: [Your WordPress API Key (trp_...)]
API Base URL: https://offertown.net (auto-filled)
Status: Connected ✓
```
✓ The plugin automatically detects your tenant ID from the API key and connects to production
Add Shortcodes to Your Site
For user dashboard/member areas:
```
[tenant_referral_widget]
```
Complete referral management widget with history and link generation
For signup/conversion pages:
```
[tenant_referral_signup]
```
Handles referral conversions from URLs like: yoursite.com/join/?ref_code=ABC123

Step 3: API Integration

Get New Leads (Recommended)

New Workflow: Use status=pending_verification to fetch new leads. This automatically verifies them and makes them ready for conversion tracking. This ensures you only process leads when you're ready to handle them.

curl -X GET "https://offertown.net/api/v1/admin/referrals?status=pending_verification" \
  -H "Authorization: Bearer tlp_your_api_key_here" \
  -H "Content-Type: application/json"

Important: The API response will show pending_verification status, but these leads are automatically verified in the background. Subsequent API calls will show them as verified.

Get Verified Leads (Alternative)

For ongoing/automated fetching, you can also fetch already verified leads:

curl -X GET "https://offertown.net/api/v1/admin/referrals?status=verified" \
  -H "Authorization: Bearer tlp_your_api_key_here" \
  -H "Content-Type: application/json"

Report Conversion

curl -X POST "https://offertown.net/api/v1/admin/referrals/48b48e96-2bec-4b87-a352-d0d329307212/convert" \
  -H "Authorization: Bearer tlp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "conversionValue": 99.99,
    "currency": "EUR",
    "externalTransactionId": "ORDER-2025-001",
    "metadata": {
      "monthlyValue": 99.99,
      "planName": "Professional"
    }
  }'

Referral IDs

Referral IDs in the API are standard UUIDs without any prefix:

• Format: 48b48e96-2bec-4b87-a352-d0d329307212
• Type: UUID v4
• Usage: Use the ID exactly as returned by the API in all subsequent requests

Example Flow

1. Tenant fetches verified leads:

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "48b48e96-2bec-4b87-a352-d0d329307212",
        "referred": {
          "email": "customer@example.com",
          "name": "John Doe"
        },
        "referrer": {
          "id": "352d9bb7-12eb-49b1-b426-c2aa77278dee",
          "customerId": "USER_352D9BB712EB"
        }
      }
    ]
  },
  "meta": {
    "timestamp": "2025-07-01T14:30:00.000Z",
    "requestId": "req_abc123",
    "version": "1.1"
  }
}

2. Tenant's system processes the lead (customer signs contract)

3. Tenant calls conversion API:

POST /api/v1/admin/referrals/48b48e96-2bec-4b87-a352-d0d329307212/convert
{
  "conversionValue": 99.99,
  "currency": "EUR",
  "externalTransactionId": "ORDER-2025-001",
  "metadata": {
    "customerId": "CUST-12345",
    "planName": "Professional"
  }
}

Complete Integration Flow

1. Visitor clicks referral link → Cookie set
2. Visitor signs up → Plugin tracks lead (status: pending_verification)
3. Email delivered → Lead stays pending_verification
4. Your system fetches pending leads via API → Leads auto-verify
5. Lead becomes customer → Call conversion API
6. Referrer gets reward automatically

Common Integration Patterns

E-commerce Integration

Track referrals through purchase completion:

Install WordPress plugin on your marketing site
Set up hourly cron job to fetch verified leads
When order is completed, call conversion API with order value
Include order ID as externalTransactionId for tracking

SaaS Subscription Model

Track trial-to-paid conversions:

Capture referrals during free trial signup
Store referral ID with user account
On subscription activation, report conversion with monthly value
Use metadata to track plan type and billing cycle

Service Business

Track leads to appointments:

Install plugin on appointment booking pages
Fetch leads daily and import to CRM
When service is completed, report conversion
Track service value for commission calculation

Bitrix24 Integration

Track referrals in your CRM:

{
  "UF_REFERRAL_ID": "48b48e96-2bec-4b87-a352-d0d329307212",
  "UF_REFERRER_ID": "USER_352D9BB712EB",
  "TITLE": "Lead from John Doe referral",
  "SOURCE_ID": "REFERRAL"
}

Documentation

Download Plugin

API Reference

Integration Guide