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:
| Plan | Price | Billing interval |
|---|---|---|
| Small Teams | $199 / month | Monthly, or annual at a 20% discount |
| Mid-Size Teams | $399 / month | Monthly, or annual at a 20% discount |
| Large Teams | $699 / month | Monthly, or annual at a 20% discount |
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 state | Account status |
|---|---|
| active | ACTIVE |
| trialing | TRIAL |
| past_due or unpaid | PAST_DUE |
| incomplete | UNPAID |
| canceled, paused, or incomplete_expired | CANCELLED |
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 )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:
| Day | Stage | What happens |
|---|---|---|
| Day 3 | Reminder | Internally logged for the account. |
| Day 7 | Final notice | Internally logged for the account. |
| Day 14 | Suspension | The 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. |
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.pdf7. 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"}'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
| Capability | Status |
|---|---|
| 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. |
| Refunds | Not 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.
| Endpoint | What it does |
|---|---|
| GET /billing/invoice-preview | Preview of usage-based charges for a date range. |
| GET /billing/invoice-pdf | The same preview, as a downloadable PDF. |
| GET /billing/usage-alerts | Lists configured usage alerts. |
| POST /billing/usage-alerts | Creates or updates a usage alert threshold. |
| GET /billing/usage-alerts/check | Manually checks current usage against configured thresholds. |
| GET /billing/usage-history | Daily 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/proration | Records 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?