Billing Endpoints
The billing endpoints provide comprehensive management of payment
processing, subscription billing, usage tracking, and credit systems
within the Spartera platform. These endpoints support both sellers
receiving payments and buyers managing their analytics purchases.
Account Billing Overview
Get Billing Summary
Retrieve current billing status and summary for your account.
GET /companies/{company_id}/billing
Get Billing Summary Parameters
company_id(path, required): Company identifier
Get Billing Summary Response
{
"data": {
"company_id": "company_456",
"billing_status": "current",
"current_period": {
"start_date": "2025-01-01T00:00:00Z",
"end_date": "2025-01-31T23:59:59Z",
"days_remaining": 11
},
"account_balance": {
"available_credits": 2450.75,
"pending_charges": 156.25,
"currency": "USD"
},
"spending_summary": {
"current_month": 3245.80,
"last_month": 2890.45,
"average_monthly": 3150.20,
"year_to_date": 3245.80
},
"revenue_summary": {
"current_month": 8947.60,
"last_month": 7825.30,
"total_earnings": 124568.90,
"pending_payouts": 2845.20
},
"subscription_status": {
"plan": "professional",
"status": "active",
"next_billing_date": "2025-02-01T00:00:00Z",
"auto_renewal": true
},
"payment_method": {
"type": "card",
"last_four": "4242",
"brand": "visa",
"expires": "12/27"
}
}
}
Get Detailed Usage
Retrieve detailed usage and spending breakdown.
GET /companies/{company_id}/billing/usage
Get Detailed Usage Parameters
company_id(path, required): Company identifier
Get Detailed Usage Query Parameters
period(optional): Time period (current, last_30d, last_90d, ytd)group_by(optional): Group results by (day, week, month, analytics)analytics_id(optional): Filter by specific analytics
Get Detailed Usage Response
{
"data": {
"period": "last_30d",
"total_usage": {
"total_requests": 15420,
"total_cost": 3245.80,
"average_cost_per_request": 0.21
},
"usage_by_analytics": [
{
"analytics_id": "analytics_123",
"name": "Customer Churn Predictor",
"provider": "DataInsights Corp",
"usage": {
"requests": 8500,
"cost": 2125.00,
"average_response_time": 165
},
"cost_breakdown": {
"base_cost": 2125.00,
"overage_cost": 0,
"discount_applied": 0
}
},
{
"analytics_id": "analytics_456",
"name": "Market Sentiment Analyzer",
"provider": "ML Analytics Pro",
"usage": {
"requests": 6920,
"cost": 1120.80,
"average_response_time": 95
}
}
],
"usage_trends": [
{
"date": "2025-01-20",
"requests": 892,
"cost": 187.45
},
{
"date": "2025-01-19",
"requests": 756,
"cost": 158.76
}
]
}
}
Payment Methods
List Payment Methods
Get all payment methods associated with the account.
GET /companies/{company_id}/billing/payment-methods
List Payment Methods Parameters
company_id(path, required): Company identifier
List Payment Methods Response
{
"data": [
{
"payment_method_id": "pm_123",
"type": "card",
"brand": "visa",
"last_four": "4242",
"expires": {
"month": 12,
"year": 2027
},
"is_default": true,
"status": "active",
"billing_address": {
"line1": "123 Business Ave",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"created_at": "2024-03-15T10:00:00Z"
},
{
"payment_method_id": "pm_456",
"type": "bank_account",
"bank_name": "Chase Bank",
"last_four": "1234",
"account_type": "checking",
"is_default": false,
"status": "verified",
"created_at": "2024-06-20T14:30:00Z"
}
]
}
Add Payment Method
Add a new payment method to the account.
POST /companies/{company_id}/billing/payment-methods
Add Payment Method Parameters
company_id(path, required): Company identifier
Add Payment Method Request Body
{
"type": "card",
"token": "card_token_from_stripe_js",
"billing_address": {
"line1": "456 Corporate Blvd",
"line2": "Suite 100",
"city": "New York",
"state": "NY",
"postal_code": "10001",
"country": "US"
},
"set_as_default": true
}
Add Payment Method Response
{
"data": {
"payment_method_id": "pm_789",
"type": "card",
"brand": "mastercard",
"last_four": "5678",
"expires": {
"month": 8,
"year": 2028
},
"is_default": true,
"status": "active",
"created_at": "2025-01-20T20:30:00Z"
}
}
Update Payment Method
Update billing address or default status for a payment method.
PATCH /companies/{company_id}/billing/payment-methods/{payment_method_id}
Update Payment Method Parameters
company_id(path, required): Company identifierpayment_method_id(path, required): Payment method identifier
Update Payment Method Request Body
{
"billing_address": {
"line1": "789 Updated Address",
"city": "Los Angeles",
"state": "CA",
"postal_code": "90210",
"country": "US"
},
"set_as_default": true
}
Update Payment Method Response
{
"data": {
"payment_method_id": "pm_789",
"is_default": true,
"billing_address": {
"line1": "789 Updated Address",
"city": "Los Angeles",
"state": "CA",
"postal_code": "90210",
"country": "US"
},
"updated_at": "2025-01-20T21:00:00Z"
}
}
Delete Payment Method
Remove a payment method from the account.
DELETE /companies/{company_id}/billing/payment-methods/{payment_method_id}
Delete Payment Method Parameters
company_id(path, required): Company identifierpayment_method_id(path, required): Payment method identifier
Delete Payment Method Response
204 No Content
Invoices and Billing History
List Invoices
Retrieve billing invoices and payment history.
GET /companies/{company_id}/billing/invoices
List Invoices Parameters
company_id(path, required): Company identifier
List Invoices Query Parameters
status(optional): Filter by invoice status (draft, paid, overdue)start_date(optional): Filter from dateend_date(optional): Filter to datelimit(optional): Results per pageoffset(optional): Pagination offset
List Invoices Response
{
"data": [
{
"invoice_id": "inv_123",
"invoice_number": "INV-2025-001234",
"status": "paid",
"amount_due": 3245.80,
"amount_paid": 3245.80,
"currency": "USD",
"billing_period": {
"start_date": "2024-12-01T00:00:00Z",
"end_date": "2024-12-31T23:59:59Z"
},
"issued_date": "2025-01-01T00:00:00Z",
"due_date": "2025-01-15T23:59:59Z",
"paid_date": "2025-01-12T14:30:00Z",
"line_items": [
{
"description": "Analytics API Usage - December 2024",
"quantity": 15420,
"unit_price": 0.21,
"amount": 3238.20
},
{
"description": "Platform Fee",
"quantity": 1,
"unit_price": 7.60,
"amount": 7.60
}
],
"payment_method": {
"type": "card",
"last_four": "4242"
},
"pdf_url": "https://api.spartera.com/billing/invoices/inv_123.pdf"
}
],
"meta": {
"total": 24,
"outstanding_amount": 0,
"overdue_count": 0
}
}
Get Invoice Details
Retrieve detailed information for a specific invoice.
GET /companies/{company_id}/billing/invoices/{invoice_id}
Get Invoice Details Parameters
company_id(path, required): Company identifierinvoice_id(path, required): Invoice identifier
Get Invoice Details Response
{
"data": {
"invoice_id": "inv_123",
"invoice_number": "INV-2025-001234",
"status": "paid",
"amount_subtotal": 3238.20,
"amount_tax": 259.06,
"amount_total": 3497.26,
"amount_paid": 3497.26,
"currency": "USD",
"billing_period": {
"start_date": "2024-12-01T00:00:00Z",
"end_date": "2024-12-31T23:59:59Z"
},
"company_details": {
"name": "Analytics Corp",
"address": {
"line1": "123 Business Ave",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"tax_id": "12-3456789"
},
"line_items": [
{
"item_id": "item_1",
"description": "Customer Churn Predictor API",
"analytics_id": "analytics_123",
"quantity": 8500,
"unit_price": 0.25,
"amount": 2125.00,
"usage_period": {
"start_date": "2024-12-01T00:00:00Z",
"end_date": "2024-12-31T23:59:59Z"
}
}
],
"tax_details": [
{
"tax_type": "sales_tax",
"rate": 0.08,
"amount": 259.06,
"jurisdiction": "CA"
}
],
"payment_details": {
"payment_method": {
"type": "card",
"brand": "visa",
"last_four": "4242"
},
"transaction_id": "txn_789",
"paid_date": "2025-01-12T14:30:00Z"
},
"pdf_url": "https://api.spartera.com/billing/invoices/inv_123.pdf",
"issued_date": "2025-01-01T00:00:00Z",
"due_date": "2025-01-15T23:59:59Z"
}
}
Download Invoice PDF
Download a PDF version of an invoice.
GET /companies/{company_id}/billing/invoices/{invoice_id}/pdf
Download Invoice PDF Parameters
company_id(path, required): Company identifierinvoice_id(path, required): Invoice identifier
Download Invoice PDF Response
Binary PDF data with appropriate headers:
Content-Type: application/pdf
Content-Disposition: attachment; filename="INV-2025-001234.pdf"
Credits and Prepaid Balance
Get Credit Balance
Retrieve current credit balance and transaction history.
GET /companies/{company_id}/billing/credits
Get Credit Balance Parameters
company_id(path, required): Company identifier
Get Credit Balance Response
{
"data": {
"balance": {
"available_credits": 2450.75,
"pending_credits": 125.00,
"reserved_credits": 75.25,
"total_credits": 2651.00,
"currency": "USD"
},
"usage_forecast": {
"estimated_monthly_usage": 3200.00,
"days_remaining_at_current_rate": 23,
"recommended_top_up": 1000.00
},
"auto_top_up": {
"enabled": true,
"threshold": 500.00,
"amount": 1000.00,
"payment_method_id": "pm_123"
}
}
}
Add Credits
Purchase additional credits for the account.
POST /companies/{company_id}/billing/credits/purchase
Add Credits Parameters
company_id(path, required): Company identifier
Add Credits Request Body
{
"amount": 1000.00,
"currency": "USD",
"payment_method_id": "pm_123",
"bonus_eligible": true
}
Add Credits Response
{
"data": {
"transaction_id": "credit_txn_456",
"amount_purchased": 1000.00,
"bonus_credits": 50.00,
"total_credits_added": 1050.00,
"new_balance": 3500.75,
"currency": "USD",
"processed_at": "2025-01-20T21:30:00Z",
"payment_method": {
"type": "card",
"last_four": "4242"
}
}
}
Configure Auto Top-Up
Set up automatic credit top-up when balance falls below threshold.
POST /companies/{company_id}/billing/credits/auto-topup
Configure Auto Top-Up Parameters
company_id(path, required): Company identifier
Configure Auto Top-Up Request Body
{
"enabled": true,
"threshold": 250.00,
"top_up_amount": 1000.00,
"payment_method_id": "pm_123",
"max_top_ups_per_month": 3
}
Configure Auto Top-Up Response
{
"data": {
"auto_top_up": {
"enabled": true,
"threshold": 250.00,
"top_up_amount": 1000.00,
"payment_method_id": "pm_123",
"max_top_ups_per_month": 3,
"next_eligible_top_up": "immediate",
"top_ups_this_month": 0
},
"updated_at": "2025-01-20T21:45:00Z"
}
}
Revenue and Payouts (For Sellers)
Get Revenue Summary
Retrieve earnings summary for analytics providers.
GET /companies/{company_id}/billing/revenue
Get Revenue Summary Parameters
company_id(path, required): Company identifier
Get Revenue Summary Query Parameters
period(optional): Time period (current, last_30d, last_90d, ytd)analytics_id(optional): Filter by specific analytics
Get Revenue Summary Response
{
"data": {
"period": "last_30d",
"revenue_summary": {
"gross_revenue": 9847.60,
"platform_fees": 2950.28,
"net_revenue": 6897.32,
"currency": "USD"
},
"revenue_by_analytics": [
{
"analytics_id": "analytics_789",
"name": "Sales Forecasting Model",
"gross_revenue": 6200.00,
"platform_fees": 1860.00,
"net_revenue": 4340.00,
"requests": 2480,
"unique_customers": 67
},
{
"analytics_id": "analytics_101",
"name": "Customer Segmentation AI",
"gross_revenue": 3647.60,
"platform_fees": 1094.28,
"net_revenue": 2553.32,
"requests": 1823,
"unique_customers": 45
}
],
"revenue_trends": [
{
"date": "2025-01-20",
"gross_revenue": 456.80,
"net_revenue": 319.76,
"requests": 183
}
]
}
}
Get Payout History
Retrieve history of payments made to the seller.
GET /companies/{company_id}/billing/payouts
Get Payout History Parameters
company_id(path, required): Company identifier
Get Payout History Query Parameters
status(optional): Filter by payout status (pending, paid, failed)start_date(optional): Filter from dateend_date(optional): Filter to date
Get Payout History Response
{
"data": [
{
"payout_id": "payout_123",
"amount": 6245.78,
"currency": "USD",
"status": "paid",
"payout_period": {
"start_date": "2024-12-01T00:00:00Z",
"end_date": "2024-12-31T23:59:59Z"
},
"payout_method": {
"type": "bank_transfer",
"bank_name": "Chase Bank",
"last_four": "1234"
},
"processed_date": "2025-01-15T10:00:00Z",
"fees_deducted": 18.74,
"analytics_breakdown": [
{
"analytics_id": "analytics_789",
"net_revenue": 4340.00,
"requests": 2480
}
]
}
],
"meta": {
"total_payouts": 12,
"total_amount": 75689.45,
"pending_amount": 2845.20
}
}
Request Manual Payout
Request an immediate payout of available balance.
POST /companies/{company_id}/billing/payouts/request
Request Manual Payout Parameters
company_id(path, required): Company identifier
Request Manual Payout Request Body
{
"amount": 2500.00,
"payout_method_id": "pm_bank_456",
"reason": "Early payout requested for cash flow"
}
Request Manual Payout Response
{
"data": {
"payout_request_id": "payout_req_789",
"amount": 2500.00,
"currency": "USD",
"status": "pending_approval",
"estimated_processing_time": "1-3 business days",
"fees": {
"express_fee": 25.00,
"total_fees": 25.00
},
"net_amount": 2475.00,
"requested_at": "2025-01-20T22:00:00Z"
}
}
Billing Settings
Get Billing Settings
Retrieve billing configuration and preferences.
GET /companies/{company_id}/billing/settings
Get Billing Settings Parameters
company_id(path, required): Company identifier
Get Billing Settings Response
{
"data": {
"billing_preferences": {
"currency": "USD",
"invoice_delivery": "email",
"billing_cycle": "monthly",
"payment_terms": "net_15"
},
"notifications": {
"invoice_generated": true,
"payment_succeeded": true,
"payment_failed": true,
"low_credit_balance": true,
"credit_threshold": 100.00
},
"tax_settings": {
"tax_exempt": false,
"tax_id": "12-3456789",
"tax_location": {
"country": "US",
"state": "CA"
}
},
"auto_payment": {
"enabled": true,
"retry_attempts": 3,
"retry_interval_days": 3
}
}
}
Update Billing Settings
Modify billing preferences and configuration.
PATCH /companies/{company_id}/billing/settings
Update Billing Settings Parameters
company_id(path, required): Company identifier
Update Billing Settings Request Body
{
"billing_preferences": {
"invoice_delivery": "email_and_postal",
"payment_terms": "net_30"
},
"notifications": {
"low_credit_balance": true,
"credit_threshold": 250.00
},
"tax_settings": {
"tax_exempt": true,
"tax_exempt_certificate": "cert_789"
}
}
Update Billing Settings Response
{
"data": {
"updated_settings": [
"invoice_delivery",
"payment_terms",
"credit_threshold",
"tax_exempt_status"
],
"updated_at": "2025-01-20T22:15:00Z"
}
}
The billing endpoints provide comprehensive financial management
capabilities for both buyers and sellers in the Spartera marketplace,
ensuring transparent and efficient payment processing.