Sign in

v10

latestOpenAPI 3.0.1raw.githubusercontent.com2025-12-033223581.2 MB
PlanTemplate

Create PlanTemplate

Create a new PlanTemplate.

This endpoint creates a new PlanTemplate within a specific Organization, identified by its unique UUID. The request body should contain the necessary information for the new PlanTemplate.

post/organizations/{orgId}/plantemplates

Path parameters

orgIdstring required

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

Request body

versioninteger

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.
customFieldsobject

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.

productIdstring required

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

namestring required

Descriptive name for the PlanTemplate.

currencystring 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.
standingChargenumber double required

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

standingChargeDescriptionstring

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

standingChargeIntervalinteger

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.

standingChargeOffsetinteger

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.

billFrequencyIntervalinteger

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

billFrequency'DAILY' | 'WEEKLY' | 'MONTHLY' | 'ANNUALLY' | 'AD_HOC' | 'MIXED' required

Defines how often Bills are generated.

  • 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.

  • Ad_Hoc. Use this setting when a custom billing schedule is used for billing an Account, such as for billing of Prepayment/Commitment fees using a custom billing schedule.

ordinalinteger

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.

codestring

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

minimumSpendnumber 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.

minimumSpendDescriptionstring

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

standingChargeBillInAdvanceboolean

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.

minimumSpendBillInAdvanceboolean

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.

Example request

{
  "version": null,
  "customFields": [],
  "productId": "string",
  "name": "string",
  "currency": "USD",
  "standingCharge": 0,
  "standingChargeDescription": "string",
  "standingChargeInterval": 1,
  "standingChargeOffset": 364,
  "billFrequencyInterval": 1,
  "billFrequency": "DAILY",
  "ordinal": 0,
  "code": "string",
  "minimumSpend": 0,
  "minimumSpendDescription": "string",
  "standingChargeBillInAdvance": true,
  "minimumSpendBillInAdvance": true
}

Response

Returns the created PlanTemplate

idstring required

The UUID of the entity.

versioninteger

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.
customFieldsobject

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.

productIdstring

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

namestring

Descriptive name for the PlanTemplate.

currencystring

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.

standingChargenumber double

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

standingChargeDescriptionstring

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

standingChargeIntervalinteger

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.

standingChargeOffsetinteger

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.

billFrequencyIntervalinteger

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

billFrequency'DAILY' | 'WEEKLY' | 'MONTHLY' | 'ANNUALLY' | 'AD_HOC' | 'MIXED'

Defines how often Bills are generated.

  • 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.

  • Ad_Hoc. Use this setting when a custom billing schedule is used for billing an Account, such as for billing of Prepayment/Commitment fees using a custom billing schedule.

ordinalinteger

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.

codestring

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

minimumSpendnumber 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.

minimumSpendDescriptionstring

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

standingChargeBillInAdvanceboolean

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.

minimumSpendBillInAdvanceboolean

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.

dtCreatedstring date-time

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

dtLastModifiedstring date-time

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

createdBystring

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

lastModifiedBystring

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

Example response

{
  "id": "string",
  "version": 1,
  "customFields": {
    "example1": 123,
    "example2": "string"
  },
  "productId": "string",
  "name": "string",
  "currency": "USD",
  "standingCharge": 0,
  "standingChargeDescription": "string",
  "standingChargeInterval": 1,
  "standingChargeOffset": 364,
  "billFrequencyInterval": 1,
  "billFrequency": "DAILY",
  "ordinal": 0,
  "code": "string",
  "minimumSpend": 0,
  "minimumSpendDescription": "string",
  "standingChargeBillInAdvance": true,
  "minimumSpendBillInAdvance": false
}