curl -X GET "https://vantio.app/api/v1/earnings/earn_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here"
{
"id": "earn_123abc",
"referral_id": "ref_123abc",
"amount": 1000,
"currency": "USD",
"type": "purchase",
"description": "Commission from customer purchase - Order #12345",
"status": "paid",
"reference_id": "payout_456def",
"created_at": "2024-01-15T10:30:00Z",
"paid_at": "2024-01-20T14:20:00Z",
"metadata": {
"order_id": "order_12345",
"commission_rate": "10%"
}
}
Earnings
Get Earning
Retrieve detailed information about a specific earning
GET
/
api
/
v1
/
earnings
/
{id}
curl -X GET "https://vantio.app/api/v1/earnings/earn_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here"
{
"id": "earn_123abc",
"referral_id": "ref_123abc",
"amount": 1000,
"currency": "USD",
"type": "purchase",
"description": "Commission from customer purchase - Order #12345",
"status": "paid",
"reference_id": "payout_456def",
"created_at": "2024-01-15T10:30:00Z",
"paid_at": "2024-01-20T14:20:00Z",
"metadata": {
"order_id": "order_12345",
"commission_rate": "10%"
}
}
Retrieve detailed information about a specific earning by its unique ID. Use this endpoint to fetch complete earning details including amount, status, and associated referral.
Overview
The Get Earning endpoint returns comprehensive information about a single earning. This is useful for:- Viewing earning details in dashboards
- Checking earning status before processing payouts
- Verifying earning information for customer support
- Building earning detail pages
- Tracking payout progress
Authentication
This endpoint requires authentication using a Bearer token in the Authorization header:Authorization: Bearer sk_your_secret_key_here
Path Parameters
The unique identifier of the earning you want to retrieve. This ID is returned when you create an earning or list earnings.Example:
earn_123abcRequest Example
curl -X GET "https://vantio.app/api/v1/earnings/earn_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here"
Response
The API returns a detailed earning object:Response Example
{
"id": "earn_123abc",
"referral_id": "ref_123abc",
"amount": 1000,
"currency": "USD",
"type": "purchase",
"description": "Commission from customer purchase - Order #12345",
"status": "paid",
"reference_id": "payout_456def",
"created_at": "2024-01-15T10:30:00Z",
"paid_at": "2024-01-20T14:20:00Z",
"metadata": {
"order_id": "order_12345",
"commission_rate": "10%"
}
}
Error Responses
Unauthorized - Invalid or missing API key
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
Not Found - The earning with the specified ID does not exist
{
"error": "Not Found",
"message": "Earning not found"
}
Use Cases
Checking Earning Status
Before processing a payout, verify the earning status:async function checkEarningStatus(earningId) {
const response = await fetch(
`https://vantio.app/api/v1/earnings/${earningId}`,
{
headers: {
'Authorization': `Bearer ${API_KEY}`
}
}
);
if (response.status === 404) {
throw new Error('Earning not found');
}
const earning = await response.json();
return earning.status; // 'pending', 'processing', 'paid', or 'failed'
}
Building Earning Detail View
Display complete earning information:async function EarningDetail({ earningId }) {
const [earning, setEarning] = useState(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
async function fetchEarning() {
try {
const response = await fetch(
`https://vantio.app/api/v1/earnings/${earningId}`,
{
headers: {
'Authorization': `Bearer ${API_KEY}`
}
}
);
if (response.ok) {
const data = await response.json();
setEarning(data);
}
} catch (error) {
console.error('Error:', error);
} finally {
setLoading(false);
}
}
fetchEarning();
}, [earningId]);
if (loading) return <div>Loading...</div>;
if (!earning) return <div>Earning not found</div>;
const amountInDollars = (earning.amount / 100).toFixed(2);
return (
<div>
<h1>Earning Details</h1>
<p>Amount: ${amountInDollars} {earning.currency}</p>
<p>Status: {earning.status}</p>
<p>Type: {earning.type || 'N/A'}</p>
<p>Description: {earning.description || 'N/A'}</p>
<p>Created: {new Date(earning.created_at).toLocaleDateString()}</p>
{earning.paid_at && (
<p>Paid: {new Date(earning.paid_at).toLocaleDateString()}</p>
)}
</div>
);
}
Best Practices
- Cache earning data - Earning information doesn’t change frequently
- Handle 404 errors - Always check if the earning exists
- Convert amounts for display - Remember amounts are in cents
- Monitor status changes - Use webhooks or polling to track status updates
- Link to referrals - Use referral_id to fetch related referral information
Rate Limits
This endpoint is subject to rate limiting. Check response headers for rate limit information.Was this page helpful?