Billing and Plans

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. Preset packages provide a straightforward way to add credits in common denominations, while custom purchases allow any amount between one and one hundred dollars.

• $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 in OrcaPulse has a transparent per-use rate. Credits are deducted based on actual usage after each operation completes. The table below shows current rates.

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, which redirects the user to a hosted payment page. After successful payment, a webhook event confirms the transaction and credits are added to the account.

The system also supports a setup mode for saving a payment method without charging. This is used when users want to save a card for future quick purchases or auto-recharge without making an immediate purchase.

• 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 (cards) to their account for faster future purchases. Saved cards store the last four digits, card brand, and expiration date. The system automatically creates a Stripe customer record if one does not already exist when a card is saved.

• Card metadata: last four digits, brand (Visa, Mastercard, etc.), and expiration month/year are stored for display.
• Customer creation: Stripe customer records are created automatically via getOrCreateCustomer() if missing.
• Remove card: saved payment methods can be deleted through the payment methods endpoint.

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 using chargePaymentMethod() and adds credits immediately. Both preset packages and custom amounts are supported.

• Instant charge: the saved card is charged directly without a checkout redirect.
• Package or custom: supports both preset package selections and custom dollar amounts.
• Immediate credit: credits are added to the account as soon as the charge succeeds.

Auto-recharge

Auto-recharge automatically purchases credits when an account's balance drops below a configured threshold. This prevents workflow interruptions caused by insufficient credits. 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 and the usage summary endpoint provides category-level breakdowns.

• 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.
• Metadata: each transaction includes provider, feature, Stripe session ID, and payment intent for traceability.

Phone number billing

Phone numbers have a monthly recurring cost that is 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. The per-number cost and last-billed timestamp are tracked on the user record.

• Daily cron: runs at 02:15 UTC to check and process phone number billing across all accounts.
• Monthly cycle: each phone number is billed once per month based on its last billing date.
• Credit deduction: the monthly rental cost is deducted from the user's credit balance automatically.

Billing API reference

The billing system exposes the following endpoints. All endpoints except packages and the webhook require authentication.

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. The credit model with configurable rates and 20% markup provides a clear revenue layer.

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. Today, billing is per-user and credit-based with pay-as-you-go pricing.

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.