TM Forum billingAccount API

openapi: 3.0.1
info:
  title: Product Catalog Management agreement billingAccount API
  description: "Product Catalog API is one of Catalog Management API Family. Product Catalog API goal is to provide a catalog of products. \n### Operations\nProduct Catalog API performs the following operations on the resources :\n- Retrieve an entity or a collection of entities depending on filter criteria\n- Partial update of an entity (including updating rules)\n- Create an entity (including default values and creation rules)\n- Delete an entity\n- Manage notification of events"
  version: 5.0.0
servers:
- url: https://serverRoot/productCatalogManagement/v5/
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
        type: string
      - name: offset
        description: Requested index for start of resources to be provided in response
        required: false
        in: query
        type: integer
      - name: limit
        description: Requested number of resources to be provided in response
        required: false
        in: query
        type: integer
      responses:
        '200':
          description: Success
          headers:
            X-Result-Count:
              description: Actual number of items returned in the response body
              type: integer
            X-Total-Count:
              description: Total number of items matching criteria
              type: integer
          schema:
            type: array
            items:
              $ref: '#/definitions/BillingAccount'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
    post:
      operationId: createBillingAccount
      summary: Creates a BillingAccount
      description: This operation creates a BillingAccount entity.
      tags:
      - billingAccount
      parameters:
      - name: billingAccount
        description: The BillingAccount to be created
        required: true
        schema:
          $ref: '#/definitions/BillingAccount_Create'
        in: body
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/BillingAccount'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  /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
        type: string
        in: path
      - name: fields
        description: Comma-separated properties to provide in response
        required: false
        type: string
        in: query
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/BillingAccount'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/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
        type: string
        in: path
      - name: billingAccount
        description: The BillingAccount to be updated
        required: true
        schema:
          $ref: '#/definitions/BillingAccount_Update'
        in: body
      responses:
        '200':
          description: Updated
          schema:
            $ref: '#/definitions/BillingAccount'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
    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
        type: string
        in: path
      responses:
        '204':
          description: Deleted
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
definitions:
  BillingAccount_Create:
    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'
    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.'
      accountBalance:
        type: array
        items:
          $ref: '#/definitions/AccountBalance'
      accountRelationship:
        type: array
        items:
          $ref: '#/definitions/AccountRelationship'
      billStructure:
        $ref: '#/definitions/BillStructure'
      contact:
        type: array
        items:
          $ref: '#/definitions/Contact'
      creditLimit:
        $ref: '#/definitions/Money'
        description: The maximum amount of money that may be charged on an account
      defaultPaymentMethod:
        $ref: '#/definitions/PaymentMethodRef'
      financialAccount:
        $ref: '#/definitions/FinancialAccountRef'
      paymentPlan:
        type: array
        items:
          $ref: '#/definitions/PaymentPlan'
      relatedParty:
        type: array
        items:
          $ref: '#/definitions/RelatedParty'
        minItems: 1
      taxExemption:
        type: array
        items:
          $ref: '#/definitions/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
  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.
  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: '#/definitions/Money'
        description: Balance amount
      validFor:
        $ref: '#/definitions/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
  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: '#/definitions/MediumCharacteristic'
        description: Any additional characteristic(s) of this contact medium
      validFor:
        $ref: '#/definitions/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
  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: '#/definitions/AccountRelationship'
      billStructure:
        $ref: '#/definitions/BillStructure'
      contact:
        type: array
        items:
          $ref: '#/definitions/Contact'
      creditLimit:
        $ref: '#/definitions/Money'
        description: The maximum amount of money that may be charged on an account
      defaultPaymentMethod:
        $ref: '#/definitions/PaymentMethodRef'
      financialAccount:
        $ref: '#/definitions/FinancialAccountRef'
      paymentPlan:
        type: array
        items:
          $ref: '#/definitions/PaymentPlan'
      relatedParty:
        type: array
        items:
          $ref: '#/definitions/RelatedParty'
        minItems: 1
      taxExemption:
        type: array
        items:
          $ref: '#/definitions/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
  FinancialAccountRef:
    type: object
    description: AccountReceivable reference. An account of money owed by a party to another entity in exchange for goods or services that have been delivered or used. An account receivable aggregates the amounts of one or more party accounts (billing or settlement) owned by a given party.
    properties:
      id:
        type: string
        description: Unique identifier of the account
      href:
        type: string
        description: Unique reference of the account
      name:
        type: string
        description: Name of the account
      accountBalance:
        $ref: '#/definitions/AccountBalance'
      '@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
  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
  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.
  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
        description: Frequency of the billing cycle (monthly for instance)
      isRef:
        default: true
        type: boolean
      mailingDateOffset:
        type: integer
        description: An offset of a customer bill mailing date. The offset is expressed as number of days with regard to the start of the BillingPeriod.
      name:
        type: string
        description: A short descriptive name
      paymentDueDateOffset:
        type: integer
        description: An offset of a payment due date. The offset is expressed as number of days with regard to the start of the BillingPeriod.
      validFor:
        $ref: '#/definitions/TimePeriod'
        description: The period for which the billing specification cycle 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
      '@referredType':
        type: string
        description: The actual type of the target instance when needed for disambiguation.
  PaymentPlan:
    type: object
    description: Defines a plan for payment (when a party wants to spread his payments)
    properties:
      numberOfPayments:
        type: integer
        description: Number of payments used to spread the global payment
      paymentFrequency:
        type: string
        description: Frequency of the payments, such as monthly and bimonthly
      planType:
        type: string
        description: Type of payment plan
      priority:
        type: integer
        description: Priority of the payment plan
      status:
        type: string
        description: Status of the payment plan (effective, ineffective)
      paymentMethod:
        $ref: '#/definitions/PaymentMethodRef'
      totalAmount:
        $ref: '#/definitions/Money'
        description: Amount paid
      validFor:
        $ref: '#/definitions/TimePeriod'
        description: Validity period of the payment plan
      '@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
  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.
  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: '#/definitions/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
  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
  Contact:
    type: object
    description: An individual or an organization used as a contact point for a given account and accessed via some contact medium.
    required:
    - contactType
    - validFor
    properties:
      contactName:
        type: string
        description: A displayable name for that contact
      contactType:
        type: string
        description: Type of contact (primary, secondary...)
      partyRoleType:
        type: string
        description: Identifies what kind of party role type is linked to the contact (a account manager...)
      contactMedium:
        type: array
        items:
          $ref: '#/definitions/ContactMedium'
      relatedParty:
        $ref: '#/definitions/RelatedParty'
      validFor:
        $ref: '#/definitions/TimePeriod'
        description: Validity period of that contact
      '@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
  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
  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: '#/definitions/AccountBalance'
      accountRelationship:
        type: array
        items:
          $ref: '#/definitions/AccountRelationship'
      billStructure:
        $ref: '#/definitions/BillStructure'
      contact:
        type: array
        items:
          $ref: '#/definitions/Contact'
      creditLimit:
        $ref: '#/definitions/Money'
        description: The maximum amount of money that may be charged on an account
      defaultPaymentMethod:
        $ref: '#/definitions/PaymentMethodRef'
      financialAccount:
        $ref: '#/definitions/FinancialAccountRef'
      paymentPlan:
        type: array
        items:
          $ref: '#/definitions/Paymen

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