API Reference Documentation

API Introduction

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

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

Authentication

API requests must be authenticated. Authentication can be handled via API Keys (recommended for programmatic access) or potentially session cookies if used within the Refgrow dashboard context.

To use API Keys:

Generate an API Key from your Refgrow project settings (Project Settings → API Keys → Generate Key).
Include the API Key in the `Authorization` header of your requests as a Bearer token:

Authorization: Bearer <YOUR_API_KEY>

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 -X GET "https://refgrow.com/api/v1/affiliates?limit=10&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

const axios = require('axios');

const response = await axios.get('https://refgrow.com/api/v1/affiliates', {
  params: {
    limit: 10,
    status: 'active'
  },
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

console.log(response.data);

import requests

url = "https://refgrow.com/api/v1/affiliates"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"limit": 10, "status": "active"}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)

<?php
$url = "https://refgrow.com/api/v1/affiliates?" . http_build_query([
    'limit' => 10,
    'status' => 'active'
]);

$headers = ['Authorization: Bearer YOUR_API_KEY'];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
print_r($data);
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://refgrow.com/api/v1/affiliates')
uri.query = URI.encode_www_form(limit: 10, status: 'active')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)
data = JSON.parse(response.body)
puts 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"
    },
    {
      "id": 125,
      "user_email": "affiliate2@example.com",
      "referral_code": "AFF2",
      "created_at": "2024-03-20T14:00:00.000Z",
      "status": "active",
      "clicks": 120,
      "signups": 25,
      "purchases": 15,
      "unpaid_earnings": "110.50",
      "total_earnings": "320.75",
      "eligible_earnings": "110.50",
      "held_earnings": "0.00",
      "next_release_date": null
    }
    // ... more affiliates
  ],
  "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

Error Responses

401 Unauthorized: Missing or invalid API key.
403 Forbidden: API key doesn't have permission to access this resource.

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 for the affiliate. If omitted, one will be generated automatically.

Example Request

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

const axios = require('axios');

const data = {
  email: "new.affiliate@example.com",
  referral_code: "NEWCODE"
};

const response = await axios.post('https://refgrow.com/api/v1/affiliates', data, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

console.log(response.data);

import requests
import json

url = "https://refgrow.com/api/v1/affiliates"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "email": "new.affiliate@example.com",
    "referral_code": "NEWCODE"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
result = response.json()
print(result)

<?php
$url = "https://refgrow.com/api/v1/affiliates";
$data = [
    'email' => 'new.affiliate@example.com',
    'referral_code' => 'NEWCODE'
];

$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
curl_close($curl);
$result = json_decode($response, true);
print_r($result);
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://refgrow.com/api/v1/affiliates')
data = {
  email: "new.affiliate@example.com",
  referral_code: "NEWCODE"
}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = data.to_json

response = http.request(request)
result = JSON.parse(response.body)
puts result

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" 
    // Note: Calculated fields like clicks, signups, purchases, earnings 
    // are typically not returned on creation. Fetch separately if needed.
  }
}

Error Responses

400 Bad Request: Invalid email or other parameters.
409 Conflict: Email or referral code already exists for this project.

Retrieve Affiliate

GET /api/v1/affiliates/:email

Retrieves details, including calculated stats, for a specific affiliate by their email address.

Path Parameters

Parameter	Type	Description
`email`	string	The URL-encoded email address of the affiliate to retrieve.

Example Request

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

const axios = require('axios');

