openapi: 3.2.0
info:
  title: CustomerBill Applied Customer Billing Rate API
  description: "## TMF API Reference: TMF 678 - Customer bill Management\n\n### Release: 19.5 - December 2019\n\nThe Customer Bill Management API allows to find and retrieve one or several customer bills (also called invoices) produced for a customer. A customer bill is an electronic or paper document produced at the end of the billing process. The customer bill gathers and displays different items (applied customer billing rates generated during the rating and billing processes) to be charged to a customer. It represents a total amount due for all the products during the billing period and all significant information like dates, bill reference...\nThis API provides also operations to find and retrieve the details of applied customer billing rates presented on a customer bill. \nFinally, this API allows to request in real-time a customer bill creation and to manage this request.\n\n### Resources \n- customerBill\n- appliedCustomerBillingRate\n- customerBillOnDemand\n- billingCycle\n\n### Operations\nCustomer Bill Management API performs the following operations :\n- Retrieve a customer bill or a collection of customer bills depending on filter criteria.\n- Partial update of  a customer bill (for administration purposes).\n-  Retrieve an applied customer billing rate or a collection of applied customer billing rates depending on filter criteria.\n-  Create a customer bill on demand request, retrieve one or a collection of  customer bill on demand request(s) depending on filter criteria.\n\n- Manage notification of events on customer bill and customer bill on demand.\n\nCopyright © TM Forum 2018. All Rights Reserved."
  version: 4.0.0
servers:
- url: https://serverRoot/tmf-api/customerBillManagement/v4/
tags:
- name: appliedCustomerBillingRate
paths:
  /appliedCustomerBillingRate:
    get:
      operationId: listAppliedCustomerBillingRate
      summary: List or find AppliedCustomerBillingRate objects
      description: This operation list or find AppliedCustomerBillingRate entities
      tags:
      - appliedCustomerBillingRate
      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/AppliedCustomerBillingRate'
        '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'
  /appliedCustomerBillingRate/{id}:
    get:
      operationId: retrieveAppliedCustomerBillingRate
      summary: Retrieves a AppliedCustomerBillingRate by ID
      description: This operation retrieves a AppliedCustomerBillingRate entity. Attribute selection is enabled for all first level attributes.
      tags:
      - appliedCustomerBillingRate
      parameters:
      - name: id
        description: Identifier of the AppliedCustomerBillingRate
        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/AppliedCustomerBillingRate'
        '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:
    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
    AppliedCustomerBillingRate:
      type: object
      description: A customer bill displays applied billing rates created before or during the billing process.
      required:
      - id
      properties:
        id:
          type: string
          description: Unique identifier of the customer applied billing rate
        href:
          type: string
          description: Reference of the customer applied billing rate
        date:
          type: string
          format: date-time
          description: Creation date of the applied billing rate
        description:
          type: string
          description: Additional data to be displayed on the bill for this customer applied billing rate
        isBilled:
          type: boolean
          description: If isBilled = true then bill should be provided, if false then billingAccount should be provided
        name:
          type: string
          description: Name of the customer applied billing rate
        type:
          type: string
          description: 'Type of the applied billing rate : appliedBillingCharge (any kind of charge except taxation charges : recurringCharge, oneTimeCharge, usageCharge),  appliedBillingCredit (any kind of credit : rebate or productAlteration) or appliedPenaltyCharge (penalty charges such as late fees, payment rejection fees,...)'
        appliedTax:
          type: array
          items:
            $ref: '#/components/schemas/AppliedBillingTaxRate'
        bill:
          $ref: '#/components/schemas/BillRef'
        billingAccount:
          $ref: '#/components/schemas/BillingAccountRef'
        characteristic:
          type: array
          items:
            $ref: '#/components/schemas/AppliedBillingRateCharacteristic'
        periodCoverage:
          $ref: '#/components/schemas/TimePeriod'
          description: periodCoverage for RecurringCharge (RC) indicating the RC coverage period dates for different purposes, such as RC proration, display on bill, GL reporting, etc. periodCoverage for OC start and end date will be the same
        product:
          $ref: '#/components/schemas/ProductRef'
          description: Usually this information should be provided by the PRODUCT, which implies that there is a valid reference to product. In this case, this property should be empty. For all other situations, a text or structured info could be provided using this property. Regular modelling would suggest tu use the reforvalue pattern for this case. It is not choosen here because it would generate declarational dependencies which would be hard to maintain.
        taxExcludedAmount:
          $ref: '#/components/schemas/Money'
        taxIncludedAmount:
          $ref: '#/components/schemas/Money'
        '@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
    AppliedBillingTaxRate:
      type: object
      description: The applied billing tax rate represents taxes applied billing rate it refers to. It is calculated during the billing process.
      properties:
        taxCategory:
          type: string
          description: A categorization of the tax rate
        taxRate:
          type: number
          format: float
          description: Applied rate
        taxAmount:
          $ref: '#/components/schemas/Money'
          description: Tax amount expressed in the given currency
        '@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
    BillingAccountRef:
      type: object
      description: Reference to the billing account in case of not billed item.
      properties:
        id:
          type: string
          description: Unique-Identifier for this <123>
        href:
          type: string
          description: URL serving as reference for the <xyz> resource
        name:
          type: string
          description: Name of the Billingaccount
        '@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
    AppliedBillingRateCharacteristic:
      type: object
      description: An applied billing rate has dynamic characteristics according to the its type (characteristics are based on the service type, line of business or on others parameters)
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: Name of the characteristic
        valueType:
          type: string
          description: Data type of the value of the characteristic
        value:
          $ref: '#/components/schemas/Any'
          description: The value of the characteristic
        '@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
    Any: {}
    ProductRef:
      type: object
      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.
        '@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
    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.
    BillRef:
      type: object
      description: Bill reference.
      properties:
        id:
          type: string
          description: Unique-Identifier for this <123>
        href:
          type: string
          description: URL serving as reference for the <xyz> resource
        '@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