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 identifier
payment_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 identifier
payment_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 date
end_date (optional): Filter to date
limit (optional): Results per page
offset (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 identifier
invoice_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 identifier
invoice_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 date
end_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.