const email = encodeURIComponent('affiliate1@example.com');
const response = await axios.get(`https://refgrow.com/api/v1/affiliates/${email}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

console.log(response.data);

import requests
from urllib.parse import quote

email = quote('affiliate1@example.com')
url = f"https://refgrow.com/api/v1/affiliates/{email}"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

<?php
$email = urlencode('affiliate1@example.com');
$url = "https://refgrow.com/api/v1/affiliates/" . $email;
$headers = ['Authorization: Bearer YOUR_API_KEY'];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
print_r($data);
?>

require 'net/http'
require 'uri'
require 'json'

email = URI.encode_www_form_component('affiliate1@example.com')
uri = URI("https://refgrow.com/api/v1/affiliates/#{email}")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)
data = JSON.parse(response.body)
puts 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" 
  }
}

Error Responses

400 Bad Request: Invalid email format in URL.
404 Not Found: Affiliate with the specified email not found for this project.

Update Affiliate

PUT /api/v1/affiliates/:email

Updates specific details for an existing affiliate identified by their email address.

Path Parameters

Parameter	Type	Description
`email`	string	The URL-encoded email address of the affiliate to update.

Request Body (JSON)

Include only the fields you want to update.

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

Example Request

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

const axios = require('axios');

const email = encodeURIComponent('affiliate1@example.com');
const data = { status: "inactive" };

const response = await axios.put(`https://refgrow.com/api/v1/affiliates/${email}`, data, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }
});

console.log(response.data);

import requests
import json
from urllib.parse import quote

email = quote('affiliate1@example.com')
url = f"https://refgrow.com/api/v1/affiliates/{email}"
headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
data = {"status": "inactive"}

response = requests.put(url, headers=headers, data=json.dumps(data))
print(response.json())

<?php
$email = urlencode('affiliate1@example.com');
$url = "https://refgrow.com/api/v1/affiliates/" . $email;
$data = json_encode(["status" => "inactive"]);
$headers = ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"];

$curl = curl_init();
curl_setopt_array($curl, [CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_POSTFIELDS => $data, CURLOPT_HTTPHEADER => $headers]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));
?>

require 'net/http'
require 'uri'
require 'json'

email = URI.encode_www_form_component('affiliate1@example.com')
uri = URI("https://refgrow.com/api/v1/affiliates/#{email}")
data = {status: "inactive"}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = data.to_json

response = http.request(request)
puts JSON.parse(response.body)

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": 123,
    "user_email": "affiliate1@example.com", 
    "referral_code": "REF123", 
    "unpaid_earnings": null, 
    "total_earnings": null,  
    "created_at": "2024-01-15T10:00:00.000Z", 
    "status": "inactive" 
    // Note: Calculated fields are not typically returned on update.
    // The core affiliate fields (email, code, status) are updated.
  }
}

Error Responses

400 Bad Request: Invalid parameters or email format in URL.
404 Not Found: Affiliate not found.
409 Conflict: New email or referral code conflicts with another affiliate.

Delete Affiliate

DELETE /api/v1/affiliates/:email

Permanently deletes an affiliate (identified by email) and all associated data.

Warning: This action is irreversible.

Path Parameters

Parameter	Type	Description
`email`	string	The URL-encoded email address of the affiliate to delete.

Example Request

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

const axios = require('axios');

