​
Billing & Payments

AIUS uses Stripe for all payment processing, subscription management, and billing operations.

​
Overview

The billing system provides:
  • Subscription Management - Recurring billing for plans (Free, Basic, Pro, Enterprise)
  • Credit System - Monthly credit quotas with prepaid top-ups for overage
  • Payment Methods - Customer payment method management
  • Invoices - Invoice tracking and history
  • Billing Portal - Self-service customer portal

​
Pricing Model

AIUS uses a subscription + credits model:
  • Each plan includes a monthly credit quota that refreshes automatically
  • Credits are deducted based on actual API usage costs (1 credit = 0.01USD,100credits=0.01 USD, 100 credits = 1)
  • Additional credits can be purchased anytime for overage
  • When quota is exceeded, users must purchase credits to continue using the service unless the quota resets (daily/weekly/monthly)
  • Plans:
    • Free: $10 one-time credit (1,000 credits), no monthly fee, quota never resets
    • Basic: $50/month (5,000 credits/month), monthly quota resets
    • Pro: $200/month (20,000 credits/month), monthly quota resets
    • Enterprise: Custom pricing (50,000+ credits/month), monthly quota resets

​
Subscriptions

​
Create Subscription Checkout

Create a Stripe checkout session for a new subscription. 
POST /v1/clients/{client_id}/subscription/checkout
Request Body: 
{
  "price_id": "price_pro_monthly",
  "success_url": "https://aius.co/account/clients/{client_id}/billing?success=true",
  "cancel_url": "https://aius.co/account/clients/{client_id}/billing?canceled=true",
  "customer_email": "user@example.com"
}
Response: 
{
  "session_id": "cs_1234567890",
  "checkout_url": "https://checkout.stripe.com/..."
}

​
Get Subscription

Retrieve subscription details for a client. 
GET /v1/clients/{client_id}/subscription
Response: 
{
  "org_id": "client_123",
  "plan_name": "pro",
  "status": "active",
  "monthly_quota_credits": 20000,
  "current_period_start": 1714560000,
  "current_period_end": 1717238400,
  "cancel_at_period_end": false,
  "stripe_subscription_id": "sub_1234567890"
}

​
Credits

​
Create Credit Top-up

Create a checkout session for purchasing credits. 
POST /v1/clients/{client_id}/credits/topup
Request Body: 
{
  "amount_usd": 1000,
  "success_url": "https://aius.co/account/clients/{client_id}/billing?success=true",
  "cancel_url": "https://aius.co/account/clients/{client_id}/billing?canceled=true",
  "customer_email": "user@example.com"
}
Response: 
{
  "session_id": "cs_1234567890",
  "checkout_url": "https://checkout.stripe.com/..."
}

​
Get Credit Balance

Retrieve current credit balance. 
GET /v1/clients/{client_id}/credits/balance
Response: 
{
  "org_id": "client_123",
  "balance_credits": 10000,
  "balance_usd": 10000,
  "monthly_quota_remaining": 50
}

​
List Credit Transactions

Retrieve credit transaction history. 
GET /v1/clients/{client_id}/credits/transactions?limit=50&offset=0
Response: 
[
  {
    "id": 1,
    "org_id": "client_123",
    "amount_credits": 1000,
    "amount_usd": 1000,
    "transaction_type": "topup",
    "balance_after_credits": 1000,
    "balance_after_usd": 1000,
    "description": "Credit top-up via Stripe",
    "created_at": 1714560000
  }
]

​
Billing Portal

​
Create Portal Session

Create a Stripe customer portal session for self-service billing management. 
POST /v1/clients/{client_id}/billing/portal
Request Body: 
{
  "return_url": "https://aius.co/account/clients/{client_id}/billing"
}
Response: 
{
  "portal_url": "https://billing.stripe.com/..."
}

​
Payment Methods

​
List Payment Methods

Retrieve saved payment methods for a client. 
GET /v1/clients/{client_id}/payment-methods
Response: 
[
  {
    "id": "pm_1234567890",
    "org_id": "client_123",
    "type": "card",
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2025,
    "is_default": true
  }
]

​
Invoices

​
List Invoices

Retrieve invoice history for a client. 
GET /v1/clients/{client_id}/invoices?limit=50&offset=0
Response: 
[
  {
    "id": "in_1234567890",
    "org_id": "client_123",
    "amount_due_cents": 2900,
    "amount_paid_cents": 2900,
    "status": "paid",
    "currency": "usd",
    "invoice_pdf": "https://pay.stripe.com/...",
    "created_at": 1714560000,
    "due_date": 1714646400
  }
]

​
Credit System

​
How Credits Work

  1. Monthly Quota - Each subscription plan includes a monthly credit quota that refreshes automatically (except Free tier which never resets)
  2. Purchase Credits - Users can purchase additional credits via Stripe checkout for overage
  3. Credit Addition - Webhook adds credits to balance on successful payment
  4. Usage Deduction - Credits are deducted when using AI services based on actual cost
  5. Transaction History - All credit transactions are logged
  6. Quota Refresh - Monthly quota is reset at the start of each billing cycle (Basic, Pro, Enterprise)
  7. Quota Exceeded - When quota is exceeded, users must purchase credits to continue using the service unless the quota resets

​
Credit Conversion

Current conversion: **1 credit = 0.01USD∗∗(1cent,100credits=0.01 USD** (1 cent, 100 credits = 1)

​
Transaction Types

  • topup - Credits purchased via Stripe
  • usage - Credits consumed by API usage
  • refund - Credits refunded (manual or automatic)
  • quota_refresh - Monthly quota reset at billing cycle start

​
Webhooks

Stripe webhooks are used to keep billing data synchronized:
  • checkout.session.completed - Processes successful payments
  • invoice.paid - Syncs paid invoices
  • invoice.payment_failed - Handles payment failures
  • customer.subscription.created - Syncs new subscriptions
  • customer.subscription.updated - Updates subscription changes
  • customer.subscription.deleted - Marks subscriptions as canceled

​
Error Handling

Billing endpoints return standard error responses: 
{
  "success": false,
  "error": {
    "code": "payment_failed",
    "message": "Payment processing failed"
  }
}
Common error codes:
  • payment_failed - Payment processing error
  • invalid_price_id - Invalid Stripe price ID
  • subscription_not_found - No active subscription
  • insufficient_credits - Not enough credits for operation