Troubleshooting Bills - m3ter Documentation

Troubleshooting Bills

If you’re experiencing issues when generating bills for an end customer Account, it’s well worth running through the following troubleshooting checklist of common billing problems with suggested remedies/checks.

Failed Bill Checklist

Bills for an Account in your Organization might be failing to create for several reasons. You can use the System Alerts page in the Console as a starting point to check and remedy any issues which are causing Bills to fail. On your Organization Dashboard, Your alerts are listed and you can click View all to open the System Alerts page:

• When a Bill is created successfully, an INFO Alert is generated. You can click the Alert to bring up an Alert dialog, which identifies the Account and the Bill total is shown. You can then use this information to keep track of Bills and also to check if the calculated Bill amount is what you’d expected it to be.
• When a Bill fails to create, an ERROR Alert is generated. You can click on the Alert and in many cases the reason for the failure is explained in the Alert dialog.

Here are some of the main reasons Bills fail to create and how to remedy the cause of failure:

• Currency Conversion Rate Missing
• Compound Aggregation Calculation Invalid
• No Price Plan Attached to Account
• Usage Data Issues
• Parent/Child Accounts - Billing Hierarchy Issues
• Accounts with Prepayments/Commitments
• Unexpected Error

Currency Conversion Rate Missing

If the billing currency set for your Organization or at Account level doesn’t match the pricing currency set in the Plan Template/Plan you’ve attached to an Account for billing and you haven’t defined a rate for converting the Plan pricing currency into the billing currency, then Bills will fail for the Account. To remedy:

• Check the currency set for the Organization or at Account Level - see Creating and Managing Currencies.

• Check the pricing currency set for the Plan Template/Plan - see Editing Plan Templates and Plans.

• Edit your Organization configuration. First select Settings:

• The Organization page opens with the Configuration tab selected:

• Select Currency settings:

• Follow the steps to add the required Currency conversion and then select Update currency conversions.

• Re-run billing for the Account.

Compound Aggregation Calculation Invalid

If you’ve used a Compound Aggregation - an Aggregation that uses a calculation - and the calculation is invalid and cannot be resolved by the m3ter calculation engine, then Bills will fail for any Account on a Plan that is priced using the Compound Aggregation. A simple example would be if your calculation attempts to multiply or divide two non-numeric values. An ERROR Alert will be generated that identifies the invalid Compound Aggregation and explains why the calculation it uses is invalid. To remedy:

• Open the Compound Aggregation and update the calculation as required in light of the explanation given on the Alert.
• Re-run Billing for the Account.

No Priced Plan Attached to Account

A priced Plan has not been attached to an Account. This means that no pricing metrics are available for any usage data submitted for the Account so no Bill is generated. To resolve this problem:

1. Create a Priced Plan if you have not already created one.
2. Attach the Plan to the Account to create an Account Plan.
3. Re-run Bill generation.

Usage Data Issues

Usage data may not have been uploaded correctly due to a variety of reasons. You can use the Usage Data Explorer (v2) to check if usage data and measures have been submitted against the Account. Key points to check:

• Does the Account number on the usage data match the Account number you are billing?
• Is the usage data within the service period being billed?

Parent/Child Accounts - Billing Hierarchy Issues

For Parent/Child Accounts, billing hierarchy issues can cause problems. If Bills are failing to generate:

• Check at which level the Account Plan to be used for billing has been attached?
• Is the Account Plan attached to the Parent/Child, or both?
• Is the Account to which the Account Plan is attached part of the billing hierarchy?

For more details on Parent/Child Accounts billing hierarchy mode settings, see Billing Hierarchy Modes for Parent/Child Accounts.

Accounts with Prepayments/Commitments

If the Account has a Prepayment added, then it’s worth noting:

• When using the Bill with plan option for billing Prepayment fees, ensure:
  • The Account Plan has the same Billing cycle date as the Prepayment/Commitment.
  • If configured, the Account Plan has the same Contract associated with it as the Prepayment. If Contracts do not match, then at billing the Prepayment amount will not be drawn-down against.
• If you have set up billing for Prepayment fees to Bill on a schedule and you have made changes to the schedule, check Bills that were generated according to the original schedule. See Prepayment Billing on a Schedule for more details.

Unexpected Error

If you receive a “Failed to create bill” ERROR on your System Alerts page, when you open the Alert an “Unexpected error” might be given as the reason for failure. This is for failures where the system cannot identify and report on a specific reason for the failure. In such cases, we recommend:

• Select the Alert. The Alert dialog will identify the Account for which a Bill has failed to generate and the date the error occurred is given.
• Contact m3ter Support for help in investigating the error and have these details given in the Alert dialog ready to hand.

Billing Dates Issues

