Understanding Billing Options for Plan Templates/Plans - m3ter Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

When you create and configure Plan Templates and Plans for your Products to prepare for setting up usage-based pricing to charge Accounts that consume your Products, several key billing options are available. These billing options are designed to give you maximum flexibility in controlling the way you want to Bill your customer Accounts. This topic explains in detail the key billing options available for Plan Templates/Plans:

Billing Currency, Pricing Currency, and Currency Conversions

You can select a billing currency at two levels:

Organization level. This defines the currency used for Bills created against Accounts across your Organization.
Individual Account level. You also can set the billing currency at level of an individual Account level and choose to override the Organization-level billing currency for the Account.

However, when you create a Plan Template you must select a currency. Product Plans are always based on a Plan Template and inherit the currency setting of their template. When you price the Plan, this currency is used as the pricing currency.

Why might I want to use a billing currency that’s different to the pricing currency?

Suppose you have end-customer Accounts across many different countries. You might want to always price for product usage by any Account using the same pricing currency. However, you want to generate the Bills for each Account using the appropriate billing currency - the one used in the country where the end-customer lives. For an Account where the pricing currency does not match the required billing currency, billing charges are calculated using the pricing currency and then currency conversion rates are used to convert those charges into the appropriate billing currency amounts. This means you must ensure any required currency conversion rates have been set up for your Organization.

What does this mismatch between billing currency and pricing currency mean for Bills?

If you attach a Plan to an Account and the Plan uses a pricing currency that is different to the billing currency, when a Bill is generated for the Account the line items are first calculated using the Plan pricing currency and then the line item amounts are converted to the selected billing currency:

Billing Currency is Organization-level or Account-level. This process occurs whether you are using the Organization-level billing currency or using an Account billing currency.
Currency Conversions. For this to work, you must first set up currency conversion rates which the billing process can use to convert the Plan pricing currency amounts into the billing currency amounts. See Adding Currency Conversion Rates.

IMPORTANT! If you’re using different pricing and billing currencies and you haven’t defined a conversion rate in your Organization configuration for converting a Plan pricing currency into the selected billing currency, then Bill creation will fail and you’ll receive an error Alert.

Scheduled Billing. Note that for scheduled billing runs, Billing always uses the billing currency that you’ve selected either at Organization level or individual Account level.

Example Bill: Mixed Pricing Currencies vs. Billing Currency

Suppose you are a US based company offering a purified water supply, monitoring, and management service to dental practice groups worldwide. Your general pricing and billing policies are as follows:

Your billing currency is always US Dollars (USD).
Most customers consume two product lines:
- A core product charged by liters of water consumed per billing period and a standing charge per billing period that varies from country to country. These charges are priced in the customer’s local currency.
- An online customer support service charged by number of help inquiries made per billing period. This is priced in US Dollars regardless of the country of origin of the customer.

Reviewing Example Bill in Console

For a monthly billing frequency, here’s an example of Bill generated in the m3ter Console under Bill management for a UK customer where the end-customers are charged in British Pounds (GBP) for the core water consumption product with a £5 monthly standing charge applied:

On review, we can see that the required mixed currency pricing has been accommodated:

For the core WaterGen Standard product:
The Water Usage Charges Usage line item is shown as priced at £1.00 per Liter Unit price according to the priced Plan attached to the Account for the Product. However, using the configured conversion rate for GBP to USD of 1.5 and shown at the bottom of the Bill under Currency conversions, the £1,000 due in this pricing currency has been converted into a billing currency Subtotal of $1,500.
- The Water Usage Charges Standing charge line item is also priced under the same priced Plan attached to the Account. However, since this type of line item doesn’t require any Unit price, the GBP total is not shown on the Bill and the UK rate of £5 shows as the converted $7.50 Subtotal.
For the WaterGen Support product:
The Support Charges Usage line item is shown as priced at $0.50 per Call Unit price according to the priced Plan attached to the Account for the Product because the pricing currency is USD, and the billing currency Subtotal is simply a multiplication of the recorded number of Calls by $0.50 = $550.

Using API to Review Example Bill JSON

If we now use the GET Retrieve Bill API endpoint for this Bill’s id, we can review the response schema JSON to see how the mixed currencies pricing is handled:

First, the Bill details section provides a number of parameters including:
- A "currency" parameter, which gives the billing currency - in this example the value is "USD".
- A "currencyConversions" parameter giving an array listing the conversion rates configured for use in billing for your m3ter Organization:

