Skip to main content
PUT
/
organizations
/
{orgId}
/
organizationconfig
Update OrganizationConfig
curl --request PUT \
  --url https://api.m3ter.com/organizations/{orgId}/organizationconfig \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "timezone": "UTC",
  "yearEpoch": "2022-01-01",
  "monthEpoch": "2022-01-01",
  "weekEpoch": "2022-01-04",
  "dayEpoch": "2022-01-01",
  "currency": "USD",
  "daysBeforeBillDue": 1,
  "version": 123,
  "currencyConversions": [
    {
      "from": "EUR",
      "to": "USD",
      "multiplier": 1.12
    }
  ],
  "scheduledBillInterval": 123,
  "standingChargeBillInAdvance": true,
  "commitmentFeeBillInAdvance": true,
  "minimumSpendBillInAdvance": true,
  "scheduledBillOffset": 11,
  "autoApproveBillsGracePeriod": 2,
  "autoApproveBillsGracePeriodUnit": "DAYS",
  "externalInvoiceDate": "LAST_DAY_OF_ARREARS",
  "suppressedEmptyBills": true,
  "consolidateBills": true,
  "defaultStatementDefinitionId": "<string>",
  "creditApplicationOrder": [],
  "allowNegativeBalances": false,
  "allowOverlappingPlans": false,
  "useUnifiedDrawdowns": false,
  "billPrefix": "Bill-",
  "sequenceStartNumber": 1000
}
'
{
  "id": "<string>",
  "version": 123,
  "timezone": "UTC",
  "yearEpoch": "2022-01-01",
  "monthEpoch": "2022-01-01",
  "weekEpoch": "2022-01-04",
  "dayEpoch": "2022-01-01",
  "currency": "<string>",
  "currencyConversions": [
    {
      "from": "EUR",
      "to": "USD",
      "multiplier": 1.12
    }
  ],
  "daysBeforeBillDue": 123,
  "scheduledBillInterval": 123,
  "scheduledBillOffset": 123,
  "standingChargeBillInAdvance": true,
  "commitmentFeeBillInAdvance": true,
  "minimumSpendBillInAdvance": true,
  "autoApproveBillsGracePeriod": 123,
  "suppressedEmptyBills": true,
  "consolidateBills": true,
  "defaultStatementDefinitionId": "<string>",
  "billPrefix": "<string>",
  "sequenceStartNumber": 123,
  "creditApplicationOrder": [],
  "allowNegativeBalances": true,
  "allowOverlappingPlans": true,
  "useUnifiedDrawdowns": true,
  "dtCreated": "2023-11-07T05:31:56Z",
  "dtLastModified": "2023-11-07T05:31:56Z",
  "createdBy": "<string>",
  "lastModifiedBy": "<string>"
}

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 the m3ter service.

Body

application/json
​
timezone
string
default:UTC
required

Sets the timezone for the Organization.

Example:

"UTC"

​
yearEpoch
string
default:2022-01-01
required

Optional setting that defines the billing cycle date for Accounts that are billed yearly. Defines the date of the first Bill and then acts as reference for when subsequent Bills are created for the Account:

  • For example, suppose the Plan you attach to an Account is configured for yearly billing frequency and will apply to the Account from January 1st, 2022 until January 15th, 2028. If you set a yearEpoch date of January 1st, 2023, then the first Bill is created for the Account on that date and subsequent Bills are created for the Account on January 1st of each year following through to the end of the billing service period - January 1st, 2023, January 1st, 2024 and so on.
  • The date is in ISO-8601 format.
Example:

"2022-01-01"

​
monthEpoch
string
default:2022-01-01
required

Optional setting that defines the billing cycle date for Accounts that are billed monthly. Defines the date of the first Bill and then acts as reference for when subsequent Bills are created for the Account:

  • For example, suppose the Plan you attach to an Account is configured for monthly billing frequency and will apply to the Account from January 1st, 2022 until June 30th, 2022. If you set a monthEpoch date of January 15th, 2022, then the first Bill is created for the Account on that date and subsequent Bills are created for the Account on the 15th of each month following through to the end of the billing service period - February 15th, March 15th, and so on.
  • The date is in ISO-8601 format.
Example:

"2022-01-01"

​
weekEpoch
string
default:2022-01-04
required

Optional setting that defines the billing cycle date for Accounts that are billed weekly. Defines the date of the first Bill and then acts as reference for when subsequent Bills are created for the Account:

  • For example, suppose the Plan you attach to an Account is configured for weekly billing frequency and will apply to the Account from January 1st, 2022 until June 30th, 2022. If you set a weekEpoch date of January 15th, 2022, which falls on a Saturday, then the first Bill is created for the Account on that date and subsequent Bills are created for the Account on Saturday of each week following through to the end of the billing service period.
  • The date is in ISO-8601 format.
