API Reference

API Introduction

Welcome to the Refgrow API documentation. This API allows you to programmatically interact with your affiliate program data, including affiliates, conversions, referrals, and coupons.

The base URL for all API endpoints is: https://refgrow.com/api/v1

Authentication

All API requests require a Bearer token. Generate an API key from your project settings under API Keys. API keys have the prefix rgk_.

Authorization: Bearer rgk_YOUR_API_KEY

Affiliates

Endpoints for managing affiliates within your project.

List Affiliates

Retrieves a list of affiliates associated with your project. Supports pagination and filtering.

Query Parameters

Example Request (cURL)

curl -X GET "https://refgrow.com/api/v1/affiliates?limit=10&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Request (Node.js)

const response = await fetch(
  'https://refgrow.com/api/v1/affiliates?limit=10&status=active',
  {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);
const data = await response.json();
console.log(data);

Example Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 123,
      "user_email": "affiliate1@example.com",
      "referral_code": "REF123",
      "created_at": "2024-01-15T10:00:00.000Z",
      "status": "active",
      "clicks": 58,
      "signups": 12,
      "purchases": 5,
      "unpaid_earnings": "50.00",
      "total_earnings": "150.00",
      "eligible_earnings": "35.00",
      "held_earnings": "15.00",
      "next_release_date": "2024-02-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 55,
    "has_more": true
  }
}

Hold Period Fields

When a project has a hold period configured, affiliate responses include additional earnings breakdown fields:

Note: total_earnings = eligible_earnings + held_earnings + paid_earnings

Create Affiliate

Creates a new affiliate for your project.

Request Body (JSON)

Example Request (cURL)

curl -X POST "https://refgrow.com/api/v1/affiliates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.affiliate@example.com",
    "referral_code": "NEWCODE",
    "payment_method": "USDT TRC-20",
    "payment_details": "TXyz...wallet"
  }'

Example Response (201 Created)

{
  "success": true,
  "data": {
    "id": 124,
    "user_email": "new.affiliate@example.com",
    "referral_code": "NEWCODE",
    "unpaid_earnings": null,
    "total_earnings": null,
    "created_at": "2024-07-29T12:30:00.000Z",
    "status": "active"
  }
}

Error Responses: 400 Invalid email or parameters. 409 Email or referral code already exists.

Retrieve Affiliate

Retrieves details, including calculated stats, for a specific affiliate by their email address. The email must be URL-encoded.

Example Request (cURL)

curl -X GET "https://refgrow.com/api/v1/affiliates/affiliate1%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": 123,
    "user_email": "affiliate1@example.com",
    "referral_code": "REF123",
    "created_at": "2024-01-15T10:00:00.000Z",
    "status": "active",
    "clicks": 58,
    "signups": 12,
    "purchases": 5,
    "unpaid_earnings": "50.00",
    "total_earnings": "150.00"
  }
}

Error Responses: 400 Invalid email format. 404 Affiliate not found.

Update Affiliate

Updates specific details for an existing affiliate. Include only the fields you want to update.

Request Body (JSON)

Example Request (cURL)

curl -X PUT "https://refgrow.com/api/v1/affiliates/affiliate1%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'

Error Responses: 400 Invalid parameters. 404 Not found. 409 Conflict with existing data.

Delete Affiliate

Permanently deletes an affiliate and all associated data.

Example Request (cURL)

curl -X DELETE "https://refgrow.com/api/v1/affiliates/affiliate1%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content on success.

Conversions

Endpoints for managing conversions (registrations and purchases) attributed to affiliates. Use these to record, view, and manage conversion events for your project.

List Conversions

Retrieves a list of conversions for your project. Supports pagination and filtering.

Query Parameters

Example Request (cURL)

curl -X GET "https://refgrow.com/api/v1/conversions?type=purchase&affiliate_id=123&paid=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "type": "purchase",
      "affiliate_id": 123,
      "referred_user_id": 501,
      "value": 12.5,
      "base_value": 250,
      "base_value_currency": "USD",
      "paid": false,
      "created_at": "2024-07-29T13:00:00.000Z",
      "reference": "ORDER-123",
      "coupon_code_used": "SUMMER2024"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 2,
    "has_more": false
  }
}

Create Conversion

Manually creates a new conversion (registration or purchase). Use this to record conversions from your backend. Also triggers referral_converted and referral_updated webhook events automatically.

Request Body (JSON)

How the affiliate is chosen

Refgrow credits the first match, in this order: affiliate_id, then referral_code, then the customer email.

The email step matters for backend integrations. If your payment step runs on the server (a Clerk hook, a hosted checkout, a billing provider callback) the referral code was captured in the browser at signup and never reaches that code path. Send just the email and the amount: Refgrow looks up which affiliate referred that customer and credits them, exactly as the Stripe integration does. Send the code as well whenever you have it, since that is an exact match rather than a lookup.

Every response includes an attribution object showing which affiliate was credited and how, so you can confirm your integration works on the very first call rather than discovering later that nothing was attributed.

Hold period

If your program has a hold period, conversions created here respect it just like the ones from your payment provider. The conversion is recorded straight away with a status of pending and becomes payable automatically once the period passes. With no hold period configured it is active immediately. The status is on the conversion in the response.