{
    "id": "5226324a-dcfe-4ff4-a1b0-98766f38ad7d",
    "version": 3,
    "accountId": "32728b36-5822-4568-8731-951762593b3c",
    "accountCode": "water_gen_customer_uk",
    "startDate": "2026-05-01",
    "endDate": "2026-06-01",
    "startDateTimeUTC": "2026-05-01T00:00:00.000Z",
    "endDateTimeUTC": "2026-06-01T00:00:00.000Z",
    "billDate": "2026-06-01",
    "dueDate": "2026-06-08",
    "billingFrequency": "MONTHLY",
    "billFrequencyInterval": 1,
    "timezone": "UTC",
    "currency": "USD",
    "locked": false,
    "createdDate": "2026-06-11T15:31:24.663Z",
    "status": "PENDING",
    "billJobId": "ba5f053e-0f5d-4b08-bf9b-a3cdf5f46e4a",
    "currencyConversions": [
        {
            "from": "GBP",
            "to": "USD",
            "multiplier": 1.5
        },
        {
            "from": "APC",
            "to": "USD",
            "multiplier": 0.5
        },
        {
            "from": "USD",
            "to": "APC",
            "multiplier": 2.0
        },
        {
            "from": "CAD",
            "to": "USD",
            "multiplier": 0.75
        }
    ],
}

In the response, the Bill’s line items are returned in an array:

"lineItems": [...],

The Water Usage Charges USAGE line item shows:
A "currency" parameter, which gives a pricing currency of "GBP" for the line item, and which derives from the Plan template on which the priced Plan attached to the end-customer Account is based.
- A "subtotal" parameter, which gives the total due in the pricing currency of 1,000 "GBP".
- A "conversionRate" parameter of 1.5, which is determined by the conversion rate set under the "currencyConversions" parameter.
- A "convertedSubtotal" parameter, which gives the total due in the billing currency of 1,500 "USD".

{
            "id": "c36960e1-a52f-488b-9ec5-821da30e4949",
            "productId": "773d030e-61c5-4e95-9cb7-a5414ae8bdda",
            "productName": "WaterGen Standard",
            "productCode": "water_gen_standard",
            "accountingProductId": "",
            "accountingProductName": "",
            "accountingProductCode": "",
            "aggregationId": "e0ff067a-6407-4ffd-bfb4-a1bf8250d221",
            "compoundAggregationId": "",
            "group": {},
            "meterId": "6ee668bd-cc89-41d0-b313-8a7aaedadeee",
            "planId": "607cf3ec-eee6-43fd-aa0f-d1da8679a5f6",
            "planGroupId": "",
            "description": "Water Usage Charges",
            "quantity": 1000,
            "units": 1000,
            "unit": "Liters",
            "subtotal": 1000,
            "currency": "GBP",
            "conversionRate": 1.5,
            "convertedSubtotal": 1500,
            "lineItemType": "USAGE",
            "pricingId": "90aac9f0-f336-43f9-a755-dae429f84734",
            "childAccountId": "",
            "childAccountCode": "",
            "usagePerPricingBand": [
                {
                    "pricingBandId": "fb8a56c8-8b54-484d-ae00-61920185a323",
                    "lowerLimit": 0.0,
                    "fixedPrice": 0,
                    "unitSubtotal": 1000,
                    "unitPrice": 1,
                    "bandUnits": 1000,
                    "bandQuantity": 1000,
                    "bandSubtotal": 1000,
                    "convertedBandSubtotal": 1500
                }
            ],
            "servicePeriodStartDate": "2026-05-01T00:00:00.000Z",
            "servicePeriodEndDate": "2026-06-01T00:00:00.000Z",
            "averageUnitPrice": 1,
            "sequenceNumber": 3
        }

Similarly, the Water Usage Charges STANDING_CHARGE line item shows:
A "currency" parameter, which gives a pricing currency of "GBP" for the line item.
- A "subtotal" parameter, which gives the total due in the pricing currency of 5 "GBP".
- A "conversionRate" parameter of "1.5", which is determined by the conversion rate set under the "currencyConversions" parameter.
- A "convertedSubtotal" parameter, which gives the total due in the billing currency of 7.5 "USD".

{
            "id": "9346e0f1-4d8a-4ca5-b8fd-fe7660e3a896",
            "productId": "773d030e-61c5-4e95-9cb7-a5414ae8bdda",
            "productName": "WaterGen Standard",
            "productCode": "water_gen_standard",
            "accountingProductId": "",
            "accountingProductName": "",
            "accountingProductCode": "",
            "aggregationId": "",
            "compoundAggregationId": "",
            "meterId": "",
            "planId": "607cf3ec-eee6-43fd-aa0f-d1da8679a5f6",
            "planGroupId": "",
            "description": "Water Usage Charges",
            "quantity": 1,
            "units": 1,
            "unit": "",
            "subtotal": 5,
            "currency": "GBP",
            "conversionRate": 1.5,
            "convertedSubtotal": 7.5,
            "lineItemType": "STANDING_CHARGE",
            "pricingId": "",
            "childAccountId": "",
            "childAccountCode": "",
            "servicePeriodStartDate": "2026-05-01T00:00:00.000Z",
            "servicePeriodEndDate": "2026-06-01T00:00:00.000Z",
            "averageUnitPrice": 5,
            "sequenceNumber": 1
        }

