API Reference — Refgrow Docs

The Refgrow REST API lets you manage affiliates, conversions, referrals, and coupons programmatically.

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_.

bash

Authorization: Bearer rgk_YOUR_API_KEY

Security: API keys are stored hashed (bcrypt) in the database. Keep your key secret and never expose it in client-side code. All API requests must be made over HTTPS.

Affiliates

Endpoints for managing affiliates within your project.

List Affiliates

GET/api/v1/affiliates

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

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	Optional	Number of affiliates to return (default: 20).
`offset`	integer	Optional	Number of affiliates to skip (for pagination, default: 0).
`status`	string	Optional	Filter by status (e.g., 'active', 'inactive').

Example Request (cURL)

bash

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

Example Request (Node.js)

javascript

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)

json

{
  "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:

Field	Type	Description
`eligible_earnings`	string	Earnings that have passed the hold period and are available for payout.
`held_earnings`	string	Earnings still within the hold period, not yet eligible for payout.
`next_release_date`	string (ISO date) or null	Date when the next batch of held earnings will become eligible. Null if no earnings are held.

Note: total_earnings = eligible_earnings + held_earnings + paid_earnings

Create Affiliate

POST/api/v1/affiliates

Creates a new affiliate for your project.

Request Body (JSON)

Parameter	Type	Required	Description
`email`	string	Yes	The email address of the affiliate. Must be unique per project.
`referral_code`	string	Optional	A unique referral code. If omitted, one will be generated automatically.

Example Request (cURL)

bash

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"
  }'

Example Response (201 Created)

json

{
  "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

GET/api/v1/affiliates/:email

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

Example Request (cURL)

bash

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

Example Response (200 OK)

json

{
  "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

PUT/api/v1/affiliates/:email

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

Request Body (JSON)

Parameter	Type	Description
`email`	string	New email address. Must be unique per project.
`referral_code`	string	New unique referral code.
`status`	string	Update the status ('active' or 'inactive').

Example Request (cURL)

bash

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

DELETE/api/v1/affiliates/:email

Permanently deletes an affiliate and all associated data.

Warning: This action is irreversible.

Example Request (cURL)

bash

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

GET/api/v1/conversions

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

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	Optional	Number of conversions to return (default: 50).
`offset`	integer	Optional	Number of conversions to skip (default: 0).
`type`	string	Optional	Filter by type (`signup` or `purchase`).
`affiliate_id`	integer	Optional	Filter by affiliate ID.
`referred_user_id`	integer	Optional	Filter by referred user ID.
`paid`	boolean	Optional	Filter by payout status (`true` or `false`).
`from`	string (ISO date)	Optional	Filter conversions created after this date.
`to`	string (ISO date)	Optional	Filter conversions created before this date.

Example Request (cURL)

bash

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)

json

{
  "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

POST/api/v1/conversions

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)

Parameter	Type	Required	Description
`type`	string	Yes	Conversion type: `signup` or `purchase`.
`affiliate_id`	integer	Optional	ID of the affiliate (required for attributed conversions).
`referred_user_id`	integer	Optional	ID of the referred user (if known).
`value`	number	Optional	Commission value (will be calculated if omitted).
`base_value`	number	Optional	Original transaction value (required for purchases).
`base_value_currency`	string	Optional	Currency code (e.g., USD, EUR).
`paid`	boolean	Optional	Payout status (default: false).
`reference`	string	Optional	Custom reference (e.g., order ID).
`coupon_code_used`	string	Optional	Coupon code used for this conversion.

Example Request (cURL)

bash

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

Example Request (Node.js)

javascript

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)

json

{
  "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

GET/api/v1/conversions/:id

Retrieves details for a specific conversion by its ID.

Example Request (cURL)

bash

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

PUT/api/v1/conversions/:id

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

Updatable Fields

Parameter	Type	Description
`value`	number	Update the commission value.
`base_value`	number	Update the original transaction value.
`type`	string	Update conversion type (`signup` or `purchase`).
`paid`	boolean	Update the payout status.
`reference`	string	Update the custom reference.
`coupon_code_used`	string	Update the coupon code used.
`base_value_currency`	string	Update the currency code.

Example Request (cURL)

bash

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

DELETE/api/v1/conversions/:id

Permanently deletes a conversion by its ID.

Warning: This action is irreversible.

Example Request (cURL)

bash

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

GET/api/v1/referrals

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

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	Optional	Number of referrals to return (default: 20).
`offset`	integer	Optional	Number of referrals to skip (default: 0).
`affiliate_id`	integer	Optional	Filter by the associated affiliate ID.
`status`	string	Optional	Filter by conversion status ('pending', 'converted', 'direct', 'direct_signup').

Example Request (cURL)

bash

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

Example Response (200 OK)

json

{
  "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

POST/api/v1/referrals

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

Request Body (JSON)

Parameter	Type	Required	Description
`email`	string	Yes	Email of the referred user. Must be unique per project.
`affiliate_id`	integer	Optional	ID of the referring affiliate. If omitted, treated as a direct signup.
`status`	string	Optional	Conversion status ('pending', 'converted', 'direct', 'direct_signup'). Defaults to 'pending'.

Example Request (cURL)

bash

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)

json

{
  "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

GET/api/v1/referrals/:email

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

Example Request (cURL)

bash

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

Update Referral

PUT/api/v1/referrals/:email

Updates specific details for an existing referred user.

Updatable Fields

Parameter	Type	Description
`email`	string	New email address. Must be unique per project.
`affiliate_id`	integer \| null	Change the associated affiliate ID, or set to null to disassociate.
`status`	string	Update conversion status. Setting to 'converted' or 'direct' updates conversion_date.

Example Request (cURL)

bash

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

GET/api/v1/coupons

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

Create Coupon

POST/api/v1/coupons

Request Body (JSON)

json

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

Retrieve Coupon

GET/api/v1/coupons/:id

Retrieves details for a specific coupon by its ID.

Update Coupon

PUT/api/v1/coupons/:id

Updates a coupon's details.

Delete Coupon

DELETE/api/v1/coupons/:id

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:

json

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

Status	Meaning
`200`	Success
`201`	Created
`204`	Deleted (no content)
`400`	Bad request (missing or invalid parameters)
`401`	Unauthorized (invalid or missing API key)
`403`	Forbidden (API key does not have permission)
`404`	Resource not found
`409`	Conflict (duplicate resource)
`429`	Rate limited
`500`	Internal server error

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