Working with Bill Statements
You can create Statements to accompany the Bills you send out to your end customers as backing sheets to their invoices. Bill Statements can provide a useful and welcome breakdown of the usage responsible for the usage charge line items your customers see on their invoices:
Create Statement Definitions to specify the way billed usage will be aggregated and compiled in the Statement. For example, if you are billing customers monthly, you might want to breakdown the usage responsible for the monthly charge on a Bill into weekly portions in Bill statements.
At Organization level select a default Statement Definition. See Viewing and Editing Organization Configuration.
At Account level:
Select a Statement Definition, which will override the Organization default.
Select to auto-generate Statements when Bills are approved or locked.
When viewing a Bill, generate Statements manually.
When Statements have been generated for a Bill, download them in JSON and CSV format, which you can then transpose and compile into the required delivery format.
Check if a Bill Statement needs refreshing by comparing the Bill calculation timestamp against the Statement's last modified date, which is available in the response to a get Statement API call
This topic explains how to create Statement Definitions, how to set up default Statements, and how to generate Statements for a Bill and download them in your preferred format.
Creating Statement Definitions
When you create and configure a Statement Definition, you can define how the usage data collected by a Meter for a billing period, and on which usage charges are based, is broken down for customers who will receive a statement with their invoices:
One common use case is to provide a breakdown by time period. For example, if you bill and issue invoices on a monthly frequency, then you might want to provide a weekly or daily charge breakdown statement as a backing sheet to invoices so that customers can see how their usage was distributed across the billing period.
Another use case would be to provide a breakdown on the basis of location of usage charged for. For example, a text messaging service imposes a usage charge per billing period for all messages logged that originate from outside of a customer's native country. This usage is measured for the billing charge as a single block of total recorded usage, which results in a single usage charge line item for "other country" usage in customer invoices. But if the Meter collecting that usage is set up to also record a location for message events by country of origin, you can set up a Statement Definition that provides the required breakdown by the Meter's location dimension.
To create and configure a Statement Definition:
1. Select Billing>Statement Definitions. The Statement Definitions page opens and list any existing Statement Definitions.
2. Select Create Statement Definition. The Create page opens.
3. Enter a Name for the Statement Definition.
4. Use the drop-down to select an Aggregation frequency.
5. Use the switch to enable Include price per unit. Default is disabled.
6. Under Measures, use the drop-down to select a Meter that collects the usage data used as the basis of the usage charges for billing. The Measure drop-down selection field is activated for the selected Meter.
7. Use the Measure drop-down to select a Meter measure Data Field which is aggregated into unit price rates and used as the basis for usage charges at billing.
8. Use the Aggregation functions drop-down list to select the way you want to aggregate the selected Meter Data Field values for statements. Seven options:
Sum. Adds the values
Minimum. Uses the minimum value.
Maximum. Uses the maximum value.
Count. Counts the number of values
Latest. Uses the most recent value.
Mean. Uses the arithmetic mean of the values.
Unique. Lists each of the unique values.
9. Under Dimensions, use the drop-down to select a Meter that collects the usage data as the basis of the usage charges on Bills. The Dimension drop-down is activated for the selected Meter.
10. Use the Dimension drop-down to select the Meter Dimension you want to use as the basis of the Statement's breakdown of usage.
11. If you want to filter the selected Dimension values which will appear on the Statement, under Filter, choose the Selected values radio button. The Filter values field is activated.
12. Enter any values you want to filter the Statement breakdown by - only the Dimension values you enter will be used:
In this example, the Statement Definition uses:
A single numeric Messages measure on a Meter, which collects usage data on the number of messages and on which billing usage charges are based.
A single non-numeric Origin Country dimension on a Meter and on which a breakdown of charges will be based. No filtering of values is enabled.
13. If you want to use other Meter Measures and Dimensions for your Statement Definition, select Add under Measures or Dimensions and repeat steps 6 to 12.
14. Click Create Statement Definition. The new Statement Definition Details page opens:
Using Statement Definitions
When you've set up a Statement Definition, you can select it as the one used to generate Statements for Bills:
Select it as the default at the Organization level. See Viewing and Editing Organization Configuration.
Select it to be used for a particular Account as one of the Account settings.
These options act in the following way:
If you set a default Statement Definition at the Organizational level, this is used when you generate Bill Statements for any Accounts for which you haven't selected a Statement Definition.
If you set a Statement Definition for an individual Account, this will be used when you generate Bill Statements for the Account and takes precedence over any Statement Definition you've selected at Organization level.
To set up default Bill Statements:
1. Create the Statement Definition you want to set as the default at Organization level or the one you want set as the default for a particular Account level. See the previous section.
2. To define a default Statement Definition at Organization level, select Settings>Organization. The Organization page opens with the Configuration tab selected.
3. On the Organization Configuration Details panel, select Edit. The Organization Configuration page opens.
4. Scroll down the page and under Bill Statements, use the Statement definition drop-down to select the Statement Definition you want to set as the default.
5. Select Update Organization Configuration. You are returned to the Organization page and the selected Statement Definition is shown on the Organization Configuration panel as the Default Statement Definition.
Note that you can select the hotlink name text of the Statement Definition to open its details page directly.
6. If you want to override the Statement Definition you've set as the default at Organization level for a particular Account, open the Edit page for the Account.
7. Scroll down the page and on the Bill Statements panel, use the Statement definition drop-down to select the Statement Definition you want to use for the Account.
8. Select Update Account.
Generating Statements for Bills and Downloading
When you open and view a Bill for an Account under Bill Management, you can manually generate a Statement:
The Statement generated will use the Statement Definition you've set as the default at Organization level or the Statement Definition you applied to the Account - if you've defined a default at Account level, this will take precedence.
You can choose to generate the Statement in JSON format only or both JSON and CSV format.
When the Statement has been generated for the Bill, you can download the Statement in JSON or CSV format, if you selected CSV format when generating the Statement.
To generate Statements for Bills and Download:
1. Open the Bill you want to generate a Statement for in Bill Management:
In this example, we've opened a manually calculated interim Bill showing the charges for a single day for an Account that uses the Statement Definition we created in the previous section called Message Location Statement:
We can see that the day's charge is for a total of 6,100 messages, but this is shown as a single line item.
The generated Statement should show a breakdown into separate countries of message origin.
2. At top-right, select the Statements drop-down menu and select Generate statements. A Generate statements pop-up appears, which shows two options:
Generate JSON statement. This is selected by default and you cannot de-select.
Generate CSV statement. By default this is de-selected - use the switch to select it if you want the statement to be generated in CSV format also.
Important: Statement Definition default must be selected! If you haven't selected a default Statement Definition for Bills at either Organization or Account level, then the Generate statements option will not be available and an advisory help text will show to remind you. See above section Using Statement Definitions.
3. Make your statement selection on the pop-up and select Generate. This will kick-off the job to generate Statements for the Bill, which might take a few minutes. Note that if you want to monitor progress, you can click the Running Tasks button at top-right and open the Running Tasks panel:
Warning: Statements not generated? If you haven't set a Statement Definition to be used for Bill Statements at either the Organizational level or at Account level, then the Statements job will not start and you will not see the job registered as a Running Task.
4. When the Statement job has completed, select the Statements drop-down menu again. This now gives you options to Download JSON (always) or Download CSV (if you selected to generate CSV format):
5. Select which format you want to download. The statement is downloaded and saved locally to your Downloads folder.
6. You can now open the statement in the 3rd-party application of your choice and transpose and compile it as required for issuing to your customers as a charge breakdown backing sheet to their invoice.
For the current example using the Messaging Location Statement as Statement Definition for the example Bill showing a day's usage, we've generated and downloaded the Statement in CSV format and loaded it into a spreadsheet:
We can see that the Bill statement shows the breakdown on the basis of location of message origin using the Meter dimension field Origin Country (orig_country), and in accordance with the Statement Definition we set up and applied to the billed Account.
Enabling Auto-Generation for Statements
You can enable auto-generation of Bill Statements for Accounts whenever a Bill is approved or locked:
At Organization level.
At individual Account level.
These alternatives work together in the following way:
If you make a selection for auto-generation of Bill Statements at Organization level but do not select for this at the individual Account level, the Organizational level setting is applied.
If you make a selection for auto-generation of Bill Statements at the individual Account level, this selection will apply to the individual Account, regardless of the selection for this made at the Organizational level.
To enable auto-generation of Bill Statements when Bills are approved or locked :
1. Either:
At Settings>Organization, on the Configuration tab select Edit Configuration. The Organization Configuration page opens.
Open the Account you want to enable auto-generation of Bill statements for and select Edit. The Edit page opens.
2. Scroll down the page and on the Bill statements panel, use the radio buttons to enable Auto-generate statements:
None. Statements will not be auto-generated.
JSON. Statements will be auto-generated in JSON format.
JSON and CSV. Statements will be auto-generated in both JSON and CSV format.
Tip: Make no Selection? Note that the default is to have auto-generation of Bill Statements disabled and none of the three radio buttons will be selected when you open to edit. If you make no selection, Statements will not be auto-generated.
3. Select Update Organization Configuration or Update Account.
Checking a Statement's Last Modified Date
You can obtain the last modified date for a Bill Statement using API calls. This is useful if you want to check whether or not the Statement needs regenerating by comparing the last modified date/time with the Bill's timestamp.
To obtain a Statement's last modified date:
1. First, obtain the id of the Bill whose Statement you want to check the last modified date/time for.
2. Use this id to make one of the available Retrieve Bill Statement API calls:
3. The response to either call returns a pre-signed URL, which you can use to download the Statement file in either JSON or CSV format with a GET call using the URL. For example:
GET https://m3ter-billing-statements-16yxyxyxyxy-eu-west-2.s3.eu-west-2.amazonaws.com/0a5ec4d1-3300-4e2e-975d-16b3009fbf4e/89b234c3-bbb7-4179...
The response to this call includes a Last-Modified header, where you can read off the date and time.
Next: Bill Line Item Types
Additional Support
Login to the Support portal for additional help and to send questions to our Support team.