openapi: 3.0.1 info: title: m3ter Account Balances API description: "If you are using Postman, you can:\n- Use the **Download** button above to download the m3ter Open API spec JSON file and then import this file as the **m3ter API Collection** into your Workspace. See [Importing the m3ter Open API](https://www.m3ter.com/docs/guides/m3ter-apis/getting-started-with-api-calls#importing-the-m3ter-open-api) in our main user Documentation for details.\n- Copy this link: [m3ter-Template API Collection](https://www.datocms-assets.com/78893/1672846767-m3ter-template-api-collection-postman_collection.json) and use it to import the **m3ter-Template API Collection** into your Workspace. See [Importing the m3ter Template API Collection](https://www.m3ter.com/docs/guides/m3ter-apis/getting-started-with-api-calls#importing-the-m3ter-template-api-collection) in our main user Documentation for details.\n\n---\n\n# Introduction\nThe m3ter platform supports two HTTP-based REST APIs returning JSON encoded responses:\n- The **Ingest API**, which you can use for submitting raw data measurements. *(See the [Submit Measurements](https://www.m3ter.com/docs/api#tag/Measurements/operation/SubmitMeasurements) endpoint in this API Reference.)*\n- The **Config API**, which you can use for configuration and management. *(All other endpoints in this API Reference.)* \n\n## Authentication and Authorization\nOur APIs use an industry-standard authorization protocol known as the OAuth 2.0 specification.\n\nOAuth2 supports several grant types, each designed for a specific use case. m3ter uses the following two grant types:\n - **Authorization Code**: Used for human login access via the m3ter Console.\n - **Client Credentials**: Used for machine-to-machine communication and API access.\n\nComplete the following flow for API access:\n\n1. **Create a Service User and add Permissions**: Log in to the m3ter Console, go to **Settings**, **Access** then **Service Users** tab, and create a Service User. To enable API calls, grant the user **Administrator** permissions. \n \n2. **Generate Access Keys**: In the Console, open the *Overview* page for the Service User by clicking on the name. Generate an **Access Key id** and **Api Secret**. Make sure you copy the **Api Secret** because it is only visible at the time of creation. \n\nSee [Service Authentication](https://www.m3ter.com/docs/guides/authenticating-with-the-platform/service-authentication) for detailed instructions and an example.\n\n3. **Obtain a Bearer Token using Basic Auth**: We implement the OAuth 2.0 Client Credentials Grant authentication flow for Service User Authentication. Submit a request to the m3ter OAuth Client Credentials authentication flow, using your concatenated **Access Key id** and **Api Secret** to obtain a Bearer Token for your Service User. *See examples below.* \n \n4. **Bearer Token Usage**: Use the HTTP 'Authorization' header with the bearer token to authorise all subsequent API requests. \n\n> Warning: The Bearer Token is valid for 18,000 seconds or 5 hours. When the token has expired, you must obtain a new one.\n\nBelow are two examples for obtaining a Bearer Token using Basic Auth: the first in cURL and the second as a Python script. \n\n### cURL Example\n1. Open your terminal or command prompt. \n2. Use the following `cURL` command to obtain a Bearer Token:\n\n```bash\ncurl -X POST https://api.m3ter.com/oauth/token \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -u your_access_key_id:your_api_secret \\\n -d 'grant_type=client_credentials'\n```\n\nReplace `your_access_key_id` and `your_api_secret` with your actual **Access Key id** and **Api Secret**.\n\n3. Run the command, and if successful, it will return a JSON response containing the Bearer Token. The response will look like this:\n\n```json\n{\n \"access_token\": \"your_bearer_token\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 18000\n}\n```\n\nYou can then use the Bearer Token *(the value of `\"access_token\"`)* for subsequent API calls to m3ter.\n\n### Python Example\n1. Install the `requests` library if you haven't already:\n\n```bash\npip install requests\n```\n\n2. Use the following Python script to obtain a Bearer Token:\n\n```python\nimport requests\nimport base64\n\n# Replace these with your Access Key id and Api Secret\naccess_key_id = 'your_access_key_id'\napi_secret = 'your_api_secret'\n\n# Encode the Access Key id and Api Secret in base64 format\ncredentials = base64.b64encode(f'{access_key_id}:{api_secret}'.encode('utf-8')).decode('utf-8')\n\n# Set the m3ter token endpoint URL\ntoken_url = 'https://api.m3ter.com/oauth/token'\n\n# Set the headers for the request\nheaders = {\n 'Authorization': f'Basic {credentials}',\n 'Content-Type': 'application/x-www-form-urlencoded'\n}\n\n# Set the payload for the request\npayload = {\n 'grant_type': 'client_credentials'\n}\n\n# Send the request to obtain the Bearer Token\nresponse = requests.post(token_url, headers=headers, data=payload)\n\n# Check if the request was successful\nif response.status_code == 200:\n # Extract the Bearer Token from the response\n bearer_token = response.json()['access_token']\n print(f'Bearer Token: {bearer_token}')\nelse:\n print(f'Error: {response.status_code} - {response.text}')\n```\n\nReplace `your_access_key_id` and `your_api_secret` with your actual **Access Key id** and **Api Secret**. \n\n3. Run the script, and if successful, it will print the Bearer Token. You can then use this Bearer Token for subsequent API calls to m3ter.\n\n## Submitting Personally Identifiable Information (PII)\n**IMPORTANT!** Under the [Data Processing Agreement](https://www.m3ter.com/docs/legal/dpa), the only fields permissible for use in submitting any of your end-customer PII data in m3ter are the ``name``, ``address``, and ``emailAddress`` fields on the **Account** entity - see the details for [Create Account](https://www.m3ter.com/docs/api#operation/PostAccount). See also section 4.2 of the [Terms of Service](https://www.m3ter.com/docs/legal/terms-of-service).\n\n## Rate and Payload Limits\n### Config API Request Rate Limits\nSee [Config API Limits](https://www.m3ter.com/docs/guides/m3ter-apis/config-api-limits).\n\n### Data Explorer API Request Rate Limits\nSee [Data Explorer Request Rate Limits](https://www.m3ter.com/docs/guides/m3ter-apis/config-api-limits#date-explorer-request-rate-limits).\n\n### Ingest API Request Rate and Payload Limits\nSee [Ingest API Limits](https://www.m3ter.com/docs/guides/m3ter-apis/ingest-api-limits) for more information.\n\n## Pagination\n**List Endpoints**\nAPI endpoints that have a List resources request support cursor-based pagination - for example, the `List Accounts` request. These List calls support pagination by taking the two parameters `pageSize` and `nextToken`. \n\nThe response of a List API call is a single page list. If the `nextToken` parameter is not supplied, the first page returned contains the newest objects chronologically. Specify a `nextToken` to retrieve the page of older objects that occur immediately after the last object on the previous page.\n\nUse `pageSize` to limit the list results per page, typically this allows up to a maximum of 100 or 200 per page.\n\n**Search Endpoints**\nAPI endpoints that have a Search resources request support cursor-based pagination - for example, the `Search Accounts` request. These Search calls support pagination by taking the two parameters `pageSize` and `fromDocument`.\n\nThe response of a Search API call is a single page list. If the `fromDocument` parameter is not supplied, the first page returned contains the newest objects chronologically. Specify a `fromDocument` to retrieve the page of older objects that occur immediately after the last object on the previous page.\n\nUse `pageSize` to limit the list results per page, typically this allows up to a maximum of 100 or 200 per page. Default is 10.\n\n## API Quick Start\nSee [Getting Started with API Calls](https://www.m3ter.com/docs/guides/m3ter-apis/getting-started-with-api-calls) for detailed guidance on how to use our API to:\n* Create a Service User and add permissions.\n* Generate access keys for the Service User.\n* Use basic authentication to obtain a Bearer Token.\n\nFor further guidance, also see [Creating and Configuring Service Users](https://www.m3ter.com/docs/guides/organization-and-access-management/managing-users/creating-and-configuring-service-users).\n\n## Other Languages\nIf you want to work with the m3ter REST APIs using other languages such as:\n* Python\n* JavaScript\n* C++\n\nPlease see the [Developer Tools](https://www.m3ter.com/docs/guides/developer-tools) topic in our main documentation for information about available SDKs.\n\n\n# Authentication\n" version: '1.0' x-logo: url: https://console.m3ter.com/m3ter-logo-black.svg servers: - url: https://api.m3ter.com security: - OAuth2: [] tags: - name: Balances description: "Endpoints for creating/retrieving/updating/deleting Balances on Accounts.\n\nWhen you have created a Balance for an Account, you can create a positive or negative Transaction amounts for the Balance. To do this, you must first define Transaction Types for your Organization, and then use one of these Transaction Types when you add a specific Transaction to a Balance - see the [Create TransactionType](https://www.m3ter.com/docs/api#tag/TransactionType/operation/CreateTransactionType) call in the Transaction Type section in this API Reference for more details.\n\nBalances are typically used when a customer prepays an amount to add a credit to their Account, which can then be draw-down against charges due for product or service consumption. You can include options to top-up the original Balance.\n\nExamples of how Balances for end customer Accounts can be used:\n\n* Onboarding Balance/Free Trials. Offering an onboarding incentive to new customers as an initial free credit Balance on their Account. \n\n* Balance as initial commitment. Add a Balance amount to a new customer Account. This acts as an initial commitment, which allows them to use the service and gain an accurate insight into their usage level. \n\n* Managing Customer Satisfaction. Use Balance as credits that will be applied to subsequent Bills as compensation for acknowledged service delivery issues.\n\n* Facilitating Balance Adjustments:\n\t* Apply negative amounts to immediately write-off outstanding Balances.\n\n#### What is the difference between Balances and Commitments/Prepayments?\n\nTo manage credit amounts for your end-customer Accounts, you can use Balances or Commitments/Prepayments. However, these two kinds of credits for Accounts serve different purposes.\n\nCommitments - also referred to as Prepayments - are used for amounts end-customers have agreed to pay for consuming your product or services across a full contract term. A customer might pay the entire or only part of the agreed amount upfront, but ***the commitment or prepayment amount is payable regardless of the actual usage by the customer of your service or product.***\n\nIn contrast, a Balance - often referred to as a Top-Up or Prepaid draw-down - is used when a customer wants to add a credit amount to their Account at any time during the service period or when you as service provider want to add a credit to a customer Account. This Balance credit can then be drawn-down against for billing the Account for usage, minimum spend, standing charges, or recurring charges due. Balances therefore serve payment use cases in a more flexible way, for example to be used for a \"Free Credit\" sign-up scheme you offer to encourage sales or to enhance customer satisfaction by adding credit to an Account to compensate for service delivery issues.\n\nYou can use Commitments/Prepayments and Balances together on Account, and define at Organization or individual Account level the order in which any Balance/Commitment credit on an Account is drawn-down - Balance amounts first or Commitment/Prepayment amounts first. \n" paths: /organizations/{orgId}/balances/{balanceId}/transactions: get: tags: - Balances summary: List Transactions description: 'Retrieve all Transactions for a specific Balance. This endpoint returns a list of all Transactions associated with a specific Balance. You can paginate through the Transactions by using the `pageSize` and `nextToken` parameters.' operationId: ListBalanceTransactions parameters: - name: orgId in: path description: The unique identifier (UUID) for your Organization. The Organization represents your company as a direct customer of our service. required: true style: simple explode: false schema: type: string deprecated: true x-stainless-deprecation-message: the org id should be set at the client level instead - name: balanceId in: path description: The unique identifier (UUID) for the Balance whose Transactions you want to retrieve. required: true style: simple explode: false schema: type: string - name: pageSize in: query description: The maximum number of transactions to return per page. required: false allowEmptyValue: true style: form explode: true schema: maximum: 200 minimum: 1 type: integer format: int32 - name: nextToken in: query description: '`nextToken` for multi page retrievals. A token for retrieving the next page of transactions. You''ll get this from the response to your request. ' required: false allowEmptyValue: true style: form explode: true schema: type: string - name: transactionTypeId in: query description: '' required: false style: form explode: true schema: type: string nullable: true - name: entityType in: query description: '' required: false style: form explode: true schema: nullable: true allOf: - $ref: '#/components/schemas/EntityType' - name: entityId in: query description: '' required: false style: form explode: true schema: type: string nullable: true responses: '200': description: Returns the list of Balance Transactions content: application/json: schema: $ref: '#/components/schemas/PaginatedBalanceTransactionResponseData' 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/Error' post: tags: - Balances summary: Create Balance Transaction description: 'Add a Transaction to a Balance. This endpoint allows you to create a new Transaction amount for a Balance. This amount then becomes available at billing for draw-down to cover charges due. The Transaction details should be provided in the request body. Before you can add a Transaction amount, you must first set up Transaction Types at the Organization Level - see the [Transaction Type](https://www.m3ter.com/docs/api#tag/TransactionType) section in this API Reference for more details. You can then use this call to add an instance of a Transaction Type to a Balance. **Note:** If you have a customer whose payment is in a different currency to the Balance currency, you can use the `paid` and `paidCurrency` request parameters to record the amount paid and alternative currency respectively. For example, you might add a Transaction amount of 200 USD to a Balance on a customer Account where the customer actually paid you 50 units in virtual currency X.' operationId: PostBalanceTransaction parameters: - name: orgId in: path description: The unique identifier (UUID) for your Organization. The Organization represents your company as a direct customer of our service. required: true style: simple explode: false schema: type: string deprecated: true x-stainless-deprecation-message: the org id should be set at the client level instead - name: balanceId in: path description: The unique identifier (UUID) for the Balance to which you want to add a transaction. required: true style: simple explode: false schema: type: string requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/BalanceTransactionRequest' required: true responses: '200': description: Returns the created Balance transaction content: application/json: schema: $ref: '#/components/schemas/BalanceTransactionResponse' 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/Error' /organizations/{orgId}/balances/{balanceId}/transactions/summary: get: tags: - Balances summary: Get Balance Transactions Summary description: 'Retrieves the Balance Transactions Summary for a given Balance. The response contains useful recorded and calculated Transaction amounts created for a Balance during the time it is active for the Account, including amounts relevant to any rollover amount configured for a Balance: * `totalCreditAmount`. The sum of all credits amounts created for the Balance. * `totalDebitAmount`. The sum of all debit amounts created for the Balance. * `initialCreditAmount`. The initial credit amount created for the Balance. * `expiredBalanceAmount`. The amount of the Balance remaining at the time the Balance expires and which is not included in any configured Rollover amount. For example, suppose a Balance reaches its end date and $1000 credit remains unused. If the Balance is configured to rollover $800, then the `expiredBalanceAmount` is calculated as $1000 - $800 = $200. * `rolloverConsumed`. The sum of debits made against the configured rollover amount. Note that this amount is dynamic relative to when the API call is made until either the rollover end date is reached or the cap configured for the rollover amount is reached, after which it will be unchanged. If no rollover is configured for a Balance, then this is ignored. * `balanceConsumed`. The sum of debits made against the Balance. Note that this amount is dynamic relative to when the API call is made until either the Balance end date is reached or the available Balance amount reaches zero, after which it will be unchanged. ' operationId: GetBalanceTransactionsSummary parameters: - name: orgId in: path description: UUID of the organization required: true style: simple explode: false schema: type: string deprecated: true x-stainless-deprecation-message: the org id should be set at the client level instead - name: balanceId in: path description: The UUID of the Balance required: true style: simple explode: false schema: type: string responses: '200': description: Summary of all Balance Transactions content: application/json: schema: $ref: '#/components/schemas/BalanceTransactionsSummary' 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/Error' /organizations/{orgId}/balances: get: tags: - Balances summary: List Balances description: 'Retrieve a list of all Balances for your Organization. This endpoint returns a list of all Balances associated with your organization. You can filter the Balances by the end customer''s Account UUID and end dates, and paginate through them using the `pageSize` and `nextToken` parameters. **NOTE:** If a Balance has a rollover amount configured and you want to use the `endDateStart` or `endDateEnd` query parameters, the `rolloverEndDate` is used as the end date for the Balance.' operationId: ListBalances parameters: - name: orgId in: path description: 'The unique identifier (UUID) for your organization. The Organization represents your company as a direct customer of our service. ' required: true style: simple explode: false schema: type: string deprecated: true x-stainless-deprecation-message: the org id should be set at the client level instead - name: pageSize in: query description: The maximum number of Balances to return per page. required: false allowEmptyValue: true style: form explode: true schema: maximum: 100 minimum: 1 type: integer format: int32 - name: nextToken in: query description: The `nextToken` for retrieving the next page of Balances. It is used to fetch the next page of Balances in a paginated list. required: false allowEmptyValue: true style: form explode: true schema: type: string - name: accountId in: query description: The unique identifier (UUID) for the end customer's account. required: false allowEmptyValue: true style: form explode: true schema: type: string - name: endDateStart in: query description: Only include Balances with end dates equal to or later than this date. If a Balance has a rollover amount configured, then the `rolloverEndDate` will be used as the end date. required: false allowEmptyValue: true style: form explode: true schema: type: string - name: endDateEnd in: query description: Only include Balances with end dates earlier than this date. If a Balance has a rollover amount configured, then the `rolloverEndDate` will be used as the end date. required: false allowEmptyValue: true style: form explode: true schema: type: string - name: contract in: query description: '' required: false allowEmptyValue: true style: form explode: true schema: type: string - name: contractId in: query description: Filter Balances by contract id. Use '' with accountId to fetch unlinked balances. required: false allowEmptyValue: true style: form explode: true schema: type: string - name: ids in: query description: A list of unique identifiers (UUIDs) for specific Balances to retrieve. required: false allowEmptyValue: true style: form explode: true schema: type: array items: type: string responses: '200': description: Returns list of Balances content: application/json: schema: $ref: '#/components/schemas/PaginatedBalanceResponseData' 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/Error' post: tags: - Balances summary: Create Balance description: "Create a new Balance for the given end customer Account. \n\nThis endpoint allows you to create a new Balance for a specific end customer Account. The Balance details should be provided in the request body." operationId: PostBalance parameters: - name: orgId in: path description: The unique identifier (UUID) for your Organization. The Organization represents your company as a direct customer of our service. required: true style: simple explode: false schema: type: string deprecated: true x-stainless-deprecation-message: the org id should be set at the client level instead requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/BalanceRequest' required: true responses: '200': description: Returns the created Balance content: application/json: schema: $ref: '#/components/schemas/BalanceResponse' 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/Error' /organizations/{orgId}/balances/{id}: get: tags: - Balances summary: Retrieve Balance description: 'Retrieve a specific Balance. This endpoint returns the details of the specified Balance.' operationId: GetBalance parameters: - name: orgId in: path description: The unique identifier (UUID) for your Organization. The Organization represents your company as a direct customer of our service. required: true style: simple explode: false schema: type: string deprecated: true x-stainless-deprecation-message: the org id should be set at the client level instead - name: id in: path description: The unique identifier (UUID) of the Balance to retrieve. required: true style: simple explode: false schema: type: string responses: '200': description: Returns the Balance content: application/json: schema: $ref: '#/components/schemas/BalanceResponse' 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/Error' put: tags: - Balances summary: Update Balance description: 'Update a specific Balance. This endpoint allows you to update the details of a specific Balance. The updated Balance details should be provided in the request body.' operationId: PutBalance parameters: - name: orgId in: path description: The unique identifier (UUID) for your Organization. The Organization represents your company as a direct customer of our service. required: true style: simple explode: false schema: type: string deprecated: true x-stainless-deprecation-message: the org id should be set at the client level instead - name: id in: path description: The unique identifier (UUID) of the Balance to update. required: true style: simple explode: false schema: type: string requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/BalanceRequest' required: true responses: '200': description: Returns the updated Balance content: application/json: schema: $ref: '#/components/schemas/BalanceResponse' 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/Error' delete: tags: - Balances summary: Delete Balance description: 'Delete a specific Balance. This endpoint allows you to delete a specific Balance with the given UUID.' operationId: DeleteBalance parameters: - name: orgId in: path description: The unique identifier (UUID) for your Organization. The Organization represents your company as a direct customer of our service. required: true style: simple explode: false schema: type: string deprecated: true x-stainless-deprecation-message: the org id should be set at the client level instead - name: id in: path description: The unique identifier (UUID) of the Balance to delete. required: true style: simple explode: false schema: type: string responses: '200': description: Returns the deleted Balance content: application/json: schema: $ref: '#/components/schemas/BalanceResponse' 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/Error' components: schemas: EntityType: type: string description: '' enum: - BILL - COMMITMENT - USER - SERVICE_USER - SCHEDULER PaginatedBalanceTransactionResponseData: type: object properties: data: type: array description: '' items: $ref: '#/components/schemas/BalanceTransactionResponse' nextToken: type: string description: '' description: '' BalanceRequest: type: object description: '' allOf: - $ref: '#/components/schemas/AbstractRequestWithCustomFields' - $ref: '#/components/schemas/AbstractRequest' - required: - accountId - code - currency - endDate - name - startDate properties: code: maxLength: 80 minLength: 1 pattern: ^([^[\p{Cntrl}\s]])|([^[\p{Cntrl}\s]][[^[\p{Cntrl}\s]] ]*[^[\p{Cntrl}\s]])$ type: string description: Unique short code for the Balance. name: minLength: 1 type: string description: 'The official name for the Balance. ' description: type: string description: A description of the Balance. accountId: minLength: 1 type: string description: The unique identifier (UUID) for the end customer Account. startDate: type: string description: The date *(in ISO 8601 format)* when the Balance becomes active. format: date-time endDate: type: string description: 'The date *(in ISO 8601 format)* after which the Balance will no longer be active for the Account. **Note:** You can use the `rolloverEndDate` request parameter to define an extended grace period for continued draw-down against the Balance if any amount remains when the specified `endDate` is reached.' format: date-time currency: minLength: 1 type: string description: 'The currency code used for the Balance amount. For example: USD, GBP or EUR. ' rolloverAmount: minimum: 0 type: number description: 'The maximum amount that can be carried over past the Balance end date for draw-down at billing if there is any unused Balance amount when the end date is reached. Works with `rolloverEndDate` to define the amount and duration of a Balance "grace period". *(Optional)* **Notes:** - If you leave `rolloverAmount` empty and only enter a `rolloverEndDate`, any amount left over after the Balance end date is reached will be drawn-down against up to the specified `rolloverEndDate`. - You must enter a `rolloverEndDate`. If you only enter a `rolloverAmount` without entering a `rolloverEndDate`, you''ll receive an error when trying to create or update the Balance. - If you don''t want to grant any grace period for outstanding Balance amounts, then do not use `rolloverAmount` and `rolloverEndDate`. ' rolloverEndDate: type: string description: 'The end date *(in ISO 8601 format)* for the grace period during which unused Balance amounts can be carried over and drawn-down against at billing. **Note:** Use `rolloverAmount` if you want to specify a maximum amount that can be carried over and made available for draw-down.' format: date-time balanceDrawDownDescription: maxLength: 200 type: string description: 'A description for the bill line items for draw-down charges against the Balance. *(Optional).* ' overageSurchargePercent: type: number description: Define a surcharge level, as a percentage of regular usage rating, applied to overages *(usage charges that exceed the Balance amount)*. For example, if the regular usage rate is $10 per unit of usage consumed and `overageSurchargePercent` is set at 10%, then any usage charged above the original Balance amount is charged at $11 per unit of usage. format: double overageDescription: maxLength: 200 type: string description: A description for Bill line items overage charges. productIds: type: array description: 'Specify the Products whose consumption charges due at billing can be drawn-down against the Balance amount. **Note:** If you don''t specify any Products for Balance draw-down, by default the consumption charges for any Product the Account consumes will be drawn-down against the Balance amount.' items: type: string lineItemTypes: type: array description: 'Specify the line item charge types that can draw-down at billing against the Balance amount. Options are: - `"MINIMUM_SPEND"` - `"STANDING_CHARGE"` - `"USAGE"` - `"COUNTER_RUNNING_TOTAL_CHARGE"` - `"COUNTER_ADJUSTMENT_DEBIT"` - `AD_HOC` **NOTE:** If no charge types are specified, by default *all types* can draw-down against the Balance amount at billing.' items: $ref: '#/components/schemas/BalanceLineItemType' contractId: type: string description: The unique identifier (UUID) of a Contract on the Account that the Balance will be added to. consumptionsAccountingProductId: maxLength: 36 minLength: 36 type: string description: Product ID that any Balance Consumed line items will be attributed to for accounting purposes.(*Optional*) feesAccountingProductId: maxLength: 36 minLength: 36 type: string description: Product ID that any Balance Fees line items will be attributed to for accounting purposes.(*Optional*) allowOverdraft: type: boolean description: 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 BalanceTransactionResponse: type: object description: '' allOf: - $ref: '#/components/schemas/AbstractResponse' - properties: description: type: string description: A brief description explaining the purpose or context of the transaction. amount: type: number description: The financial value of the transaction, as recorded in the balance. paid: type: number description: The actual payment amount if the payment currency differs from the Balance currency. currencyPaid: type: string description: The currency code such as USD, GBP, EUR of the payment, if it differs from the balance currency. entityType: description: The type of entity associated with the Transaction - identifies who or what was responsible for the Transaction being added to the Balance - such as a **User**, a **Service User**, or a **Bill**. $ref: '#/components/schemas/EntityType' entityId: type: string description: The unique identifier (UUID) for the entity associated with the Transaction, as specified by the `entityType`. transactionTypeId: type: string description: 'The unique identifier (UUID) for the Transaction type. This is obtained from the list of created Transaction Types within the Organization Configuration. ' appliedDate: type: string description: The date *(in ISO 8601 format)* when the balance transaction was applied, i.e., when the balance was affected. format: date-time transactionDate: type: string description: The date *(in ISO 8601 format)* when the transaction was recorded in the system. format: date-time dtCreated: type: string description: The date and time *(in ISO 8601 format)* when the balance transaction was first created. format: date-time x-stainless-skip: - terraform dtLastModified: type: string description: The date and time *(in ISO 8601 format)* when the balance transaction was last modified. format: date-time x-stainless-skip: - terraform createdBy: type: string description: The unique identifier (UUID) for the user who created the balance transaction. x-stainless-skip: - terraform lastModifiedBy: type: string description: The unique identifier (UUID) for the user who last modified the balance transaction. x-stainless-skip: - terraform AbstractRequestWithCustomFields: type: object description: '' allOf: - $ref: '#/components/schemas/AbstractRequest' - properties: customFields: type: object description: '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](https://www.m3ter.com/docs/guides/creating-and-managing-products/working-with-custom-fields) in the m3ter documentation for more information.' maxItems: 100 additionalProperties: anyOf: - title: StringCustomFieldReq type: string - title: IntegerCustomFieldReq type: integer - title: NumberCustomFieldReq type: number AbstractResponse: required: - id type: object properties: id: type: string description: 'The UUID of the entity. ' version: type: integer description: '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.' format: int64 x-stainless-terraform-configurability: computed x-stainless-terraform-always-send: true description: '' PaginatedBalanceResponseData: type: object properties: data: type: array description: '' items: $ref: '#/components/schemas/BalanceResponse' nextToken: type: string description: '' description: '' BalanceTransactionRequest: type: object description: '' allOf: - $ref: '#/components/schemas/AbstractRequest' - required: - amount properties: description: type: string description: A brief description explaining the purpose and context of the transaction. amount: type: number description: The financial value of the transaction. paid: type: number description: The payment amount if the payment currency differs from the Balance currency. currencyPaid: type: string description: 'The currency code of the payment if it differs from the Balance currency. For example: USD, GBP or EUR. ' transactionTypeId: maxLength: 36 pattern: ^[a-zA-Z0-9-]*$ type: string description: 'The unique identifier (UUID) of the transaction type. This is obtained from the list of created Transaction Types within the Organization Configuration. ' appliedDate: type: string description: The date *(in ISO 8601 format)* when the Balance transaction was applied. format: date-time transactionDate: type: string description: The date *(in ISO 8601 format)* when the transaction occurred. format: date-time BalanceLineItemType: type: string description: Available line item types for Balances enum: - STANDING_CHARGE - USAGE - MINIMUM_SPEND - COUNTER_RUNNING_TOTAL_CHARGE - COUNTER_ADJUSTMENT_DEBIT - AD_HOC AbstractRequest: type: object properties: version: type: integer description: '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.' format: int64 x-stainless-terraform-configurability: computed x-stainless-terraform-always-send: true description: '' BalanceTransactionsSummary: type: object properties: totalCreditAmount: type: number description: '' example: 250 totalDebitAmount: type: number description: '' example: 125.5 initialCreditAmount: type: number description: '' example: 300 expiredBalanceAmount: type: number description: Amount of the balance that expired without being used example: 50 rolloverConsumed: type: number description: Amount consumed from rollover credit example: 75 balanceConsumed: type: number description: Amount consumed from the original balance example: 100 description: '' BalanceResponse: type: object description: '' allOf: - $ref: '#/components/schemas/AbstractResponseWithCustomFields' - $ref: '#/components/schemas/AbstractResponse' - properties: code: type: string description: A unique short code assigned to the Balance. name: type: string description: The official name of the Balance. description: type: string description: A description of the Balance. accountId: type: string description: The unique identifier (UUID) for the end customer Account the Balance belongs to. amount: type: number description: The financial value that the Balance holds. currency: type: string description: 'The currency code used for the Balance amount. For example: USD, GBP or EUR.' startDate: type: string description: The date *(in ISO 8601 format)* when the Balance becomes active. format: date-time endDate: type: string description: The date *(in ISO 8601 format)* after which the Balance will no longer be active. format: date-time rolloverAmount: type: number description: 'The maximum amount that can be carried over past the Balance end date and draw-down against for billing if there is an unused Balance amount remaining when the Balance end date is reached. ' rolloverEndDate: type: string description: The end date *(in ISO 8601 format)* for the rollover grace period, which is the period that unused Balance amounts can be carried over beyond the specified Balance `endDate` and continue to be drawn-down against for billing. format: date-time balanceDrawDownDescription: type: string description: A description for the bill line items for charges drawn-down against the Balance. overageSurchargePercent: type: number description: The percentage surcharge applied to overage charges *(usage above the Balance)*. format: double overageDescription: type: string description: A description for overage charges. productIds: type: array description: A list of Product IDs whose consumption charges due at billing can be drawn-down against the Balance amount. items: type: string lineItemTypes: type: array description: 'A list of line item charge types that can draw-down against the Balance amount at billing. ' items: $ref: '#/components/schemas/BalanceLineItemType' contractId: type: string description: The unique identifier (UUID) for a Contract on the Account the Balance has been added to. consumptionsAccountingProductId: type: string description: Product ID that any Balance Consumed line items will be attributed to for accounting purposes.(*Optional*) feesAccountingProductId: type: string description: Product ID that any Balance Fees line items will be attributed to for accounting purposes.(*Optional*) allowOverdraft: type: boolean description: 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). dtCreated: type: string description: The date and time *(in ISO 8601 format)* when the Balance was first created. format: date-time x-stainless-skip: - terraform dtLastModified: type: string description: The date and time *(in ISO 8601 format)* when the Balance was last modified. format: date-time x-stainless-skip: - terraform createdBy: type: string description: The unique identifier (UUID) for the user who created the Balance. x-stainless-skip: - terraform lastModifiedBy: type: string description: The unique identifier (UUID) for the user who last modified the Balance. x-stainless-skip: - terraform AbstractResponseWithCustomFields: type: object description: '' allOf: - $ref: '#/components/schemas/AbstractResponse' - properties: customFields: type: object description: '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](https://www.m3ter.com/docs/guides/creating-and-managing-products/working-with-custom-fields) in the m3ter documentation for more information.' additionalProperties: anyOf: - title: StringCustomFieldRes type: string - title: IntegerCustomFieldRes type: integer - title: NumberCustomFieldRes type: number responses: Error: description: Error message content: application/json: schema: type: object properties: message: type: string securitySchemes: OAuth2: type: oauth2 description: "m3ter supports machine to machine authentication using the `clientCredentials` OAuth2 flow.\n\nThe `authorizationCode` flow controls access for human users via the m3ter Console application. \n" flows: clientCredentials: tokenUrl: /oauth/token scopes: m3ter-resources/m3ter-scope: m3ter resources measurements:upload: Upload measurements measurements:fileUpload: Upload file measurements:retrieve: Retrieve measurements authorizationCode: authorizationUrl: https://m3ter.auth.us-east-1.amazoncognito.com/oauth2/authorize tokenUrl: https://m3ter.auth.us-east-1.amazoncognito.com/oauth2/token scopes: m3ter-resources/m3ter-scope: m3ter resources openid: OpenID email: email measurements:upload: Upload measurements measurements:fileUpload: Upload file measurements:retrieve: Retrieve measurements