working with dates in m3ter easy reference

Settings for Dates in M3ter

Settings for dates are required in several functional contexts in m3ter. This topic provides a quick reference starter on how dates are handled in m3ter, such as when configuring dates for your billing operations:

Date/Time Fields - Format

Date/time fields are required to be in ISO-8601 format:

For example, the ts field used for the timestamp when you use the Submit Measurements API to make a usage data measurement ingest into the platform needs to be in ISO-8601 format.

Tip: More on ISO-8601? If you would like to learn more about the background and history of this standardized format, we suggest this resource as a starting point: ISO 8601.

Organization Timezone

Timezone is a baseline setting for dates in your Organization and it’s important to understand how the timezone setting affects date/time settings you select.

Setting your Timezone

The default timezone for a m3ter Organization is UTC. You can quickly change this setting in the Console:

Select Settings:
Select Edit on the Organization configuration details panel. On the Organization configuration page scroll down to the Timezone setting:
Timezone. Enter the timezone for your Organization. You can use any format that is valid under Release 2021c of the tz database (tzdata). For example:
If you want to set your timezone by a UTC offset of plus one hour, you can enter UTC+1:00.
- If you want to set your timezone to GMT plus one hour, you can enter GMT+1:00 or GMT+1 or +1:00 or simply +1.
- If you want to set your timezone to a regional timezone by tz database name, you can select from the drop-down list, for example, Europe/Berlin.

Tip! Alternatively, you can use the timezone request parameter for the Update OrganizationConfig API call to set your Timezone.

Dates for Billing and Pricing

Your m3ter setup for controlling when and how bills for an end-customer account are created involves several key aspects:

Billing Frequency

Billing frequency means how often bills are generated - every day, week, month, and so on. You can set Billing frequency when you create Plan Templates for your Products. Each Plan will be based on a Plan Template and will inherit the billing frequency setting. You’ll then be able to attach a Plan to an end-customer Account, and go on to price the attached Plan to define the billing charge rates against the Account for consuming your Products. In the Console, go to Pricing>Plan Templates>Create Plan Template and for Bill frequency there are four options:

Daily. Starting at midnight each day, covering a twenty-four hour period following.
Weekly. Starting at midnight on a Monday morning covering the seven-day period following.
Monthly. Starting at midnight on the morning of the first day of each month covering the entire calendar month following.
Annually. Starting at midnight on the morning of the first day of each year covering the entire calendar year following.

Note that when the repeat cycle of bill creation - weekly, monthly, and so on - starts depends on the date you have defined as the start date for each of these billing frequency options.

First and Subsequent Bill Creation Dates

Linked to billing frequency are settings that define when bills are generated for the first time. When first billing dates are set, dates for subsequent bills depend on the billing frequency you’ve selected. For example, in a simple case where you are using a monthly billing frequency and set a first bill date of January 1st, subsequent bills will be created on the 1st of each month following throughout the billing period.

In m3ter, we use the concept of Epoch dates for billing periods: Year, Month, Week, and Day.

To define the Epoch dates for billing periods, go to Settings>Organization and on the Configuration tab, select Edit on the Organization Configuration Details panel and set the Epoch dates.

First Bill Dates for Prepayments/Commitments

You can create Prepayments/Commitments amounts for your end-customer Accounts. If your end-customer hasn’t paid the Prepayment amount in full upfront at the start of their contract, you can use billing options to control how the outstanding Prepayment fees are to be billed against the Account. You can do this in two ways:

Bill with a Plan
Bill on a Schedule

In the Console, go to Accounts and open the Account. On the Prepayments tab, select Create Prepayment. If the Amount pre-paid is less than the Amount, then the Billing options are enabled.

Bill with Plan - Set First Bill Date

Select Bill with plan.
Use the optional Billing cycle date to set a date when line items for the Prepayment fees will first appear on a Bill.

Bill on a Schedule - Set First Bill Date

Select Bill on a schedule.
Use the Add button to define the details of the first Bill in the schedule for Prepayment fees due.
Enter a Date for the first Bill.

Dates for Pricing

In the Console Pricing Editor, you can add a Plan for a Product, add an Aggregation or a Counter, and then create a Pricing for the Plan:

You must enter a Start date and can optionally enter an End date.
Start/End dates define the period you want the Pricing you’ve configured to apply to the Plan.

End Dates for Billing are Exclusive

You must define start and end dates in contexts related to billing on your end-customer Accounts.

Billing In Arrears/In Advance

Related to dates for billing, you can define when standing charge, minimum spend, and Prepayment fee amounts will be billed - either in arrears or in advance.

Dates for Usage Data

When you have completed your usage-based pricing and billing setup in m3ter, you can submit some test usage data for an Account. This allows you to then calculate bills on the basis of the data you’ve submitted and check everything is working as you expect it to before switching to your production environment.