# Update earning status to processing
curl -X PUT "https://vantio.app/api/v1/earnings/earn_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"status": "processing"
}'
# Update status to paid with payout reference
curl -X PUT "https://vantio.app/api/v1/earnings/earn_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"status": "paid",
"reference_id": "payout_456def",
"metadata": {
"payout_id": "payout_456def",
"processed_at": "2024-01-20T14:20:00Z"
}
}'
{
"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",
"updated_at": "2024-01-20T14:20:00Z",
"metadata": {
"order_id": "order_12345",
"payout_id": "payout_456def",
"processed_at": "2024-01-20T14:20:00Z"
}
}
Earnings
Update Earning
Update an existing earning’s information
PUT
/
api
/
v1
/
earnings
/
{id}
# Update earning status to processing
curl -X PUT "https://vantio.app/api/v1/earnings/earn_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"status": "processing"
}'
# Update status to paid with payout reference
curl -X PUT "https://vantio.app/api/v1/earnings/earn_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"status": "paid",
"reference_id": "payout_456def",
"metadata": {
"payout_id": "payout_456def",
"processed_at": "2024-01-20T14:20:00Z"
}
}'
{
"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",
"updated_at": "2024-01-20T14:20:00Z",
"metadata": {
"order_id": "order_12345",
"payout_id": "payout_456def",
"processed_at": "2024-01-20T14:20:00Z"
}
}
Update an existing earning’s information. Use this endpoint to change earning status, update payout references, or modify metadata.
Overview
The Update Earning endpoint allows you to modify earning information after it has been created. Common use cases include:- Updating earning status (e.g., from
pendingtoprocessingtopaid) - Adding payout reference IDs (e.g., Stripe payout ID)
- Updating metadata with transaction information
- Marking earnings as failed if payout fails
- Correcting earning amounts or descriptions
Authentication
This endpoint requires authentication using a Bearer token in the Authorization header:Authorization: Bearer sk_your_secret_key_here
Path Parameters
Request Body
All fields in the request body are optional. Only include the fields you want to update.Update the amount in cents. Use this to correct amounts if needed.Example:
1500 (represents $15.00)Update the description of the earning.Example:
Commission from customer purchase - Order #12345Update the earning 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
paidUpdate the external reference ID (e.g., Stripe payout ID, transaction ID). Typically set when status changes to
processing or paid.Example: payout_456defUpdate additional metadata. This will merge with existing metadata or replace it depending on your API configuration.Example:
{
"order_id": "order_12345",
"payout_id": "payout_456def",
"processed_at": "2024-01-20T14:20:00Z"
}
Request Example
# Update earning status to processing
curl -X PUT "https://vantio.app/api/v1/earnings/earn_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"status": "processing"
}'
# Update status to paid with payout reference
curl -X PUT "https://vantio.app/api/v1/earnings/earn_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"status": "paid",
"reference_id": "payout_456def",
"metadata": {
"payout_id": "payout_456def",
"processed_at": "2024-01-20T14:20:00Z"
}
}'
Response
On success, the API returns the updated 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",
"updated_at": "2024-01-20T14:20:00Z",
"metadata": {
"order_id": "order_12345",
"payout_id": "payout_456def",
"processed_at": "2024-01-20T14:20:00Z"
}
}
Error Responses
Bad Request - Invalid request data
{
"error": "Bad Request",
"message": "Invalid status value. Must be one of: pending, processing, paid, failed"
}
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
Processing Payouts
When initiating a payout, update the earning status:async function processPayout(earningId, payoutId) {
const response = await fetch(
`https://vantio.app/api/v1/earnings/${earningId}`,
{
method: 'PUT',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
status: 'processing',
reference_id: payoutId,
metadata: {
payout_id: payoutId,
processing_started_at: new Date().toISOString()
}
})
}
);
return await response.json();
}
Marking Earnings as Paid
After successful payout, mark the earning as paid:async function markEarningAsPaid(earningId, payoutId) {
const response = await fetch(
`https://vantio.app/api/v1/earnings/${earningId}`,
{
method: 'PUT',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
status: 'paid',
reference_id: payoutId,
metadata: {
payout_id: payoutId,
paid_at: new Date().toISOString()
}
})
}
);
return await response.json();
}
Handling Failed Payouts
If a payout fails, mark the earning as failed:async function markEarningAsFailed(earningId, errorMessage) {
const response = await fetch(
`https://vantio.app/api/v1/earnings/${earningId}`,
{
method: 'PUT',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
status: 'failed',
metadata: {
failure_reason: errorMessage,
failed_at: new Date().toISOString()
}
})
}
);
return await response.json();
}
Correcting Earning Amounts
If an amount needs to be corrected:async function correctEarningAmount(earningId, correctAmountInCents) {
const response = await fetch(
`https://vantio.app/api/v1/earnings/${earningId}`,
{
method: 'PUT',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: correctAmountInCents,
metadata: {
corrected_at: new Date().toISOString(),
correction_reason: 'Amount adjustment'
}
})
}
);
return await response.json();
}
Best Practices
- Update status carefully - Status changes should reflect actual payout events
- Store payout references - Always include reference_id when processing payouts
- Track status transitions - Use metadata to log when and why status changes
- Handle failures gracefully - Mark earnings as failed and store error messages
- Validate status values - Ensure status values are valid before sending
- Link to external systems - Store payout IDs in reference_id and metadata
Status Workflow
Typical earning status progression:pending→ Earning created, ready for processingprocessing→ Payout initiated, payment being processedpaid→ Payout completed successfullyfailed→ Payout failed (can happen at processing stage)
Rate Limits
This endpoint is subject to rate limiting. Check response headers for rate limit information.Authorizations
Body
application/json
Response
Earning updated successfully
Was this page helpful?