Update Earning

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 pending to processing to paid)
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

string

required

The unique identifier of the earning you want to update.Example: earn_123abc

Request Body

All fields in the request body are optional. Only include the fields you want to update.

amount

number

Update the amount in cents. Use this to correct amounts if needed.Example: 1500 (represents $15.00)

currency

string

Update the currency code (ISO 4217 format).Example: USD

type

string

Update the type of earning.Example: purchase, subscription, recurring

description

string

Update the description of the earning.Example: Commission from customer purchase - Order #12345

status

string

Update the earning status. Valid values are:

pending - Earning created but not yet processed
processing - Earning is being processed for payout
paid - Earning has been paid out
failed - Earning payment failed

Example: paid

reference_id

string

Update the external reference ID (e.g., Stripe payout ID, transaction ID). Typically set when status changes to processing or paid.Example: payout_456def

metadata

object

Update 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:

string

required

Unique identifier for the earning.

referral_id

string

required

ID of the referral that generated this earning.

amount

number

required

Updated amount in cents (if provided).

currency

string

required

Updated currency code (if provided).

status

string

required

Updated status (if provided).

reference_id

string

Updated reference ID (if provided).

updated_at

string

required

ISO 8601 timestamp of when the earning was last updated.

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

400

object

Bad Request - Invalid request data

{
  "error": "Bad Request",
  "message": "Invalid status value. Must be one of: pending, processing, paid, failed"
}

401

object

Unauthorized - Invalid or missing API key

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

404

object

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 processing
processing → Payout initiated, payment being processed
paid → Payout completed successfully
failed → Payout failed (can happen at processing stage)

Rate Limits

This endpoint is subject to rate limiting. Check response headers for rate limit information.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string

required

Earning ID

Body

application/json

amount

number

Amount in cents

currency

string

type

string

description

string

status

enum<string>

Available options:

pending,

processing,

paid,

failed

reference_id

string

External reference (e.g., Stripe payout ID)

metadata

object

Response

Earning updated successfully

API Documentation

Users

Referrals

Posters

Impressions

Earnings

Update Earning

Overview

Authentication

Path Parameters

Request Body

Request Example

Response

Response Example

Error Responses

Use Cases

Processing Payouts

Marking Earnings as Paid

Handling Failed Payouts

Correcting Earning Amounts

Best Practices

Status Workflow

Rate Limits

Authorizations

Path Parameters

Body

Response

API Documentation

Users

Referrals

Posters

Impressions

Earnings

​Overview

​Authentication

​Path Parameters

​Request Body

​Request Example

​Response

​Response Example

​Error Responses

​Use Cases

​Processing Payouts

​Marking Earnings as Paid

​Handling Failed Payouts

​Correcting Earning Amounts

​Best Practices

​Status Workflow

​Rate Limits

Authorizations

Path Parameters

Body

Response

Overview

Authentication

Path Parameters

Request Body

Request Example

Response

Response Example

Error Responses

Use Cases

Processing Payouts

Marking Earnings as Paid

Handling Failed Payouts

Correcting Earning Amounts

Best Practices

Status Workflow

Rate Limits