const email = encodeURIComponent('affiliate1@example.com');
const response = await axios.delete(`https://refgrow.com/api/v1/affiliates/${email}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

console.log(response.status); // 204

import requests
from urllib.parse import quote

email = quote('affiliate1@example.com')
url = f"https://refgrow.com/api/v1/affiliates/{email}"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.delete(url, headers=headers)
print(response.status_code)  # 204

<?php
$email = urlencode('affiliate1@example.com');
$url = "https://refgrow.com/api/v1/affiliates/" . $email;
$headers = ["Authorization: Bearer YOUR_API_KEY"];

$curl = curl_init();
curl_setopt_array($curl, [CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "DELETE", CURLOPT_HTTPHEADER => $headers]);
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
echo "HTTP Code: " . $httpCode; // 204
?>

require 'net/http'
require 'uri'

email = URI.encode_www_form_component('affiliate1@example.com')
uri = URI("https://refgrow.com/api/v1/affiliates/#{email}")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)
puts response.code # "204"

Example Response (204 No Content)

A successful deletion returns a 204 No Content status code with an empty body.

Error Responses

400 Bad Request: Invalid email format in URL.
404 Not Found: Affiliate not found.
500 Internal Server Error: If an error occurs during the deletion cascade.

Conversions

Endpoints for managing conversions (registrations and purchases) attributed to affiliates or direct users. Use these endpoints 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 by type, affiliate, user, paid status, and date.

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	Optional	Number of conversions to return (default: 50).
`offset`	integer	Optional	Number of conversions to skip (for pagination, default: 0).
`type`	string	Optional	Filter by conversion 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 -X GET "https://refgrow.com/api/v1/conversions?type=purchase&affiliate_id=123&paid=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

const axios = require('axios');

const response = await axios.get('https://refgrow.com/api/v1/conversions', {
  params: {
    type: 'purchase',
    affiliate_id: 123,
    paid: true
  },
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

console.log(response.data);

import requests

url = "https://refgrow.com/api/v1/conversions"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"type": "purchase", "affiliate_id": 123, "paid": True}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)

<?php
$url = "https://refgrow.com/api/v1/conversions?" . http_build_query([
    'type' => 'purchase',
    'affiliate_id' => 123,
    'paid' => 'true'
]);

$headers = ['Authorization: Bearer YOUR_API_KEY'];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
print_r($data);
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://refgrow.com/api/v1/conversions')
uri.query = URI.encode_www_form(type: 'purchase', affiliate_id: 123, paid: true)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)
data = JSON.parse(response.body)
puts data

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"
    }
    // ... more conversions
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 2,
    "has_more": false
  }
}

Error Responses

401 Unauthorized: Missing or invalid API key.
403 Forbidden: API key doesn't have permission to access this resource.

Create Conversion

POST /api/v1/conversions

Manually creates a new conversion (registration or purchase). Use this to record conversions from your backend.

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) for the base value.
`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, if any.

Example Request

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

const axios = require('axios');

const data = {
  type: "purchase",
  affiliate_id: 123,
  base_value: 250,
  base_value_currency: "USD",
  reference: "ORDER-123"
};

const response = await axios.post('https://refgrow.com/api/v1/conversions', data, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

console.log(response.data);

import requests
import json

url = "https://refgrow.com/api/v1/conversions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "type": "purchase",
    "affiliate_id": 123,
    "base_value": 250,
    "base_value_currency": "USD",
    "reference": "ORDER-123"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
result = response.json()
print(result)

<?php
$url = "https://refgrow.com/api/v1/conversions";
$data = [
    'type' => 'purchase',
    'affiliate_id' => 123,
    'base_value' => 250,
    'base_value_currency' => 'USD',
    'reference' => 'ORDER-123'
];

$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
curl_close($curl);
$result = json_decode($response, true);
print_r($result);
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://refgrow.com/api/v1/conversions')
data = {
  type: "purchase",
  affiliate_id: 123,
  base_value: 250,
  base_value_currency: "USD",
  reference: "ORDER-123"
}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = data.to_json

response = http.request(request)
result = JSON.parse(response.body)
puts 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 Bad Request: Invalid parameters or missing required fields.
404 Not Found: Specified affiliate or user does not exist.
409 Conflict: Duplicate conversion for this reference/order.

Retrieve Conversion

GET /api/v1/conversions/:id

Retrieves details for a specific conversion by its ID.

Path Parameters

Parameter	Type	Description
`id`	integer	The ID of the conversion to retrieve.

Example Request

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

const axios = require('axios');

const response = await axios.get('https://refgrow.com/api/v1/conversions/1002', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

console.log(response.data);

import requests

url = "https://refgrow.com/api/v1/conversions/1002"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

<?php
$url = "https://refgrow.com/api/v1/conversions/1002";
$headers = ['Authorization: Bearer YOUR_API_KEY'];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
print_r($data);
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://refgrow.com/api/v1/conversions/1002')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)
data = JSON.parse(response.body)
puts data

Example Response (200 OK)

{
  "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 Bad Request: Invalid conversion ID.
404 Not Found: Conversion not found for this project.

Update Conversion

PUT /api/v1/conversions/:id

Updates specific fields for an existing conversion by its ID. Only the following fields can be updated: value, base_value, type, paid, reference, coupon_code_used, base_value_currency.

Path Parameters

Parameter	Type	Description
`id`	integer	The ID of the conversion to update.

Request Body (JSON)

Include only the fields you want to update.

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

Example Request

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

const axios = require('axios');

const data = { paid: true };
const response = await axios.put('https://refgrow.com/api/v1/conversions/1002', data, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }
});

console.log(response.data);

import requests
import json

url = "https://refgrow.com/api/v1/conversions/1002"
headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
data = {"paid": True}

response = requests.put(url, headers=headers, data=json.dumps(data))
print(response.json())

<?php
$url = "https://refgrow.com/api/v1/conversions/1002";
$data = json_encode(["paid" => true]);
$headers = ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"];

$curl = curl_init();
curl_setopt_array($curl, [CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_POSTFIELDS => $data, CURLOPT_HTTPHEADER => $headers]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://refgrow.com/api/v1/conversions/1002')
data = {paid: true}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = data.to_json

response = http.request(request)
puts JSON.parse(response.body)

Example Response (200 OK)

{
  "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": true,
    "created_at": "2024-07-29T13:05:00.000Z",
    "reference": "ORDER-123",
    "coupon_code_used": null
  }
}

Error Responses

400 Bad Request: Invalid parameters or conversion ID.
404 Not Found: Conversion not found for this project.

Delete Conversion

DELETE /api/v1/conversions/:id

Permanently deletes a conversion by its ID.

Warning: This action is irreversible.

Path Parameters

Parameter	Type	Description
`id`	integer	The ID of the conversion to delete.

Example Request

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

const axios = require('axios');

const response = await axios.delete('https://refgrow.com/api/v1/conversions/1002', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

console.log(response.status); // 204

import requests

url = "https://refgrow.com/api/v1/conversions/1002"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.delete(url, headers=headers)
print(response.status_code)  # 204

<?php
$url = "https://refgrow.com/api/v1/conversions/1002";
$headers = ["Authorization: Bearer YOUR_API_KEY"];

$curl = curl_init();
curl_setopt_array($curl, [CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "DELETE", CURLOPT_HTTPHEADER => $headers]);
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
echo "HTTP Code: " . $httpCode; // 204
?>

require 'net/http'
require 'uri'

uri = URI('https://refgrow.com/api/v1/conversions/1002')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)
puts response.code # "204"

Example Response (204 No Content)

A successful deletion returns a 204 No Content status code with an empty body.

Error Responses

400 Bad Request: Invalid conversion ID.
404 Not Found: Conversion not found for this project.
500 Internal Server Error: If an error occurs during deletion.

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 (for pagination, default: 0).
`affiliate_id`	integer	Optional	Filter referrals by the associated affiliate ID.
`status`	string	Optional	Filter by conversion status (e.g., 'pending', 'converted', 'direct', 'direct_signup').

Example Request

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

const axios = require('axios');

const response = await axios.get('https://refgrow.com/api/v1/referrals', {
  params: {
    affiliate_id: 123,
    status: 'converted'
  },
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

console.log(response.data);

import requests

url = "https://refgrow.com/api/v1/referrals"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"affiliate_id": 123, "status": "converted"}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)

<?php
$url = "https://refgrow.com/api/v1/referrals?" . http_build_query([
    'affiliate_id' => 123,
    'status' => 'converted'
]);

$headers = ['Authorization: Bearer YOUR_API_KEY'];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
print_r($data);
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://refgrow.com/api/v1/referrals')
uri.query = URI.encode_www_form(affiliate_id: 123, status: 'converted')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)
data = JSON.parse(response.body)
puts data

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"
    },
    // ... more referred users
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 5,
    "has_more": false
  }
}

