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_123abc
Request Example
curl -X GET "http://localhost:3000/api/v1/earnings/earn_123abc" \
-H "Authorization: Bearer sk_your_secret_key_here"
Response
The API returns a detailed earning object:
Unique identifier for the earning.
ID of the referral that generated this earning.
Amount in cents (e.g., 1000 = $10.00).
Currency code (ISO 4217 format).
Type of earning (e.g., “purchase”, “subscription”, “recurring”).
Description of the earning.
Current status: pending, processing, paid, or failed.
External reference (e.g., Stripe payout ID, transaction ID).
ISO 8601 timestamp of when the earning was created.
ISO 8601 timestamp of when the earning was paid out, if applicable.
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
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(
`http://localhost:3000/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(
`http://localhost:3000/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.Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
