Get Earning

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%"
  }
}

GET

api

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_123abc

Request 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.

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

Response

Earning details

API Documentation

Users

Referrals

Posters

Impressions

Earnings

Overview

Authentication

Path Parameters

Request Example

Response

Response Example

Error Responses

Use Cases

Checking Earning Status

Building Earning Detail View

Best Practices

Rate Limits

Authorizations

Path Parameters

Response

​Overview

​Authentication

​Path Parameters

​Request Example

​Response

​Response Example

​Error Responses

​Use Cases

​Checking Earning Status

​Building Earning Detail View

​Best Practices

​Rate Limits

Authorizations

Path Parameters

Response

Overview

Authentication

Path Parameters

Request Example

Response

Response Example

Error Responses

Use Cases

Checking Earning Status

Building Earning Detail View

Best Practices

Rate Limits