There are several areas where billing dates can get out of alignment and cause issues for Bill generation:

• Plan Pricing and Account Plan Dates not Synchronized
• First and Subsequent Bill Dates not Aligned
• Prepayment Dates Alignment with Required Billing Period

Plan Pricing Dates and Account Plan Dates not Synchronized

When Account Bills are generated in m3ter, two key sets of dates affect what is calculated with respect to the usage charged for in the Bill:

• Plan Pricing. The period you’ve configured for the pricing on a Plan to be applied to that Plan - you set a start date and optional end date when you price a Plan.
• Account Plan. The period you’ve configured for a priced Plan to be active for an Account - when you attach the Plan to an Account to create an Account Plan, you set a start date and optional end date.

The start and end dates that define these two periods do not have to coincide, but if they do not, you might see a generated bill with unexpected amounts showing:

• Example. Suppose you’ve set up a pricing to be applied to a Plan to start on September 1st 2022 for the rest of the calendar year. You’ve then attached the priced Plan to become active for an Account on August 1st, also through to the end of the year. If, after some usage data has been submitted for the Account during the month of August, you open Bill management in the Console and Re-run billing, the Bill generated for the Account will not show charges for this submitted usage data. Because the pricing start date is set at September 1st, the Bill will only show any standing charges configured for the Plan.
• Fix. What’s the fix for this sort of misalignment of dates for billing? Assuming monthly billing frequency, if you want to produce a Bill for the month of August that includes charges for usage data, you must go back into the Pricing editor and create a second pricing for the Plan with a start/end date of August 1st/ September 1st (remembering end dates are exclusive so to cover the August period through to midnight on August 31st). If you return to Bill management and Re-run billing, the bill for the same Account will now show charges for the August usage data according to the new pricing you’ve configured for the Plan, since the Plan is already active for the Account.

If you suspect this might be your billing issue, you can follow a course through the Console to quickly chase it down and confirm Account Plan/Plan Pricing dates alignment:

1. Open the page for the Account with billing issues and select the Attached Plans tab. The Active and pending plans panel lists Account Plans with ACTIVE and PENDING tags. Note the start/end dates of an ACTIVE Account Plan.
2. Select the hotlink text for the Account Plan. The Plan attachment page opens:

• Under Plan attachment details, you can read off the Start and End dates defining the period the Account Plan will be active for the Account.

3. Scroll down the page:

• Under Plan details you can read-off details of the Plan attached to the Account to create the Account Plan.
• Any Pricing configured for the attached Plan will be shown with the Start and End dates defining the period a Pricing applies to the Plan.

4. Check the start/end dates for the pricing on the Plan to confirm date alignment between period pricing applies to Plan and period Account Plan is active for the Account.
5. If you want to investigate further, select the View pricing schedule hotlink text for a Pricing:

• The Pricing schedule page for the priced Plan opens and gives you comprehensive details of the Plan with the Aggregation used to price it and date ranges for a list of (active or pending) Pricings you’ve configured for the Plan.

First and Subsequent Bill Dates not Aligned

You can set up first and subsequent Bill creation dates at the Organization level when you configure your Epoch settings at Settings>Organization>Edit Organization. However, you can also define first and subsequent Bill creation dates at two further points in your overall configuration:

• At Account Level. You can optionally set a Billing cycle date for a specific Account and this will override the Epoch settings at Organizational level.
• At Account Plan Level. You can optionally set a Billing cycle date for a specific Account Plan that will be used to determine charges on an Account and this will override the Billing cycle date you might have set up at Account level.

With these configuration dependencies in mind, if you’re seeing some unexpected billing behavior, it’s well worth performing a quick check to confirm the first and subsequent Bill creation date that applies for the Account - at Organization, Account, or Account Plan level - is correct. For more details with explanatory examples, see First and Subsequent Bill Dates.

Prepayment Dates Alignment with Required Billing Period

If you add a Prepayment to an end-customer Account and not all of the Prepayment is paid upfront, to set up billing on the Account for the remaining Prepayment fees due you can select either to Bill with Plan or Bill on a Schedule - see Creating Prepayments for Accounts for more details. If you choose to set up billing for any outstanding Prepayment fees due on an Account using the Bill with plan option, please take care to ensure the required alignment of start/end dates for the Prepayment service period with the required overall billing period:

• For example, suppose you select a Plan for Prepayment billing that is set up for quarterly billing. This is what your Prepayment billing use case requires:

  • A $10,000 Prepayment has been agreed with your customer with nothing to be paid upfront. The Prepayment amount is to be paid in four equal amounts at quarterly intervals across the first year.
  • You want to Bill in advance and the first bill date to be July 1st 2025.
  • The first Bill amount to be set at $2,500, and the remaining $7,500 is to be billed at quarterly intervals in three equal amounts of $2,500.