Example:

"2022-01-04"

​
dayEpoch
string
default:2022-01-01
required

Optional setting that defines the billing cycle date for Accounts that are billed daily. Defines the date of the first Bill:

  • For example, suppose the Plan you attach to an Account is configured for daily billing frequency and will apply to the Account from January 1st, 2022 until June 30th, 2022. If you set a dayEpoch date of January 2nd, 2022, then the first Bill is created for the Account on that date and subsequent Bills are created for the Account each day following through to the end of the billing service period.
  • The date is in ISO-8601 format.
Example:

"2022-01-01"

​
currency
string
default:USD
required

The currency code for the Organization. For example: USD, GBP, or EUR:

  • This defines the billing currency for the Organization. You can override this by selecting a different billing currency at individual Account level.
  • You must first define the currencies you want to use in your Organization. See the Currency section in this API Reference.

Note: If you use a different currency as the pricing currency for Plans to set charge rates for Product consumption by an Account, you must define a currency conversion rate from the pricing currency to the billing currency before you run billing for the Account, otherwise billing will fail. See below for the currencyConversions request parameter.

Minimum string length: 1
Example:

"USD"

​
daysBeforeBillDue
integer<int32>
required

Enter the number of days after the Bill generation date that you want to show on Bills as the due date.

Note: If you define daysBeforeBillDue at individual Account level, this will take precedence over any daysBeforeBillDue setting defined at Organization level.

Required range: x > 0
​
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.
​
currencyConversions
object[]

Define currency conversion rates from pricing currency to billing currency:

  • You can use the currency request parameter with this call to define the billing currency for your Organization - see above.
  • You can also define a billing currency at the individual Account level and this will override the Organization billing currency.
  • A Plan used to set Product consumption charge rates on an Account might use a different pricing currency. At billing, charges are calculated in the pricing currency and then converted into billing currency amounts to appear on Bills. If you haven't defined a currency conversion rate from pricing to billing currency, billing will fail for the Account.
​
scheduledBillInterval
number<double>

Sets the required interval for updating bills. It is an optional parameter that can be set as:

  • For portions of an hour (minutes). Two options: 0.25 (15 minutes) and 0.5 (30 minutes).
  • For full hours. Enter 1 for every hour, 2 for every two hours, and so on. Eight options: 1, 2, 3, 4, 6, 8, 12, or 24.
  • Default. The default is 0, which disables scheduling.
​
standingChargeBillInAdvance
boolean

Boolean setting to specify whether the standing charge is billed in advance at the start of each billing period, or billed in arrears at the end of each billing period.

  • TRUE - bill in advance (start of each billing period).
  • FALSE - bill in arrears (end of each billing period).
​
commitmentFeeBillInAdvance
boolean

Boolean setting to specify whether commitments (prepayments) are billed in advance at the start of each billing period, or billed in arrears at the end of each billing period.

  • TRUE - bill in advance (start of each billing period).
  • FALSE - bill in arrears (end of each billing period).
​
minimumSpendBillInAdvance
boolean

Boolean setting to specify whether minimum spend amounts are billed in advance at the start of each billing period, or billed in arrears at the end of each billing period.

  • TRUE - bill in advance (start of each billing period).
  • FALSE - bill in arrears (end of each billing period).
​
scheduledBillOffset
integer<int32>

Offset (hours) within the scheduled interval to start the run, interpreted in the organization's timezone. For daily (24h) schedules this is the hour of day (0-23). Only supported when ScheduledBillInterval is 24 (daily) at present.

Required range: 0 <= x <= 23
​
autoApproveBillsGracePeriod
integer<int32>

Grace period before bills are auto-approved. Used in combination with autoApproveBillsGracePeriodUnit parameter.

Note: When used in combination with autoApproveBillsGracePeriodUnit enables auto-approval of Bills for Organization, which occurs when the specified time period has elapsed after Bill generation.

Required range: x > 0
Example:

2

​
autoApproveBillsGracePeriodUnit
string

Time unit of grace period before bills are auto-approved. Used in combination with autoApproveBillsGracePeriod parameter. Allowed options are MINUTES, HOURS, or DAYS.

Note: When used in combination with autoApproveBillsGracePeriod enables auto-approval of Bills for Organization, which occurs when the specified time period has elapsed after Bill generation.

Example:

"DAYS"

​
externalInvoiceDate
string

