Prepaid billing

No open-ended invoices. Every request is paid for first.

1chat charges provider API cost plus 10%, but the platform reserves prepaid balance before sending the provider request.

Ledger movements

top_upBalance added through Stripe Checkout, manual admin credit, or future auto recharge.
reservationEstimated customer charge held before provider execution.
chargeFinal customer charge after actual provider usage is known.
releaseUnused reservation returned, or full reservation released after a provider failure.

Request accounting

  1. Estimate request cost from request size and max output settings.
  2. Compute the customer reservation as estimated provider cost plus 10%.
  3. Lock the account row in Postgres and confirm available balance covers the reservation.
  4. Send the provider request only after the reservation commits.
  5. Finalize actual provider cost plus 10% and release unused reservation.
customer_charge_usd = upstream_provider_cost_usd * 1.10

Insufficient balance

If available prepaid balance is too low, 1chat returns `402 insufficient_prepaid_balance` before the provider request. This protects both the customer and 1chat from accidental usage spikes.

HTTP/1.1 402 Payment Required

{
  "error": {
    "type": "insufficient_prepaid_balance",
    "message": "Insufficient prepaid balance.",
    "balance_usd": 1.25,
    "reserved_usd": 0.40,
    "required_usd": 1.10
  }
}

Auto recharge

Auto recharge should trigger when available balance drops below the account threshold. The current product data model stores `auto_recharge_enabled`, `auto_recharge_amount_usd`, and `recharge_threshold_usd`; production automation should run through Cloud Scheduler and Pub/Sub so recharge checks are auditable and retryable.

Production expectation

Store Stripe customer and payment method references, use idempotency keys for recharge attempts, and write every successful top-up into the same ledger used for request accounting.

Customer-facing pricing

1chat should be simple to explain: customers add prepaid balance, use any supported SDK surface, and pay the underlying provider API cost plus a 10% 1chat platform margin. The portal should show model, upstream cost, 1chat charge, and route reason per request.