Skip to main content
Subscriptions are the default for traditional SaaS products. You charge customers on a regular schedule to maintain access to your application.

​
Set up recurring billing

  1. Open a draft plan and make sure it is set to Paid.
  2. Under Billing cycles, select the recurring intervals you want to offer, such as 28 days, Monthly, 3 Months, 6 Months, or Yearly.
  3. Enter the price for each interval.
  4. Click Save.
You can enable multiple intervals on one plan. Customers choose among the enabled intervals at checkout.
A 28-day subscription renews every four weeks. It is not the same as a calendar-month subscription. If the 28 days option is not visible for your organization, contact Kelviq support to have it enabled.

​
Subscription lifecycle

Kelviq handles recurring payments automatically. This includes:
  • Charging the saved payment method at the end of each billing cycle
  • Sending receipts and tax invoices
  • Retrying failed card payments
  • Applying prorated charges when a customer changes plans during a billing cycle
Check the current subscription status with the Kelviq SDK or API. If your application needs event notifications, use webhooks.

​
Change a subscription

By default, plan upgrades and downgrades take effect immediately. As soon as the change is processed, Kelviq applies the new plan and its feature limits. For a paid change, you can wait until payment succeeds before activating the new plan. Pass paymentBehavior: "activate_on_payment" when you update the subscription:
Omit paymentBehavior to keep the default immediate-update behavior.

​
Control how a change is billed

Proration decides what the customer pays for the rest of the period: charged now (IMMEDIATE_CHARGE), added to the next invoice (PRORATE_NEXT_INVOICE), or skipped (NO_PRORATION). Set your defaults in Settings → Subscription proration, or pass prorationBehavior when you update a subscription. Proration walks through each option with an upgrade and a downgrade example. The defaults are also available through the API as updateSubscriptionProrationBehavior and migrateSubscriptionProrationBehavior on PATCH /organizations/settings/.

​
Wait for payment before changing access

activate_on_payment keeps the customer’s current subscription active while payment for the change is pending. This prevents an unpaid plan change from replacing working access. Card payments that do not require authentication are usually completed during the update request, so the status change can happen immediately. When the payment method requires customer action, continue using the existing subscription until the updated subscription becomes active.
With activate_on_payment, the new plan goes live after its payment succeeds. Check the subscription’s plan or the customer’s entitlements before granting access to the new plan.

​
Upgrades

Under the default IMMEDIATE_CHARGE proration behavior, Kelviq prorates the price change against the time left in the current billing period. It credits the unused portion of the old plan, charges for the remaining portion of the new plan, and collects the net difference. See Control how a change is billed for the other options. With activate_on_payment, Kelviq waits for that payment to succeed before activating the upgraded plan. For example, if a customer moves from a $100 monthly plan to a $200 monthly plan halfway through the period, the approximate calculation is: The exact amount depends on when the upgrade is processed. Existing usage counters are retained and evaluated against the new plan’s limits.

​
Downgrades

Under the default payment behavior, downgrades also apply immediately. If the customer has unused value on the higher-priced plan, Kelviq converts it to account credit and applies that credit to future invoices.
An immediate downgrade can lower a customer’s limits below their current usage. Check the customer’s entitlements after the change and decide how your application should handle any over-limit state.

​
Cancel a subscription

When cancelling, choose whether the subscription should end immediately or at the end of the current billing period. A plan downgrade and a subscription cancellation are separate actions: the downgrade follows the payment behavior you choose, while the cancellation follows the timing option you select.

​
Pause a subscription

A paused subscription stops billing and stops access. The customer isn’t charged, their entitlements return hasAccess: false, and plan changes are blocked until the subscription resumes. Cancelling stays available. When a customer tries to cancel, Kelviq shows the offer you’ve set for the reason they give: a discount, a pause, or a link to your support team. If the offer is a pause and they accept it, they pick a length from the ones you allow: 1, 3, or 6 months. This works in the customer portal and from a Cancel button in your own app. See Retention offers. A pause has to cover at least one full billing period, so yearly plans can’t be paused. Only an active subscription can be paused, not one on trial, past due, already paused, or scheduled to cancel. Free and manually billed subscriptions can’t be paused.

​
Resume a subscription

A paused subscription resumes on its own at the end of the pause. Choose what happens on resume in Settings → Retention → Advanced settings: For a monthly plan billed on the 1st, paused on 10 September and resumed on 20 October, reset charges a full month on 20 October and bills on the 20th from then on. Keep billing day charges nothing and bills on 1 November as before, which gives the customer free access from the 20th to the 1st. A customer who resumes inside a period they’ve already paid for is never charged again, whichever behavior you pick. On resume, entitlements come back with usage reset to zero and a fresh period.

​
What changes while paused

The subscription has status: "paused", pausedAt, and pauseResumesAt (null for an open-ended pause). Kelviq sends subscription.paused and subscription.resumed webhooks, whichever surface the change came from. Webhook payloads use snake_case, so the same fields arrive there as paused_at and pause_resumes_at. Renewals that would fall inside the pause are skipped silently, so a paused subscription sends no other events until it resumes. If you cache entitlement checks, clear them when you receive subscription.paused, otherwise the customer keeps access until the cache expires. Both SDKs have a call for it: client.entitlements.invalidateCache({ customerId }) in Node and client.entitlements.invalidate_cache(customerId=...) in Python.

​
Retention offers

Before a customer cancels, you can offer them a reason to stay. In the dashboard retention settings, switch retention on and map each cancellation reason to an offer:
  • Discount: a percentage off for a set number of billing cycles, applied as a single-use coupon.
  • Pause: a break of one of the lengths you allow. Billing and access stop, then resume on a renewal boundary.
  • Support: a link to a booking page or support form, for reasons a conversation can fix.
The customer portal shows these offers automatically. To build the same flow in your own app, call Get retention offers for the subscription. It returns every cancellation reason with its configured offer and whether this subscription is eligible for it right now, so you can show an unavailable offer greyed out with a reason. When the customer takes an offer, call Accept a retention offer with the reason and the offer. If they cancel anyway, call Cancel a subscription with the same reason as cancellationFeedback.
An offer must be the one configured for the reason the customer picked, and eligibility is checked again when it is accepted. The repeat policy you set decides whether a customer who has already taken an offer can be offered it again, so discounts cannot be stacked by reopening the cancellation flow.

​
Refund a cancelled subscription

When a subscription is canceled mid-period, you decide whether to refund: in full, in part, or not at all. For a usage-based subscription, work out the amount from the customer’s usage and the time left. Then open the corresponding order in the dashboard and issue the full or partial refund there.

​
Failed subscription payments

After a failed card payment, the customer’s authorization stays in place, so Kelviq can retry and bill future cycles. If the customer pays the failed card invoice manually, automatic payments remain active. Kelviq will still use the saved payment method for the next billing cycle.

​
Card payment retries

When an automatic card payment fails, the subscription moves to past_due. Kelviq retries the payment up to eight times over the next 14 days. If recovery is unsuccessful, Kelviq cancels the subscription. After each failed attempt, Kelviq emails the customer a link to pay the invoice. The customer can also use the Customer Portal to update their payment method. You do not need to schedule retries, send card payment links, or ask the customer to set up automatic payments again. Kelviq handles this recovery flow.
Card and UPI AutoPay renewals follow this retry schedule. If the payment still hasn’t gone through after 14 days, the subscription is canceled.