--- title: Billing and Plans subtitle: Understand how billing works in OrcaPulse slug: documentation/billing-and-plans --- # Billing and Plans This page documents how billing works in OrcaPulse: credit-based pricing, Stripe checkout, saved payment methods, one-click purchases, auto-recharge, per-operation costs, transaction history, and phone number billing. ## How billing works OrcaPulse uses a credit-based billing model where every platform operation consumes credits at a published rate. The base exchange rate is one USD to one credit. Credits are purchased through Stripe and deducted automatically when operations complete successfully. The credit system is enforced by the checkCredits middleware, which verifies sufficient balance before allowing credit-consuming operations. Credits are deducted after successful completion rather than before, so users are never charged for failed operations. ## Credit packages OrcaPulse offers four preset credit packages plus custom purchase amounts. - $50 package: 50 credits for standard usage. - $200 package: 200 credits for moderate operations. - $500 package: 500 credits for higher-volume teams. - $1,000 package: 1,000 credits for heavy usage. - Custom amount: any amount from $1 to $100 for flexible top-ups. ## What credits cost Each operation has a transparent per-use rate. Credits are deducted based on actual usage after each operation completes. - AI Call: $0.0168 per minute - Call recording: $0.003 per minute - WhatsApp message: $0.006 per message - SMS (Twilio): $0.009 per segment - SMS (Telnyx): $0.006 per segment - Email: $0.00036 per recipient - Deepgram transcription: $0.00708 per minute - ElevenLabs TTS: $0.036 per 1k characters - OpenAI tokens: usage-based per model ## Stripe checkout and payments Credit purchases are processed through Stripe Checkout. When a user initiates a purchase, the system creates a Stripe checkout session in payment mode. After successful payment, a webhook event confirms the transaction and credits are added. - Payment mode: creates a checkout session that charges the card and adds credits on completion. - Setup mode: saves a card to the account without any charge. - Webhook confirmation: checkout.session.completed events trigger credit addition and transaction logging. - Failure handling: checkout.session.async_payment_failed events are captured for reconciliation. ## Saved payment methods Users can save payment methods to their account for faster future purchases. Saved cards store the last four digits, card brand, and expiration date. Stripe customer records are created automatically if missing. ## Quick purchase Accounts with a saved payment method can make one-click purchases without going through the full Stripe checkout flow. The quick purchase endpoint charges the saved card directly and adds credits immediately. Both preset packages and custom amounts are supported. ## Auto-recharge Auto-recharge automatically purchases credits when an account's balance drops below a configured threshold. The feature requires a saved payment method and is configured per user with a minimum threshold of five credits and a minimum recharge amount of twenty dollars. - Threshold: configurable per user, minimum five credits. - Recharge amount: configurable per user, minimum twenty dollars. - Email alerts: notifications sent on successful recharge and on recharge failure. - Transaction logging: auto-recharge transactions are tagged with autoRecharge: true in metadata. ## Transaction history Every credit movement is recorded as a transaction with a type, amount, balance before and after, description, and metadata. Transaction types include purchase, deduction, refund, and bonus. The history endpoint supports pagination. - Purchase: credits added from Stripe payments, quick purchases, or auto-recharge. - Deduction: credits consumed by operations like calls, SMS, emails, and AI generation. - Refund: credits returned for failed or reversed operations. - Bonus: credits added by admins for promotions or manual adjustments. ## Phone number billing Phone numbers have a monthly recurring cost billed automatically through a cron job running daily at 02:15 UTC. The cron checks each user's phone number billing date and deducts the monthly rental cost from their credit balance when due. ## Billing API reference - GET /api/credits/packages: available credit packages. - GET /api/credits/balance: current credit balance (triggers auto-recharge if low). - GET /api/credits/history: paginated transaction history. - GET /api/credits/usage-summary: category breakdown of credit usage. - POST /api/credits/create-checkout: initiate Stripe checkout for package or custom amount. - POST /api/credits/create-setup-checkout: save a card without charging. - POST /api/credits/quick-purchase: one-click purchase with saved card. - GET /api/credits/payment-methods: list saved payment methods. - DELETE /api/credits/payment-methods: remove a saved payment method. - GET /api/credits/auto-recharge: get auto-recharge settings. - PUT /api/credits/auto-recharge: update auto-recharge settings. - POST /api/credits/webhook: Stripe webhook handler (signature verified). ## Current project shape The billing system is production-ready with full Stripe integration, multiple purchase flows, auto-recharge, per-operation metering across all providers, and comprehensive transaction logging. What the project does not yet include is subscription-based plans with tiered features, volume discounts on credit packages, invoicing or billing history exports, or team-level billing with shared credit pools. ## Next steps After Billing and Plans, the next useful page is FAQ / Troubleshooting, which covers common issues, error patterns, and resolution steps across authentication, credits, workflows, and integrations.