Run the renewal cycle.
Calendar, approval queue, dry-run, boundary. What Revvly applies at each renewal and how to keep every uplift and migration deliberate.
01Watch the calendar
Renewals → Calendar shows every subscription anniversary in a date window, with the total renewal value at stake across the range. The calendar is the only renewals screen in the dashboard. Thirty days out is when a renewal typically becomes actionable.
02Queue a renewal for review
A Renewal Action puts one subscription's upcoming renewal into an approval queue. The queue is available through the GraphQL API (createRenewalAction); the dashboard has no screen for it. Use it whenever a renewal shouldn't just happen silently: a price uplift, a pending migration landing at the boundary, an at-risk account.
03Decide — singly or in bulk
Each queued action is approved or rejected with notes through the API (decideRenewalAction). Cohorts that share a decision — say, every subscription migrating to Bundle v3 at renewal — can be bulk-approved or bulk-rejected in one call. Queue stats keep the backlog visible.
04Preview the run before it writes anything
previewRenewalProcessing is a dry-run of the whole boundary: which subscriptions would renew, which pending migrations and Custom Pricing Agreements would apply, what would be invoiced. Nothing is written. Make this a habit before any manual processing run.
05What happens at the boundary
When a renewal processes, Revvly applies any queued NEXT_RENEWAL migration and any published Custom Pricing Agreement, decrements the remaining duration on fixed-count Discounts, issues the renewal invoice, and writes a RENEWED lifecycle event — all in one pass. A single subscription can also be renewed manually with renewSubscription.
06A committed term can stop or gate the boundary
If the subscription is sold under a contract with a committed term, the period whose end reaches that term consults the contract instead of just renewing. An auto-renewing commitment rolls into its next term; one that simply ends does not renew past the boundary; one that renews unless notice is given raises a single item in this same approval queue as soon as the notice window opens, and blocks the boundary until somebody decides it. A contract narrows a renewal rather than forcing one — inside the term, ordinary boundaries stay with the subscription’s own auto-renew setting.
07Month-end dates hold their day
A subscription billed on the 31st renews on the last day of February — the 28th, or the 29th in a leap year — because there is no 31st to renew on, and then returns to the 31st in March. It does not quietly become a 28th-of-the-month subscription after one February, because the day the customer signed on is remembered as the subscription’s billing anchor and every boundary is measured from that, clamped to the last day of any month too short to hold it. The same rule governs the 29th and 30th, quarterly and annual anniversaries, and the coverage marker on a prepaid span, so a renewal, its invoice and its service period all agree on the date.
08Invoice ahead of the renewal (optional)
If your customers need the invoice before the period starts, set a renewal-invoice lead time so the renewal invoice is generated ahead of the renewal date. It is configured per billing period — monthly, quarterly, yearly — as a workspace-wide default under Settings → General, and overridable per client on the Edit Client modal (blank inherits the default; 0 keeps invoicing at the renewal itself). The effective timing for each client is shown on their details card. Only the base recurring charge is billed early; the renewal boundary then closes out just the variable/usage lines, so nothing is double-charged and usage counters are not reset ahead of time. A client with a NEXT_RENEWAL migration pending is skipped until the migration applies, so the current period is never billed at the pre-migration price.
09When the customer doesn't renew
cancelSubscription first records a CANCEL_SCHEDULED event, which moves no MRR because access continues until the end date. CHURNED, with the negative MRR delta, is written later by the daily job once the end date and the churn grace window have passed. markSubscriptionChurnedDueToPaymentFailure records the involuntary path. Churn analytics stay truthful without any manual bookkeeping.
- Cancel requestedCancel scheduledCANCEL_SCHEDULED is recorded. No MRR moves and access continues.
- End date, then grace windowChurn waitsThe daily job acts once both have passed.
- Daily jobChurnedCHURNED is written with the negative MRR delta.