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 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 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. First select Settings:
The Organization page opens with the Configuration tab selected:
Under Organization configuration details, select Edit.
Scroll down the Edit page and add the required Currency conversions and the Update Organization configuration.
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 data and measures have been submitted against the Account. See Performing Usage Queries and Reviewing Results for more details.
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.
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 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 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:
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.
The Associated pricing panel shows the pricing applied to the Plan and shows the Start and End dates defining the period the Pricing applies to the Plan.
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 Plan is active for the Account.
4. If you want to investigate further, click the calendar icon 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 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 2023.
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 2024:
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 2024:
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
Suppose 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 the recalculated Bills:
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.
In a similar way, if Bills have been created for an Account, you want adjust the pricing for the product. To do this, you swap out the Account Plan for a product your end-customer consumes by removing the original Account Plan attached to the Account and replacing it with a new one. To ensure Bills created for the original billing configuration are updated, you must first manually delete those existing Bills and then re-run billing.
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, a Bill that might also includes usage charges for priced Plans attached to the Account. 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 first and last calendar month of the overall service period.
Similarly, for other billing frequencies - weekly or yearly.
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, and the last Bill will apply prorating to cover the appropriate trailing portion of the last billing period of the overall service period.
Similarly, for other billing frequencies - weekly or yearly.
Here are some examples to illustrate:
Billing Charges Start Mid-Billing Period
Suppose we've set up an Account to be billed using a priced Product Plan we've attached to the Account where the Plan is set up for:
Monthly billing frequency billed on the 1st of each month.
A Standing Charge of $20.
A Minimum Spend amount of $40.
However, when we attached the Plan to create an Account Plan, we select a start date for the Account Plan to become active for the Account that falls somewhere within the first monthly billing period. This means on the first Bill, the Standing Charge and Minimum Spend amounts will be prorated for the number of days of the first month's billing period the Account Plan was active for the Account:
In this example, we've attached the Plan to create an Account Plan that becomes active on May 25th 2023 for the Account. Suppose that as yet no usage charges have accrued since we attached the Plan and we now run a Bill for June 1st 2023:
We can see that prorating is applied for the non-usage charges to bill only 7-day's worth each of the 31-day month of May for the $20 Standing Charge and $40 Minimum Spend.
A similar prorating occurs if we set the end date for when the Account Plan ceases to be active for the Account on a date that falls somewhere within the final billing period:
To adapt this example, suppose we'd set the end date for the Account Plan at May 25th 2024. The final Bill for June 1st 2024, would then prorate the $20 Standing Charge and $40 Minimum spend amounts accordingly. Remembering that end dates are exclusive, the final Bill shows 24-day's worth of the 31-day month of May for these charges:
First and Subsequent Bill Date Not Set to 1st of Month
If you set the first and subsequent Bill creation date for an Account to fall somewhere mid-month, then the billing period for calculating any prorated charges will span that date on successive months. For example with a monthly billing frequency, if you set first and subsequent Bill date at May 15th, then the first billing period is April 15th to May 15th, and it's important to note that the number of days in that period will vary depending on the successive months the period spans.
Suppose we've set up an Account to be billed using a priced Product Plan we've attached to the Account where the Plan is set up for:
Monthly billing frequency.
A Standing Charge of $20.
A Minimum Spend amount of $40.
The Account Plan is active for billing the Account from the first day of the first month until the last day of the last month - for our example, an overall period of May 1st 2023 until May 31st 2024:
However, we've set the Billing cycle date for the Account at May 15th 2023:
Suppose as yet no usage charges have accrued on the Account and we run billing for the first bill date:
Since we've set the Billing cycle date as May 15th, the billing period is determined as the 30-day period April 15th 2023 to May 15th 2023. We can see that prorating is applied for the non-usage charges to bill only 14-day's worth each of this 30-day period for the $20 Standing Charge and $40 Minimum Spend.
A similar prorating occurs for the final Bill for this example, when we again assume no usage charges have accrued and we run billing for June 15th 2024 - only 17-day's worth each of the 31-day billing period from May 15th 2024 to June 14th 2024 for the $20 Standing Charge and $40 Minimum Spend:
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 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 - 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 Data Explorers>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.
Next: Integrations
Additional Support
Login to the Support portal for additional help and to send questions to our Support team.