Date to use for the invoice date. Allowed values are FIRST_DAY_OF_NEXT_PERIOD or LAST_DAY_OF_ARREARS.

Example:

"LAST_DAY_OF_ARREARS"

​
suppressedEmptyBills
boolean

Boolean setting that supresses generating bills that have no line items.

  • TRUE - prevents generating bills with no line items.
  • FALSE - bills are still generated even when they have no line items.
Example:

true

​
consolidateBills
boolean

Boolean setting to consolidate different billing frequencies onto the same bill.

  • TRUE - consolidate different billing frequencies onto the same bill.
  • FALSE - bills are not consolidated.
Example:

true

​
defaultStatementDefinitionId
string

Organization level default statementDefinitionId to be used when there is no statement definition linked to the account.

Statement definitions are used to generate bill statements, which are informative backing sheets to invoices.

​
autoGenerateStatementMode
enum<string>

Specify whether to auto-generate statements once Bills are approved or locked. It will not auto-generate if a bill is in pending state.

The default value is None.

  • None. Statements will not be auto-generated.
  • JSON. Statements are auto-generated in JSON format.
  • JSON and CSV. Statements are auto-generated in both JSON and CSV formats.
Available options:
NONE,
JSON,
JSON_AND_CSV
​
creditApplicationOrder
enum<string>[]

Define the order in which any Prepayment or Balance amounts on Accounts are to be drawn-down against for billing. Four options:

  • "PREPAYMENT","BALANCE". Draw-down against Prepayment credit before Balance credit.
  • "BALANCE","PREPAYMENT". Draw-down against Balance credit before Prepayment credit.
  • "PREPAYMENT". Only draw-down against Prepayment credit.
  • "BALANCE". Only draw-down against Balance credit.

NOTES:

  • You can override this Organization-level setting for creditApplicationOrder at the level of an individual Account.
  • If the Account belongs to a Parent/Child Account hierarchy, then the creditApplicationOrder settings are not available, and the draw-down order defaults always to Prepayment then Balance order.
Available options:
PREPAYMENT,
BALANCE
​
allowNegativeBalances
boolean

Allow balance amounts to fall below zero. This feature is enabled on request. Please get in touch with m3ter Support or your m3ter contact if you would like it enabling for your organization(s).

Example:

false

​
allowOverlappingPlans
boolean

Boolean setting to control whether or not multiple plans for the same Product can be active on an Account at the same time:

  • TRUE - multiple overlapping plans for the same product can be attached to the same Account.
  • FALSE - multiple overlapping plans for the same product cannot be attached to the same Account.(Default)
Example:

false

​
useUnifiedDrawdowns
boolean

Use unified drawdowns when applying credits, commitments, and balances to bills.

Example:

false

​
billPrefix
string

Prefix to be used for sequential invoice numbers. This will be combined with the sequenceStartNumber.

NOTES:

  • If you do not define a billPrefix, a default will be used in the Console for the Bill REFERENCE number. This default will concatenate INV- with the last four characters of the billId.
  • If you do not define a billPrefix, the Bill response schema for API calls that retrieve Bill data will not contain a sequentialInvoiceNumber.
Example:

"Bill-"

​
sequenceStartNumber
integer<int32>

The starting number to be used for sequential invoice numbers. This will be combined with the billPrefix.

For example, if you define billPrefix to be INVOICE- and you set the seqenceStartNumber as 100, the first Bill created after updating your Organization Configuration will have a sequentialInvoiceNumber assigned of INVOICE-101. Subsequent Bills created will be numbered in time sequence for their initial creation date/time.

Example:

1000

Response

Return the updated Organization configuration

​
id
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.
​
timezone
string
default:UTC

The timezone for the Organization.

Example:

"UTC"

​
yearEpoch
string
default:2022-01-01

The first bill date (in ISO-8601 format) for yearly billing periods.

Example:

"2022-01-01"

​
monthEpoch
string
default:2022-01-01

The first bill date (in ISO-8601 format) for monthly billing periods.

Example:

"2022-01-01"

​
weekEpoch
string
default:2022-01-04

The first bill date (in ISO-8601 format) for weekly billing periods.

Example:

"2022-01-04"

​
dayEpoch
string
default:2022-01-01

The first bill date (in ISO-8601 format) for daily billing periods.

Example:

"2022-01-01"

​
currency
string

The currency code for the currency used in this Organization. For example: USD, GBP, or EUR.

​
currencyConversions
object[]

Currency conversion rates from Bill currency to Organization currency.

