Billing & Subscriptions API

Comprehensive billing management including LLM token usage, API call tracking, subscription management, and Stripe integration for payments. Monitor usage, receive alerts, and manage your organization's subscription.

30 FeaturesLLM Token BillingAPI Usage BillingStripe Integration

Overview

Billing Types

  • • LLM Tokens: AI/Nelo usage tracking
  • • API Calls: Request-based billing
  • • Storage: File storage usage
  • • PDF Processing: Document extraction

Features

  • • Real-time usage monitoring
  • • Quota alerts (75%, 90%, 100%)
  • • Monthly billing reports
  • • Stripe subscription management
  • • Usage projections and forecasting

Subscription Tiers

Free
Getting started
  • • 2 machines
  • • 100 MB storage
  • • 50K LLM tokens/mo
  • • Basic support
Professional
Most Popular
  • • 25 machines
  • • 10 GB storage
  • • 2.5M LLM tokens/mo
  • • Priority support
Small Teams
Growing teams
  • • Unlimited machines
  • • 50 GB storage
  • • 10M LLM tokens/mo
  • • Dedicated support
Enterprise
Custom solutions
  • • Unlimited everything
  • • Custom storage
  • • Custom tokens
  • • SSO, SLA, dedicated

LLM Token Billing

Track AI/LLM token consumption across Nelo conversations, semantic tag analysis, PDF processing, and other AI features. All services share a unified token pool based on your subscription tier.

GET/v1/billing/llm/overviewAuth Required
Billing Overview
Get current billing period summary including token usage across all services.

Response

