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, performance metrics, and nested account details: 
{
  "id": "saff_xyz789abc",
  "status": "active",
  "source": {
    "value": "invitation",
    "label": "Invitation",
    "description": "Joined via store invitation"
  },
  "total_visits": 156,
  "total_sales": 32,
  "total_earnings": {
    "value": 1250,
    "formatted": "$1,250.00",
    "short": "1.25K",
    "currency": "USD"
  },
  "first_visit_at": "2025-01-16T08:00:00+00:00",
  "last_visit_at": "2025-02-01T14:22:00+00:00",
  "suspended_at": null,
  "suspended_reason": null,
  "account": {
    "id": "aff_abc123def",
    "pseudo": "creative_studio",
    "country": {
      "code": "US",
      "name": "United States"
    },
    "status": "active",
    "user": {
      "id": "usr_def456",
      "name": "John Doe",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "created_at": "2025-01-15T09:00:00+00:00"
  },
  "store": {
    "id": "str_xyz789",
    "name": "My Digital Store"
  },
  "created_at": "2025-01-15T10:00:00+00:00",
  "updated_at": "2025-02-01T14:22:00+00:00"
}

​
Key Fields

  • id: Store affiliate public ID (prefixed with saff_)
  • status: Current status (active or suspended)
  • source: How the affiliate joined (e.g., invitation, network)
  • total_visits: Number of referral link visits
  • total_sales: Number of completed sales from referrals
  • total_earnings: Total commission earned with formatted amount
  • account: Nested affiliate account details including user information
  • account.user: The affiliate’s user profile (name, email, etc.)
  • account.pseudo: Display name used by the affiliate
  • account.country: The affiliate’s country with code and name
  • suspended_at: Timestamp when suspended (null if active)
  • suspended_reason: Reason for suspension (null if active)

​
Affiliate Statuses

StatusDescription
activeAffiliate is active and can earn commissions
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/CREATOR123" \
  -H "Authorization: Bearer sk_live_your_api_key"
This is useful for:
  • Validating an affiliate code before applying commissions
  • 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": ["john@example.com", "jane@example.com", "partner@business.com"]
  }'

​
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": [
    {
      "id": "affinv_abc123xyz",
      "email": "john@example.com",
      "status": "pending",
      "expires_at": "2026-02-10T10:30:00+00:00",
      "invited_by": {
        "id": "tm_abc123",
        "name": "Store Owner"
      },
      "accepted_at": null,
      "created_at": "2026-01-11T10:30:00+00:00"
    },
    {
      "id": "affinv_def456uvw",
      "email": "jane@example.com",
      "status": "pending",
      "expires_at": "2026-02-10T10:30:00+00:00",
      "invited_by": {
        "id": "tm_abc123",
        "name": "Store Owner"
      },
      "accepted_at": null,
      "created_at": "2026-01-11T10:30:00+00:00"
    }
  ],
  "errors": []
}

​
Invitation Object

An invitation contains information about its status, who sent it, and expiration: 
{
  "id": "affinv_abc123xyz",
  "email": "john@example.com",
  "status": "pending",
  "expires_at": "2026-02-10T10:30:00+00:00",
  "invited_by": {
    "id": "tm_abc123",
    "name": "Store Owner"
  },
  "accepted_at": null,
  "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
cancelledInvitation has been cancelled

​
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": "creator@example.com",
      "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('CREATOR123');
if (valid) {
  console.log(`Affiliate ${affiliate.account.user.name} is active`);
  console.log(`Total earnings: ${affiliate.total_earnings.formatted}`);
}

// Send invitations to potential affiliates
const result = await manager.sendInvitations([
  'partner1@example.com',
  'partner2@example.com'
]);
console.log(`${result.data.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)
  • Handle skipped emails 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