Recurring payments

Send one call per charge, including renewals, with the same customer email each time. Refgrow recognises a repeat payment from that email and applies your recurring commission rate and your commission duration, so a lifetime program keeps paying and a capped one stops on schedule. Nothing extra is needed on your side.

Give each charge its own reference. It doubles as an idempotency key, which matters here because payment hooks retry: a resent webhook returns the original conversion with duplicate: true rather than crediting the affiliate a second time.

Example Request (cURL)

curl -X POST "https://refgrow.com/api/v1/conversions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "purchase",
    "email": "customer@example.com",
    "base_value": 250,
    "base_value_currency": "USD",
    "reference": "ORDER-123"
  }'

# Response
# {
#   "success": true,
#   "data": { ... },
#   "attribution": { "affiliate_id": 123, "matched_by": "email" }
# }

Example Request (Node.js)

const response = await fetch('https://refgrow.com/api/v1/conversions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'purchase',
    affiliate_id: 123,
    base_value: 250,
    base_value_currency: 'USD',
    reference: 'ORDER-123'
  })
});

const result = await response.json();
console.log(result);

Example Response (201 Created)

{
  "success": true,
  "data": {
    "id": 1002,
    "type": "purchase",
    "affiliate_id": 123,
    "referred_user_id": 501,
    "value": 12.5,
    "base_value": 250,
    "base_value_currency": "USD",
    "paid": false,
    "created_at": "2024-07-29T13:05:00.000Z",
    "reference": "ORDER-123",
    "coupon_code_used": null
  }
}

Error Responses: 400 Invalid parameters or missing required fields. 404 Affiliate or user not found. 409 Duplicate conversion for this reference.

Retrieve Conversion

Retrieves details for a specific conversion by its ID.

Example Request (cURL)

curl -X GET "https://refgrow.com/api/v1/conversions/1002" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses: 400 Invalid conversion ID. 404 Conversion not found.

Update Conversion

Updates specific fields for an existing conversion. Also triggers referral_updated webhook event.

Updatable Fields

Example Request (cURL)

curl -X PUT "https://refgrow.com/api/v1/conversions/1002" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paid": true}'

Delete Conversion

Permanently deletes a conversion by its ID.

Example Request (cURL)

curl -X DELETE "https://refgrow.com/api/v1/conversions/1002" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content on success.

Referrals

Endpoints for managing referred users associated with your affiliates.

List Referrals

Retrieves a list of referred users for your project. Supports pagination and filtering.

Query Parameters

Example Request (cURL)

curl -X GET "https://refgrow.com/api/v1/referrals?affiliate_id=123&status=converted" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 501,
      "user_email": "customer1@example.com",
      "conversion_status": "converted",
      "conversion_date": "2024-02-10T11:05:00.000Z",
      "created_at": "2024-02-01T09:00:00.000Z",
      "affiliate_id": 123,
      "affiliate_code": "REF123"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 5,
    "has_more": false
  }
}

Create Referral

Manually creates a new referred user record. This is typically handled automatically by tracking, but can be used for manual attribution.

Request Body (JSON)

Example Request (cURL)

curl -X POST "https://refgrow.com/api/v1/referrals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "manual.customer@example.com",
    "affiliate_id": 123,
    "status": "converted"
  }'

Example Response (201 Created)

{
  "success": true,
  "data": {
    "id": 502,
    "user_email": "manual.customer@example.com",
    "affiliate_id": 123,
    "conversion_status": "converted",
    "conversion_date": "2024-07-29T13:00:00.000Z",
    "created_at": "2024-07-29T13:00:00.000Z"
  }
}

Error Responses: 400 Invalid email or parameters. 404 Specified affiliate_id does not exist. 409 Referred user with this email already exists.

Retrieve Referral

Retrieves details for a specific referred user by their email address. The email must be URL-encoded.

Example Request (cURL)

curl -X GET "https://refgrow.com/api/v1/referrals/customer1%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Referral

Updates specific details for an existing referred user.

Updatable Fields

Example Request (cURL)

curl -X PUT "https://refgrow.com/api/v1/referrals/manual.customer%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"affiliate_id": null, "status": "direct"}'

Coupons

Endpoints for managing affiliate coupons. Coupons are used for conversion attribution when customers use a coupon code that matches an affiliate's assigned code.

List Coupons

Returns all coupons associated with affiliates in your project. Supports pagination and filtering.

Create Coupon

Request Body (JSON)

{
  "affiliate_id": 42,
  "coupon_code": "JANE20",
  "stripe_coupon_id": "promo_xxx"
}

Retrieve Coupon

Retrieves details for a specific coupon by its ID.

Update Coupon

Updates a coupon's details.

Delete Coupon

Permanently deletes a coupon.

Error Handling

The API uses standard HTTP status codes. Error responses include a JSON body with a success field set to false and an error message:

{
  "success": false,
  "error": "Affiliate not found"
}

Rate Limits

API requests are limited to 100 requests per minute per API key. Rate limit headers are included in every response:

• X-RateLimit-Limit — requests allowed per window
• X-RateLimit-Remaining — requests remaining
• X-RateLimit-Reset — Unix timestamp when the window resets