# Create an earning from a purchase
curl -X POST "https://vantio.app/api/v1/earnings" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"referral_id": "ref_123abc",
"amount": 1000,
"currency": "USD",
"type": "purchase",
"description": "Commission from customer purchase - Order #12345",
"metadata": {
"order_id": "order_12345",
"commission_rate": "10%"
},
"idempotency_key": "earn_order12345_20240115"
}'
# Create a subscription earning
curl -X POST "https://vantio.app/api/v1/earnings" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"referral_id": "ref_123abc",
"amount": 500,
"currency": "USD",
"type": "subscription",
"description": "Monthly subscription commission",
"metadata": {
"subscription_id": "sub_123",
"commission_rate": "5%"
},
"idempotency_key": "earn_sub123_20240115"
}'
{
"id": "earn_789ghi",
"referral_id": "ref_123abc",
"amount": 1000,
"currency": "USD",
"type": "purchase",
"description": "Commission from customer purchase - Order #12345",
"status": "pending",
"created_at": "2024-01-15T10:30:00Z",
"metadata": {
"order_id": "order_12345",
"commission_rate": "10%"
}
}
Earnings
Create Earning
Create a new earning when a referred customer spends money on your platform
POST
/
api
/
v1
/
earnings
# Create an earning from a purchase
curl -X POST "https://vantio.app/api/v1/earnings" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"referral_id": "ref_123abc",
"amount": 1000,
"currency": "USD",
"type": "purchase",
"description": "Commission from customer purchase - Order #12345",
"metadata": {
"order_id": "order_12345",
"commission_rate": "10%"
},
"idempotency_key": "earn_order12345_20240115"
}'
# Create a subscription earning
curl -X POST "https://vantio.app/api/v1/earnings" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"referral_id": "ref_123abc",
"amount": 500,
"currency": "USD",
"type": "subscription",
"description": "Monthly subscription commission",
"metadata": {
"subscription_id": "sub_123",
"commission_rate": "5%"
},
"idempotency_key": "earn_sub123_20240115"
}'
{
"id": "earn_789ghi",
"referral_id": "ref_123abc",
"amount": 1000,
"currency": "USD",
"type": "purchase",
"description": "Commission from customer purchase - Order #12345",
"status": "pending",
"created_at": "2024-01-15T10:30:00Z",
"metadata": {
"order_id": "order_12345",
"commission_rate": "10%"
}
}
Create a new earning when a referred customer spends money on your platform. This endpoint is typically called when processing a purchase, subscription, or other transaction from a referred customer.
Overview
The Create Earning endpoint allows you to record commissions and earnings for student ambassadors when their referrals make purchases. This is a critical endpoint that:- Links earnings to specific referrals
- Tracks commission amounts and currency
- Records earning type and description
- Enables payout processing
- Supports idempotent requests to prevent duplicates
- Record commissions from customer purchases
- Track subscription-based earnings
- Create recurring earnings
- Process one-time payments
- Enable automated payout systems
Authentication
This endpoint requires authentication using a Bearer token in the Authorization header:Authorization: Bearer sk_your_secret_key_here
Request Body
Required. The ID of the referral that generated this earning. This links the earning back to the original signup and ambassador.Example:
ref_123abcNote: The referral must exist in your system and typically should have a status of converted.Required. Amount in cents. For example, to represent $10.00, send `1000`. To represent $5.50, send
550.Example: 1000 (represents $10.00)Important: Always specify amounts in the smallest currency unit (cents for USD).Currency code in ISO 4217 format. Defaults to “USD” if not specified.Examples:
USD, EUR, GBP, CADNote: Ensure the currency matches your program’s payout currency.Type of earning. Use this to categorize different earning types for reporting and analytics.Examples:
purchase- One-time purchase commissionsubscription- Subscription-based commissionrecurring- Recurring payment commissionbonus- Bonus or special promotion
purchaseHuman-readable description of the earning. This helps ambassadors understand what the earning is for.Example:
Commission from customer purchase - Order #12345Optional additional metadata about the earning. Use this to store custom information like order IDs, transaction IDs, commission rates, or other relevant data.Example:
{
"order_id": "order_12345",
"transaction_id": "txn_67890",
"commission_rate": "10%",
"product_name": "Premium Subscription"
}
Optional unique key for idempotent requests. If you send the same
idempotency_key within a short time window, the API will return the same earning instead of creating a duplicate. This is essential for retry logic and webhook processing.Example: earn_20240115_order12345Best Practice: Use a combination of order/transaction ID and timestamp to ensure uniqueness.Request Example
# Create an earning from a purchase
curl -X POST "https://vantio.app/api/v1/earnings" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"referral_id": "ref_123abc",
"amount": 1000,
"currency": "USD",
"type": "purchase",
"description": "Commission from customer purchase - Order #12345",
"metadata": {
"order_id": "order_12345",
"commission_rate": "10%"
},
"idempotency_key": "earn_order12345_20240115"
}'
# Create a subscription earning
curl -X POST "https://vantio.app/api/v1/earnings" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"referral_id": "ref_123abc",
"amount": 500,
"currency": "USD",
"type": "subscription",
"description": "Monthly subscription commission",
"metadata": {
"subscription_id": "sub_123",
"commission_rate": "5%"
},
"idempotency_key": "earn_sub123_20240115"
}'
Response
On success, the API returns the created earning object:Response Example
{
"id": "earn_789ghi",
"referral_id": "ref_123abc",
"amount": 1000,
"currency": "USD",
"type": "purchase",
"description": "Commission from customer purchase - Order #12345",
"status": "pending",
"created_at": "2024-01-15T10:30:00Z",
"metadata": {
"order_id": "order_12345",
"commission_rate": "10%"
}
}
Error Responses
Bad Request - Invalid request dataCommon causes:
{
"error": "Bad Request",
"message": "Missing required field: referral_id"
}
- Missing required fields (referral_id, amount)
- Invalid amount (must be a positive number)
- Invalid referral_id (referral doesn’t exist)
- Invalid currency code
Unauthorized - Invalid or missing API key
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
Use Cases
Processing Purchase Webhooks
When a referred customer makes a purchase, create an earning:async function handlePurchaseWebhook(orderData, referralId) {
try {
// Calculate commission (e.g., 10% of order total)
const commissionRate = 0.10;
const amountInCents = Math.round(orderData.total * commissionRate * 100);
const response = await fetch('https://vantio.app/api/v1/earnings', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
referral_id: referralId,
amount: amountInCents,
currency: 'USD',
type: 'purchase',
description: `Commission from order #${orderData.orderId}`,
metadata: {
order_id: orderData.orderId,
transaction_id: orderData.transactionId,
commission_rate: `${commissionRate * 100}%`,
order_total: orderData.total
},
idempotency_key: `earn_${orderData.orderId}_${Date.now()}`
})
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.message);
}
const earning = await response.json();
console.log('Earning created:', earning.id);
return earning;
} catch (error) {
console.error('Error creating earning:', error);
throw error;
}
}
Creating Subscription Earnings
Process recurring subscription commissions:async function createSubscriptionEarning(subscriptionData, referralId) {
const commissionRate = 0.05; // 5% for subscriptions
const amountInCents = Math.round(subscriptionData.monthlyAmount * commissionRate * 100);
const response = await fetch('https://vantio.app/api/v1/earnings', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
referral_id: referralId,
amount: amountInCents,
currency: 'USD',
type: 'subscription',
description: `Monthly subscription commission - ${subscriptionData.planName}`,
metadata: {
subscription_id: subscriptionData.subscriptionId,
commission_rate: '5%',
plan_name: subscriptionData.planName
},
idempotency_key: `earn_sub_${subscriptionData.subscriptionId}_${subscriptionData.billingPeriod}`
})
});
return await response.json();
}
Idempotent Earning Creation
Use idempotency keys to prevent duplicate earnings:async function createEarningSafely(earningData, orderId) {
const idempotencyKey = `earn_${orderId}_${earningData.referral_id}`;
const response = await fetch('https://vantio.app/api/v1/earnings', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
...earningData,
idempotency_key: idempotencyKey
})
});
// If the earning already exists (idempotent), the API returns the existing one
return await response.json();
}
Best Practices
- Always use idempotency keys - Critical for webhook processing and retry logic
- Validate referral status - Ensure referral is
convertedbefore creating earnings - Store amounts in cents - Always convert dollar amounts to cents (multiply by 100)
- Include metadata - Store order IDs, transaction IDs, and commission rates for tracking
- Use descriptive types - Categorize earnings for better reporting
- Handle errors gracefully - Check for 400 errors and provide user-friendly messages
- Link to external systems - Store reference IDs in metadata for payment processing
Amount Conversion
Remember to convert dollar amounts to cents:// Converting $10.00 to cents
const dollars = 10.00;
const cents = Math.round(dollars * 100); // 1000
// Converting cents back to dollars for display
const displayAmount = cents / 100; // 10.00
Workflow
The typical earning creation workflow:- Referred customer makes a purchase → Earning created (this endpoint)
- Earning status is
pending→ Ready for processing - Earning status changes to
processing→ Payout initiated - Earning status changes to
paid→ Commission paid to ambassador
Rate Limits
This endpoint is subject to rate limiting. Check response headers for rate limit information.Authorizations
Body
application/json
Response
Earning created successfully
Was this page helpful?