API Reference

List Affiliates

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

Query Parameters

Example Request

curl -X GET "https://refgrow.com/api/v1/affiliates?limit=10&status=active" \
-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" 
    },
    {
      "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"
    }
    // ... more affiliates
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 55,
    "has_more": true
  }
}

Error Responses

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

Create Affiliate

Creates a new affiliate for your project.

Request Body (JSON)

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

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

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

Path Parameters

Example Request

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 Bad Request: Invalid email format in URL.
• 404 Not Found: Affiliate with the specified email not found for this project.

Update Affiliate

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

Path Parameters

Request Body (JSON)

Include only the fields you want to update.

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

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

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

Warning: This action is irreversible.

Path Parameters

Example Request

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

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.

List Conversions

Retrieves a list of conversions for your project. Supports pagination and filtering by type, affiliate, user, paid status, and date.

Query Parameters

Example Request

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

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

Request Body (JSON)

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

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

Retrieves details for a specific conversion by its ID.

Path Parameters

Example Request

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

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

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

Request Body (JSON)

Include only the fields you want to update.

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

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

Permanently deletes a conversion by its ID. Warning: This action is irreversible.

Path Parameters

Example Request

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

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.

List Referrals

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

Query Parameters

Example Request

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"
    },
    // ... 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

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

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

Path Parameters

Example Request

curl -X GET "https://refgrow.com/api/v1/referrals/customer1%40example.com" \
-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"
  }
}

Error Responses

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

Update Referral

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

Path Parameters

Request Body (JSON)

Include only the fields you want to update.

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

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

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

Warning: This action is irreversible.

Path Parameters

Example Request

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

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.