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.

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
{   
2
3
"lastDateInBillingPeriod": "2022-06-30",
4
"accountIds": ["18611463-aa04-46bf-9233-bfdab1fcf082"],
5
"billingFrequency": "MONTHLY",
6
"billFrequencyInterval": 1
7
8
}
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.

Next: Working with Custom Fields