Troubleshooting Bills
If you're experiencing issues when generating bills for an end customer Account, it's well worth running through this troubleshooting checklist of common bill 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 Alerts system in the Console as a starting point to check and remedy any issues which are causing Bills to fail. From your Dashboard, Alerts are listed and you can click View all to open the 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
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 at Settings>Organization on the Overview tab to add and define the required currency conversion rate.
Re-run billing for the Account.
Tip: The mismatch between the billing currency and pricing currency setting might not be explicit. For example, if you have entered "USD" for billing currency for Organization but entered "usd" - that is, in lower case - for Plan Template/Plan pricing currency, this will cause Bills to fail and a "Currency conversion missing" ERROR Alert will be generated. The remedy in this example is to update the Plan pricing currency setting to use upper case: "USD".
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 Price Plan Attached to Account
A Price 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:
Create a Price Plan if you have not already created one.
Attach the Plan to the Account to create an Account Plan.
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 Data Explorer to check if usage date and measures have been submitted against the Account. See the Documentation page: Performing Usage Queries and Reviewing Results.
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 Accounts that have Parent/Child billing hierarchies. If Bills are failing to generate:
Check at which level is the Plan billed?
Is the Account Plan attached to the Parent/Child, or both?
Is the Account 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 First bill date as the Prepayment.
If you have set up billing for Prepayment fees to Bill on a schedule, check the billing schedule frequency is correct. See the Scheduling Billing page in the documentation.
Unexpected Error
If you receive a "Failed to create bill" ERROR on your 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 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 ready.
Billing Dates Issues
There are a couple of areas where billing dates can get out of alignment and cause issues.
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/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 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 Attached Plans tab adjusts to show details of the Plan including an Associated Pricing panel, which shows the pricing you've set up for the Plan - effectively reproducing what's seen in the Pricing Editor.
3. Check the start/end dates for the pricing on the Plan to confirm date alignment between period pricing applies to Plan and period Account is active for the Account..
4. If you want to investigate further, click a View pricing schedule hotlink text in the pricing grid. 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 Bill Date not Aligned
You can set up First bill dates in the first instance at the Organization level when you configure your Epoch settings at Settings>Organization>Edit Organization. However, you can also enter a First bill date at two further points in your overall configuration:
At Account Level. You can optionally set a First bill date for a specific Account and this will override the Epoch settings at Organizational level.
At Account Plan Level. You can optionally set a First bill date for a specific Account Plan that will be used to determine charges on an Account and this will override the First bill 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 bill date that applies for the Account - at Organization, Account, or Account Plan level - is correct. For more details, see First and Subsequent Bill Dates.
Using Preview Bill API Call with Debug Enabled
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.
To make a Preview Bill call with debug enabled in Postman:
1. Make the usual preparation for Service User authentication with the service 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 - see Obtaining a Bearer Token Using Basic Auth.
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
The response will list all of the Accounts in your Organization and you can read-off the Account id you need. See the API Reference for the List Accounts call for more details.
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
In the Body tab, enter the relevant bill data, for example:
1{23"lastDateInBillingPeriod": "2022-06-30",4"accountIds": ["18611463-aa04-46bf-9233-bfdab1fcf082"],5"billingFrequency": "MONTHLY",6"billFrequencyInterval": 178}9
See the API Reference for the Preview Bill call for more details.
5. In the debugLog section of the response schema, you can read-off debug INFO. For example:
1"debugLog": [2"INFO Retrieving billing configuration for account:18611463-aa04-46bf-9233-bfdab1fcf082",3"INFO Getting required bills to generate",4"INFO Will generate bill for date:2022-07-01 interval:1 frequency:MONTHLY",5"INFO Generating bill for account:18611463-aa04-46bf-9233-bfdab1fcf082 date:2022-07-01 interval:1 frequency:MONTHLY",6"INFO Adding standing charge of 25.0 for Plan ee03ac6f-77d1-4ae7-81cd-4e62673b2b0f",7"INFO Retrieving aggregated usage between 2022-06-01T00:00:00Z to 2022-07-01T00:00:00Z for meter code:my_meter1 aggregation:SUM field:gb_store segments:<null> for account codes:[doetech_premium2]",8"INFO No aggregated usage found",9"INFO Processing usage for Plan ee03ac6f-77d1-4ae7-81cd-4e62673b2b0f",10"INFO No product dynamic credits to apply",11"INFO Adding arrears minimum spend adjustment of 1.5E+2 for Plan ee03ac6f-77d1-4ae7-81cd-4e62673b2b0f",12"INFO No global dynamic credits to apply",13"INFO No commitments to consume",14"INFO No commitments to charge fee"15]
In this example, at line 8, we can see that "No aggregated usage found" for the target field on the Meter for the billing time period, all as detailed on line 7. This might the reason the bill amount is not what was expected, which can now be followed-up.
Querying and Checking Bill Data in Data Explorer
Data Explorer is a great tool that let's you query for billing data held for your Organization in m3ter. We strongly urge you to exploit Data Explorer when investigating and chasing down any knottier billing issues you are encountering. You can review your returned billing data in flat Data Tables or use powerful Pivot Tables to sort-and-sift the data to help you find any anomalies that are causing bills to fail or generate in error. For details see Working in the Data Explorer>Performing Billing Queries and Reviewing Results.
Tip: Usage Data Check? In Data Explorer, you can also query for usage data when investigating and check across with the billing data returned.