> ## Documentation Index
> Fetch the complete documentation index at: https://chariow.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Affiliates
> Learn how to manage your affiliate programme via the Chariow API
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:
```json theme={null}
{
"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
| 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:
```bash cURL theme={null}
curl -X GET "https://api.chariow.com/v1/affiliates/CREATOR123" \
-H "Authorization: Bearer sk_live_your_api_key"
```
```javascript JavaScript theme={null}
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:
```bash cURL theme={null}
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"]
}'
```
```javascript JavaScript theme={null}
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
### Response
```json theme={null}
{
"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:
```json theme={null}
{
"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
| 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 (accepts an invitation), a webhook event is triggered via [Pulses](/en/guides/pulses).
### affiliate.joined
Triggered when a new affiliate joins your store.
```json theme={null}
{
"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:
```javascript theme={null}
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
## Related Resources
Set up webhooks for affiliate events
View the Get Affiliate API reference
View the Send Invitations API reference
Track affiliate sales