• Home
/
• Working in m3ter - User Guides
/
• Getting Started

Dates in m3ter - Quick Reference Starter

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

• Setting your Timezone

• Dates for Billing and Pricing

• Dates for Usage Data

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.

Setting your Timezone

Timezone is a baseline setting for dates in your Organization.

In the Console, you can change your Timezone by going to Settings>Organization and on the Configuration tab, select Edit on the Organization Configuration Details panel:

• 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 enter, for example, Europe/Berlin.

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

See also: Managing your Organization

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

• First and Subsequent Bill Creation Dates

• First Bill Dates for Prepayments/Commitments

• Dates for Pricing

• End Dates for Billing are Exclusive

• Billing In Arrears/In Advance

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. See the next section on how to define billing start dates.

Alternatively, you can use billFrequency request parameter for the Create PlanTemplate API call to set billing frequency.

See also: Reviewing Options for Plans and Plan Templates

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. Note that you can also use a Billing interval setting on your Plans to control when subsequent bills are generated. If Billing frequency is monthly and you've set Billing interval at 3, bills are generated every three months.

In m3ter, we use the concept of Epoch dates for billing periods: Year, Month, Week, and Day. These Epoch settings define the date when the first Bill is created for Accounts and then act as a reference for when in the applied billing frequency period subsequent bills for Accounts are created:

• For example, suppose you attach a Plan to an Account where the Plan is configured for monthly billing frequency and you've defined the period the Plan will apply to the Account to be from January 1st, 2022 until January 1st, 2023. You then set a Month Epoch date of February 15th, 2022. The first Bill will be created for the Account on February 15th, and subsequent Bills created on the 15th of the months following for the remainder of the billing period - March 15th, April 15th, and so on.

• The defaults are:

  • Year Epoch. January 1st, 2022.

  • Month Epoch. January 1st, 2022.

  • Week Epoch. January 4th, 2022.

  • Day Epoch. January 1st, 2022.

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.

However, having set up your dates for Epochs at the Organization level, you can override these dates at two points when completing your configuration for billing against an end-customer Account:

• When you create an Account, you can use a Billing cycle date setting to override the Epoch settings:

  • Account Billing cycle date. Optional attribute, which allows you to set the date of first and subsequent billing against the end customer Account. For example, if the Plan you attach to the Account for charging is configured for monthly billing frequency and you set a Billing cycle date at the Account level of January 14th 2022, then m3ter will create a first bill for the Account on that date and every month from that date. If you leave this blank then the start of billing defaults to the Epoch setting you've configured for your Organization.

• When you attach a Plan to an Account and create an Account Plan, you can use a Billing cycle date setting to override the Account-level setting:

  • Account Plan Billing cycle date. Optional attribute, which allows you to set the date of first and subsequent billing against the end customer Account using the Account Plan. Subsequent billing will be determined from this first date. For example, if the Plan is configured for monthly billing frequency and you set a Billing cycle date of February 14th 2022, then m3ter will create a first bill for the Account on that date and every month from that date. If you leave this blank, then the start of billing defaults to the first bill date configured for the Account. Note that if you leave this setting at the Account Plan level blank and the Billing cycle date setting was left blank at the Account level, then start of billing defaults to the Epoch settings you've configured for your Organization.

API Calls:

• You can use the yearEpoch, monthEpoch, weekEpoch, and dayEpoch request parameters for the Update OrganizationConfig API call to set your Organization Epoch dates.

• You can use the billEpoch request parameter for the Create Account API call to set the first and subsequent bill dates at the Account level.

• You can use the billEpoch request parameter for the Create AccountPlan API call to set the first and subsequent bill dates at the Account Plan level.

See also: Managing your Organization, Creating an Account, Attaching Plans to an Account.

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 both cases, you can define the first and subsequent bill dates.

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

1. Select Bill with plan.

2. Use the optional Billing cycle date to set a date when line items for the Prepayment fees will first appear on a Bill. The dates of all future Bills for Prepayment fees will be calculated from this initial date. If you leave this blank, then the start of billing for Prepayments fees defaults to the Epoch setting you've configured for your Organization.

Bill on a Schedule - Set First Bill Date

1. Select Bill on a schedule.

2. Use the Add button to define the details of the first Bill in the schedule for Prepayment fees due.

3. Enter a Date for the first Bill.

4. Select Add again to define the second and subsequent Bills with Dates for the Prepayment fees.

See also: Creating Prepayments for Accounts.

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.

• Note that you can also apply pricing to Plan Templates.

What if you have an end-customer Account that will consume one of your Products and you want to charge them at a reduced rate - as a sign-up bonus - for the first six months and then bump them up to the standard rate afterwards? You can attach a priced Product Plan to their Account and:

• Configure a Pricing for the Plan that applies for the first six months at the reduced rate.

• Configure a second Pricing that applies to the Plan after six months.

This allows you to set, for example, a year period for your customer to be on the Product Plan, which you set up when you set the Start and End dates for the Account Plan to be active for their Account, but ensures the standard rate will cut in for billing the Account at six months in - you won't have to attach a priced Plan to the Account twice to do this!

