# Get all earnings
curl -X GET "https://vantio.app/api/v1/earnings" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get paid earnings from a specific program
curl -X GET "https://vantio.app/api/v1/earnings?program_id=prog_123abc&status=paid&limit=100" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get earnings for a specific referral
curl -X GET "https://vantio.app/api/v1/earnings?referral_id=ref_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here"
{
"earnings": [
{
"id": "earn_123abc",
"referral_id": "ref_123abc",
"amount": 1000,
"currency": "USD",
"type": "purchase",
"description": "Commission from customer purchase",
"status": "paid",
"reference_id": "payout_456def",
"created_at": "2024-01-15T10:30:00Z",
"paid_at": "2024-01-20T14:20:00Z",
"metadata": {
"order_id": "order_789",
"commission_rate": "10%"
}
},
{
"id": "earn_456def",
"referral_id": "ref_789ghi",
"amount": 500,
"currency": "USD",
"type": "subscription",
"description": "Monthly subscription commission",
"status": "pending",
"reference_id": null,
"created_at": "2024-01-17T09:15:00Z",
"paid_at": null,
"metadata": {
"subscription_id": "sub_123",
"commission_rate": "5%"
}
}
]
}
Earnings
List Earnings
Retrieve a list of all earnings from your programs
GET
/
api
/
v1
/
earnings
# Get all earnings
curl -X GET "https://vantio.app/api/v1/earnings" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get paid earnings from a specific program
curl -X GET "https://vantio.app/api/v1/earnings?program_id=prog_123abc&status=paid&limit=100" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get earnings for a specific referral
curl -X GET "https://vantio.app/api/v1/earnings?referral_id=ref_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here"
{
"earnings": [
{
"id": "earn_123abc",
"referral_id": "ref_123abc",
"amount": 1000,
"currency": "USD",
"type": "purchase",
"description": "Commission from customer purchase",
"status": "paid",
"reference_id": "payout_456def",
"created_at": "2024-01-15T10:30:00Z",
"paid_at": "2024-01-20T14:20:00Z",
"metadata": {
"order_id": "order_789",
"commission_rate": "10%"
}
},
{
"id": "earn_456def",
"referral_id": "ref_789ghi",
"amount": 500,
"currency": "USD",
"type": "subscription",
"description": "Monthly subscription commission",
"status": "pending",
"reference_id": null,
"created_at": "2024-01-17T09:15:00Z",
"paid_at": null,
"metadata": {
"subscription_id": "sub_123",
"commission_rate": "5%"
}
}
]
}
Retrieve a list of all earnings from your programs. This endpoint helps you track commissions, monitor payout status, and analyze earnings performance across programs and ambassadors.
Overview
The List Earnings endpoint returns a paginated list of all earnings created when referred customers spend money on your platform. Use this endpoint to:- Track all earnings across programs
- Monitor earnings by referral or program
- Filter earnings by status (pending, processing, paid, failed)
- Build earnings dashboards and reports
- Calculate total commissions owed to ambassadors
Authentication
This endpoint requires authentication using a Bearer token in the Authorization header:Authorization: Bearer sk_your_secret_key_here
Query Parameters
Filter results to only include earnings from a specific referral. Useful when tracking earnings for a particular signup.Example:
referral_id=ref_123abcFilter results to only include earnings from a specific program. Useful when analyzing earnings for individual programs.Example:
program_id=prog_123abcFilter earnings by their current status. Valid values are:
pending- Earning created but not yet processedprocessing- Earning is being processed for payoutpaid- Earning has been paid outfailed- Earning payment failed
status=paid returns only paid earningsMaximum number of results to return per page. Default is 50, maximum is typically 100.Example:
limit=25Number of results to skip before starting to return results. Use for pagination.Example:
offset=50 skips the first 50 resultsRequest Example
# Get all earnings
curl -X GET "https://vantio.app/api/v1/earnings" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get paid earnings from a specific program
curl -X GET "https://vantio.app/api/v1/earnings?program_id=prog_123abc&status=paid&limit=100" \
-H "Authorization: Bearer sk_your_secret_key_here"
# Get earnings for a specific referral
curl -X GET "https://vantio.app/api/v1/earnings?referral_id=ref_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here"
Response
The API returns a JSON object containing an array of earning objects: Each earning object contains:Response Example
{
"earnings": [
{
"id": "earn_123abc",
"referral_id": "ref_123abc",
"amount": 1000,
"currency": "USD",
"type": "purchase",
"description": "Commission from customer purchase",
"status": "paid",
"reference_id": "payout_456def",
"created_at": "2024-01-15T10:30:00Z",
"paid_at": "2024-01-20T14:20:00Z",
"metadata": {
"order_id": "order_789",
"commission_rate": "10%"
}
},
{
"id": "earn_456def",
"referral_id": "ref_789ghi",
"amount": 500,
"currency": "USD",
"type": "subscription",
"description": "Monthly subscription commission",
"status": "pending",
"reference_id": null,
"created_at": "2024-01-17T09:15:00Z",
"paid_at": null,
"metadata": {
"subscription_id": "sub_123",
"commission_rate": "5%"
}
}
]
}
Use Cases
Building an Earnings Dashboard
Fetch all earnings and display them in a dashboard:async function fetchEarnings(filters = {}) {
const params = new URLSearchParams();
if (filters.referralId) params.append('referral_id', filters.referralId);
if (filters.programId) params.append('program_id', filters.programId);
if (filters.status) params.append('status', filters.status);
if (filters.limit) params.append('limit', filters.limit);
if (filters.offset) params.append('offset', filters.offset);
const response = await fetch(
`https://vantio.app/api/v1/earnings?${params.toString()}`,
{
headers: {
'Authorization': `Bearer ${API_KEY}`
}
}
);
return await response.json();
}
Calculating Total Earnings
Calculate total earnings for a program or ambassador:async function calculateTotalEarnings(programId, status = 'paid') {
const earnings = await fetchEarnings({ programId, status, limit: 1000 });
const total = earnings.earnings.reduce((sum, earning) => {
return sum + earning.amount;
}, 0);
// Convert from cents to dollars
return total / 100;
}
Tracking Pending Payouts
Get all earnings that need to be paid out:async function getPendingPayouts(programId) {
const pending = await fetchEarnings({
programId,
status: 'pending',
limit: 1000
});
const processing = await fetchEarnings({
programId,
status: 'processing',
limit: 1000
});
return {
pending: pending.earnings,
processing: processing.earnings,
totalPending: pending.earnings.reduce((sum, e) => sum + e.amount, 0) / 100,
totalProcessing: processing.earnings.reduce((sum, e) => sum + e.amount, 0) / 100
};
}
Exporting Earnings Data
Fetch all earnings for export:async function exportAllEarnings(programId) {
let allEarnings = [];
let offset = 0;
const limit = 100;
let hasMore = true;
while (hasMore) {
const response = await fetch(
`https://vantio.app/api/v1/earnings?program_id=${programId}&limit=${limit}&offset=${offset}`,
{
headers: {
'Authorization': `Bearer ${API_KEY}`
}
}
);
const data = await response.json();
allEarnings = [...allEarnings, ...data.earnings];
hasMore = data.earnings.length === limit;
offset += limit;
}
return allEarnings;
}
Best Practices
- Use filters effectively - Combine filters to narrow results and improve performance
- Implement pagination - Always use
limitandoffsetfor large datasets - Track status changes - Monitor earnings status to ensure timely payouts
- Store reference IDs - Use reference_id to link to external payment systems
- Calculate totals carefully - Remember amounts are in cents, convert to dollars for display
Error Responses
Unauthorized - Invalid or missing API key
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
Rate Limits
This endpoint is subject to rate limiting. Check response headers for rate limit information.Authorizations
Query Parameters
Response
List of earnings
Was this page helpful?