The Support Charges USAGE line item shows:
A "currency" parameter, which gives a pricing currency of "USD" for the line item, and which derives from the Plan template on which the priced Plan attached to the end-customer Account is based.
- A "subtotal" parameter, which gives the total due in the pricing currency of 550 "USD".
- A "conversionRate" parameter of "1", since in this case the pricing currency for the line item is the same as the billing currency.
- A "convertedSubtotal" parameter, which gives the total due in the billing currency of 550 "USD".

{
            "id": "72543f02-9b3d-4eb2-8043-de827543e3de",
            "productId": "88a719a7-f90d-4074-9e13-e3dfb2d36a11",
            "productName": "WaterGen Support",
            "productCode": "water_gen_support",
            "accountingProductId": "",
            "accountingProductName": "",
            "accountingProductCode": "",
            "aggregationId": "82fc80f2-a9bd-4dfc-ad0f-8a30e60627e5",
            "compoundAggregationId": "",
            "group": {},
            "meterId": "96bd030b-0523-4ae7-b6bc-32bf514e9c36",
            "planId": "dbd987c3-1333-4441-8fba-d2be86e8770d",
            "planGroupId": "",
            "description": "Support Charges",
            "quantity": 1100,
            "units": 1100,
            "unit": "Calls",
            "subtotal": 550,
            "currency": "USD",
            "conversionRate": 1,
            "convertedSubtotal": 550,
            "lineItemType": "USAGE",
            "pricingId": "cd02b224-74b4-4a5f-b2bc-5973e242f5e7",
            "childAccountId": "",
            "childAccountCode": "",
            "usagePerPricingBand": [
                {
                    "pricingBandId": "f161c79c-6800-46c6-9dca-d866831d7e04",
                    "lowerLimit": 0.0,
                    "fixedPrice": 0,
                    "unitSubtotal": 550,
                    "unitPrice": 0.5,
                    "bandUnits": 1100,
                    "bandQuantity": 1100,
                    "bandSubtotal": 550,
                    "convertedBandSubtotal": 550
                }
            ],
            "servicePeriodStartDate": "2026-05-01T00:00:00.000Z",
            "servicePeriodEndDate": "2026-06-01T00:00:00.000Z",
            "averageUnitPrice": 0.5,
            "sequenceNumber": 2
        }

What if I want to use a different billing currency for some of my Accounts and outside of the scheduled billing runs?

You can do this by creating a Bill Job, where you can specify:

The Accounts for which you want their Bills created in a specific currency.
The currency the Bills will use.
Conversion rates for converting Plan currencies to Bill currency.
Conversion rates you’ve defined at Organization level can also be used. If a conversion rate is defined both at Organization level and for the Bill Job, the Bill Job rate is used.

You can use the Create a new Bill Job API call to do this. See the Bill Job section in our API Reference Docs for other calls you can use to create and manage Bill Jobs.

Standing Charge

What is a Billing Standing Charge?

A Standing Charge allows you to set a fixed amount that is charged on Account Bills:

You can define this fixed amount for Plan Templates, Plans, and Plan Groups.

How is the Standing Charge applied for a Plan Group?

If you define a Standing Charge for a Plan Group, which doesn’t have a well-defined billing cycle because the Plans it contains might have different billing dates or frequencies, then if any of the Plans in the Group should be included in the billing run, then the Plan Group Standing Charge amount is included.

Can I control which Bills the Standing Charge is applied to?

Yes. If you don’t want the Standing charge to be applied to every Bill in a series, you can use the settings for Standing charge interval and Standing charge offset to control which Bills in a series of Bills the Standing Charge is applied to:

A Standing charge interval of 3 means the charge is applied to the first Bill and then only to every 3rd Bill following in the billing series:
For example, suppose you have a daily Bill Frequency with Bills issued every day, a First bill date of January 1st, and the Standing charge offset at 0, and with a Standing charge interval set at 3. The Standing charge amount will be applied to the January 1st Bill, the January 4th Bill, the January 7th Bill, and so on. Here’s how the billing series unfolds for an Account that incurs a regular $10 per month usage charge and the Standing charge is set at $47:
If you’ve set the Standing charge interval to 3, you can then use the Standing charge offset to determine which of the Bills in a series the charge is applied to:
- Do you want to apply the Standing charge to the 1st bill, 4th bill, 7th bill and so on? Or, do you want to apply it to the 2nd Bill, 5th Bill, 8th Bill, and so on?
- A Standing charge offset of 0 would mean the charge is applied to the 1st Bill, 4th Bill, 7th Bill and so on; a Standing charge offset of 1 would mean the charge is first applied to the 2nd Bill in the series, so in this case to the 2nd Bill, 5th Bill, 8th Bill, and so on.
- To illustrate we can adapt the current example, and change the Standing charge offset setting to 1. Here’s how the billing series now unfolds with respect to which Bills have the $47 Standing charge applied:

