💳 Billing API

Access invoices, payments, and billing information programmatically with SolveForce's comprehensive billing API.

🎯 Overview

The SolveForce Billing API provides complete programmatic access to:

Invoice Management: Retrieve, create, and update invoices
Payment Processing: Handle payments and refunds
Billing History: Access complete billing records
Usage Analytics: Monitor service consumption and costs
Account Management: Manage billing accounts and preferences
Automated Billing: Set up recurring payments and billing cycles

🔐 Authentication

All billing API endpoints require authentication using API keys with billing permissions:

Authorization: Bearer your_api_key_here
Content-Type: application/json

Security Note: Billing APIs use enhanced security with additional verification for sensitive operations.

📊 Core Endpoints

Invoice Management

Get All Invoices

GET /api/v1/billing/invoices

Parameters:

limit (integer): Number of invoices to return (default: 50, max: 200)
offset (integer): Number of invoices to skip (default: 0)
status (string): Filter by status (pending, paid, overdue, cancelled)
date_from (string): Start date (ISO 8601 format)
date_to (string): End date (ISO 8601 format)

Response:

{
  "invoices": [
    {
      "id": "inv_123456789",
      "number": "INV-2025-001234",
      "status": "paid",
      "amount": 2499.99,
      "currency": "USD",
      "due_date": "2025-02-01T00:00:00Z",
      "paid_date": "2025-01-28T14:30:00Z",
      "services": [
        {
          "service_id": "svc_fiber_enterprise",
          "description": "Enterprise Fiber 1Gbps",
          "amount": 1999.99,
          "quantity": 1
        }
      ]
    }
  ],
  "total_count": 156,
  "has_more": true
}

Get Specific Invoice

GET /api/v1/billing/invoices/{invoice_id}

Create Invoice

POST /api/v1/billing/invoices

Request Body:

{
  "account_id": "acc_123456789",
  "services": [
    {
      "service_id": "svc_cloud_storage",
      "quantity": 5,
      "unit_price": 49.99
    }
  ],
  "due_date": "2025-02-15T00:00:00Z",
  "notes": "Monthly cloud storage services"
}

Payment Processing

Process Payment

POST /api/v1/billing/payments

Request Body:

{
  "invoice_id": "inv_123456789",
  "amount": 2499.99,
  "payment_method": {
    "type": "credit_card",
    "card_token": "tok_secure_card_token",
    "billing_address": {
      "street": "123 Business Ave",
      "city": "Enterprise City",
      "state": "TX",
      "zip": "75001",
      "country": "US"
    }
  }
}

Response:

{
  "payment_id": "pay_987654321",
  "status": "successful",
  "amount": 2499.99,
  "currency": "USD",
  "processed_at": "2025-01-15T10:30:00Z",
  "transaction_id": "txn_abc123def456"
}

Get Payment History

GET /api/v1/billing/payments

Account Management

Get Billing Account

GET /api/v1/billing/accounts/{account_id}

Update Billing Preferences

PUT /api/v1/billing/accounts/{account_id}/preferences

Request Body:

{
  "billing_cycle": "monthly",
  "auto_pay": true,
  "payment_method_id": "pm_default_card",
  "invoice_delivery": "email",
  "currency": "USD"
}

📈 Usage and Analytics

Usage Reports

GET /api/v1/billing/usage

Parameters:

service_type (string): Filter by service type
period (string): current_month, last_month, current_year
detailed (boolean): Include detailed breakdown

Response:

{
  "period": "current_month",
  "total_usage": {
    "voice_minutes": 15420,
    "data_gb": 2048,
    "cloud_storage_gb": 5120,
    "api_calls": 125000
  },
  "services": [
    {
      "service_id": "svc_voice_enterprise",
      "usage": 15420,
      "unit": "minutes",
      "cost": 462.60
    }
  ],
  "estimated_monthly_cost": 4567.89
}

Cost Analysis

GET /api/v1/billing/cost-analysis

Response:

{
  "current_month": {
    "total": 4567.89,
    "breakdown": {
      "connectivity": 1999.99,
      "voice": 462.60,
      "cloud": 1205.30,
      "security": 900.00
    }
  },
  "year_to_date": 45678.90,
  "trends": {
    "monthly_growth": 5.2,
    "cost_optimization_savings": 1234.56
  }
}

🔄 Automated Billing

Set Up Recurring Billing

POST /api/v1/billing/recurring

Request Body:

{
  "account_id": "acc_123456789",
  "services": [
    {
      "service_id": "svc_managed_security",
      "billing_cycle": "monthly",
      "auto_renew": true
    }
  ],
  "payment_method_id": "pm_default_card",
  "start_date": "2025-02-01T00:00:00Z"
}

Manage Subscriptions

GET /api/v1/billing/subscriptions
PUT /api/v1/billing/subscriptions/{subscription_id}
DELETE /api/v1/billing/subscriptions/{subscription_id}

🚨 Webhooks

Subscribe to billing events for real-time notifications:

Available Events

invoice.created
invoice.paid
invoice.overdue
payment.successful
payment.failed
subscription.created
subscription.cancelled

Webhook Configuration

POST /api/v1/billing/webhooks

Request Body:

{
  "url": "https://your-system.com/billing-webhooks",
  "events": ["invoice.paid", "payment.failed"],
  "secret": "your_webhook_secret"
}

💡 Code Examples

Python SDK

from solveforce import SolveForceAPI

# Initialize client
client = SolveForceAPI(api_key="your_api_key")

# Get recent invoices
invoices = client.billing.get_invoices(
    limit=10,
    status="pending"
)

# Process payment
payment = client.billing.process_payment(
    invoice_id="inv_123456789",
    payment_method="pm_default_card"
)

# Get usage analytics
usage = client.billing.get_usage(
    period="current_month",
    detailed=True
)

JavaScript SDK

const SolveForce = require('@solveforce/api');
const client = new SolveForce({ apiKey: 'your_api_key' });

// Get billing summary
const summary = await client.billing.getSummary({
  period: 'current_month'
});

// Set up auto-pay
const autopay = await client.billing.setupAutoPay({
  accountId: 'acc_123456789',
  paymentMethodId: 'pm_default_card'
});

🔍 Error Handling

Common Error Codes

400 - Bad Request (invalid parameters)
401 - Unauthorized (invalid API key)
403 - Forbidden (insufficient permissions)
404 - Not Found (invoice/payment not found)
409 - Conflict (duplicate payment attempt)
429 - Rate Limit Exceeded
500 - Internal Server Error

Error Response Format

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Payment method has insufficient funds",
    "details": {
      "payment_method_id": "pm_123456789",
      "required_amount": 2499.99,
      "available_amount": 1500.00
    }
  }
}

📊 Rate Limits

Standard Plan: 1,000 requests per hour
Business Plan: 5,000 requests per hour
Enterprise Plan: 25,000 requests per hour
Custom Plans: Unlimited requests available

🛡️ Security Best Practices

API Key Security: Store API keys securely, rotate regularly
Webhook Verification: Always verify webhook signatures
HTTPS Only: Use HTTPS for all API communications
Input Validation: Validate all input parameters
Error Handling: Implement proper error handling and logging

📞 Support

Need help with the Billing API?

Documentation: Complete API reference at docs.solveforce.com
Support: billing-api@solveforce.com
Phone: (888) 765-8301 ext. BILLING
Status: status.solveforce.com for API status updates

Ready to integrate SolveForce billing into your systems? Contact us at (888) 765-8301 for API access and implementation support.

Streamline your billing operations with SolveForce's comprehensive Billing API.

SOLVEFORCE.COM Documentation