For example, if Account is billed in GBP and Organization is set to USD, Bill line items are calculated in GBP and then converted to USD using the defined rate.

​
daysBeforeBillDue
integer<int32>

The number of days after the Bill generation date shown on Bills as the due date.

​
scheduledBillInterval
number<double>

Specifies the required interval for updating bills.

  • For portions of an hour (minutes). Two options: 0.25 (15 minutes) and 0.5 (30 minutes).
  • For full hours. Eight possible values: 1, 2, 3, 4, 6, 8, 12, or 24.
  • Default. The default is 0, which disables scheduling.
​
scheduledBillOffset
integer<int32>

Offset (hours) within the scheduled interval to run the job, interpreted in the organization's timezone. For daily (24h) schedules this is the hour of day (0-23). Only supported when ScheduledBillInterval is 24 (daily) at present.

​
standingChargeBillInAdvance
boolean

Specifies whether the standing charge is billed in advance at the start of each billing period, or billed in arrears at the end of each billing period.

  • TRUE - bill in advance (start of each billing period).
  • FALSE - bill in arrears (end of each billing period).
​
commitmentFeeBillInAdvance
boolean

Specifies whether commitments (prepayments) are billed in advance at the start of each billing period, or billed in arrears at the end of each billing period.

  • TRUE - bill in advance (start of each billing period).
  • FALSE - bill in arrears (end of each billing period).
​
minimumSpendBillInAdvance
boolean

Specifies whether minimum spend amounts are billed in advance at the start of each billing period, or billed in arrears at the end of each billing period.

  • TRUE - bill in advance (start of each billing period).
  • FALSE - bill in arrears (end of each billing period).
​
autoApproveBillsGracePeriod
integer<int32>

Grace period before bills are auto-approved. Used in combination with the field autoApproveBillsGracePeriodUnit.

​
autoApproveBillsGracePeriodUnit
enum<string>
Available options:
MINUTES,
HOURS,
DAYS
​
externalInvoiceDate
enum<string>
Available options:
LAST_DAY_OF_ARREARS,
FIRST_DAY_OF_NEXT_PERIOD
​
suppressedEmptyBills
boolean

Specifies whether to supress generating bills that have no line items.

  • TRUE - prevents generating bills with no line items.
  • FALSE - bills are still generated even when they have no line items.
​
consolidateBills
boolean

Specifies whether to consolidate different billing frequencies onto the same bill.

  • TRUE - consolidate different billing frequencies onto the same bill.
  • FALSE - bills are not consolidated.
​
defaultStatementDefinitionId
string

Organization level default statementDefinitionId to be used when there is no statement definition linked to the account.

Statement definitions are used to generate bill statements, which are informative backing sheets to invoices.

​
billPrefix
string

Prefix to be used for sequential invoice numbers. This will be combined with the sequenceStartNumber.

​
sequenceStartNumber
integer<int32>

The starting number to be used for sequential invoice numbers. This will be combined with the billPrefix.

​
autoGenerateStatementMode
enum<string>

Specifies whether to auto-generate statements once Bills are approved or locked. It will not auto-generate if a bill is in pending state.

The default value is None.

  • None. Statements will not be auto-generated.
  • JSON. Statements are auto-generated in JSON format.
  • JSON and CSV. Statements are auto-generated in both JSON and CSV formats.
Available options:
NONE,
JSON,
JSON_AND_CSV
​
creditApplicationOrder
enum<string>[]

The order in which any Prepayment or Balance credit amounts on Accounts are to be drawn-down against for billing. Four options:

  • "PREPAYMENT","BALANCE". Draw-down against Prepayment credit before Balance credit.
  • "BALANCE","PREPAYMENT". Draw-down against Balance credit before Prepayment credit.
  • "PREPAYMENT". Only draw-down against Prepayment credit.
  • "BALANCE". Only draw-down against Balance credit.
Available options:
PREPAYMENT,
BALANCE
​
allowNegativeBalances
boolean

Allow balance amounts to fall below zero. This feature is enabled on request. Please get in touch with m3ter Support or your m3ter contact if you would like it enabling for your organization(s).

​
allowOverlappingPlans
boolean

Allows plans to overlap time periods for different contracts.

​
useUnifiedDrawdowns
boolean

Use unified drawdowns when applying credits, commitments, and balances to bills.

​
dtCreated
string<date-time>

The DateTime when the organization config was created (in ISO-8601 format).

​
dtLastModified
string<date-time>

The DateTime when the organization config was last modified (in ISO-8601 format).

​
createdBy
string

The id of the user who created this organization config.

​
lastModifiedBy
string

The id of the user who last modified this organization config.