Subscription Settings
Subscription settings control the default behavior for subscription lifecycle operations across your BillHive tenant. These are admin-level configurations that apply globally but can be overridden per-subscription where applicable.
URL: Settings > Subscription Settings Access: Owner, Administrator
Preferences
General subscription behavior, in six groups. Each setting is explained in its own section below.
| Group | Setting | Purpose | Default |
|---|---|---|---|
| Billing & Invoicing | Default payment terms (days) | Days a customer has to pay an invoice. See Default payment terms. | 0 |
| Allow custom prices | Let signed-in merchant portal users set a custom price. See Allow custom prices. | Off | |
| Add-on billing cycle | Whether add-ons bill on the plan’s cycle or on their own. See Add-on billing cycle. | Plan Based | |
| Proration | Plan changes | Prorate now a mid-term plan change, or charge the new plan in full and Start a new term. See Plan changes. | Prorate now |
| Proration Method | How the unused part of a term is calculated. See Proration Method. | Actual days | |
| Start & Activation | Backdating limit (days) | How far in the past an admin may start a new subscription. See Backdating limit. | 90 |
| Activate before first payment | Whether a future-dated Auto Collect subscription is Active before its first payment is collected. See Activate before first payment. | On | |
| Renewal | Renewal lead time (days) | Days before the renewal date that the renewal invoice goes out. See Renewal lead time. | 5 |
| Keep access during unpaid renewals | Keep an unpaid renewal of a usage-billed subscription without Auto Collect Active. See Keep access during unpaid renewals. | Off | |
| Renewal grace period (days) | With the previous setting on, days after the term ends that an unpaid renewal stays Active. See Renewal grace period. | 0 | |
| Trial | Trial reminder lead time (days) | Days before a trial ends that the customer is reminded to activate. See Trial reminder lead time. | 5 |
| Usage | Late usage window (days) | Days after a term ends during which usage for that term can still be recorded. See Late usage window. | 0 |
Billing & Invoicing
Default payment terms
Shown as Net Term Days before.
The number of days a customer has to pay an invoice, counted from its issue date (0–365). A new customer starts with these net terms; change them for one customer on its Preferences. Each invoice’s due date comes from the customer’s net terms. Auto Collect subscriptions don’t use net terms: their invoices are due, and paid, when issued. On a renewal, an account with net terms above 0 isn’t expired for an unpaid invoice: it renews, and goes into dunning if the invoice is still unpaid after its due date. See Accounts on Net Terms.
Allow custom prices
Shown as Price Override before.
When Price Override is on, a signed-in merchant portal user can enter a custom unit price instead of the list price when creating a subscription, changing a plan, or adding an add-on. When it is off, or unset, every order uses the list price.
API keys are always blocked from setting a custom price, whatever this setting says. A request with a custom price that is not allowed fails with HTTP 400 and the message Custom prices are not allowed for this request. See Custom Prices on an Order.
Add-on billing cycle
Shown as Billing Frequency, then Add-on Alignment, before; the setting key is still subscriptionBillingFreq. It is the only add-on alignment setting: the separate addonAlignmentPolicy key was removed because nothing read it.
Decides how add-ons are billed relative to the plan.
| Option | What happens |
|---|---|
| Plan Based (default; also when never saved) | The rate plan price sets the billing cycle. Add-ons are billed on the plan’s cycle and renew with it. They are prorated with the plan on a change. |
| Multi Frequency | Add-ons can have their own billing cycle, separate from the plan. Only mandatory add-ons renew with the plan; the others bill on their own cycle. |
See Which add-ons renew with the plan.
Proration
Plan changes
Decides what a mid-term plan change does (it was shown as Prorated Billing for Upgrade/Downgrade; the setting key is still ProratedUpgradeDowngrade). It applies to upgrades and downgrades alike. End of Term changes are never prorated: the new plan starts at the renewal, at its full price. There is no “apply at renewal” policy: to switch at the renewal, choose End of Term on that plan change.
| Option | What happens |
|---|---|
| Prorate now (default; also when never saved) | The customer is credited for the unused part of the old plan and charged the new plan for the rest of the term. The term keeps its dates. |
| Start a new term | No proration. The customer pays the new plan in full and a new term starts on the change date. Nothing from the old plan is credited, and neither are add-ons billed with the plan. |
Example. A customer moves from a ₹1,000/month plan to a ₹3,000/month plan on day 10 of a 30-day term. The table shows both settings together:
| Pre-Pay Flat Fee | Plan changes | Charged on the day of the change | Term |
|---|---|---|---|
| On | Prorate now | ₹2,000 for the 20 days left at ₹3,000, minus a ₹667 credit for the 20 unused days at ₹1,000 = ₹1,333 | Unchanged |
| On | Start a new term | ₹3,000 in full, with no credit | A new term starts that day |
| Off | Prorate now | ₹333 for the 10 days used at ₹1,000. At term end, ₹2,000 for the 20 days at ₹3,000. | Unchanged |
| Off | Start a new term | ₹1,000 in full, which settles the old term | A new term starts that day; ₹3,000 is invoiced at its end |
The day counts follow the Proration Method.
Changing to a different billing period, for example monthly to annual, always starts a new term on the change date:
- With On, the unused days of the old term are credited against the full price of the new plan.
- With Off, the customer pays the new plan’s full price, with no credit.
Proration Method
The proration method decides how much of a term counts as unused when a plan changes, an add-on is removed or changed, or a subscription is cancelled with prorated credits. It applies to credits and to the prorated charge for the new plan. It does not apply to End of Term changes, which use the full term price. Tenants that have not set it use Actual days.
| Method | Unused share of the term |
|---|---|
| Actual days (default) | Unused calendar days ÷ days in the term. |
| 30/360 | Unused days ÷ total days, counting every month as 30 days. |
| Whole months | Only complete unused months are counted; a partial month earns nothing. |
Example. A monthly term of ₹2,656 runs 23 Oct to 22 Nov and is cancelled on 8 Nov with prorated credits:
| Method | Credit |
|---|---|
| Actual days | 15 ÷ 31 × 2,656 = ₹1,285.16 |
| 30/360 | 15 ÷ 30 × 2,656 = ₹1,328.00 |
| Whole months | No complete month is left = ₹0.00 |
There is no “No proration” method: whether a period is prorated at all is set per event, by Plan changes for plan changes and by Unused Period Credit Policy (“Don’t issue credits”) for cancellations. A value saved as “No proration” before is counted as Actual days.
For how Proration Method works with Plan changes and the cancellation Unused Period Credit Policy, with examples for each event, see Proration & Credits.
Start & Activation
Backdating limit
Shown as Backdate lookback (days) before.
Backdate lookback (days) sets how many days before today a new subscription’s start date may be, so admins can onboard existing customers with their real start dates. The default is 90 days, also used when the value is missing or not a whole number of 0 or more. Set it to 0 to disallow backdating. A start date older than the limit is rejected with HTTP 400. Past start dates are accepted only from admin channels; the Website checkout and Self-Serve Portal always require a start date of today or later. See Backdated Start Dates.
Activate before first payment
Shown as Pre-Payment Access before.
Decides when a subscription that starts on a later date with Auto Collect becomes Active, which is when the customer has access to the service. It doesn’t apply to subscriptions that start immediately, which collect the first payment at checkout before becoming Active, or to accounts on net terms.
| Option | When the subscription becomes Active | If the first payment fails |
|---|---|---|
| On (default; also when never saved) | On its start date, once the payment mandate is approved and the first payment is scheduled, before the money is collected | The subscription goes In Dunning: payment is retried and your dunning final action decides what happens |
| Off | Only once the first payment is collected, after the settlement period | BillHive checks again after a second settlement period. If the payment still hasn’t arrived, the scheduled payment is cancelled, the order fails and the subscription never becomes Active |
Example. A subscription starts on 1 Jul with Auto Collect, and the bank needs 3 days to settle. With On it’s Active from 1 Jul. With Off it becomes Active on 4 Jul, when the payment is confirmed.
With a Cashfree mandate on a fixed schedule, Cashfree debits the first payment itself on the start date, and the subscription becomes Active once that debit is recorded, whichever option is set.
Renewal
Renewal lead time
Shown as Renewal Offset Days before.
How many days before the renewal date (the day after the term ends) the renewal’s expiring-soon step runs: the renewal invoice and payment request are created and sent to the customer. A whole number from 1 to 60; the default is 5, also used when the value is missing or invalid.
Example. A term ends on 30 Jun, so the renewal date is 1 Jul. With 5 days the invoice goes out on 26 Jun; with 10 days, on 21 Jun.
- Events: every renewal scheduled after the change, including renewals rescheduled by a plan change, a resumed pause or a removed cancellation. Renewals already scheduled keep their date.
- If the date has already passed when a renewal is scheduled, the step runs straight away.
Keep access during unpaid renewals
Shown as Access Continuity before.
Decides what happens at renewal when the renewal invoice isn’t paid yet, for subscriptions that bill usage and don’t use Auto Collect. A subscription bills usage when it has an active Per Unit or Volume add-on, or a Percentage rate plan price, whose price aggregates usage events (see Addon Price UBB Configuration).
| Option | Unpaid renewal |
|---|---|
| Off (default) | The subscription expires, unless the account has net terms. |
| On | The subscription renews and stays Active, and usage keeps being recorded for the new term, the same way an account on net terms renews. If the invoice is still unpaid when the Renewal Grace Period ends, the subscription goes In Dunning. |
Subscriptions with Auto Collect, and subscriptions without usage billing, aren’t affected. With a grace period of 0, the subscription renews but goes into dunning on the renewal date, so turn on Access Continuity together with a grace period.
Renewal grace period
Applies only when Access Continuity applies to a renewal. It’s the number of days after the term ends that an unpaid renewal stays Active: whole days from 0 to 90, default 0. If the renewal invoice is still unpaid the next day, the subscription goes In Dunning. If the account has net terms that give a later due date, the net terms win.
Example. A term ends on 30 Nov and the renewal invoice isn’t paid. With a 7-day grace period the subscription stays Active until 7 Dec and goes into dunning on 8 Dec. With 0 days it goes into dunning on the renewal date, 1 Dec.
Trial
Trial reminder lead time
Shown as Trial Expiring Soon Offset Days before.
How many days before a trial ends the customer gets the Trial Ending Soon notification, reminding them to activate. A whole number from 1 to 60; the default is 5, also used when the value is missing or invalid.
Example. A trial ends on 30 Jun. With 5 days the reminder goes out on 26 Jun; with 10 days, on 21 Jun.
- Events: every trial started after the change. Trials already running keep their date.
- If the date has already passed when the trial starts, the reminder goes out straight away.
Usage
Late usage window
Shown as Usage Data Entry Grace Period before.
The number of days after a term ends during which usage for that term can still be recorded (0–90). Usage recorded in that window is saved as Late; usage after it is saved as Invalid. The default is 0: once the term ends, usage for it is no longer accepted. See Usage Recorded After the Term Ends.
Coming soon: Pre-Pay Flat Fee
Decides when flat fees are invoiced: the plan’s price, add-ons billed with the plan, and Recurring charges. Usage is always billed at the end of the term, and one-time charges are billed when they happen, whatever this setting says.
| Option | What happens |
|---|---|
| On (default) | Flat fees are invoiced upfront, at the start of each term, before the service is delivered. The renewal invoice for the next term goes out before the current term ends. |
| Off | Flat fees are invoiced in arrears, at the end of the term they cover. A new subscription starts without a flat-fee invoice. On the renewal date, one invoice bills the term that just ended, and the next term starts. A subscription that doesn’t renew still gets its final end-of-term invoice. |
With Off:
- Unpaid end-of-term invoice. The subscription keeps renewing, because the customer has already used the service. If the invoice is still unpaid after its due date, the subscription goes into dunning.
- Cancelling mid-term. The customer is invoiced for the days used so far, plus any early-termination fee. No unused-period credit is due, because nothing was paid in advance.
- Trials. A trial is free. The first paid term is invoiced when it ends.
- Changing the setting. Each term keeps the timing it started with, so no term is ever billed twice or skipped. The new timing applies from the next term whose renewal hasn’t been prepared yet.
Coming soon. This setting isn’t on the Preferences tab yet: until it ships, BillHive invoices every flat fee upfront.
Pause Subscription Settings
| Setting | Description |
|---|---|
| Default pause timing | Pause Immediately (default) or Pause on Next renewal (End of Term). Pre-selected on the pause form, and used by API requests that leave out pauseOption. Stored as PauseSubscriptionInvoked. See Pause Options. |
The resume date, the resume timing and the pause duration are chosen on each pause or resume request, so they are not settings. Pause Subscription Period, Resume Subscription Invoked and Unpaid Charges Handling were removed for that reason; saving them through the API returns an error. Unbilled Charges Handling, Invoice Dunning Handling and Unpaid Invoices Handling are no longer shown, because pausing and resuming don’t read them yet.
Cancel Subscription Settings
Defaults for cancellations. The admin cancel form starts on them and each cancellation can change them; Self-Serve Portal cancellations always use them. Until a value is saved, the form starts on the default shown.
| Setting | Description | Default |
|---|---|---|
| Default cancellation timing | Cancel immediately or Cancel at end of current term. Used by API requests that leave out cancelOption. Stored as CancelSubscriptionInvoked. See Default timing. | Cancel at end of current term |
| Unused Period Credit Policy | Don’t issue credits, Issue prorated credits, or Issue full credits. | Issue prorated credits |
| Refundable Credit Action | Credits are always applied to unpaid invoices first; then keep the rest as credit (Retain credits) or refund it (Initiate refund). See Refundable Credit Action. | Initiate refund |
| Unpaid Invoice Handling | Retain as unpaid (invoices stay open), Attempt Collection (try to collect payment for them) or Write Off (close them with nothing to pay). | Attempt Collection |
Unbilled Charge Handling is no longer shown on this tab, because the cancellation doesn’t act on it yet.
Tax Handling
URL: Settings > Taxation
One switch per tax region decides who handles tax: Calculated by BillHive or Handled by you. It affects every order estimate, invoice and credit note in that region’s currency. BillHive calculates tax and shows it on your documents; filing tax returns always stays with you. There are no other tax settings: rates and HSN/SAC codes live on your tax profiles. See Taxation Settings.
How Settings Apply
- Settings are configured once at the tenant level.
- When an admin performs a subscription action (pause, cancel, etc.), the form is pre-populated with these default values.
- The admin can override any default for the specific subscription.
- The actual values used for each action are recorded in the Activity Log.
This two-level approach (global defaults + per-action overrides) balances consistency with flexibility.