Freeside:2.1:Documentation:Administration:VoIP:Timed Rates

From Freeside
Jump to: navigation, search

This is a new feature in version 2.1, waiting for a home in the new documentation.


Timed rates allow VoIP calls to be charged according to different rates according to the time of day and day of the week. A typical use of this is to offer a discounted per-minute rate for night or weekend usage.

In Freeside 1.9, VoIP calls are rated according to two properties of the call:

  • The rate plan associated with the customer's package definition.
  • The region determined from the call's destination number.

Together, these determine a rate_detail record containing the per-minute rate, connection charge, rounding increment, and other billing properties of the call.

Version 2.1 adds an additional factor:

  • The time period in which the call occurs.

Rate plans, regions, and time periods can be edited via Configuration -> Billing -> Call rates and regions.

Setting up time periods

Each time period comprises one or more intervals. For example, a "Daytime" period, covering the hours of 7 AM to 7 PM every weekday, would consist of five intervals: "Monday 7 AM to 7 PM", "Tuesday 7 AM to 7 PM", and so on. This only needs to be set up once, and then can be used to define daytime rates for any number of rate plans.

To create a time period, go to Configuration -> Billing -> Call rates and regions -> Time periods and click "Add a new period". Enter a name for the period (such as "Daytime"), then click "Add" to create an interval. In the dropdown boxes, select the day, hour, and minute for the start and end of the interval. Click "Add" again for as many intervals as you need. To delete an interval, click the "X" icon to the right side.

  • Usually, if your intervals start on the hour, they should end on the hour. That is, "7:00 AM to 7:00 PM", not "7:00 AM to 6:59 PM".
  • For billing purposes the week starts at 12:00 AM on Sunday. An interval can span multiple days, but not the end of the week; a "Weekend" period covering all of Saturday and Sunday would have to be defined as two intervals, one from 12 AM Saturday to 12 AM Sunday, and another from Sunday to Monday.

Setting up rates

After defining your rate plans and regions, go to Configuration -> Billing -> Call rates and regions -> Rate plans. Click the name of your rate plan, or, to see rates only in a specific country, choose the country code from the dropdown list. This will open the "Edit Rate Plan" screen, which is arranged as a matrix with a row for each region and a column for each time period. Each cell in the matrix is a rate definition. Click the "(add)" link to define a new rate. This will open a popup window with several fields:

  • 'Included minutes/calls': The number of minutes in each billing cycle that will be exempt from per-minute charges.
  • 'Connection charge' / 'For': The minimum charge for each call, and the amount of time in the call that is "covered" by the connection charge rather than billed per minute.
  • 'Charge per minute/call': The per-minute rate.
  • 'Granularity': The increment for rounding the call duration. Choosing "Call" here will cause calls to be billed per call rather than per minute.

Click the "Add rate" button and the "Edit Rate Plan" screen will refresh, showing your new rate with a summary such as "$0.10000 / minute in 10 second increments".

To view and edit all rates for a particular region, go to Configuration -> Billing -> Call rates and regions -> Regions and prefixes, then click the name of a region. This is similar to the rate plan view, but with a row for each rate plan. Click the row headers in either view to switch to editing that rate plan or region.

The rightmost column in the matrix is for default rates. These apply to any call that falls outside any defined time period, or in a time period that has no rate. For example, you can set up a "Daytime" time period, and then define a default rate which will apply the rest of the time. Default rates can't be deleted, and it's wise to create one for every region to ensure that no calls fall through the gaps.

How billing works with time periods

Each call is associated to a svc_phone or svc_pbx record, and thus a customer and rate plan, based on its source number, accounting code, or other properties of the call detail record. The call's destination region is identified by matching the destination number to a prefix, choosing the longest prefix that matches.

If the start time of the call falls within a defined time period which has a rate in that region, the call is assigned that rate. Otherwise, it's assigned the default rate for the region, if there is one. If not, the call will not be billed and, unless you've turned on the "ignore_unrateable" option in the package settings, billing will fail entirely.

If the call extends past a time period boundary, it will be split and billed according to the duration falling within each period. Only the first rate's connection charge will apply.


Two rates are defined in some rate plan and region:

  • A "Daytime" rate of $0.10/min with a $0.20 connection charge. The time period for this rate includes intervals from 7 AM to 7 PM every day.
  • A default rate: $0.05/min with a $0.10 connection charge.

A call from 6:00 to 6:30 AM is billed at the default rate:

  • Connection: $0.10
  • 30 min @ $0.05/min: $1.50

Total: $1.60

A call from 6:50 to 7:20 AM is split at the boundary:

  • Connection: $0.10
  • 10 min @ $0.05/min: $0.50
  • 20 min @ $0.10/min: $2.00

Total: $2.60