• However, if the end date configured for the Prepayment service period doesn’t extend for the full year from the first bill date - say the Prepayment end date is set at June 15th 2026:

• In this case, the Bills will not be calculated at the correct $2,500 for each of the remaining three quarters:

• We can see that because the Prepayment service period does not extend for the full extent of the final quarter, the remaining $7,500 due has been split between the 2nd and 3rd quarterly Bills.

• If we adjust the Prepayment service period to make the end date July 1st 2026:

• And we then recalculate the 2nd, 3rd, and 4th quarter Bills, we see the correct Bill totals of $2,500:

Recalculating Bills after Billing Configuration Changes

If you’ve set up a specific billing configuration for an end-customer Account and Bills have already been generated according to this configuration. If you then make changes to the billing configuration, when you recalculate the previously generated Bills, the changes might not be reflected in the recalculated Bills:

• Removing or Changing an Account Plan
• Updating a Prepayment/Commitment Fee Billing Schedule

Removing or Changing an Account Plan

After setting up billing configuration for an end-customer Account by attaching one or more Account Plans to the Account, you might need to change the billing configuration for the Account for cases such as:

• An end-customer begins their service period with you having signed-up to consume several of your products or services. After some billing dates have passed, the customer decides they want to drop one of the products. Several Account Plans are attached to the Account - one for each of the products consumed. You therefore remove the Account Plan from their Account covering charges for the dropped product. In this type of case, any charges due under the previously attached Account Plan - such as standing charges even if no product usage charges had accrued - will not be removed when you simply recalculate the existing Bills. You must first manually delete these Bills and then re-run billing to ensure the billing configuration changes are correctly shown on the Account’s Bills.
• Similar to this, if Bills have been created for an Account, you want to adjust the pricing for the product.

Updating a Prepayment/Commitment Fee Billing Schedule

Suppose you’ve set up a schedule for Prepayment billing for an Account and a Bill has already been generated for one of the Prepayment fee dates on that schedule. If you then change the dates for the Prepayment schedule, when you recalculate the existing Bill the Prepayment fee due under the original schedule will still be included. You must first delete the old Bill generated for the original Prepayment fee schedule and then re-run billing. The new Bill will then be generated in accordance with the updated Prepayment schedule.

Important: Scheduled Billing! If you are using Scheduled Billing, please ensure you check for this after updating a Prepayment fee schedule.

Prorated Charges

There are cases where line item charges shown on Bills are prorated. If you see a charge amount on a Bill which you were not expecting or which you find puzzling, this mechanism might be the cause. It’s worth checking for this when you find what at first appears to be an odd billing charge.

Bill Doesn’t Cover Entire Billing Period

If a Bill doesn’t cover the entire billing period, then prorating is applied:

• Billing Charges Start Mid Billing Period. For example, if you’ve set things up to bill an Account on a monthly frequency on the 1st of each month, BUT you’ve set the start and end dates for the Account Plan to fall somewhere within calendar month billing periods - the first and last Bills will apply prorating accordingly:
  • Similarly, if the Account Plan is active for the Account from the first day of the first month and last day of the last month of the overall service period, BUT when you priced the Product Plan you set the start and end dates for the period the pricing applies to the Plan somewhere within the service period.
• First and subsequent Bill dates not set to 1st day of Billing Period. For example, prorating is applied if you’ve set things up to bill an Account on a monthly frequency and the Account Plan is set to start to be active for the Account on the 1st of a month and end on the last day of a month, BUT you’ve set the first and subsequent Bill date somewhere in the middle of the first and successive months. The first Bill will apply prorating to cover the appropriate leading portion of the first billing period.

Usage Data Explorer and Debugging

When you generate a bill and the result isn’t what you expect, you can use the Preview Bill API call with Debug enabled to review information in the response which might help you to figure out what’s going wrong. Here’s an example to follow using Postman:

1. Make the usual preparation for Service User authentication with the platform by generating an Access Key id and Api Secret in the Console - see Generating an API Key and Secret for a Service User.

2. In your Postman workspace, obtain a Bearer Token for the Service User using the Access Key id and Api Secret.

3. If you are unsure of the Account id of the Account for which bill generation has failed, then use your Bearer Token to submit a GET List Accounts call for your Organization:

   https://api.m3ter.com/organizations/396d788d-5174-XyXy-RsRs-a12f3456fc78/accounts

4. Now, submit a POST Preview Bill call for the relevant Account using your Bearer Token and with debug enabled:

   https://api.m3ter.com/organizations/396d788d-5174-4e8b-9d69-a41f4671fc33/bills/preview?debug=true

5. In the debugLog section of the response schema, you can read-off debug INFO.