ShipAI Docs
Features

Billing and Limits

Plan limits, usage metering, Stripe lifecycle routes, and limit-enforcement behavior.

Billing is split into two concerns:

  • Usage metering + limit checks (@ai/billing)
  • Payment/subscription lifecycle (@ai/stripe + app billing routes)

@ai/billing determines plan limits, operation gating, and usage accounting per request.

@ai/stripe and billing routes manage customer/checkout/portal/webhook state transitions.

Core Package Responsibilities

@ai/billing

  • defines plan limits and operation types
  • checks limits per operation via checkUsageLimits(...)
  • creates consistent limit responses via createLimitExceededResponse(...)
  • records usage logs and aggregates token/cost counters

@ai/stripe

  • creates customers and checkout sessions
  • opens customer portal sessions
  • verifies webhook signatures and parses subscription state

Enforcement Model

checkUsageLimits(...) supports operations:

  • chat
  • upload
  • deep_search
  • transcription
  • artifact_creation
  • artifact_update
  • document_comparison

Enforcement behavior:

  • if shouldEnforceBilling() is false, operations are allowed (usage still tracked)
  • shouldEnforceBilling() is false when DEVELOPMENT_MODE=true or FEATURE_BILLING_ENFORCEMENT_ENABLED=false

API Surface

  • GET /api/billing/plans
  • GET /api/billing/usage
  • GET /api/billing/subscription
  • POST /api/billing/subscription
  • DELETE /api/billing/subscription
  • POST /api/billing/checkout
  • POST /api/billing/portal
  • POST /api/billing/webhook
  • GET /api/billing/telegram-upgrade

Stripe Webhook Behavior

Handled events:

  • checkout.session.completed
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
  • invoice.paid
  • invoice.payment_failed

Operational details:

  • signature verification required (stripe-signature)
  • webhook deduplication key stored in KV with TTL
  • event processing is idempotent where subscription/payment records may already exist

Environment Variables

Stripe keys:

STRIPE_SECRET_KEY=
STRIPE_PUBLISHABLE_KEY=
STRIPE_WEBHOOK_SECRET=

Plan linkage:

STRIPE_PRICE_ID_PRIME=
STRIPE_PRODUCT_ID_PRIME=

Billing controls:

FEATURE_BILLING_ENFORCEMENT_ENABLED=true
DEVELOPMENT_MODE=false

AI Chat and Research

Request pipeline for chat, search routing, deep search, document generation, and streaming.

Search

SearXNG-backed search, phased search-agent execution, and deep research integration.

On this page

Core Package Responsibilities@ai/billing@ai/stripeEnforcement ModelAPI SurfaceStripe Webhook BehaviorEnvironment Variables