TM Forum billingAccount API

openapi: 3.2.0
info:
  title: Account Management Billing Account API
  description: This is Swagger UI environment generated for the TMF Account Management specification
  version: 4.0.0
servers:
- url: https://serverRoot/tmf-api/accountManagement/v4/
tags:
- name: billingAccount
paths:
  /billingAccount:
    get:
      operationId: listBillingAccount
      summary: List or find BillingAccount objects
      description: This operation list or find BillingAccount entities
      tags:
      - billingAccount
      parameters:
      - name: fields
        description: Comma-separated properties to be provided in response
        required: false
        in: query
        schema:
          type: string
      - name: offset
        description: Requested index for start of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      - name: limit
        description: Requested number of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Success
          headers:
            X-Result-Count:
              description: Actual number of items returned in the response body
              schema:
                type: integer
            X-Total-Count:
              description: Total number of items matching criteria
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BillingAccount'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createBillingAccount
      summary: Creates a BillingAccount
      description: This operation creates a BillingAccount entity.
      tags:
      - billingAccount
      responses:
        '201':
          description: Created
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/BillingAccount'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/BillingAccount_Create'
        description: The BillingAccount to be created
        required: true
  /billingAccount/{id}:
    get:
      operationId: retrieveBillingAccount
      summary: Retrieves a BillingAccount by ID
      description: This operation retrieves a BillingAccount entity. Attribute selection is enabled for all first level attributes.
      tags:
      - billingAccount
      parameters:
      - name: id
        description: Identifier of the BillingAccount
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Comma-separated properties to provide in response
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/BillingAccount'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: patchBillingAccount
      summary: Updates partially a BillingAccount
      description: This operation updates partially a BillingAccount entity.
      tags:
      - billingAccount
      parameters:
      - name: id
        description: Identifier of the BillingAccount
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Updated
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/BillingAccount'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/BillingAccount_Update'
        description: The BillingAccount to be updated
        required: true
    delete:
      operationId: deleteBillingAccount
      summary: Deletes a BillingAccount
      description: This operation deletes a BillingAccount entity.
      tags:
      - billingAccount
      parameters:
      - name: id
        description: Identifier of the BillingAccount
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: Deleted
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      description: Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)
      type: object
      required:
      - code
      - reason
      properties:
        code:
          type: string
          description: Application relevant detail, defined in the API or a common list.
        reason:
          type: string
          description: Explanation of the reason for the error which can be shown to a client user.
        message:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client user.
        status:
          type: string
          description: HTTP Error code extension
        referenceError:
          type: string
          format: uri
          description: URI of documentation describing the error.
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class.
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name.
    TimePeriod:
      type: object
      description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both
      properties:
        endDateTime:
          type: string
          format: date-time
          description: End of the time period, using IETC-RFC-3339 format
        startDateTime:
          type: string
          format: date-time
          description: Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end
    BillingAccount_Update:
      type: object
      description: 'A party account used for billing purposes. It includes a description of the bill structure (frequency, presentation media, format and so on). It is a specialization of entity PartyAccount.

        Skipped properties: id,href,accountBalance'
      required:
      - name
      - relatedParty
      properties:
        accountType:
          type: string
          description: 'A categorization of an account, such as individual, joint, and so forth, whose instances share some of the same characteristics. Note: for flexibility we use a String here but an implementation may use an enumeration with a limited list of valid values.'
        description:
          type: string
          description: Detailed description of the party account
        lastModified:
          type: string
          format: date-time
          description: Date of last modification of the account
        name:
          type: string
          description: Name of the account
        paymentStatus:
          type: string
          description: The condition of the account, such as due, paid, in arrears.
        state:
          type: string
          description: 'Contains the lifecycle state such as: Active, Closed, Suspended and so on.'
        accountRelationship:
          type: array
          items:
            $ref: '#/components/schemas/AccountRelationship'
        billStructure:
          $ref: '#/components/schemas/BillStructure'
        contact:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        creditLimit:
          $ref: '#/components/schemas/Money'
          description: The maximum amount of money that may be charged on an account
        defaultPaymentMethod:
          $ref: '#/components/schemas/PaymentMethodRef'
        financialAccount:
          $ref: '#/components/schemas/FinancialAccountRef'
        paymentPlan:
          type: array
          items:
            $ref: '#/components/schemas/PaymentPlan'
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          minItems: 1
        taxExemption:
          type: array
          items:
            $ref: '#/components/schemas/AccountTaxExemption'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    BillStructure:
      type: object
      description: The structure of the bill for party accounts (billing or settlement).
      properties:
        cycleSpecification:
          $ref: '#/components/schemas/BillingCycleSpecificationRefOrValue'
        format:
          $ref: '#/components/schemas/BillFormatRefOrValue'
        presentationMedia:
          type: array
          items:
            $ref: '#/components/schemas/BillPresentationMediaRefOrValue'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    ContactMedium:
      type: object
      description: Indicates the contact medium that could be used to contact the party.
      properties:
        mediumType:
          type: string
          description: 'Type of the contact medium, such as: email address, telephone number, postal address'
        preferred:
          type: boolean
          description: If true, indicates that is the preferred contact medium
        characteristic:
          $ref: '#/components/schemas/MediumCharacteristic'
          description: Any additional characteristic(s) of this contact medium
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The time period that the contact medium is valid for
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    AccountTaxExemption:
      type: object
      description: Proof of freedom from taxes imposed by a taxing jurisdiction
      required:
      - issuingJurisdiction
      - validFor
      properties:
        certificateNumber:
          type: string
          description: Identifier of a document that shows proof of exemption from taxes for the taxing jurisdiction
        issuingJurisdiction:
          type: string
          description: Name of the taxing jurisdiction for which taxes are exempt
        reason:
          type: string
          description: Reason of the tax exemption
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: Period for which the exemption is valid
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    MediumCharacteristic:
      type: object
      description: Describes the contact medium characteristics that could be used to contact a party (an individual or an organization)
      properties:
        city:
          type: string
          description: The city
        contactType:
          type: string
          description: 'The type of contact, for example: phone number such as mobile, fixed home, fixed office. postal address such as shipping instalation…'
        country:
          type: string
          description: The country
        emailAddress:
          type: string
          description: Full email address in standard format
        faxNumber:
          type: string
          description: The fax number of the contact
        phoneNumber:
          type: string
          description: The primary phone number of the contact
        postCode:
          type: string
          description: Postcode
        socialNetworkId:
          type: string
          description: Identifier as a member of a social network
        stateOrProvince:
          type: string
          description: State or province
        street1:
          type: string
          description: Describes the street
        street2:
          type: string
          description: Complementary street description
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    BillFormatRefOrValue:
      type: object
      description: An attachment by value or by reference.
      required:
      - name
      - isRef
      properties:
        id:
          type: string
          description: Unique identifier of the bill format
        href:
          type: string
          description: Reference of the bill format
        description:
          type: string
          description: An explanatory text for this bill format
        isRef:
          default: true
          type: boolean
        name:
          type: string
          description: A short descriptive name
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    RelatedParty:
      type: object
      description: Related Entity reference. A related party defines party or party role linked to a specific entity.
      required:
      - '@referredType'
      - id
      - name
      properties:
        id:
          type: string
          description: Unique identifier of a related entity.
        href:
          type: string
          description: Reference of the related entity.
        name:
          type: string
          description: Name of the related entity.
        role:
          type: string
          description: Role played by the related party
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    AccountRef:
      type: object
      description: Account reference. A account may be a party account or a financial account.
      properties:
        id:
          type: string
          description: Unique identifier of the account
        href:
          type: string
          description: Reference of the account
        description:
          type: string
          description: Detailed description of the account
        name:
          type: string
          description: Name of the account
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - id
    PaymentMethodRef:
      type: object
      description: PaymentMethod reference. A payment method defines a specific mean of payment (e.g direct debit).
      properties:
        id:
          type: string
          description: Unique identifier of the payment mean
        href:
          type: string
          description: Reference of the payment mean
        name:
          type: string
          description: Name of the payment mean
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - id
    Money:
      type: object
      description: A base / value business entity used to represent money
      properties:
        unit:
          type: string
          description: Currency (ISO4217 norm uses 3 letters to define the currency)
        value:
          type: number
          format: float
          description: A positive floating point number
    BillPresentationMediaRefOrValue:
      type: object
      description: An attachment by value or by reference.
      required:
      - name
      - isRef
      properties:
        id:
          type: string
          description: Unique identifier of the bill presentation media
        href:
          type: string
          description: Reference of the bill presentation media
        description:
          type: string
          description: An explanatory text describing this bill presentation media
        isRef:
          default: true
          type: boolean
        name:
          type: string
          description: A short descriptive name
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    BillingAccount:
      type: object
      description: A party account used for billing purposes. It includes a description of the bill structure (frequency, presentation media, format and so on). It is a specialization of entity PartyAccount.
      required:
      - name
      - relatedParty
      properties:
        id:
          type: string
          description: Unique identifier of the account
        href:
          type: string
          description: Unique reference of the account
        accountType:
          type: string
          description: 'A categorization of an account, such as individual, joint, and so forth, whose instances share some of the same characteristics. Note: for flexibility we use a String here but an implementation may use an enumeration with a limited list of valid values.'
        description:
          type: string
          description: Detailed description of the party account
        lastModified:
          type: string
          format: date-time
          description: Date of last modification of the account
        name:
          type: string
          description: Name of the account
        paymentStatus:
          type: string
          description: The condition of the account, such as due, paid, in arrears.
        state:
          type: string
          description: 'Contains the lifecycle state such as: Active, Closed, Suspended and so on.'
        accountBalance:
          type: array
          items:
            $ref: '#/components/schemas/AccountBalance'
        accountRelationship:
          type: array
          items:
            $ref: '#/components/schemas/AccountRelationship'
        billStructure:
          $ref: '#/components/schemas/BillStructure'
        contact:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        creditLimit:
          $ref: '#/components/schemas/Money'
          description: The maximum amount of money that may be charged on an account
        defaultPaymentMethod:
          $ref: '#/components/schemas/PaymentMethodRef'
        financialAccount:
          $ref: '#/components/schemas/FinancialAccountRef'
        paymentPlan:
          type: array
          items:
            $ref: '#/components/schemas/PaymentPlan'
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          minItems: 1
        taxExemption:
          type: array
          items:
            $ref: '#/components/schemas/AccountTaxExemption'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    AccountBalance:
      type: object
      description: Balances linked to the account
      required:
      - amount
      - balanceType
      - validFor
      properties:
        balanceType:
          type: string
          description: 'Type of the balance : deposit balance, disputed balance, loyalty balance, receivable balance...'
        amount:
          $ref: '#/components/schemas/Money'
          description: Balance amount
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: Balance validity period
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    AccountRelationship:
      type: object
      description: Significant connection between accounts. For instance an aggregating account for a list of shop branches each having its own billing account.
      required:
      - relationshipType
      - validFor
      properties:
        relationshipType:
          type: string
          description: Type of relationship
        account:
          $ref: '#/components/schemas/AccountRef'
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: Validity period of that relationship
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    BillingCycleSpecificationRefOrValue:
      type: object
      description: An attachment by value or by reference.
      required:
      - name
      - isRef
      properties:
        id:
          type: string
          description: Unique identifier of the billing cycle specification
        href:
          type: string
          description: Reference of the billing cycle specification
        billingDateShift:
          type: integer
          description: An offset of a billing/settlement date. The offset is expressed as number of days with regard to the start of the billing/settlement period.
        billingPeriod:
          type: string
          description: 'A billing time period. It can be recurring, for example: week, month, quarter of year, year .'
        chargeDateOffset:
          type: integer
          description: An offset of a date through which charges previously received by the billing system will appear on the bill. The offset is expressed as number of days with regard to the start of the BillingPeriod.
        creditDateOffset:
          type: integer
          description: An offset of a date through which credits previously received by the billing system will appear on the bill. The offset is expressed as number of days with regard to the start of the BillingPeriod.
        dateShift:
          type: integer
          description: An offset of a billing/settlement date. The offset is expressed as number of days with regard to the start of the billing/settlement period.
        description:
          type: string
          description: An explanation regarding this billing cycle specification
        frequency:
          type: string
          descri

# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tm-forum/refs/heads/main/openapi/tm-forum-billingaccount-api-openapi.yml