Alternatively, you can define the period a Pricing applies to a Plan using the startDate and endDate request parameters for the Create Pricing API call.

End Dates for Billing are Exclusive

You must define start and end dates in contexts related to billing on your end-customer Accounts, such as:

• When you attach a Plan to an Account to create an Account Plan, you enter start and end dates to define the period you want the Plan to be active for the Account - that is, to define the period when the Account will be charged according to the pricing configured for the Plan for consuming one of your products.

• When you create a Prepayment amount for an Account, you enter start and end dates to define the period the Prepayment is active for the Account - that is, what is the period of contract for consuming one of your products and for which the Account customer is committed to paying the Prepayment amount.

Start dates are treated inclusively but end dates are treated exclusively in m3ter. What does this mean when setting up your billing periods? Note that with respect to end dates:

• If you set the end date for an Account Plan to be June 1st 2022, then the Account Plan ceases to be active for the Account at midnight on May 31st 2022, and any billing is calculated up to that point in time, NOT up to midnight on June 1st. If you want to include for billing for customer Account usage occurring on June 1st, you have to set the end date as June 2nd.

• Similarly, if your set the end date for a Prepayment on an Account to be February 1st 2022, this means the contract period for the Prepayment, and the period for calculation of any fees due on that Prepayment ceases at midnight on January 31st 2022.

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.

You can set this up in the first instance at the level of your Organization. In the Console, go to Settings>Organization and on the Configuration tab select Edit on the Organization Configuration Details panel:

• Standing charge billing. Default is to bill in arrears.

• Minimum spend billing. Default is to bill in arrears.

• Prepayment fee billing. Default is to bill in advance.

You can override this Organization-level setting for two of these - standard charge and minimum spend billing - when you create your Plan Templates and Plans:

• Plan Templates. When you create a Plan Template in the Console at Pricing>Plan Templates>Create Plan Template, by default the Standing charge billing setting is selected to Use organization-wide configuration and which is shown in brackets:

  • You can select to override the Organization setting for Standing charge billing - Bill in arrears or Bill in advance.

  • You can do the same for Minimum spend billing.

• Plans. When you create a Plan from a Plan Templates in the Console at Pricing>Plans>Create Plan, by default the Standing charge billing setting is selected to Use configuration from plan template and which is shown in brackets:

  • You can select to override the Plan Template setting for Standing charge billing - Bill in arrears or Bill in advance.

  • You can do the same for Minimum spend billing.

Alternatively, you can use API calls to set this at the level of Plan Template or Plan:

• Plan Template. You can use the standingchargeBillInAdvance or minimumSpendBillInAdvance request parameters for the Create PlanTemplate API call.

• Plan. You can use the standingchargeBillInAdvance or minimumSpendBillInAdvance request parameters for the Create Plan API call.

You can also override the Organizational-level setting for minimum spend billing when you price a Plan Template or Plan:

• In the Console, go to Pricing>Pricing Editor, add a Plan or Plan Template and an Aggregation. Select Edit Pricing. By default, the Minimum spend billing setting is checked to Use organization-wide configuration and which is shown in brackets:

  • You can select to override the Organization setting for Minimum spend billing - Bill in arrears or Bill in advance.

Alternatively, you can use the minimumSpendBillInAdvance request parameter for the Create Pricing API call to set this when you price a Plan Template or Plan.

Lastly, when you create or edit a Prepayment for an Account and you've set up outstanding amounts to Bill with plan, you can override the Organizational-level setting for Prepayment fee billing:

• In the Console, go to Accounts and open the Account details page and select the Prepayments tab.

• Select Create Prepayment or edit an existing Prepayment for the Account. By default, the Fee billing setting is checked to Use organization-wide configuration and which is shown in brackets:

  • You can override this and select to have Fee billing for the Prepayment to Bill in arrears or Bill in advance.

Alternatively, you can use the commitmentFeeBillInAdvance request parameter for the Create Commitment or Update Commitment API call to set Fee billing for the Prepayment in arrears or in advance.

See also: Managing your Organization, Creating Plan Templates, Creating Plans, or Creating Prepayments for Accounts.

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.

In the Console, you can perform data submission from the Account or from Meter details pages. When you do this, a Timestamp field is automatically populated with the current date/time. You can edit this field and enter your own past date/time value for the usage data submission:

• The data item is ingested immediately into m3ter.

• The date/time value you enter determines billing for the submitted usage.

• The date/time value you enter for the submission is used for the usage data item in the Usage Data Explorer - when you query for usage data, the date/time value you've entered for the submission is shown for Meter Data Fields and is the value that can be filtered on. If the Meter also has Derived Fields whose value is derivative on the Meter Data Fields, the custom date/time value you enter for the submission is applied to any such Derived Fields also.

Adjusting the Timestamp to use date/time values in the past for submitted usage data is useful if you need to make corrections for billing retrospectively against an Account - you can submit positive or negative usage data amounts to correct and reconcile earlier billing anomalies.

Alternatively, you can use the ts request parameter for the Submit Measurements Ingest API call to change the timestamp value for usage data items.

Next: Knowledge Index

Additional Support