openapi: 3.0.1
info:
  title: Billing Model API
  description: >-
    The Billing Model API allows you to view your billing model and manage the
    details of your capacity billing model. 

    While transitioning between metered and capacity billing plans requires
    contacting our support team, this API provides you with control over key
    aspects of your capacity plan. 

    Specifically, you can:

    - View your current capacity billing details, like capacity threshold and
    effective date.

    - Manage and adjust your voice capacity thresholds.

    - Schedule future changes to your capacity thresholds using effective dates.

    - Access records of your past capacity thresholds and settings.


    This API gives you visibility and control over your capacity billing
    settings, enabling you to manage your service usage and associated costs
    effectively within the parameters of your current billing plan.
  version: 1.0.0
  termsOfService: https://www.bandwidth.com/legal/terms-of-use-bandwidthcom-web-sites/
  contact:
    name: Bandwidth Support
    email: support@bandwidth.com
    url: https://support.bandwidth.com
servers:
  - url: https://api.bandwidth.com/v2
    description: Production
paths:
  /accounts/{accountId}/billing-models:
    get:
      summary: Retrieve billing models for a specific account
      tags:
        - Account Billing Models
      description: Retrieves billing models for a specific account.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/statusQueryParameter'
        - $ref: '#/components/parameters/afterCursor'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          $ref: '#/components/responses/billingModelsListResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '405':
          $ref: '#/components/responses/notAllowedError'
        5XX:
          $ref: '#/components/responses/internalServerError'
    post:
      summary: Create a new billing model
      tags:
        - Account Billing Models
      description: >-
        Create a new billing model record to set and configure future billing
        model settings. A new billing model should be created whenever there is
        a change in your capacity threshold, or a change in your billing model
        type (from metered to capacity or vice versa).

        The effective date is automatically set based on your account status.
        For new accounts, the effective date is the date of creation and billing
        is prorated. For changes to an existing billing model, the effective
        date will be the first day of the next month.
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        $ref: '#/components/requestBodies/billingModelCreateRequest'
      responses:
        '201':
          $ref: '#/components/responses/billingModelResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '405':
          $ref: '#/components/responses/notAllowedError'
        '409':
          $ref: '#/components/responses/duplicateRequestError'
        5XX:
          $ref: '#/components/responses/internalServerError'
  /accounts/{accountId}/billing-models/{billingModelId}:
    get:
      summary: Retrieve a specific billing model for a specific account
      tags:
        - Account Billing Models
      description: Retrieves a specific billing model by its ID for a specific account.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/billingModelId'
      responses:
        '200':
          $ref: '#/components/responses/billingModelResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '405':
          $ref: '#/components/responses/notAllowedError'
        5XX:
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Update a billing model
      tags:
        - Account Billing Models
      description: >-
        Updates an existing billing model.

        The billing model ID must be provided in the URL path, and the request
        body should contain the updated details.

        The update does not change the effective date. Updates can only be made
        to billing models with an effective date in the future; active billing
        models cannot be updated.

        Please reach out to our support team if you wish to transition between
        metered and capacity billing plans, or wish to reduce your voice
        capacity threshold.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/billingModelId'
      requestBody:
        $ref: '#/components/requestBodies/billingModelUpdateRequest'
      responses:
        '200':
          $ref: '#/components/responses/billingModelResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '405':
          $ref: '#/components/responses/notAllowedError'
        5XX:
          $ref: '#/components/responses/internalServerError'
    delete:
      summary: Delete a billing model
      tags:
        - Account Billing Models
      description: >-
        Deletes a specific billing model by its ID.

        Please note that a billing model cannot be deleted once the effective
        date has passed.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/billingModelId'
      responses:
        '204':
          $ref: '#/components/responses/noContentResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '405':
          $ref: '#/components/responses/notAllowedError'
        5XX:
          $ref: '#/components/responses/internalServerError'
