Future Rate Versioning
Overview
Rate schedule versioning for Aria Billing Cloud supports accurate invoicing with positive or negative bill lag days, or for accounts created with a retroactive start date. This feature ensures invoices reflect the correct rate schedule version effective at the time of invoice generation, considering future rates you set in the product catalog when configuring services on a plan.
Prerequisites
- Configure bill lag days.
- Request that Aria Support enable the client parameter, VERSIONING_ENABLED, to enable future rate versioning. When set to "True", Aria will pick the appropriate service rate to generate invoices, based on product catalog future rate schedule rate changes, ahead of an account’s anniversary date, to accommodate negative bill lag days. The actual change will not be reflected on the account until the effective date. When set to "False" (the default), Aria picks the rate current at the time of invoicing.
- (Optional) Enable the Plan Activity logs (Configuration > Client Settings > Miscellaneous > Plan Activity Logs). Enabling the Plan Activity Logs allows you to audit rate changes executed by Aria related to scheduled rate changes.
Scheduling a Future Rate Change
Getting Here: Products > Plans > New > Rates tab, or Products > Plans > (choose existing plan) > Rates tab
- Navigate to the step of updating or specifying a new rate for a plan.
- Click the Schedule Future Rate Change check box when configuring the rates of services on a plan.
- Click in the Future Rate Change Start Date box and select a date from the calendar.
Use Cases
General Version Selection Rules
- Custom Rates: If a custom rate is set at the account level, the application will ignore any future effective rates defined at the product catalog level for that plan. Only the account-specific rate will be considered during invoicing. This is an existing behavior.
- Retroactive Start Dates: When an account is created with a retroactive start date, and no matching rate version exists in history for that past date, the application will default to using the first available rate schedule version from the history.
Example: If an account is created with a start date of 17-Apr-2024, but the plan itself was created on 17-Apr-2025, the application will still generate the invoice using the rate schedule version effective as of the plan creation date, as no earlier rate version exists for the retroactive date.
API-related Proration Support
You can perform various actions on customers' plans using Aria's API. Depending on the type of service on the plan, and dates you specify, plan change APIs can result in proration.
- assign_acct_plan_m
- replace_acct_plan_m
- update_acct_plan_m
- cancel_acct_plan_m
- update_acct_plan_multi_m
- update_acct_complete_m
- edit_acct_plan_queued_change_m
Aria picks rates for proration calculation based on various date fields, depending on which plan change API you are calling. The following table outlines various plan actions and the date fields related to proration for the various service types:
| Action | Service Type | Comment (if more than one date present, the precedence is listed in order) |
|---|---|---|
| Assign | Recurring |
The application will use the below input parameter for picking the rate version, else the application will make use of current plan assignment date
|
| Activation | ||
| Recurring Arrears |
The application will use the below input parameter for picking the rate version, else the application will make use of current plan assignment date
|
|
| Minimum Fees | ||
| Replace | Recurring | The application will use the actual replacement date (current/VT) for picking the rate version. In case the user is passing any of these inputs, then the application will consider it a) alt_proration_start_date |
| Activation | ||
| Recurring Arrears | For Old Plan, it will be charged till previous day For New Plan, the application should consider the new plan’s bill thru date for picking the rates. In case the user has passed the below inputs, then the application will consider it for picking the rates. a) alt_proration_end_date—If valid inputs, then the applicaton will consider this input for picking the rate version, but it’s applicable only for plan instance that is of daily/weekly billing interval type. |
|
| Update | Recurring | The application will make use of this input “alt_proration_start_date” for determining the rate version, else the application will use the current (VT) for picking the rate version |
| Recurring Arrears | For update units/rate schedule, the application will consider the bill thru date of the current plan. | |
| Cancel | Recurring Arrears | The application will be calculated till previous date during cancel. |
| Replace and Cancel | Cancellation | For cancellation service the application will be calculated till previous date during cancel and replace action. |
| Usage | During cancel and replace the application will rate usage till current timestamp. So, it will be using the current date for picking the rate version |
"Get" APIs That Return Rate Versions
| API | Hash Name | Field Name |
|---|---|---|
| get_client_plans_all_m | <all_client_plan_dtls>
|
<future_rate_per_unit> |
| <rate_per_unit> | ||
| <monthly_fee> | ||
|
<future_change_date> | |
| <future_rate> | ||
<plan_service_rates> (array)
|
||
| get_client_plan_service_rates_m | <plan_service_rates> | <future_rate_per_unit> |
| <rate_per_unit> | ||
| <monthly_fee> | ||
| <weekly_fee> | ||
| <daily_fee> | ||
<all_acct_plans_m>
|
<future_rate_per_unit> | |
| <rate_per_unit> | ||
| <monthly_fee> | ||
| <weekly_fee> | ||
| <daily_fee> | ||
|
<future_rate_per_unit> | |
| <rate_per_unit> | ||
| <monthly_fee> | ||
| <weekly_fee> | ||
| <daily_fee> | ||
| get_avail_plans_for_acct_all_m | <all_client_plans_services>
|
<future_rate_per_unit> |
| <rate_per_unit> | ||
| <monthly_fee> | ||
| <weekly_fee> | ||
| <daily_fee> |
The API get_plan_details_m returns the following fields when <include_rs_summary> is passed as "true":
| Hash Name | Fields |
|---|---|
| <service_no> | |
| <rate_sched> (hash) | <available_from_dt> |
| <available_to_dt> | |
| <future_rate> | |
| <future_change_dt> | |
| <followup_rs_no> | |
| <service_rates> (hash) | <from_units> |
| <to_units> | |
| <description> | |
| <rate_per_unit> | |
| <future_rate_per_unit> |
Caveats
- Plan Units: Not available for Plan Unit Instance functionality.
- Sandbox Generator: Only copies current and future rate schedule versions, not historic rate schedule versions.
- Manual Migration Required: Enabling this feature when you are live in production requires a manual migration of current and future rate schedule rates with the assistance of the support team.
- Copy Config: This feature is not available.
- Only One Future Rate Scheduled: To create another future rate, the date must surpass the future rate's effective date. Similarly, there can be only one current rate.
- Retain Current Tier Structure: Future rate must retain current rate tier structure.
- Copy Plans: Attempting to copy a plan with future rate change date of "today" or any time in the past will fail with an error.
- Backdated Usage: Aria adheres to the behavior you specified for BACKDATE_USAGE_RATING.
- Future Rate Changes and Negative Bill Lag Days: If Aria has already generated a Negative Bill Lag Days invoice for an account and the rate being changed affects that invoice, you can either:
- discard the invoice and regenerate it so the new invoice reflects the updated future/current rates, or
- re-bill the invoice, manually passing the updated rates.
- Advance Invoice Proration Behavior: As a best practice, you should set the client parameter DO_FULL_ROLLBACK_ON_INVOICE_VOID to "True", allowing Aria to automatically delete any future or advance invoices during proration invoice generation.