API
A comprehensive API for tracking affiliate orders, calculating commissions, and managing partner relationships in your affiliate program.
Overview
The Affiliate Order Tracking API enables seamless integration of affiliate tracking into your e-commerce platform. When a customer makes a purchase using an affiliate code, this API records the order, creates or updates customer records, calculates commissions based on partner settings, and tracks affiliate program statistics.
Authentication
All API requests require authentication using your API key.
Y-API-Key header in all requests. You can find your API key in the dashboard settings under Settings > API.Endpoint Details
POST https://yaplet.com/api/affiliates/track/{affiliate_code}
Records a new affiliate order and calculates commission based on partner settings. Creates or updates customer records and partner statistics. Returns success: false for invalid affiliate codes (normal behavior).
Base URL: https://yaplet.com/api/affiliates/track/YOUR_AFFILIATE_CODE
YOUR_AFFILIATE_CODE with the actual affiliate partner's coupon code. If the code is invalid, the API returns success: false (this is expected behavior, not an error).Request Structure
Headers
{
"Content-Type": "application/json",
"Y-API-Key": "YOUR_API_KEY"
}
Request Body
{
"order_id": "order_12345", // Required - Unique order identifier
"total_amount": 100.0, // Required - Order total in decimal format
"customer": { // Required
"email": "[email protected]", // Required - Customer email address
"name": "John Doe",
"customer_id": "cust_12345",
"customer_metadata": {
"source": "website",
"campaign": "summer2024"
}
},
"commission": 10.0, // Optional - Custom commission amount
"notes": "First order from customer",
"timestamp": 1640995200000, // Optional - Order timestamp (milliseconds)
"product": { // Optional
"id": "prod_123",
"name": "Premium Plan",
"category": "subscription"
},
"metadata": { // Optional
"campaign_id": "camp_123",
"utm_source": "facebook"
}
}
Response Examples
Successful Tracking (Valid Affiliate Code)
Status: 200 OK
{
"success": true,
"data": {
"commission_id": "comm_123456789",
"partner_id": "partner_123",
"customer_id": "customer_456",
"commission_amount": 10.0,
"order_id": "order_12345",
"affiliate_code": "AFFILIATE_CODE"
}
}
Invalid Affiliate Code
Status: 200 OK
{
"success": false,
"message": "No approved affiliate partner found for coupon code: AFFILIATE_CODE"
}
success: false with a 200 status code. This is normal behavior and indicates the code was not found in the system.Commission Calculation
Commissions are calculated automatically based on partner settings and the following priority rules:
Calculation Priority
- Partner Override: If partner has
ignore_product_rate = trueand has a rate set, partner rate is always used - Custom Commission: If commission amount is provided in the API request, that amount is used
- Partner Rate: If partner has a rate set (and
ignore_product_rateis false), partner rate is used - No Commission: If none of the above conditions are met, commission = 0
Rate Types
Percentage Rate
commission = total_amount * (rate.value / 100)
Example: $100 order × 10% = $10 commission
Fixed Rate
commission = rate.value
Example: $5 commission per order
Code Examples
const response = await fetch('https://yaplet.com/api/affiliates/track/YOUR_AFFILIATE_CODE', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Y-API-Key': 'YOUR_API_KEY'
},
body: JSON.stringify({
"order_id": "order_12345", // Required
"total_amount": 100.0, // Required
"customer": { // Required
"email": "[email protected]", // Required
"name": "John Doe",
"customer_id": "cust_12345",
"customer_metadata": {
"source": "website",
"campaign": "summer2024"
}
},
"commission": 10.0,
"notes": "First order from customer",
"timestamp": 1640995200000,
"product": {
"id": "prod_123",
"name": "Premium Plan",
"category": "subscription"
},
"metadata": {
"campaign_id": "camp_123",
"utm_source": "facebook"
}
})
});
const result = await response.json();
console.log('Response:', result);
# order_id: Required
# total_amount: Required
# customer: Required
# customer.email: Required
curl -X POST https://yaplet.com/api/affiliates/track/YOUR_AFFILIATE_CODE \
-H "Content-Type: application/json" \
-H "Y-API-Key: YOUR_API_KEY" \
-d '{
"order_id": "order_12345",
"total_amount": 100.0,
"customer": {
"email": "[email protected]",
"name": "John Doe",
"customer_id": "cust_12345",
"customer_metadata": {
"source": "website",
"campaign": "summer2024"
}
},
"commission": 10.0,
"notes": "First order from customer",
"timestamp": 1640995200000,
"product": {
"id": "prod_123",
"name": "Premium Plan",
"category": "subscription"
},
"metadata": {
"campaign_id": "camp_123",
"utm_source": "facebook"
}
}'
<?php
$url = "https://yaplet.com/api/affiliates/track/YOUR_AFFILIATE_CODE";
$headers = [
'Content-Type: application/json',
'Y-API-Key: YOUR_API_KEY'
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"order_id" => "order_12345", // Required
"total_amount" => 100.0, // Required
"customer" => [ // Required
"email" => "[email protected]", // Required
"name" => "John Doe",
"customer_id" => "cust_12345",
"customer_metadata" => [
"source" => "website",
"campaign" => "summer2024"
]
],
"commission" => 10.0,
"notes" => "First order from customer",
"timestamp" => 1640995200000,
"product" => [
"id" => "prod_123",
"name" => "Premium Plan",
"category" => "subscription"
],
"metadata" => [
"campaign_id" => "camp_123",
"utm_source" => "facebook"
]
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
$result = json_decode($response, true);
echo "Response: " . print_r($result, true);
} else {
throw new Exception("Error: " . $response);
}
?>
import requests
url = "https://yaplet.com/api/affiliates/track/YOUR_AFFILIATE_CODE"
headers = {
"Content-Type": "application/json",
"Y-API-Key": "YOUR_API_KEY"
}
response = requests.post(url, headers=headers, json={
"order_id": "order_12345", # Required
"total_amount": 100.0, # Required
"customer": { # Required
"email": "[email protected]", # Required
"name": "John Doe",
"customer_id": "cust_12345",
"customer_metadata": {
"source": "website",
"campaign": "summer2024"
}
},
"commission": 10.0,
"notes": "First order from customer",
"timestamp": 1640995200000,
"product": {
"id": "prod_123",
"name": "Premium Plan",
"category": "subscription"
},
"metadata": {
"campaign_id": "camp_123",
"utm_source": "facebook"
}
})
if response.status_code == 200:
result = response.json()
print('Response:', result)
else:
raise Exception(f"Error: {response.text}")
Field Reference
Required Fields
| Field | Type | Description |
|---|---|---|
order_id | string | Unique identifier for the order. Used to prevent duplicate commissions and for tracking purposes. |
total_amount | number | Total order amount in decimal format. Used for commission calculation and revenue tracking. |
customer.email | string | Customer email address. Required for customer identification and tracking repeat purchases. |
Y-API-Key | header | API authentication key. Must be included in request headers for security validation. |
Optional Fields
| Field | Type | Default | Description |
|---|---|---|---|
timestamp | number | Current timestamp | Order timestamp in milliseconds. If not provided, current server time will be used. Accepts both seconds (10 digits) and milliseconds (13 digits). |
commission | number | Calculated from partner rate | Custom commission amount. If not provided, will be calculated based on partner rate settings. |
notes | string | null | Additional notes about the order or commission. |
customer.name | string | Email prefix (part before @) | Customer full name for display purposes. |
customer.customer_id | string | null | External customer ID from your system for cross-reference. |
customer.customer_metadata | object | Empty object {} | Additional customer data like source, campaign, etc. |
product | object | Empty object {} | Product information including ID, name, category, etc. Stored for reporting purposes. |
metadata | object | Empty object {} | Additional order metadata like campaign IDs, UTM parameters, etc. |
URL Parameters
| Parameter | Description |
|---|---|
affiliate_code | Replace YOUR_AFFILIATE_CODE with the actual affiliate partner's coupon code. If the code is invalid or doesn't exist, the API will return success: false (this is normal behavior, not an error). |
Error Handling
Common Error Codes
| Code | Message | Description |
|---|---|---|
401 | API key is required / Invalid API key | Missing or invalid Y-API-Key header |
403 | Unauthorized | User does not have permission to use this API |
400 | Affiliate code is required in URL | Missing affiliate code in URL path |
400 | order_id and total_amount are required | Missing required fields in request body |
400 | Customer with email is required | Missing customer object or customer.email field |
400 | Both customer and partner information are required to create a commission | Missing customer or partner data for commission creation |
409 | Order {order_id} has already been tracked for this organization | Duplicate order detection - this order has already been processed |
500 | Internal server error | Server error during processing |
Integration Best Practices
- Validate Affiliate Codes: Always check if the affiliate code exists before sending tracking requests
- Handle Invalid Codes: Expect
success: falseresponses for invalid codes - this is normal behavior - Prevent Duplicates: Use unique order IDs to avoid duplicate commission tracking
- Include Customer Data: Provide customer email at minimum for proper tracking
- Use Timestamps: Include order timestamps for accurate reporting
- Monitor Rate Limits: Implement proper error handling and retry logic
Support
For additional support or questions about the Affiliate API, please contact our support team or refer to the API settings in your dashboard.