components:
  parameters:
    billingModelId:
      name: billingModelId
      in: path
      required: true
      description: The ID of the billing model to retrieve.
      schema:
        type: string
        format: uuid
    accountId:
      name: accountId
      in: path
      required: true
      description: The account ID to get billing models for.
      schema:
        type: string
        items:
          $ref: '#/components/schemas/accountId'
      example: '10000001'
    modelTypeQueryParameter:
      name: modelType
      in: query
      description: Filters by billing model type (METERED or CAPACITY).
      required: false
      style: deepObject
      explode: true
      schema:
        $ref: '#/components/schemas/modelTypeQueryParameter'
    statusQueryParameter:
      name: status
      in: query
      description: >-
        Filters billing models by current status (ACTIVE, PENDING, EXPIRED).
        Status should not be considered when determining the effective date in
        an historical context.
      style: deepObject
      explode: true
      required: false
      schema:
        $ref: '#/components/schemas/statusQueryParameter'
    afterCursor:
      name: afterCursor
      in: query
      description: Opaque string used to retrieve the next set of results.
      schema:
        type: string
      example: '1701374259320946303'
    limit:
      name: limit
      in: query
      description: The maximum number of records to return.
      required: false
      schema:
        type: integer
        minimum: 1
        default: 10
        example: 10
  schemas:
    statusQueryParameter:
      title: Status Query Parameter
      description: Base model for Status query parameter.
      properties:
        eq:
          type: array
          items:
            $ref: '#/components/schemas/statusEnum'
      example:
        eq:
          - ACTIVE
          - PENDING
    modelTypeQueryParameter:
      title: Model Type Query Parameter
      description: Base model for Model Type query parameter.
      type: object
      properties:
        eq:
          $ref: '#/components/schemas/modelTypeEnum'
      example:
        eq: CAPACITY
    sort:
      type: string
      description: Sorting order in ascending or descending order
      enum:
        - ASC
        - DESC
      default: ASC
    genericError:
      title: Generic Error
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example: []
        data:
          type: object
          nullable: true
          example: null
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
      required:
        - links
        - data
        - errors
    billingModelsListResponse:
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example:
            - href: https://api.bandwidth.com/v2/accounts/123456/billing-models
              rel: self
              method: GET
            - href: https://api.bandwidth.com/v2/accounts/123456/billing-models
              rel: first
              method: GET
            - href: >-
                https://api.bandwidth.com/v2/accounts/123456/billing-models?afterCursor=bWF5IHRoZSBmb3JjZSBiZSB3aXRoIHlvdQ&limit=10
              rel: next
              method: GET
        data:
          $ref: '#/components/schemas/billingModelsList'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          example: []
        page:
          $ref: '#/components/schemas/pageMeta'
    billingModelResponse:
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example:
            - href: >-
                https://api.bandwidth.com/v2/accounts/123456/billing-models/123456789
              rel: billing-model
              method: GET
        data:
          $ref: '#/components/schemas/billingModel'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          example: []
    link:
      title: Link
      type: object
      properties:
        href:
          type: string
          description: URI of the link.
          example: https://api.bandwidth.com/v2/accounts/123456/billing-models
        rel:
          type: string
          description: Specifies the relationship between this link and the resource.
          example: self
        method:
          type: string
          description: HTTP method to be used.
          example: GET
    error:
      title: Error
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for this particular instance of this problem.
          example: optional-error-id
        type:
          type: string
          description: >-
            A short, human-readable summary of the problem that SHOULD NOT
            change from occurrence to occurrence of the problem.
          example: REQUEST_ERROR
        description:
          type: string
          description: >-
            A human-readable explanation that SHOULD be specific to this
            occurrence of the problem.
          example: There was an issue with a field in your request body
        code:
          type: integer
          format: int32
          description: >-
            An application-specific error code for services with extensive error
            scenarios to supplement `description`.
          minimum: 4
          example: 51130
        source:
          $ref: '#/components/schemas/errorSource'
        meta:
          $ref: '#/components/schemas/errorMeta'
      required:
        - description
    errorSource:
      title: Error Source
      type: object
      properties:
        parameter:
          type: string
          description: A string indicating which URI query parameter caused the error.
          example: someParameter
        field:
          type: string
          description: A string indicating which request body field caused the error.
          example: someField
        header:
          type: string
          description: A string indicating which header field caused the error.
          example: someHeader
        reference:
          type: string
          description: >-
            A string that references a resource ID or path to the resource (or
            non-existent resource) causing the error.
          example: /some/reference
    errorMeta:
      title: Error Meta
      type: object
      additionalProperties:
        type: string
    pageMeta:
      title: Pagination Metadata
      type: object
      properties:
        pageSize:
          type: integer
          description: The size of pages returned.
          example: 20
      nullable: true
    billingModelsList:
      type: object
      required:
        - totalCount
        - billingModels
      properties:
        totalCount:
          type: integer
          description: The total number of billing models
          example: 1
        billingModels:
          type: array
          items:
            $ref: '#/components/schemas/billingModel'
    modelTypeEnum:
      type: string
      enum:
        - METERED
        - CAPACITY
      description: The type of billing model.
    statusEnum:
      type: string
      enum:
        - ACTIVE
        - PENDING
        - EXPIRED
      description: >-
        The current status of the billing model. This is not to be used in an
        historical context.
    billingModel:
      type: object
      properties:
        billingModelId:
          $ref: '#/components/schemas/billingModelId'
        accountId:
          $ref: '#/components/schemas/accountId'
        modelType:
          $ref: '#/components/schemas/modelTypeEnum'
        effectiveDate:
          $ref: '#/components/schemas/effectiveDate'
        voiceCapacityThreshold:
          $ref: '#/components/schemas/voiceCapacityThreshold'
        status:
          $ref: '#/components/schemas/statusEnum'
    billingModelCreateRequest:
      type: object
      required:
        - accountId
        - modelType
      properties:
        accountId:
          $ref: '#/components/schemas/accountId'
        modelType:
          $ref: '#/components/schemas/modelTypeEnum'
      oneOf:
        - title: Capacity
          properties:
            modelType:
              enum:
                - CAPACITY
            voiceCapacityThreshold:
              $ref: '#/components/schemas/voiceCapacityThreshold'
          required:
            - voiceCapacityThreshold
        - title: Metered
          properties:
            modelType:
              enum:
                - METERED
    billingModelUpdateRequest:
      allOf:
        - $ref: '#/components/schemas/billingModelCreateRequest'
      type: object
      required:
        - billingModelId
      properties:
        billingModelId:
          $ref: '#/components/schemas/billingModelId'
    accountId:
      type: string
      description: The ID of the account.
      example: '10000001'
    effectiveDate:
      type: string
      format: date
      description: The date when the billing model becomes effective.
      example: 2025-04-01T00:00:00.000Z
    username:
      type: string
      description: The username of the user who created or updated the billing model.
      example: jdoe
    voiceCapacityThreshold:
      type: integer
      description: Must be in increments of 10.
      multipleOf: 10
      example: 100
    billingModelId:
      description: The unique identifier for the billing model.
      type: string
      format: uuid
  examples:
    badRequestErrorExample:
      summary: An example of a generic Bad Request Error
      value:
        links: []
        data: null
        errors:
          - id: optional-error-id
            type: VALIDATION_ERROR
            description: There is an issue with your request
            code: 1001
            source:
              field: modelType
            meta:
              message: >-
                Billing model type is required. Allowed values are METERED or
                CAPACITY.
    unauthorizedErrorExample:
      summary: An example of a generic Unauthorized Error
      value: null
    forbiddenErrorExample:
      summary: An example of a generic Unauthorized Error
      value: null
    notFoundErrorExample:
      summary: An example of a generic Not Found Error
      value:
        links: []
        errors:
          - id: optional-error-id
            type: RESOURCE_NOT_FOUND
            description: The specified resource could not be found
            code: 1002
        data: null
    notAllowedErrorExample:
      summary: An example of a generic Not Allowed Error
      value:
        links: []
        errors:
          - id: optional-error-id
            type: METHOD_NOT_ALLOWED
            description: The HTTP method is not allowed for the requested resource.
            code: 1005
        data: null
    duplicateRequestErrorExample:
      summary: An example of a generic Duplicate Request Error
      value:
        links:
          - rel: self
            href: https://api.bandwidth.com/v2/accounts/123456/billing-models
            method: POST
          - rel: billing-model
            href: >-
              https://api.bandwidth.com/v2/accounts/123456/billing-models/52ef88c7-2eee-440f-a760-04e3580d3d4d
            method: GET
          - rel: replace
            href: >-
              https://api.bandwidth.com/v2/accounts/123456/billing-models/52ef88c7-2eee-440f-a760-04e3580d3d4d
            method: PUT
          - rel: delete
            href: >-
              https://api.bandwidth.com/v2/accounts/123456/billing-models/52ef88c7-2eee-440f-a760-04e3580d3d4d
            method: DELETE
        data: null
        errors:
          - id: optional-error-id
            type: CONFLICT_BILLING_MODEL
            description: >-
              The billing model submitted conflicts with an existing billing
              model. Refer to the given link to make changes to the relevant
              model.
            code: 1003
    internalServerErrorExample:
      summary: An example of a generic Internal Server Error
      value:
        links: []
        data: null
        errors:
          - id: optional-error-id
            type: internal-server-error
            description: >-
              Unexpected internal server error. Contact Bandwidth Customer
              Support if this problem persists.
            code: 32030
  securitySchemes:
    Basic:
      type: http
      scheme: basic
      description: >-
        Basic authentication is a simple authentication scheme built into the
        HTTP protocol. To use it, send your HTTP requests with an
        `Authorization` header that contains the word `Basic` followed by a
        space and a Base64-encoded string `username:password`.


        - Example: `Authorization: Basic ZGVtbZpwQDU1dzByZA==`
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer authentication (also called token authentication) is an HTTP
        authentication scheme that involves security tokens called bearer
        tokens. The name “Bearer authentication” can be understood as “give
        access to the bearer of this token.” The client must send this token in
        the `Authorization` header when making requests to protected resources.


        - Example: `Authorization: Bearer <token>`


        Where `<token>` should be replaced with the token string without angle
        brackets.


        For more information, see the following guide:
        [Credentials](https://dev.bandwidth.com/docs/account/credentials/management)
  requestBodies:
    billingModelCreateRequest:
      description: Billing Model create request
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/billingModelCreateRequest'
    billingModelUpdateRequest:
      description: Billing Model Update Request
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/billingModelUpdateRequest'
  responses:
    billingModelResponse:
      description: Billing Model Response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/billingModelResponse'
    billingModelsListResponse:
      description: Billing Models List Response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/billingModelsListResponse'
    noContentResponse:
      description: No Content
    badRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
          examples:
            badRequestErrorExample:
              $ref: '#/components/examples/badRequestErrorExample'
    unauthorizedError:
      description: Unauthorized
    forbiddenError:
      description: Forbidden
    notFoundError:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
          examples:
            notFoundErrorExample:
              $ref: '#/components/examples/notFoundErrorExample'
    notAllowedError:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
          examples:
            notAllowedErrorExample:
              $ref: '#/components/examples/notAllowedErrorExample'
    duplicateRequestError:
      description: Duplicate Request Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
          examples:
            duplicateRequestErrorExample:
              $ref: '#/components/examples/duplicateRequestErrorExample'
    internalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
          examples:
            internalServerErrorExample:
              $ref: '#/components/examples/internalServerErrorExample'
security:
  - Basic: []
  - Bearer: []
tags:
  - name: Account Billing Models