Minimum Spend

A Minimum Spend allows you to define a minimum amount that your customer has agreed to spend for usage charges on each Bill they receive.

Important! Minimum Spend excludes any charges due at billing for Standing Charges or Prepayment/Commitment fees.

You can define a Minimum Spend at three levels:

Plan Template or Plan
Plan Group
Pricing

The way in which the Minimum Spend amount is assessed differs at the three levels:

Plan Template or Plan. All line item charges for usage of the Product are added up. If there is any shortfall against the Minimum Spend amount, this is added as a new line item to the Bill.
Plan Group. Line item charges for usage on all the Products for all the Plans in the Plan Group are considered.
For further details of how Plan Group Minimum Spend amounts are evaluated as against the Minimum Spend amounts defined for the Group’s included Plans, see Plan Group Minimum Spends vs. Plans Minimum Spends.
Pricing. Only the line item for usage charges under that specific Pricing is considered and an extra line item is added to the Bill if needed to make up any shortfall against the Minimum Spend.

For example, you might have a single priced Plan on an Account:

Standing Charge is $20
Minimum Spend defined for usage charges per billing period is $50
For first billing period:
- Calculated usage charges amount to $34.
- Extra line item in the amount of $16 is added to reach Minimum Spend.
- Total Bill 1 = $70
For second billing period:
- Calculated usage charges amount to $54, which exceed Minimum Spend.
- Total Bill 2 = $74

Tip: Minimum Spend with Parent/Child Accounts? Note that a Minimum Spend amount is for the Product as a whole for an end customer Account that consumes the Product. If the customer Account has Child Accounts which have different pricing Plans attached, the Minimum Spend amount you enter for the Parent Account pricing Plan is reckoned at billing against the total usage charges due - for both Child and Parent. For more on billing for Parent/Child Accounts, see Billing Hierarchy Modes for Parent/Child Accounts.

What if I’ve chosen to bill Minimum Spend in advance? How does Minimum Spend work in this case?

When billing in arrears, Minimum Spend constraints can be assessed against usage charges that are known at the time of Bill calculation. When billing in advance, the method for applying a Minimum Spend is as follows:

Since the actual usage charges for a given billing period are not known before the Bill is drawn in advance, for each Bill in a series except for the last Bill, the Minimum Spend is applied. At the time of the next billing, the appropriate adjustment is made in light of the actual usage charges due for the previous billing period.
For example, suppose the Minimum Spend for a priced Plan is set at $50 and no Standing Charges are defined and the Account has no Prepayment/Commitment fees due.
- At the time of the first Bill, and before the actual usage charges due are known for the billing period to come, Minimum Spend is applied and therefore the usage total for Bill 1 = $50
- If at the time of second billing, the actual usage charges due amount to $40, a refund item of $40 would be included in Bill 2 to ensure the customer does not end up paying $90 for usage in the first billing period.
Note that any refund amount is obviously capped at the defined Minimum Spend.

Minimum Spend Billed in Advance - Example

Here’s a worked example to show how billing works when minimum spend is billed in advance:

Suppose you want to bill end-customers for API calls made to your service. You charge a flat rate of $1 per call made. Billing is monthly and there is a minimum spend of $3000 per month billed in advance.
An end-customer signs-up for this deal with you and their service period commences October 1st 2024. Metered API call usage over the following three months is: 500 calls in October; 1000 calls in November; 3500 calls in December. No Standing Charges are defined and the Account has no Prepayment/Commitment fees due.
For this example, the first Bill dated October 1st will show:
- The minimum spend in advance charge for the coming month of October, since this is the first Bill for the service period and no API calls usage has yet been metered for the Account.
The second Bill dated November 1st will show:
- The $500 charge for API calls usage in October, but with a corresponding $500 rebate since the usage in the month did not exceed the minimum billed in advance at the start of the month.
- A minimum spend in advance charge for the coming month of November.
The third Bill dated December 1st will show:
- The $1000 charge for API calls usage in November, but with a corresponding $1000 rebate since the usage in the month did not exceed the minimum billed in advance at the start of the month.
- A minimum spend in advance charge for the coming month of December.
The fourth Bill dated January 1st will show:
- The $3,500 charge for API calls usage in December, but with a $3000 rebate since the usage in the month exceeded the minimum billed in advance at the start of the month.
- A minimum spend in advance charge for the coming month of January.