M3ter Balances API

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<!-- ReDoc-Inject: <security-definitions> -->"
  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 de

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/m3ter/refs/heads/main/openapi/m3ter-balances-api-openapi.yml