Skip to main content
Chariow provides a comprehensive affiliate management system that allows you to grow your sales through partnerships. Affiliates can promote your products using unique referral codes and earn commissions on successful sales.

​
Affiliate Object

An affiliate contains information about their account, commission rate, and performance: 
{
  "id": "aff_abc123xyz",
  "code": "JOHN25",
  "name": "John Smith",
  "email": "[email protected]",
  "commission_rate": 15.00,
  "status": "active",
  "stats": {
    "total_referrals": 45,
    "total_sales": 32,
    "total_earnings": {
      "amount": 1250.00,
      "currency": "USD"
    }
  },
  "created_at": "2025-01-15T09:00:00.000000Z",
  "updated_at": "2025-01-20T14:30:00.000000Z"
}

​
Key Fields

  • code: The affiliate’s unique referral code used in promotional links
  • commission_rate: Percentage of each sale the affiliate earns (e.g., 15.00 for 15%)
  • status: Current status of the affiliate account
  • stats.total_referrals: Number of customers referred by this affiliate
  • stats.total_sales: Number of completed sales from referrals
  • stats.total_earnings: Total commission earned

​
Affiliate Statuses

StatusDescription
activeAffiliate is active and can earn commissions
inactiveAffiliate account is temporarily inactive
suspendedAffiliate account has been suspended

​
Getting an Affiliate

Retrieve a specific affiliate using their unique referral code: 
curl -X GET "https://api.chariow.com/v1/affiliates/JOHN25" \
  -H "Authorization: Bearer sk_live_your_api_key"
This is useful for:
  • Validating an affiliate code before applying discounts
  • Displaying affiliate information on your website
  • Building affiliate dashboards

​
Sending Affiliate Invitations

Invite potential affiliates to join your programme by sending invitation emails: 
curl -X POST "https://api.chariow.com/v1/affiliates/invitations" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["[email protected]", "[email protected]", "[email protected]"]
  }'

​
Batch Invitations

You can send up to 25 invitations in a single request. The API will:
  • Create and send invitations for valid new emails
  • Skip emails that are already registered affiliates
  • Skip emails that have pending invitations

​
Response

{
  "message": "2 invitations sent successfully",
  "data": {
    "invitations": [
      {
        "id": "affinv_abc123xyz",
        "email": "[email protected]",
        "status": "pending",
        "expires_at": "2026-02-10T10:30:00+00:00",
        "created_at": "2026-01-11T10:30:00+00:00"
      },
      {
        "id": "affinv_def456uvw",
        "email": "[email protected]",
        "status": "pending",
        "expires_at": "2026-02-10T10:30:00+00:00",
        "created_at": "2026-01-11T10:30:00+00:00"
      }
    ],
    "skipped": {
      "already_affiliate": ["[email protected]"],
      "already_invited": []
    }
  },
  "errors": []
}

​
Invitation Object

An invitation contains information about its status and expiration: 
{
  "id": "affinv_abc123xyz",
  "email": "[email protected]",
  "status": "pending",
  "expires_at": "2026-02-10T10:30:00+00:00",
  "created_at": "2026-01-11T10:30:00+00:00"
}

​
Invitation Statuses

StatusDescription
pendingInvitation sent but not yet accepted
acceptedInvitation has been accepted
expiredInvitation has passed its expiration date

​
Webhook Events

When an affiliate joins your store (accepts an invitation), a webhook event is triggered via Pulses.

​
affiliate.joined

Triggered when a new affiliate joins your store. 
{
  "event": "affiliate.joined",
  "affiliate": {
    "id": "saff_xyz789abc",
    "account": {
      "id": "aff_abc123def",
      "code": "CREATOR123",
      "pseudo": "creative_studio",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "name": "John Doe",
      "country": {
        "code": "US",
        "name": "United States"
      },
      "phone": {
        "country_code": "US",
        "formatted": "+1 234 567 890"
      }
    },
    "source": "invitation",
    "status": "active",
    "joined_at": "2025-01-15T10:40:00+00:00"
  },
  "store": {
    "id": "str_xyz789",
    "name": "My Digital Store",
    "url": "https://mystore.mychariow.com"
  }
}
Configure Pulses in your Chariow dashboard (Automation → Pulses) to receive these events.

​
Implementation Example

Here’s a complete example of managing affiliates in your application: 
class AffiliateManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.chariow.com/v1';
  }

  async getAffiliate(code) {
    const response = await fetch(
      `${this.baseUrl}/affiliates/${code}`,
      { headers: { 'Authorization': `Bearer ${this.apiKey}` }}
    );

    if (!response.ok) {
      throw new Error('Affiliate not found');
    }

    const { data } = await response.json();
    return data;
  }

  async sendInvitations(emails) {
    const response = await fetch(
      `${this.baseUrl}/affiliates/invitations`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ emails })
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message);
    }

    return response.json();
  }

  async validateAffiliateCode(code) {
    try {
      const affiliate = await this.getAffiliate(code);
      return {
        valid: affiliate.status === 'active',
        affiliate
      };
    } catch (error) {
      return { valid: false, error: error.message };
    }
  }
}

// Usage
const manager = new AffiliateManager('sk_live_your_api_key');

// Validate an affiliate code at checkout
const { valid, affiliate } = await manager.validateAffiliateCode('JOHN25');
if (valid) {
  console.log(`Applying ${affiliate.commission_rate}% commission for ${affiliate.name}`);
}

// Send invitations to potential affiliates
const result = await manager.sendInvitations([
  '[email protected]',
  '[email protected]'
]);
console.log(`${result.data.invitations.length} invitations sent`);

​
API Endpoints Summary

EndpointMethodDescription
/v1/affiliates/{affiliateCode}GETGet affiliate details by code
/v1/affiliates/invitationsPOSTSend affiliate invitations

​
Best Practices

​
Affiliate Code Validation

  • Always validate affiliate codes before applying commissions
  • Check the affiliate status is active
  • Cache affiliate data to reduce API calls

​
Invitation Management

  • Use batch invitations for efficiency (up to 25 emails)
  • Check the skipped field to handle existing affiliates gracefully
  • Implement retry logic for failed invitations

​
Webhook Integration

  • Set up webhooks to receive affiliate.joined events
  • Use webhooks to trigger onboarding workflows
  • Store affiliate data when they join for faster lookups

​
Commission Tracking

  • Track affiliate referrals accurately
  • Provide affiliates with real-time statistics
  • Implement proper attribution windows

Pulses Guide

Set up webhooks for affiliate events

Get Affiliate API

View the Get Affiliate API reference

Send Invitations API

View the Send Invitations API reference

Sales Guide

Track affiliate sales