Billing

How plans, subscriptions, mid-cycle changes, overdue accounts, and invoices actually work today, plus a clear list of what is not built yet, so nobody relies on a capability that doesn't exist.

1. Plan tiers

Three plan tiers exist today:

PlanPriceBilling interval
Small Teams$199 / monthMonthly, or annual at a 20% discount
Mid-Size Teams$399 / monthMonthly, or annual at a 20% discount
Large Teams$699 / monthMonthly, or annual at a 20% discount
These prices are defined in the portal application and used to create a Stripe Checkout session at signup or plan change. If a specific Stripe Price ID is configured for a tier and reachable, that price is used; otherwise the session is built directly from these amounts. There is currently no separate plan catalog stored in the database, the portal is the source of truth for what a tier costs.

2. Billing cycle and subscription status

Subscriptions are managed by Stripe. The platform does not store its own "next billing date", it reads the current period end directly from Stripe when the billing page is opened, so what you see is always Stripe's own record, not a locally cached copy that could drift out of sync.

An account's status follows Stripe's subscription state:

Stripe subscription stateAccount status
activeACTIVE
trialingTRIAL
past_due or unpaidPAST_DUE
incompleteUNPAID
canceled, paused, or incomplete_expiredCANCELLED

3. Changing plans mid-cycle

Switching tiers part-way through a billing period prorates the difference, charged or credited on the next invoice. This happens in two places that work together:

  • The actual charge: handled entirely by Stripe, which calculates and applies the proration automatically when the subscription is updated.
  • An internal record of the adjustment: the platform separately calculates a proportional figure and writes it to the financial ledger, so the change is visible in your own transaction history, not only on the Stripe invoice.
adjustment = round( (newPlanPrice - oldPlanPrice) * remainingTimeInCycle / totalCycleLength )
The internal ledger-adjustment endpoint (POST /billing/proration) currently accepts the old and new prices as parameters in the request, rather than looking them up itself from a plan catalog. It is intended for the platform's own plan-switch flow to call, not as a general-purpose endpoint for third-party integrations to invoke with arbitrary figures.

4. Overdue accounts (dunning)

When an account's settlement checks show unresolved payment failures, the account is escalated on a fixed schedule, counted from the first unresolved failure:

DayStageWhat happens
Day 3ReminderInternally logged for the account.
Day 7Final noticeInternally logged for the account.
Day 14SuspensionThe account is suspended. This is enforced immediately: its API keys and any connected app tokens stop working the moment suspension takes effect, and background bot processing for that account stops.
Every stage sends a real email to the account's billing contact, in addition to the internal audit record: the reminder and final-notice stages explain what is happening and what to do, and the suspension stage confirms the account has been paused and what resolves it. Suspension itself is enforced at the authentication layer, an API key for a suspended account is rejected immediately. The whole check now also runs automatically once a day, so a past-due account is escalated without anyone needing to trigger it by hand, though it can still be run on demand from the admin console at any time.

5. Test-mode keys and billing

A orx_test_ API key behaves identically to a live key everywhere except one place: any positive charge recorded through that key is written to the ledger as $0, with a note added to the entry explaining it was a test-mode charge. This lets you safely exercise billing-adjacent flows in an integration test without risk of a real charge appearing in your ledger.

6. Invoices and receipts

  • Invoice preview: a summary for any date range you choose, calculated from metered usage in that window.
  • Invoice PDF: a downloadable PDF version of that same summary.
  • Automatic charge receipts: every time a real charge is recorded, a PDF receipt is generated and emailed automatically. If the charge is unusually large, a Slack alert is also sent, so a large or unexpected charge doesn't go unnoticed.
curl "https://portal.orenyxengine.com/api/v1/billing/invoice-preview?periodStart=2026-07-01&periodEnd=2026-08-01" \
  -H "x-api-key: your_api_key_here"

curl "https://portal.orenyxengine.com/api/v1/billing/invoice-pdf?periodStart=2026-07-01&periodEnd=2026-08-01" \
  -H "x-api-key: your_api_key_here" -o invoice.pdf

7. Metered usage and usage alerts

The billing engine supports metering individual usage types (for example, API calls or leads processed) at a configurable rate per unit, and can alert you by email once your usage for the current calendar month crosses a threshold you set, at most once per month per alert.

curl -X POST https://portal.orenyxengine.com/api/v1/billing/usage-alerts \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"metric": "leads_processed", "thresholdQuantity": 10000, "notifyEmail": "billing@yourcompany.com"}'
Metering is live for API calls. Every successful request made with an API key is recorded, attributed to the key that made it and to the endpoint it hit, so an invoice preview and a usage alert both reflect real activity. Usage is reported to Stripe once a day, for whole days that have closed, and appears on the invoice Stripe issues on its own schedule; nothing here charges a card by itself. api_calls is the only metric metered today: leads_processedis priced in the rate table but not yet recorded, so it still reads zero.

8. Currency

The ledger supports multiple currencies, each with its own independent balance and transaction history. Converting between currencies for a combined total uses a small internal exchange-rate table (USD, EUR, and GBP only) rather than live market rates, see Settlement, section 7 for the detail and the caution that goes with it. Invoices and plan prices today are USD only.

9. Chargebacks and refunds

CapabilityStatus
Chargebacks (card-network disputes)Implemented. A disputed charge is matched to the original transaction and recorded as a negative ledger entry, so the reversal is visible in the account's history.
RefundsNot yet implemented. There is no endpoint or automated flow to issue a refund or record one in the ledger today. A refund currently needs to be handled directly in Stripe, and would not yet appear in this platform's ledger.

10. Endpoint reference

All billing endpoints require an API key with the billing scope.

EndpointWhat it does
GET /billing/invoice-previewPreview of usage-based charges for a date range.
GET /billing/invoice-pdfThe same preview, as a downloadable PDF.
GET /billing/usage-alertsLists configured usage alerts.
POST /billing/usage-alertsCreates or updates a usage alert threshold.
GET /billing/usage-alerts/checkManually checks current usage against configured thresholds.
GET /billing/usage-historyDaily totals for one usage metric over a date range, zero-filled for days with no activity — feeds the usage trend chart in the portal.
POST /billing/prorationRecords an internal ledger adjustment for a plan change (see section 3).

Plan selection, upgrades, and cancellation from the customer-facing dashboard go through the portal application rather than this API directly, see the Billing & Plans page in your dashboard.

11. Summary: what to rely on today

  • Real and enforced: plan pricing and checkout, Stripe-driven subscription billing, ledger-recorded proration, test-key $0 charges, chargeback recording, automatic PDF receipts on real charges, account suspension on unresolved non-payment, and a real reminder/final-notice/suspension email at each dunning stage, running automatically once a day.
  • Real and enforced: metered usage tracking for API calls, attributed per key and per endpoint, reported to Stripe once a day for whole closed days. Reporting only, never an automatic charge.
  • Built but not yet fed real data: the leads_processed metric, which is priced but not yet recorded.
  • Not yet built: refunds, and a stored plan catalog independent of the portal's own code.

Was this page helpful?