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
string
required
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:string
required
Unique identifier for the earning.
string
required
ID of the referral that generated this earning.
number
required
Amount in cents (e.g., 1000 = $10.00).
string
required
Currency code (ISO 4217 format).
string
Type of earning (e.g., “purchase”, “subscription”, “recurring”).
string
Description of the earning.
string
required
Current status:
pending, processing, paid, or failed.string
External reference (e.g., Stripe payout ID, transaction ID).
string
required
ISO 8601 timestamp of when the earning was created.
string
ISO 8601 timestamp of when the earning was paid out, if applicable.
object
Additional metadata associated with the earning.
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
object
Unauthorized - Invalid or missing API key
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
object
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?