Upgrading Seats and Managing Usage Quotas

Buying more seats or more study headroom in Quartyl is a checkout, not a form: the firm starts a payment order, pays in the gateway’s modal, and the platform’s payment worker activates what was bought. This page is the flow end to end, plus what to do when a quota is running hot.

Checkout is not enabled in the current deployment. The gateway ships disabled and its credentials are unset, so the order step answers 503 — online payments are not enabled yet, please contact support to activate checkout. The dialog surfaces that message and closes, nothing is charged, and upgrades are provisioned by the platform team instead. Everything below describes the flow as it runs once a deployment enables payments.

The upgrade flow

1. Start the order. From the billing page — Add More Seats on the seat allocation, Add More Studies on the active-studies quota bar (see Billing and Usage) — a Firm Admin chooses a count and confirms. The backend prices it server-side — seats × per-seat price or studies × per-study price on the account’s plan tier and billing cycle — converts the USD amount to INR paise at a fixed reference rate, and returns an order with a publishable key. The secret key never leaves the server, the amount is never taken from the client, and the persisted order row is what the webhook resolves the tenant and purpose from, so a client cannot self-attest a payment. A gateway that is not configured answers 503 here; a gateway that rejects the order answers 502.
2. Pay in checkout. The gateway’s modal opens with the order (UPI, card, netbanking, EMI or virtual account — whatever the provider offers on the modal). If the modal’s script fails to load, the page reports that the payment provider could not be loaded and starts nothing.
3. The webhook settles it. On capture, the provider’s webhook — trusted for its HMAC signature over the raw body, never for a token — is recorded and handed to the platform’s payment worker, which returns 200 immediately. The worker, never the webhook, marks the order paid and applies the entitlement: seat orders raise the tenant’s seat budget, study orders raise its study limit, and subscription orders move the renewal date forward and set the account active. It then writes the paid invoice and arranges the PDF and the GST invoice through Zoho, best-effort — an invoicing failure is logged and retried by a reconciliation pass, and never fails the payment.
4. The UI catches up. The checkout’s success handler closes the dialogs, re-fetches the summary and reports “your upgrade will be activated shortly” (recharge says “your plan has been renewed”) — because the seats land when the worker processes the event, not when the modal closes. A retried webhook cannot double-apply: an order already marked paid is skipped.

Subscription recharge (the same path, different purpose)

The Recharge / Pay Plan button on the plan overview (hidden while the account is Paused) runs the identical order path with a subscription purpose: the amount is the plan’s base price plus the current seat count at the per-seat price, and on capture the worker extends the renewal window and sets the account active. One flow, three purposes — seats change the seat budget, study orders change the study limit, recharge changes the subscription window.

Managing usage at the limit

When a quota approaches its limit, the firm has a short list of levers:

• Seats. The budget is a hard guard on the team console: the invite that would exceed it is refused. The lever is a seat purchase (above) or the platform team; there is no temporary headroom.
• Studies. The bar counts studies that are not Archived, so archiving a finished engagement does free active-study headroom — but it moves that study into the reports count, so it is not a way to escape both quotas. The additive lever is a study order.
• Reports. The reports limit is the plan tier’s monthly entitlement; it resets with the cycle. Waiting is a real option here, and the overage alerts (50/90/100 per cycle, opt-in) are the early warning that makes waiting a choice rather than a surprise.
• Renewal. The expiration reminders at 14, 7 and 3 days (and the lapsed-plan notice after) carry the recharge path, so a plan lapsing into Past Due is announced, not discovered.

The numbers behind all of this — consumed versus allowed, per quota — are the usage quotas on the billing page.

FAQ

When exactly are purchased seats usable? When the payment worker processes the capture webhook — moments after payment in practice; the summary re-fetch shows them. Until then the budget is unchanged.

Is the plan’s minimum upgrade enforced at order time? No. The tier minimum (5 seats / 10 studies on the boutique plan, 10 seats / 20 studies on the enterprise suite) is the number the dialog pre-fills, and those are seeded defaults — a firm’s actual minimum is whatever its agreed plan says. The server enforces only the order bounds (1–500 units) and prices what it is given.

If the GST invoice fails to generate, is my payment lost? No — invoicing is best-effort downstream of the capture; the payment, the entitlement and the paid invoice record stand, and a missing PDF is later picked up by the reconciliation pass rather than reported as a failed payment.