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 the list endpoint with status=pending_verification to fetch new leads. This automatically verifies them in the background and makes them ready for conversion tracking.

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

How Auto-Verification Works:

List endpoint only: Auto-verification ONLY works when fetching multiple referrals with the list endpoint. Individual referral lookups (GET /referrals/[id]) do NOT trigger auto-verification.
Response timing: The initial API response will show verified status (which is processing internally for v1 API backward compatibility).
Database update: Behind the scenes, the referrals are updated to processing status with a processing_started_at timestamp.
Subsequent calls: Future API calls will show these referrals as verified (v1 API) or processing (internally).

⚠️ Important: This feature requires the AUTO_VERIFY_ON_FETCH=true environment variable. If you're self-hosting, ensure this is set in your production environment.

Get Processing Leads (Alternative)

For ongoing/automated fetching, you can also fetch leads that are being processed:

Note: The status "verified" has been renamed to "processing" for better semantic accuracy. For backward compatibility, V1 API will continue to accept "verified" and return it in responses until 2025-12-01.

curl -X GET "https://offertown.net/api/v1/admin/referrals?status=processing" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -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 <YOUR_API_KEY>" \
  -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 processing 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 processing 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