Error Responses

401 Unauthorized: Missing or invalid API key.
403 Forbidden: API key doesn't have permission to access this resource.

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	The email address of the referred user. Must be unique per project.
`affiliate_id`	integer	Optional	The ID of the affiliate who referred this user. If omitted, the user will be considered a direct signup unless status indicates otherwise.
`status`	string	Optional	The conversion status ('pending', 'converted', 'direct', 'direct_signup'). Defaults to 'pending'. If set to 'converted' or 'direct', `conversion_date` will be set to the current time.

Example Request

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

const axios = require('axios');

const data = {
  email: "manual.customer@example.com",
  affiliate_id: 123,
  status: "converted"
};

const response = await axios.post('https://refgrow.com/api/v1/referrals', data, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

console.log(response.data);

import requests
import json

url = "https://refgrow.com/api/v1/referrals"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "email": "manual.customer@example.com",
    "affiliate_id": 123,
    "status": "converted"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
result = response.json()
print(result)

<?php
$url = "https://refgrow.com/api/v1/referrals";
$data = [
    'email' => 'manual.customer@example.com',
    'affiliate_id' => 123,
    'status' => 'converted'
];

$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
curl_close($curl);
$result = json_decode($response, true);
print_r($result);
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://refgrow.com/api/v1/referrals')
data = {
  email: "manual.customer@example.com",
  affiliate_id: 123,
  status: "converted"
}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = data.to_json

response = http.request(request)
result = JSON.parse(response.body)
puts result

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 Bad Request: Invalid email or other parameters.
404 Not Found: Specified `affiliate_id` does not exist.
409 Conflict: Referred user with this email already exists for this project.

Retrieve Referral

GET /api/v1/referrals/:email

Retrieves details for a specific referred user by their email address.

Path Parameters

Parameter	Type	Description
`email`	string	The URL-encoded email address of the referred user to retrieve.

Example Request

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

const axios = require('axios');

const email = encodeURIComponent('customer1@example.com');
const response = await axios.get(`https://refgrow.com/api/v1/referrals/${email}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

console.log(response.data);

import requests
from urllib.parse import quote

email = quote('customer1@example.com')
url = f"https://refgrow.com/api/v1/referrals/{email}"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

<?php
$email = urlencode('customer1@example.com');
$url = "https://refgrow.com/api/v1/referrals/" . $email;
$headers = ['Authorization: Bearer YOUR_API_KEY'];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
print_r($data);
?>

require 'net/http'
require 'uri'
require 'json'

email = URI.encode_www_form_component('customer1@example.com')
uri = URI("https://refgrow.com/api/v1/referrals/#{email}")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)
data = JSON.parse(response.body)
puts data

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

Error Responses

400 Bad Request: Invalid email format in URL.
404 Not Found: Referred user not found for this project.

Update Referral

PUT /api/v1/referrals/:email

Updates specific details for an existing referred user identified by their email address.

Path Parameters

Parameter	Type	Description
`email`	string	The URL-encoded email address of the referred user to update.

Request Body (JSON)

Include only the fields you want to update.

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

Example Request

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

const axios = require('axios');

const email = encodeURIComponent('manual.customer@example.com');
const data = { affiliate_id: null, status: "direct" };

const response = await axios.put(`https://refgrow.com/api/v1/referrals/${email}`, data, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }
});