Responsejson
{
  "organization_id": "org_001",
  "billing_period": {
    "start": "2024-08-01T00:00:00Z",
    "end": "2024-08-31T23:59:59Z"
  },
  "subscription_tier": "professional",
  "token_quota": {
    "total": 2500000,
    "used": 1875000,
    "remaining": 625000,
    "percent_used": 75.0
  },
  "usage_by_service": {
    "nelo_chat": 1200000,
    "semantic_analysis": 450000,
    "pdf_processing": 225000
  },
  "alerts": [
    {
      "type": "quota_warning",
      "threshold": 75,
      "message": "You've used 75% of your monthly token quota"
    }
  ],
  "updated_at": "2024-08-26T14:30:00Z"
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/billing/llm/overview" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/billing/llm/projection/{service_type}Auth Required
Usage Projection
Forecast token usage to end of billing period based on current consumption patterns.

Parameters

service_typestringRequired

Service type (nelo, semantic, pdf_analysis, all)

Response

Responsejson
{
  "service_type": "all",
  "current_usage": 1875000,
  "projected_usage": 2340000,
  "days_remaining": 5,
  "average_daily_usage": 93000,
  "projection_confidence": 0.85,
  "will_exceed_quota": false,
  "estimated_overage": 0,
  "recommendation": "Current usage is on track. No action needed."
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/billing/llm/projection/{service_type}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/billing/llm/report/{year}/{month}Auth Required
Monthly Report
Detailed billing report for a specific month.

Parameters

yearintegerRequired

Year (e.g., 2024)

monthintegerRequired

Month (1-12)

Response

Responsejson
{
  "year": 2024,
  "month": 8,
  "status": "in_progress",
  "total_tokens": 1875000,
  "total_cost": 18.75,
  "usage_breakdown": [
    {"service": "nelo_chat", "tokens": 1200000, "cost": 12.00},
    {"service": "semantic_analysis", "tokens": 450000, "cost": 4.50},
    {"service": "pdf_processing", "tokens": 225000, "cost": 2.25}
  ],
  "daily_usage": [
    {"date": "2024-08-01", "tokens": 72000},
    {"date": "2024-08-02", "tokens": 85000}
  ],
  "peak_usage_day": "2024-08-15",
  "peak_usage_tokens": 145000
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/billing/llm/report/{year}/{month}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
POST/v1/billing/llm/finalize/{year}/{month}Auth Required
Finalize Month
Close the billing period and generate final invoice. Admin only.

Parameters

yearintegerRequired

Year

monthintegerRequired

Month

Response

Responsejson
{
  "year": 2024,
  "month": 7,
  "status": "finalized",
  "total_tokens": 2340000,
  "total_cost": 23.40,
  "finalized_at": "2024-08-01T00:00:01Z",
  "invoice_id": "inv_abc123"
}

Try it out

cURLbash
curl -X POST "https://sapienstream.com/api/v1/billing/llm/finalize/{year}/{month}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/billing/llm/alertsAuth Required
Billing Alerts
Get current billing alerts for quota warnings and overages.

Response

Responsejson
{
  "alerts": [
    {
      "id": "alert_001",
      "type": "quota_warning",
      "severity": "warning",
      "threshold_percent": 75,
      "current_percent": 78.5,
      "message": "You've used 78.5% of your monthly token quota",
      "action_url": "/account/billing",
      "created_at": "2024-08-20T10:00:00Z"
    }
  ],
  "has_critical_alerts": false
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/billing/llm/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/billing/llm/usage-summaryAuth Required
Usage Summary
Service-level breakdown of token usage for dashboard display.

Response

Responsejson
{
  "period": "current_month",
  "services": [
    {
      "name": "Nelo Chat",
      "service_type": "nelo",
      "tokens_used": 1200000,
      "percent_of_total": 64.0,
      "trend": "+12% vs last month"
    },
    {
      "name": "Semantic Analysis",
      "service_type": "semantic",
      "tokens_used": 450000,
      "percent_of_total": 24.0,
      "trend": "-5% vs last month"
    },
    {
      "name": "PDF Processing",
      "service_type": "pdf_analysis",
      "tokens_used": 225000,
      "percent_of_total": 12.0,
      "trend": "+8% vs last month"
    }
  ]
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/billing/llm/usage-summary" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

API Usage Billing

Track API request usage for billing purposes. Includes endpoint breakdown, response time analytics, and overage tracking.

GET/v1/billing/api/overviewAuth Required
API Billing Overview
Current API usage summary for the billing period.

Response

Responsejson
{
  "organization_id": "org_001",
  "billing_period": {
    "start": "2024-08-01T00:00:00Z",
    "end": "2024-08-31T23:59:59Z"
  },
  "request_quota": {
    "total": 100000,
    "used": 67890,
    "remaining": 32110,
    "percent_used": 67.9
  },
  "endpoints_breakdown": [
    {"endpoint": "/machines", "requests": 23456},
    {"endpoint": "/tags", "requests": 18765},
    {"endpoint": "/components", "requests": 12345}
  ],
  "avg_response_time_ms": 145
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/billing/api/overview" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/billing/api/projectionAuth Required
API Usage Projection
Forecast API usage to end of billing period.

Response

Responsejson
{
  "current_requests": 67890,
  "projected_requests": 89500,
  "days_remaining": 5,
  "average_daily_requests": 4320,
  "will_exceed_quota": false,
  "recommendation": "Usage is within normal range."
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/billing/api/projection" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/billing/api/report/{year}/{month}Auth Required
API Monthly Report
Detailed API usage report for a specific month.

Parameters

yearintegerRequired

Year

monthintegerRequired

Month

Response

Responsejson
{
  "year": 2024,
  "month": 8,
  "total_requests": 67890,
  "successful_requests": 66543,
  "failed_requests": 1347,
  "success_rate": 98.0,
  "avg_response_time_ms": 145,
  "peak_hour": "14:00",
  "peak_requests_per_hour": 4567
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/billing/api/report/{year}/{month}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Stripe Integration

Manage subscriptions, payments, and billing information through our Stripe integration.

POST/v1/payments/checkout-sessionAuth Required
Create Checkout Session
Start a new subscription or upgrade flow by creating a Stripe Checkout session.

Request Body

Requestjson
{
  "price_id": "price_professional_monthly",
  "success_url": "https://app.sapienstream.com/account/billing?success=true",
  "cancel_url": "https://app.sapienstream.com/pricing"
}

Response

Responsejson
{
  "checkout_url": "https://checkout.stripe.com/pay/cs_live_abc123...",
  "session_id": "cs_live_abc123def456"
}

Try it out

cURLbash
curl -X POST "https://sapienstream.com/api/v1/payments/checkout-session" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
POST/v1/payments/customer-portalAuth Required
Customer Portal
Generate a link to the Stripe Customer Portal for managing payment methods, invoices, and subscription.

Request Body

Requestjson
{
  "return_url": "https://app.sapienstream.com/account/billing"
}

Response

Responsejson
{
  "portal_url": "https://billing.stripe.com/session/abc123..."
}

Try it out

cURLbash
curl -X POST "https://sapienstream.com/api/v1/payments/customer-portal" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/payments/subscriptionAuth Required
Get Subscription Status
Retrieve current subscription details including plan, status, and billing dates.

Response

Responsejson
{
  "subscription_id": "sub_abc123",
  "plan": "professional",
  "status": "active",
  "current_period_start": "2024-08-01T00:00:00Z",
  "current_period_end": "2024-08-31T23:59:59Z",
  "cancel_at_period_end": false,
  "payment_method": {
    "type": "card",
    "brand": "visa",
    "last4": "4242"
  },
  "next_invoice": {
    "amount": 99.00,
    "currency": "usd",
    "due_date": "2024-09-01T00:00:00Z"
  }
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/payments/subscription" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
PUT/v1/payments/subscription/upgradeAuth Required
Upgrade Subscription
Upgrade to a higher tier subscription. Prorated billing applies.

Request Body

Requestjson
{
  "new_plan": "small_teams"
}

Response

Responsejson
{
  "subscription_id": "sub_abc123",
  "previous_plan": "professional",
  "new_plan": "small_teams",
  "effective_date": "2024-08-26T00:00:00Z",
  "prorated_amount": 45.00,
  "next_billing_amount": 199.00
}

Try it out

cURLbash
curl -X PUT "https://sapienstream.com/api/v1/payments/subscription/upgrade" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
POST/v1/payments/subscription/cancelAuth Required
Cancel Subscription
Cancel subscription at end of current billing period.

Request Body

Requestjson
{
  "reason": "Not using enough features",
  "feedback": "Would love more PLC integration options"
}

Response

Responsejson
{
  "subscription_id": "sub_abc123",
  "status": "active",
  "cancel_at_period_end": true,
  "cancellation_date": "2024-08-31T23:59:59Z",
  "features_available_until": "2024-08-31T23:59:59Z"
}

Try it out

cURLbash
curl -X POST "https://sapienstream.com/api/v1/payments/subscription/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/payments/historyAuth Required
Payment History
Retrieve payment and invoice history.

Parameters

limitinteger

Max results (default: 10)

Response

Responsejson
{
  "payments": [
    {
      "id": "pi_abc123",
      "amount": 99.00,
      "currency": "usd",
      "status": "succeeded",
      "description": "Professional Plan - August 2024",
      "invoice_url": "https://invoice.stripe.com/i/abc123",
      "created_at": "2024-08-01T00:00:00Z"
    },
    {
      "id": "pi_def456",
      "amount": 99.00,
      "currency": "usd",
      "status": "succeeded",
      "description": "Professional Plan - July 2024",
      "invoice_url": "https://invoice.stripe.com/i/def456",
      "created_at": "2024-07-01T00:00:00Z"
    }
  ]
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/payments/history" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Subscription Policies

GET/v1/subscription-policies/plans
List Plans
Get all available subscription plans with features and limits.

Response

Responsejson
{
  "plans": [
    {
      "id": "free",
      "name": "Free",
      "price_monthly": 0,
      "features": {
        "max_machines": 2,
        "max_storage_mb": 100,
        "max_llm_tokens": 50000,
        "semantic_analysis": false,
        "api_access": false
      }
    },
    {
      "id": "professional",
      "name": "Professional",
      "price_monthly": 99,
      "features": {
        "max_machines": 25,
        "max_storage_mb": 10240,
        "max_llm_tokens": 2500000,
        "semantic_analysis": true,
        "api_access": true
      }
    }
  ]
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/subscription-policies/plans" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/subscription-policies/plans/{plan_id}
Get Plan Info
Get detailed information about a specific plan.

Parameters

plan_idstringRequired

Plan identifier

Response

Responsejson
{
  "id": "professional",
  "name": "Professional",
  "description": "For growing teams and production environments",
  "price_monthly": 99,
  "price_yearly": 990,
  "features": {
    "max_machines": 25,
    "max_users": 10,
    "max_storage_mb": 10240,
    "max_llm_tokens": 2500000,
    "semantic_analysis": true,
    "api_access": true,
    "priority_support": true,
    "custom_integrations": false
  },
  "rate_limits": {
    "api_requests_per_minute": 100,
    "api_requests_per_hour": 1000
  }
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/subscription-policies/plans/{plan_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
POST/v1/subscription-policies/check-limitAuth Required
Check Limit
Check if a specific action is allowed under the current subscription.

Request Body

Requestjson
{
  "resource": "machines",
  "action": "create"
}

Response

Responsejson
{
  "allowed": true,
  "current_usage": 18,
  "limit": 25,
  "remaining": 7,
  "message": "You can create 7 more machines on your current plan."
}

Try it out

cURLbash
curl -X POST "https://sapienstream.com/api/v1/subscription-policies/check-limit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/subscription-policies/featuresAuth Required
Get Plan Features
Get feature availability for the current subscription.

Response

Responsejson
{
  "plan": "professional",
  "features": {
    "nelo_chat": true,
    "semantic_analysis": true,
    "pdf_extraction": true,
    "api_access": true,
    "bulk_operations": true,
    "priority_support": true,
    "custom_branding": false,
    "sso": false,
    "dedicated_support": false
  }
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/subscription-policies/features" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/subscription-policies/limitsAuth Required
Get Plan Limits
Get numeric limits for the current subscription.

Response

Responsejson
{
  "plan": "professional",
  "limits": {
    "max_machines": 25,
    "max_users": 10,
    "max_components": 500,
    "max_storage_mb": 10240,
    "max_llm_tokens_per_month": 2500000,
    "api_requests_per_minute": 100,
    "api_requests_per_hour": 1000,
    "max_api_keys": 10
  }
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/subscription-policies/limits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/v1/subscription-policies/usage-scenarios
Usage Scenarios Demo
Demo calculations showing how usage would map to costs for prospects.

Parameters

machinesinteger

Number of machines

usersinteger

Number of users

storage_gbnumber

Storage needed in GB

Response

Responsejson
{
  "scenario": {
    "machines": 15,
    "users": 5,
    "storage_gb": 5
  },
  "recommended_plan": "professional",
  "monthly_cost": 99,
  "yearly_cost": 990,
  "savings_yearly": 198,
  "fits_within_limits": true,
  "headroom": {
    "machines": 10,
    "users": 5,
    "storage_gb": 5
  }
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/v1/subscription-policies/usage-scenarios" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Quota Management

Unified Token Pool
All AI services share a single token allocation

Your subscription includes a monthly token allocation (e.g., 2.5M for Professional) that is shared across all AI-powered features: Nelo conversations, semantic tag analysis, and PDF processing. This provides flexibility in how you use your AI budget.

Alert Thresholds

  • • 75%: Warning notification sent
  • • 90%: Urgent warning, upgrade prompt
  • • 100%: Services limited, immediate action required
// Example: Quota Status Response
{
  "subscription_tier": "professional",
  "quota": {
    "total_llm_tokens": 2500000,
    "used_llm_tokens": 1875000,
    "remaining_llm_tokens": 625000,
    "percent_used": 75.0
  },
  "rate_limits": {
    "api_requests_per_minute": {
      "limit": 100,
      "current": 45,
      "reset_in_seconds": 32
    }
  },
  "resource_usage": {
    "machines": { "used": 18, "limit": 25 },
    "storage_mb": { "used": 5120, "limit": 10240 },
    "users": { "used": 5, "limit": 10 }
  },
  "can_upgrade": true,
  "upgrade_url": "/account/billing/upgrade"
}