QSub — Subscriptions & Billing

QSub — Subscriptions & Billing

QSub is the QoinPay Enterprise module for recurring revenue: it turns catalogue plans into live subscriptions, generates invoices on schedule, collects payment through your configured methods, and manages the failure paths — retries, dunning, and involuntary churn — that determine how much recurring revenue you actually keep. It runs on your infrastructure against the shared MariaDB instance, so customer and billing data stays within your compliance boundary.

Capabilities

QSub is built around four objects: the plan (price, currency, billing interval, and trial policy), the subscription (a customer's live enrolment on one or more plans), the invoice (a dated, immutable statement of charges), and the payment attempt (the record of each collection try). This separation lets you change catalogue pricing without rewriting history, and lets a single subscription carry several plan lines plus one-off charges.

Key capabilities include:

• Flexible plans. Flat-rate, per-seat, tiered, and usage-metered pricing, with fixed or anchored billing dates, trials, and setup fees.
• Proration. Mid-cycle upgrades, downgrades, and seat changes are prorated to the day against the active plan price.
• Dunning. A configurable retry schedule with escalating customer notifications, grace periods, and an end-state (cancel, suspend, or downgrade) when retries are exhausted.
• Tax and discounts. Percentage or fixed coupons, credit balances, and pluggable tax rules applied at invoice generation.
• Revenue events. Every state change emits a signed webhook so your general ledger and analytics stay synchronised.

Subscription lifecycle

A subscription progresses through an explicit, audited state machine: trialing → active → past_due → (canceled|unpaid), with paused available where your edition permits. The billing scheduler runs as a cron job on your application tier; at each cycle boundary it generates the invoice, applies credits and tax, and enqueues a payment attempt. Successful collection returns the subscription to active; a failure moves it to past_due and hands it to the dunning engine.

0 2 * * *  php /opt/qoinpay/bin/qsub-billing-run --tenant=default

Schedule the billing run in your own crontab (or the bundled QoinPay scheduler). The job is idempotent per cycle, so a retried or duplicated run will not double-invoice.

Key modules

• Plan Catalogue — defines products, prices, intervals, trials, and coupons.
• Subscription Manager — enrolment, plan changes, pauses, and cancellations with proration.
• Billing Scheduler — the cron-driven engine that closes cycles and generates invoices.
• Dunning Engine — retry logic, customer communications, and involuntary-churn handling.
• Invoice Ledger — immutable invoices, credit notes, and the export feed for your accounting system.

API and integration

Subscriptions and plans are managed through /api/v1. Create a subscription and QSub handles scheduling from there:

POST /api/v1/subscriptions
Content-Type: application/json
Authorization: Bearer {token}

{
  "customer_id": "cus_4b19",
  "plan_code": "PRO-MONTHLY",
  "quantity": 5,
  "trial_days": 14
}

Invoice and payment outcomes arrive as signed webhooks (invoice.paid, payment.failed, subscription.canceled). Verify the signature before acting on any event, and treat deliveries as at-least-once — key your handlers on the event id.

Editions

• Standard — flat and per-seat plans, single currency, basic fixed-schedule dunning.
• Professional — tiered and usage-metered pricing, coupons and credits, configurable dunning, multi-currency.
• Enterprise — multi-entity billing, custom tax rules, revenue-recognition export, pause/resume, and extended invoice retention.

Your edition is encoded in the entitlement and enforced by the license key.

Sizing metric — active subscriptions

QSub is licensed by active-subscription count: the peak number of subscriptions in a billable state (trialing, active, past_due, or paused) during the period. Fully canceled and unpaid subscriptions do not count. The license tier sets a ceiling; the console warns as you approach it and blocks new enrolment once exceeded. Because trials count toward the metric, factor your trial volume into sizing rather than counting only paying customers.

Licensing and Software Subscription & Support

QSub is perpetually licensed — the software keeps running regardless of S&S status. The first year of Software Subscription & Support is included and delivers version upgrades, tax-logic updates, and support. Keeping S&S current is the practical way to receive new pricing-model features and jurisdictional tax updates.

Deployment

QSub shares the application tier, database, and license-activation flow with the rest of the suite. Its one hard operational dependency is a reliable scheduler for the billing run; a missed cycle simply bills late on the next run, but a chronically failing cron will stall collections. See the Getting Started, Licensing, and API overviews for setup and integration detail.