console.log(response.data);

import requests
import json
from urllib.parse import quote

email = quote('manual.customer@example.com')
url = f"https://refgrow.com/api/v1/referrals/{email}"
headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
data = {"affiliate_id": None, "status": "direct"}

response = requests.put(url, headers=headers, data=json.dumps(data))
print(response.json())

<?php
$email = urlencode('manual.customer@example.com');
$url = "https://refgrow.com/api/v1/referrals/" . $email;
$data = json_encode(["affiliate_id" => null, "status" => "direct"]);
$headers = ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"];

$curl = curl_init();
curl_setopt_array($curl, [CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_POSTFIELDS => $data, CURLOPT_HTTPHEADER => $headers]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));
?>

require 'net/http'
require 'uri'
require 'json'

email = URI.encode_www_form_component('manual.customer@example.com')
uri = URI("https://refgrow.com/api/v1/referrals/#{email}")
data = {affiliate_id: nil, status: "direct"}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = data.to_json

response = http.request(request)
puts JSON.parse(response.body)

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": 502,
    "user_email": "manual.customer@example.com",
    "affiliate_id": null,
    "conversion_status": "direct",
    "conversion_date": "2024-07-29T13:15:00.000Z", // Updated conversion date
    "created_at": "2024-07-29T13:00:00.000Z"
  }
}

