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

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 .

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 Overview tab>Organization Configuration panel, select Edit Configuration:

  • 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

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 an Epoch to denote billing periods. In the first instance, you can set up first bill dates for each billing period using the Epoch settings for your Organization.

  • Go to Settings>Organization and on the Overview tab>Organization Configuration panel, select Edit Configuration. Set the start date for each Epoch:

    • Year Epoch

    • Month Epoch

    • Week Epoch

    • Day Epoch

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

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

    • Account First bill date. Optional attribute, which allows you to set the date of first 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 First bill 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 First bill date setting to override the Account-level setting:

    • Account Plan First bill date. Optional attribute, which allows you to set the date of first 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 First bill 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 First bill date setting was left blank at the Account level, then start of billing defaults to the Epoch settings you've configured for your Organization.

Important - Billing period spans successive months for defined First Bill date! If you set the First Bill date for an Account to fall somewhere mid-month, then the billing period for calculating any pro-rated charges will span that date on successive months. For example, if you set First Bill date at May 15th, then the first billing period is April 15th to May 15th, and the number of days in that period will vary depending on the successive months the period spans. For more details, see First Bill Date Not Set to 1st of Month.

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 bill date at the Account level.

  • You can use the billEpoch request parameter for the Create AccountPlan API call to set the first bill date 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 customer has not paid the Prepayment amount in full upfront at the start of their contract with you, 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 bill date.

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 First bill 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.

Tip; Using API Call? Alternatively, you can use the billEpoch request parameter for the Create Commitment API call to set the first bill date for Prepayment fees.

Bill on a Schedule - Set First Bill Date

1. Select Bill on a schedule.

2. Use the Add button to define the details if 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, 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 do this for a Plan Template.

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.

Tip: Pricing periods should not overlap! If you try to overlap periods for a Pricing to apply to the same Plan, you'll see an error. You can introduce gaps in a Pricing applied to a Plan.

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 how standing charge, minimum spend, and Prepayment fee amounts configured for billing will be charged - 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 Overview tab>Organization Configuration panel, select Edit Configuration:

  • 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 checked to use the Organization-level setting. You can uncheck this and then use a switch to select to bill this amount in arrears or in advance.

    • You can do the same to override the Minimum spend billing setting.

  • 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 checked to use the Plan Template setting. You can uncheck this and then use a switch to select to bill this amount in arrears or in advance.

    • You can do the same to override the Minimum spend billing setting.

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 charge billing setting is checked to use the Organization-level setting. You can uncheck this and then use a switch to select to bill this amount in arrears or 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, you can also override the Organizational-level setting for minimum spend billing when you create or edit a Prepayment for an Account:

  • In the Console, go to Accounts and open the Account details page. Select to Create prepayment or edit an existing Prepayment for the Account. By default, the Fee billing setting is checked to use the Organizational-level setting. You can uncheck this and use a switch to have Fee billing for the Prepayment applied in arrears or 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 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.

Important! If you edit the Timestamp value, you must enter a date/time that is in the past. If you try to submit usage date for a future date/time, the submission will be rejected and you'll receive an error message.

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

See also: Submitting Usage Data for an Account and Submitting Test Usage Data.

Next: Knowledge Index



Additional Support

Login to the Support portal for additional help and to send questions to our Support team.