Affiliates

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": "Added via store invitation"
  },
  "total_visits": 156,
  "total_sales": 32,
  "total_earnings": {
    "value": 1250,
    "formatted": "$1,250.00",
    "short": "1K",
    "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": {
      "name": "United States",
      "code": "US",
      "alpha_3_code": "USA",
      "dial_code": "+1",
      "currency": "USD",
      "flag": "https://cdn.axazara.com/flags/svg/US.svg"
    },
    "status": "active",
    "user": {
      "id": "usr_def456",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "nickname": null,
      "email": "john@example.com",
      "profile_photo_url": null
    },
    "created_at": "2025-01-15T09:00:00+00:00"
  },
  "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 (name, ISO codes, dial code, currency and flag)
suspended_at: Timestamp when suspended (null if active)
suspended_reason: Reason for suspension (null if active)

Affiliate Statuses

Status	Description
`active`	Affiliate is active and can earn commissions
`suspended`	Affiliate 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"

const response = await fetch('https://api.chariow.com/v1/affiliates/CREATOR123', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});

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

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

const response = await fetch('https://api.chariow.com/v1/affiliates/invitations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    emails: ['john@example.com', 'jane@example.com', 'partner@business.com']
  })
});

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

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
Lower-case the addresses and drop duplicates

Skipped addresses are not listed in the response: data only holds the invitations created, and is empty when every address was skipped. The message reads Invitation sent successfully. for one invitation and N invitations sent successfully. otherwise.

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",
      "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",
      "accepted_at": null,
      "created_at": "2026-01-11T10:30:00+00:00"
    }
  ],
  "errors": []
}

Invitation Object

An invitation contains information about its status and expiration:

{
  "id": "affinv_abc123xyz",
  "email": "john@example.com",
  "status": "pending",
  "expires_at": "2026-02-10T10:30:00+00:00",
  "accepted_at": null,
  "created_at": "2026-01-11T10:30:00+00:00"
}

Invitation Statuses

Status	Description
`pending`	Invitation sent but not yet accepted
`accepted`	Invitation has been accepted
`expired`	Invitation has passed its expiration date
`cancelled`	Invitation has been cancelled

Webhook Events

When an affiliate joins your store, whether through an invitation or the affiliate network, a webhook event is triggered via Pulses. The event is signed and recorded like every other Pulse event; see the Pulses guide for the payload details.

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": {
        "name": "United States",
        "code": "US",
        "alpha_3_code": "USA",
        "dial_code": "+1",
        "currency": "USD",
        "flag": "https://cdn.axazara.com/flags/svg/US.svg"
      },
      "phone": {
        "number": 12025550123,
        "country": {
          "name": "United States",
          "code": "US",
          "alpha_3_code": "USA",
          "dial_code": "+1",
          "currency": "USD",
          "flag": "https://cdn.axazara.com/flags/svg/US.svg"
        }
      }
    },
    "source": {
      "value": "invitation",
      "label": "Invitation",
      "description": "Added via store 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

Endpoint	Method	Description
`/v1/affiliates/{affiliateCode}`	GET	Get affiliate details by code
`/v1/affiliates/invitations`	POST	Send 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

Introduction

Guides

MCP Integration

n8n Integration

Resources

Affiliate Object

Key Fields

Affiliate Statuses

Getting an Affiliate

Sending Affiliate Invitations

Batch Invitations

Response

Invitation Object

Invitation Statuses

Webhook Events

affiliate.joined

Implementation Example

API Endpoints Summary

Best Practices

Affiliate Code Validation

Invitation Management

Webhook Integration

Commission Tracking

Pulses Guide

Get Affiliate API

Send Invitations API

Sales Guide

​Affiliate Object

​Key Fields

​Affiliate Statuses

​Getting an Affiliate

​Sending Affiliate Invitations

​Batch Invitations

​Response

​Invitation Object

​Invitation Statuses

​Webhook Events

​affiliate.joined

​Implementation Example

​API Endpoints Summary

​Best Practices

​Affiliate Code Validation

​Invitation Management

​Webhook Integration

​Commission Tracking

​Related Resources

Pulses Guide

Get Affiliate API

Send Invitations API

Sales Guide

Affiliate Object

Key Fields

Affiliate Statuses

Getting an Affiliate

Sending Affiliate Invitations

Batch Invitations

Response

Invitation Object

Invitation Statuses

Webhook Events

affiliate.joined

Implementation Example

API Endpoints Summary

Best Practices

Affiliate Code Validation

Invitation Management

Webhook Integration

Commission Tracking

Related Resources