Error Responses

400 Bad Request: Invalid parameters or email format in URL.
404 Not Found: Referred user or specified `affiliate_id` not found.
409 Conflict: New email conflicts with another referred user.

Delete Referral

DELETE /api/v1/referrals/:email

Permanently deletes a referred user record (identified by email) and any associated conversion records.

Warning: This action is irreversible.

Path Parameters

Parameter	Type	Description
`email`	string	The URL-encoded email address of the referred user to delete.

Example Request

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

const axios = require('axios');

const email = encodeURIComponent('manual.customer@example.com');
const response = await axios.delete(`https://refgrow.com/api/v1/referrals/${email}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

console.log(response.status); // 204

import requests
from urllib.parse import quote

email = quote('manual.customer@example.com')
url = f"https://refgrow.com/api/v1/referrals/{email}"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.delete(url, headers=headers)
print(response.status_code)  # 204

<?php
$email = urlencode('manual.customer@example.com');
$url = "https://refgrow.com/api/v1/referrals/" . $email;
$headers = ["Authorization: Bearer YOUR_API_KEY"];

$curl = curl_init();
curl_setopt_array($curl, [CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "DELETE", CURLOPT_HTTPHEADER => $headers]);
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
echo "HTTP Code: " . $httpCode; // 204
?>

require 'net/http'
require 'uri'

email = URI.encode_www_form_component('manual.customer@example.com')
uri = URI("https://refgrow.com/api/v1/referrals/#{email}")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)
puts response.code # "204"

Example Response (204 No Content)

A successful deletion returns a 204 No Content status code with an empty body.

Error Responses

400 Bad Request: Invalid email format in URL.
404 Not Found: Referred user not found.
500 Internal Server Error: If an error occurs during deletion.

Coupons

Endpoints for managing coupons associated with affiliates in your project. Coupons are discount codes that can be linked to specific affiliates for tracking and commission purposes.

List Coupons

GET /api/v1/coupons

Retrieves a list of coupons for your project. Supports pagination and filtering by status, affiliate, and coupon code.

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	Optional	Number of coupons to return (default: 50).
`offset`	integer	Optional	Number of coupons to skip for pagination (default: 0).
`status`	string	Optional	Filter by status ('active' or 'inactive').
`affiliate_id`	integer	Optional	Filter by affiliate ID.
`coupon_code`	string	Optional	Filter by coupon code (partial match).

Example Request

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

const axios = require('axios');

const response = await axios.get('https://refgrow.com/api/v1/coupons', {
  params: {
    limit: 10,
    status: 'active'
  },
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

console.log(response.data);

import requests

url = "https://refgrow.com/api/v1/coupons"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
params = {
    "limit": 10,
    "status": "active"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)

<?php
$url = "https://refgrow.com/api/v1/coupons?" . http_build_query([
    'limit' => 10,
    'status' => 'active'
]);

$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);
print_r($data);
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://refgrow.com/api/v1/coupons')
uri.query = URI.encode_www_form(limit: 10, status: 'active')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'

response = http.request(request)
data = JSON.parse(response.body)
puts data

Example Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "project_id": 123,
      "affiliate_id": 456,
      "coupon_code": "SAVE20",
      "stripe_coupon_id": "stripe_save20",
      "lemonsqueezy_discount_code": "LS_SAVE20",
      "status": "active",
      "created_at": "2024-01-15T10:00:00.000Z",
      "updated_at": "2024-01-15T10:00:00.000Z",
      "affiliate_email": "affiliate@example.com",
      "affiliate_referral_code": "REF123"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 25,
    "has_more": true
  }
}

Error Responses

401 Unauthorized: Invalid or missing API key.
500 Internal Server Error: If an error occurs while fetching coupons.

Create Coupon

POST /api/v1/coupons

Creates a new coupon for the specified affiliate.

Request Body Parameters

Parameter	Type	Required	Description
`affiliate_id`	integer	Required	ID of the affiliate to associate with this coupon.
`coupon_code`	string	Required	The coupon code (3+ characters, alphanumeric, hyphens, underscores only).
`stripe_coupon_id`	string	Optional	Stripe coupon ID if managing coupons in Stripe.
`lemonsqueezy_discount_code`	string	Optional	LemonSqueezy discount code if managing coupons in LemonSqueezy.
`status`	string	Optional	Status of the coupon ('active' or 'inactive', default: 'active').

Example Request

curl -X POST "https://refgrow.com/api/v1/coupons" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "affiliate_id": 456,
    "coupon_code": "SAVE30",
    "stripe_coupon_id": "stripe_save30",
    "status": "active"
  }'

const axios = require('axios');

const data = {
  affiliate_id: 456,
  coupon_code: "SAVE30",
  stripe_coupon_id: "stripe_save30",
  status: "active"
};

const response = await axios.post('https://refgrow.com/api/v1/coupons', data, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

console.log(response.data);

import requests
import json

url = "https://refgrow.com/api/v1/coupons"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "affiliate_id": 456,
    "coupon_code": "SAVE30",
    "stripe_coupon_id": "stripe_save30",
    "status": "active"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
result = response.json()
print(result)

<?php
$url = "https://refgrow.com/api/v1/coupons";
$data = [
    'affiliate_id' => 456,
    'coupon_code' => 'SAVE30',
    'stripe_coupon_id' => 'stripe_save30',
    'status' => 'active'
];

$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
print_r($result);
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://refgrow.com/api/v1/coupons')
data = {
  affiliate_id: 456,
  coupon_code: "SAVE30",
  stripe_coupon_id: "stripe_save30",
  status: "active"
}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = data.to_json

response = http.request(request)
result = JSON.parse(response.body)
puts result

Example Response (201 Created)

{
  "success": true,
  "data": {
    "id": 2,
    "project_id": 123,
    "affiliate_id": 456,
    "coupon_code": "SAVE30",
    "stripe_coupon_id": "stripe_save30",
    "lemonsqueezy_discount_code": null,
    "status": "active",
    "created_at": "2024-01-16T10:00:00.000Z",
    "updated_at": "2024-01-16T10:00:00.000Z",
    "affiliate_email": "affiliate@example.com",
    "affiliate_referral_code": "REF123"
  }
}

Error Responses

400 Bad Request: Missing required fields or invalid coupon code format.
404 Not Found: Affiliate not found or doesn't belong to this project.
409 Conflict: Coupon code already exists for this project.
500 Internal Server Error: If an error occurs while creating the coupon.

Get Coupon

GET /api/v1/coupons/:id

Retrieves a specific coupon by its ID.

Path Parameters

Parameter	Type	Description
`id`	integer	The unique ID of the coupon.

Example Request

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

const axios = require('axios');

const response = await axios.get('https://refgrow.com/api/v1/coupons/1', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

console.log(response.data);

import requests

url = "https://refgrow.com/api/v1/coupons/1"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

<?php
$url = "https://refgrow.com/api/v1/coupons/1";
$headers = ['Authorization: Bearer YOUR_API_KEY'];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
print_r($data);
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://refgrow.com/api/v1/coupons/1')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)
data = JSON.parse(response.body)
puts data

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": 1,
    "project_id": 123,
    "affiliate_id": 456,
    "coupon_code": "SAVE20",
    "stripe_coupon_id": "stripe_save20",
    "lemonsqueezy_discount_code": "LS_SAVE20",
    "status": "active",
    "created_at": "2024-01-15T10:00:00.000Z",
    "updated_at": "2024-01-15T10:00:00.000Z",
    "affiliate_email": "affiliate@example.com",
    "affiliate_referral_code": "REF123"
  }
}

Error Responses

400 Bad Request: Invalid coupon ID.
404 Not Found: Coupon not found.
500 Internal Server Error: If an error occurs while fetching the coupon.

Update Coupon

PUT /api/v1/coupons/:id

Updates an existing coupon. Only provided fields will be updated.

Path Parameters

Parameter	Type	Description
`id`	integer	The unique ID of the coupon to update.

Request Body Parameters

Parameter	Type	Required	Description
`affiliate_id`	integer	Optional	ID of the affiliate to associate with this coupon.
`coupon_code`	string	Optional	The coupon code (3+ characters, alphanumeric, hyphens, underscores only).
`stripe_coupon_id`	string	Optional	Stripe coupon ID if managing coupons in Stripe.
`lemonsqueezy_discount_code`	string	Optional	LemonSqueezy discount code if managing coupons in LemonSqueezy.
`status`	string	Optional	Status of the coupon ('active' or 'inactive').

Example Request

curl -X PUT "https://refgrow.com/api/v1/coupons/1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive", "stripe_coupon_id": "stripe_save20_updated"}'

const axios = require('axios');

const data = { status: "inactive", stripe_coupon_id: "stripe_save20_updated" };
const response = await axios.put('https://refgrow.com/api/v1/coupons/1', data, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }
});
console.log(response.data);

import requests
import json

url = "https://refgrow.com/api/v1/coupons/1"
headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
data = {"status": "inactive", "stripe_coupon_id": "stripe_save20_updated"}

response = requests.put(url, headers=headers, data=json.dumps(data))
print(response.json())

<?php
$url = "https://refgrow.com/api/v1/coupons/1";
$data = json_encode(["status" => "inactive", "stripe_coupon_id" => "stripe_save20_updated"]);
$headers = ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"];

$curl = curl_init();
curl_setopt_array($curl, [CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_POSTFIELDS => $data, CURLOPT_HTTPHEADER => $headers]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://refgrow.com/api/v1/coupons/1')
data = {status: "inactive", stripe_coupon_id: "stripe_save20_updated"}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = data.to_json

response = http.request(request)
puts JSON.parse(response.body)

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": 1,
    "project_id": 123,
    "affiliate_id": 456,
    "coupon_code": "SAVE20",
    "stripe_coupon_id": "stripe_save20_updated",
    "lemonsqueezy_discount_code": "LS_SAVE20",
    "status": "inactive",
    "created_at": "2024-01-15T10:00:00.000Z",
    "updated_at": "2024-01-16T11:00:00.000Z",
    "affiliate_email": "affiliate@example.com",
    "affiliate_referral_code": "REF123"
  }
}

Error Responses

400 Bad Request: Invalid coupon ID, no updatable fields provided, or invalid field values.
404 Not Found: Coupon not found, or affiliate not found (if updating affiliate_id).
409 Conflict: Coupon code already exists for this project (if updating coupon_code).
500 Internal Server Error: If an error occurs while updating the coupon.

Delete Coupon

DELETE /api/v1/coupons/:id

Permanently deletes a coupon.

Warning: This action is irreversible.

Path Parameters

Parameter	Type	Description
`id`	integer	The unique ID of the coupon to delete.

Example Request

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

const axios = require('axios');

const response = await axios.delete('https://refgrow.com/api/v1/coupons/1', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
console.log(response.status); // 204

import requests

url = "https://refgrow.com/api/v1/coupons/1"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.delete(url, headers=headers)
print(response.status_code)  # 204

<?php
$url = "https://refgrow.com/api/v1/coupons/1";
$headers = ["Authorization: Bearer YOUR_API_KEY"];

$curl = curl_init();
curl_setopt_array($curl, [CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "DELETE", CURLOPT_HTTPHEADER => $headers]);
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
echo "HTTP Code: " . $httpCode; // 204
?>

require 'net/http'
require 'uri'

uri = URI('https://refgrow.com/api/v1/coupons/1')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)
puts response.code # "204"

Example Response (204 No Content)

A successful deletion returns a 204 No Content status code with an empty body.

Error Responses

400 Bad Request: Invalid coupon ID.
404 Not Found: Coupon not found.
500 Internal Server Error: If an error occurs during deletion.