API Endpoints

Reference for the Refgrow API endpoints

Overview

The Refgrow API allows you to integrate affiliate functionality directly into your application. This reference documents the available endpoints, required parameters, and response formats.

All API requests require authentication using your API key, which you can find in your program settings under the "API" tab.

Authentication

To authenticate API requests, include your API key in the request headers: 


{
  "Authorization": "Bearer YOUR_API_KEY"
}

Base URL

All API endpoints use the following base URL: 

https://api.refgrow.com/v1

Affiliate Endpoints

GET /affiliates - List Affiliates

Retrieves a list of all affiliates in your program.

Query Parameters
Parameter Type Description
limit integer Maximum number of affiliates to return (default: 20, max: 100)
offset integer Number of affiliates to skip (for pagination)
status string Filter affiliates by status (active, pending, blocked)
Response Example
{
  "success": true,
  "data": {
    "affiliates": [
      {
        "id": "aff_123456",
        "email": "affiliate@example.com",
        "name": "John Doe",
        "status": "active",
        "createdAt": "2023-06-15T10:30:00Z",
        "totalEarnings": 1250.75,
        "pendingEarnings": 350.25,
        "paidEarnings": 900.50,
        "conversionRate": 0.12,
        "clickCount": 1840,
        "conversionCount": 221
      },
      // Additional affiliates...
    ],
    "total": 45,
    "limit": 20,
    "offset": 0
  }
}
GET /affiliates/:id - Get Affiliate Details

Retrieves detailed information about a specific affiliate.

URL Parameters
Parameter Type Description
id string The affiliate's unique identifier
Response Example
{
  "success": true,
  "data": {
    "affiliate": {
      "id": "aff_123456",
      "email": "affiliate@example.com",
      "name": "John Doe",
      "status": "active",
      "createdAt": "2023-06-15T10:30:00Z",
      "totalEarnings": 1250.75,
      "pendingEarnings": 350.25,
      "paidEarnings": 900.50,
      "conversionRate": 0.12,
      "clickCount": 1840,
      "conversionCount": 221,
      "referralCode": "JOHNDOE10",
      "paymentMethod": "paypal",
      "paymentDetails": "affiliate@example.com"
    }
  }
}
POST /affiliates - Create Affiliate

Creates a new affiliate in your program.

Request Body Parameters
Parameter Type Required Description
email string Yes The affiliate's email address
name string Yes The affiliate's full name
referralCode string No Custom referral code (if not provided, one will be generated)
customFields object No Any additional custom data for the affiliate
Response Example
{
  "success": true,
  "data": {
    "affiliate": {
      "id": "aff_123456",
      "email": "affiliate@example.com",
      "name": "John Doe",
      "status": "active",
      "createdAt": "2023-06-15T10:30:00Z",
      "referralCode": "JOHNDOE10"
    }
  }
}

Referral Endpoints

POST /referrals/track - Track Click

Records a click from an affiliate referral link.

Request Body Parameters
Parameter Type Required Description
referralCode string Yes The affiliate's referral code
sourceUrl string No The URL where the referral originated
userAgent string No The user agent of the visitor
ipAddress string No The IP address of the visitor
Response Example
{
  "success": true,
  "data": {
    "clickId": "click_abcdef12345",
    "referralCode": "JOHNDOE10",
    "affiliateId": "aff_123456",
    "timestamp": "2023-06-18T14:25:30Z"
  }
}
POST /referrals/convert - Record Conversion

Records a conversion (purchase, signup, etc.) from a referral.

Request Body Parameters
Parameter Type Required Description
clickId string No* The click ID from the tracking call (* either clickId or referralCode is required)
referralCode string No* The affiliate's referral code (* either clickId or referralCode is required)
amount number Yes The purchase amount or value of the conversion
orderId string No Your internal order or transaction ID
customer object No Customer information (email, name, etc.)
products array No Array of purchased products with details
Response Example
{
  "success": true,
  "data": {
    "conversionId": "conv_xyz789",
    "affiliateId": "aff_123456",
    "referralCode": "JOHNDOE10",
    "amount": 99.99,
    "commission": 20.00,
    "orderId": "order_123456",
    "timestamp": "2023-06-18T15:10:45Z"
  }
}

Commission Endpoints

GET /commissions - List Commissions

Retrieves a list of commissions generated in your program.

Query Parameters
Parameter Type Description
limit integer Maximum number of commissions to return (default: 20, max: 100)
offset integer Number of commissions to skip (for pagination)
affiliateId string Filter commissions by affiliate ID
status string Filter by status (pending, approved, paid, rejected)
Response Example
{
  "success": true,
  "data": {
    "commissions": [
      {
        "id": "comm_456789",
        "affiliateId": "aff_123456",
        "orderId": "order_123456",
        "amount": 20.00,
        "status": "pending",
        "createdAt": "2023-06-18T15:10:45Z",
        "paidAt": null,
        "conversionAmount": 99.99
      },
      // Additional commissions...
    ],
    "total": 32,
    "limit": 20,
    "offset": 0
  }
}
PUT /commissions/:id/status - Update Commission Status

Updates the status of a specific commission.

URL Parameters
Parameter Type Description
id string The commission's unique identifier
Request Body Parameters
Parameter Type Required Description
status string Yes New status (approved, paid, rejected)
reason string No Reason for status change (especially for rejections)
Response Example
{
  "success": true,
  "data": {
    "commission": {
      "id": "comm_456789",
      "affiliateId": "aff_123456",
      "orderId": "order_123456",
      "amount": 20.00,
      "status": "approved",
      "createdAt": "2023-06-18T15:10:45Z",
      "updatedAt": "2023-06-20T09:15:30Z",
      "paidAt": null,
      "conversionAmount": 99.99
    }
  }
}

Error Responses

When an error occurs, the API will return an appropriate HTTP status code along with a JSON response containing error details: 

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid affiliate ID format",
    "details": {
      "field": "affiliateId",
      "issue": "must be a string beginning with 'aff_'"
    }
  }
}

Common Error Codes

Error Code HTTP Status Description
authentication_error 401 Invalid API key or authentication token
permission_denied 403 The authenticated user doesn't have permission for the requested operation
resource_not_found 404 The requested resource (affiliate, commission, etc.) doesn't exist
invalid_request 400 The request parameters are invalid or incomplete
rate_limit_exceeded 429 You've exceeded the API rate limit
server_error 500 An internal server error occurred

Next Steps

API Overview Dashboard Customization