Create PlanTemplate - m3ter Documentation

Authorizations

Authorization

string

header

required

m3ter supports machine to machine authentication using the clientCredentials OAuth2 flow.

The authorizationCode flow controls access for human users via the m3ter Console application.

Path Parameters

orgId

string

required

UUID of the organization. The Organization represents your company as a direct customer of our service.

Body

application/json

productId

string

required

The unique identifier (UUID) of the Product associated with this PlanTemplate.

Required string length: 36

name

string

required

Descriptive name for the PlanTemplate.

Required string length: 1 - 200

currency

string

required

The ISO currency code for the currency used to charge end users - for example USD, GBP, EUR. This defines the pricing currency and is inherited by any Plans based on the Plan Template.

Notes:

You can define a currency at Organization-level or Account-level to be used as the billing currency. This can be a different currency to that used for the Plan as the pricing currency.
If the billing currency for an Account is different to the pricing currency used by a Plan attached to the Account, you must ensure a currency conversion rate is defined for your Organization to convert the pricing currency into the billing currency at billing, otherwise Bills will fail for the Account.
To define any required currency conversion rates, use the currencyConversions request body parameter for the Update OrganizationConfig call.

Required string length: 3

standingCharge

number<double>

required

The fixed charge (standing charge) applied to customer bills. This charge is prorated and must be a non-negative number.

Required range: x >= 0

billFrequency

enum<string>

required

Determines the frequency at which bills are generated.

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

Available options:

DAILY,

WEEKLY,

MONTHLY,

ANNUALLY,

AD_HOC,

MIXED

version

integer<int64>

The version number of the entity:

Create entity: Not valid for initial insertion of new entity - do not use for Create. On initial Create, version is set at 1 and listed in the response.
Update Entity: On Update, version is required and must match the existing version because a check is performed to ensure sequential versioning is preserved. Version is incremented by 1 and listed in the response.

customFields

object

User defined fields enabling you to attach custom data. The value for a custom field can be either a string or a number.

If customFields can also be defined for this entity at the Organizational level, customField values defined at individual level override values of customFields with the same name defined at Organization level.

See Working with Custom Fields in the m3ter documentation for more information.

standingChargeDescription

string

Standing charge description (displayed on the bill line item).

Maximum string length: 200

standingChargeInterval

integer<int32>

How often the standing charge is applied. For example, if the bill is issued every three months and standingChargeInterval is 2, then the standing charge is applied every six months.

Required range: 1 <= x <= 365

standingChargeOffset

integer<int32>

Defines an offset for when the standing charge is first applied. For example, if the bill is issued every three months and the standingChargeOfset is 0, then the charge is applied to the first bill (at three months); if 1, it would be applied to the second bill (at six months), and so on.

Required range: 0 <= x <= 364

billFrequencyInterval

integer<int32>

How often bills are issued. For example, if billFrequency is Monthly and billFrequencyInterval is 3, bills are issued every three months.

Required range: 1 <= x <= 365

ordinal

integer<int64>

The ranking of the PlanTemplate among your pricing plans. Lower numbers represent more basic plans, while higher numbers represent premium plans. This must be a non-negative integer.

NOTE: DEPRECATED - do not use.

Required range: x >= 0

code

string

A unique, short code reference for the PlanTemplate. This code should not contain control characters or spaces.

Maximum string length: 80

Pattern: ^([^[\p{Cntrl}\s]])|([^[\p{Cntrl}\s]][[^[\p{Cntrl}\s]] ]*[^[\p{Cntrl}\s]])$

minimumSpend

number<double>

The Product minimum spend amount per billing cycle for end customer Accounts on a pricing Plan based on the PlanTemplate. This must be a non-negative number.

Required range: x >= 0

minimumSpendDescription

string

Minimum spend description (displayed on the bill line item).

Maximum string length: 200

standingChargeBillInAdvance

boolean

A boolean that determines when the standing charge is billed.

TRUE - standing charge is billed at the start of each billing period.
FALSE - standing charge is billed at the end of each billing period.

Overrides the setting at Organizational level for standing charge billing in arrears/in advance.

minimumSpendBillInAdvance

boolean

A boolean that determines when the minimum spend is billed.

TRUE - minimum spend is billed at the start of each billing period.
FALSE - minimum spend is billed at the end of each billing period.

Overrides the setting at Organizational level for minimum spend billing in arrears/in advance.

Response

Returns the created PlanTemplate

string

required

The UUID of the entity.

version

integer<int64>

The version number:

Create: On initial Create to insert a new entity, the version is set at 1 in the response.
Update: On successful Update, the version is incremented by 1 in the response.

customFields

object

User defined fields enabling you to attach custom data. The value for a custom field can be either a string or a number.

If customFields can also be defined for this entity at the Organizational level,customField values defined at individual level override values of customFields with the same name defined at Organization level.

See Working with Custom Fields in the m3ter documentation for more information.

productId

string

The unique identifier (UUID) of the Product associated with this PlanTemplate.

name

string

Descriptive name for the PlanTemplate.

currency

string

The ISO currency code for the pricing currency used by Plans based on the Plan Template to define charge rates for Product consumption - for example USD, GBP, EUR.

standingCharge

number<double>

The fixed charge (standing charge) applied to customer bills. This charge is prorated and must be a non-negative number.

standingChargeDescription

string

Standing charge description (displayed on the bill line item).

standingChargeInterval

integer<int32>

How often the standing charge is applied. For example, if the bill is issued every three months and standingChargeInterval is 2, then the standing charge is applied every six months.

standingChargeOffset

integer<int32>

billFrequencyInterval

integer<int32>

How often bills are issued. For example, if billFrequency is Monthly and billFrequencyInterval is 3, bills are issued every three months.

billFrequency

enum<string>

Determines the frequency at which bills are generated.

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

Available options:

DAILY,

WEEKLY,

MONTHLY,

ANNUALLY,

AD_HOC,

MIXED

ordinal

integer<int64>

The ranking of the PlanTemplate among your pricing plans. Lower numbers represent more basic plans, while higher numbers represent premium plans. This must be a non-negative integer.

NOTE: DEPRECATED - no longer used.

code

string

A unique, short code reference for the PlanTemplate. This code should not contain control characters or spaces.

minimumSpend

number<double>

The Product minimum spend amount per billing cycle for end customer Accounts on a pricing Plan based on the PlanTemplate. This must be a non-negative number.

minimumSpendDescription

string

Minimum spend description (displayed on the bill line item).

standingChargeBillInAdvance

boolean

A boolean that determines when the standing charge is billed.

TRUE - standing charge is billed at the start of each billing period.
FALSE - standing charge is billed at the end of each billing period.

Overrides the setting at Organizational level for standing charge billing in arrears/in advance.

minimumSpendBillInAdvance

boolean

A boolean that determines when the minimum spend is billed.

TRUE - minimum spend is billed at the start of each billing period.
FALSE - minimum spend is billed at the end of each billing period.

Overrides the setting at Organizational level for minimum spend billing in arrears/in advance.

dtCreated

string<date-time>

The date and time (in ISO-8601 format) when the PlanTemplate was created.

dtLastModified

string<date-time>

The date and time (in ISO-8601 format) when the PlanTemplate was last modified.

createdBy

string

The unique identifier (UUID) of the user who created this PlanTemplate.

lastModifiedBy

string

The unique identifier (UUID) of the user who last modified this PlanTemplate.