MEF

MEF LSO Cantata Billing Management

Billing Management — the OpenAPI definition published by Mplify (formerly MEF) in the MEF LSO Cantata SDK, Kylie release. LSO Cantata is the Interface Reference Point between a Customer (typically an enterprise) and a Service Provider, covering the business/product layer. 5 path(s), 6 operation(s). Apache-2.0 licensed and openly downloadable from public GitHub.

GitHub OpenAPI

Documentation

📖
Documentation
https://lso.mplify.net/api-catalog
📖
APIReference
https://raw.githubusercontent.com/MEF-GIT/MEF-LSO-Cantata-SDK/kylie/productApi/billing/billingManagement.api.yaml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-cantata-billing-management-openapi.yml

Other Resources

🔗
SourceCode
https://github.com/MEF-GIT/MEF-LSO-Cantata-SDK/blob/kylie/productApi/billing/billingManagement.api.yaml
🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/overlays/mef-lso-cantata-billing-management-overlay.yaml

OpenAPI Specification

mef-lso-cantata-billing-management-openapi.yml Raw ↑ 
openapi: 3.0.1
info:
  title: Billing Management
  description: >
    **This file forms part of Mplify 141.1**


    **This API implements Business Requirements described in MEF 134.**


    Bill is a legal document generated by the Seller to the Buyer relating 

    to charges associated to Products provided by the Seller to the Buyer. 


    List of supported use cases:

    - Retrieve Invoice List

    - Retrieve Invoice by Identifier 

    - Retrieve Invoice Line Item by Identifier

    - Retrieve Printable Invoice   

    - Register for Invoice Notification


    Copyright 2025 Mplify Alliance and its contributors.


    This file includes content based on the TM Forum Customer Bill Management
    API (TMF678 v4.0.0) available at
    https://github.com/tmforum-apis/TMF678_CustomerBill, which is licensed by
    the TM Forum under the Apache License version 2.0. Such content has been
    modified by the Mplify Alliance and its contributors.
  version: 3.0.1
servers:
  - url: 'https://{serverBase}/mefApi/cantata/customerBillManagement/v3/'
    variables:
      serverBase:
        description: The base of Seller's URL.
        default: mplify.net
tags:
  - name: Customer Bill
  - name: Events Subscription
paths:
  /customerBill:
    get:
      tags:
        - Customer Bill
      summary: List or find CustomerBill objects
      description: This operation lists or finds CustomerBill entities
      operationId: listCustomerBill
      parameters:
        - name: billingAccount.id
          in: query
          description: >-
            An identifier for the Billing Account that is unique within the
            Seller.
          required: false
          schema:
            type: string
        - name: billingPeriod.startDateTime.lt
          in: query
          description: The date the Billing Period started - lower than.
          required: false
          schema:
            type: string
            format: date-time
        - name: billingPeriod.startDateTime.gt
          in: query
          description: The date the Billing Period started - greater than.
          required: false
          schema:
            type: string
            format: date-time
        - name: billingPeriod.endDateTime.lt
          in: query
          description: The date the Billing Period ended - lower than.
          required: false
          schema:
            type: string
            format: date-time
        - name: billingPeriod.endDateTime.gt
          in: query
          description: The date the Billing Period ended - greater than.
          required: false
          schema:
            type: string
            format: date-time
        - name: category
          in: query
          description: >-
            The category of Bill. One of the following:  - normal  - duplicate -
            trial
          required: false
          schema:
            type: string
            enum:
              - normal
              - duplicate
              - trial
        - name: state
          in: query
          description: The state of the Bill Item.
          required: false
          schema:
            type: string
            enum:
              - generated
              - paymentDue
              - settled
        - name: offset
          in: query
          description:
            Requested index for start of resources to be provided in response.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: Requested number of resources to be provided in response.
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Success
          headers:
            X-Pagination-Throttled:
              description: >
                Used to indicate that result page was throttled to maximum
                possible size  and there are additional results that can be
                fetched
              schema:
                type: boolean
            X-Total-Count:
              description: >
                The total number of matching records. E.g. if there are 50
                matching records in total, but the request has offset=10 and
                limit=10, then the X-Total-Count is 50.
              schema:
                type: integer
            X-Result-Count:
              description: The number of records included in the response
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerBill_Find'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '422':
          description: Unprocessable entity due to business validation problems
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Error422'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
  '/customerBill/{id}':
    get:
      tags:
        - Customer Bill
      summary: Retrieves a CustomerBill by ID
      description: This operation retrieves a CustomerBill entity.
      operationId: retrieveCustomerBill
      parameters:
        - name: id
          in: path
          description: Identifier of the CustomerBill
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerBill'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
  '/customerBillItem/{id}':
    get:
      tags:
        - Customer Bill
      summary: Retrieves a CustomerBillItem by ID
      description: This operation retrieves a CustomerBillItem entity.
      operationId: retrieveCustomerBillItem
      parameters:
        - name: id
          in: path
          description: Identifier of the CustomerBillItem
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerBillItem'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
  /hub:
    post:
      tags:
        - Events Subscription
      summary: Allows the Buyer to register to Bill state change notifications
      description: The Buyer requests to subscribe to Bill Notifications.
      operationId: registerListener
      parameters:
        - name: buyerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the a
            Buyer. MUST be specified in the request only when the requester
            represents more than one Buyer.
          required: false
          schema:
            type: string
        - name: sellerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Seller. MUST be specified in the request only when responding entity
            represents more than one Seller.
          required: false
          schema:
            type: string
      requestBody:
        description:
          Data containing the callback endpoint to deliver the information
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/EventSubscriptionInput'
        required: true
      responses:
        '201':
          description:
            'Subscribed  (https://tools.ietf.org/html/rfc7231#section-6.3.2)'
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/EventSubscription'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Method not implemented.
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error501'
  '/hub/{id}':
    get:
      tags:
        - Events Subscription
      summary: Retrieves a Hub by ID
      description: This operation retrieves a hub entity.
      operationId: retrieveHub
      parameters:
        - name: id
          in: path
          description: Identifier of the Hub
          required: true
          schema:
            type: string
        - name: buyerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the a
            Buyer. MUST be specified in the request only when the requester
            represents more than one Buyer.
          required: false
          schema:
            type: string
        - name: sellerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Seller. MUST be specified in the request only when responding
            entity  represents more than one Seller.
            9.18)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/EventSubscription'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Method not implemented.
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error501'
    delete:
      tags:
        - Events Subscription
      summary: Unregister a listener
      description: The Buyer requests to unsubscribe from Bill Notifications
      operationId: unregisterListener
      parameters:
        - name: id
          in: path
          description: The id of the EventSubscription
          required: true
          schema:
            type: string
        - name: buyerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the a
            Buyer. MUST be specified in the request only when the requester
            represents more than one Buyer.
          required: false
          schema:
            type: string
        - name: sellerId
          in: query
          description: >-
            The unique identifier of the organization that is acting as the
            Seller. MUST be specified in the request only when responding entity
            represents more than one Seller.
          required: false
          schema:
            type: string
      responses:
        '204':
          description:
            'Deleted (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
        '400':
          description: Bad request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Method not implemented.
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error501'
components:
  schemas:
    AppliedPayment:
      description:
        A list of details of a payment that has been received from the Buyer.
      type: object
      properties:
        appliedAmount:
          description: >-
            The amount of money that was received from the Buyer and applied to
            the Bill as payment.
          $ref: '#/components/schemas/Money'
        payment:
          description: A list of payment items that have been received.
          $ref: '#/components/schemas/PaymentItem'
    AttachmentURL:
      description: The URL pointing to an Attachment for download.
      type: object
      properties:
        url:
          description: The URL pointing to an Attachment for download.
          type: string
    BillingAccountRef:
      description:
        An identifier for the Billing Account that is unique within the Seller
      type: object
      properties:
        id:
          description: Unique-Identifier
          type: string
      required:
        - id
    CustomerBill:
      description: >-
        A legal document generated by the Seller to the Buyer relating to
        charges associated to Products provided by the Seller to the Buyer.
      type: object
      properties:
        id:
          description: An identifier assigned to the Bill by the Seller.
          type: string
        href:
          description: Bill's unique reference.
          type: string
        amountDue:
          description: >-
            The total amount of money with all taxes, fees, and credits applied
            that is due.
          $ref: '#/components/schemas/Money'
        appliedPayment:
          description: >-
            A list of details of a payment that has been received from the
            Buyer.
          type: array
          items:
            $ref: '#/components/schemas/AppliedPayment'
        billingAccount:
          description: >-
            An identifier for the Billing Account that is unique within the
            Seller and is assigned by the Seller.
          $ref: '#/components/schemas/BillingAccountRef'
        billCycle:
          description: The identifier of the Billing Cycle iteration.
          type: string
        billDate:
          description: Date the Bill was issued.
          type: string
          format: date-time
        billDocument:
          description: >-
            URL pointing to PDF file containing printable version of the
            Customer Bill.
          $ref: '#/components/schemas/AttachmentURL'
        billNo:
          description: A number assigned to the Bill by the Seller.
          type: string
        billingPeriod:
          description: The Start and Stop Dates of the Billing Period.
          $ref: '#/components/schemas/TimePeriod'
        category:
          description: |
            The type of Bill. One of the following:
            - normal
            - duplicate
            - trial
          $ref: '#/components/schemas/CustomerBillCategory'
        credits:
          description: Amount of credits included.
          $ref: '#/components/schemas/Money'
        customerBillItem:
          description: A reference to the Bill Items for this Bill.
          type: array
          items:
            $ref: '#/components/schemas/CustomerBillItemRef'
        discounts:
          description: Amount of discounts included.
          $ref: '#/components/schemas/Money'
        fees:
          description: Amount of fees included.
          $ref: '#/components/schemas/Money'
        financialAccount:
          description: A Financial Account within the Seller.
          $ref: '#/components/schemas/FinancialAccountRef'
        lastUpdate:
          description: The date when the Bill was last modified.
          type: string
          format: date-time
        paymentDueDate:
          description: >-
            The date by which payment of the Amount Due must be received by the
            Seller.
          type: string
          format: date-time
        runType:
          description: The Billing cycle as set by the Seller.
          $ref: '#/components/schemas/CustomerBillRunType'
        relatedContactInformation:
          description: A party related to this Bill.
          type: array
          items:
            $ref: '#/components/schemas/RelatedContactInformation'
        remainingAmount:
          description: An amount of money that still requires payment.
          $ref: '#/components/schemas/Money'
        state:
          description: The state of the Bill.
          $ref: '#/components/schemas/CustomerBillStateType'
        taxExcludedAmount:
          description: >-
            The amount of money due without taxes being calculated for the
            current Billing Cycle.
          $ref: '#/components/schemas/Money'
        taxIncludedAmount:
          description: >-
            The amount of money due with taxes being calculated for the current
            Billing Cycle.
          $ref: '#/components/schemas/Money'
        taxItem:
          description: >-
            A tax item is created for each tax rate and tax type used in the
            bill.
          type: array
          items:
            $ref: '#/components/schemas/TaxItem'
      required:
        - amountDue
        - appliedPayment
        - billCycle
        - billDate
        - billDocument
        - billNo
        - billingAccount
        - billingPeriod
        - category
        - credits
        - customerBillItem
        - discounts
        - fees
        - financialAccount
        - id
        - lastUpdate
        - paymentDueDate
        - relatedContactInformation
        - remainingAmount
        - runType
        - state
        - taxExcludedAmount
        - taxIncludedAmount
        - taxItem
    CustomerBillCategory:
      description: |
        The type of Bill. 

        | Value       | MEF 134   |Description                                                                                                                                                                    |
        | ----------- | --------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
        | `normal`    | NORMAL    |An Bill for the Billing Cycle                                                                                                                                                  |
        | `duplicate` | DUPLICATE |A copy of an Bill that has been provided                                                                                                                                       |
        | `trial`     | TRIAL     |An Bill that is sent by the Seller to the Buyer for test Billing purposes to assist in assuring that their Billing implementations are compatible. The Trial Bill is not paid. |
      type: string
      enum:
        - normal
        - duplicate
        - trial
    CustomerBillItem:
      description: >-
        One or more rows in a Bill that represent charges associated with a
        Product instance.
      type: object
      properties:
        id:
          description: The CustomerBillItem identifier.
          type: string
        href:
          description: Reference of the CustomerBillItem.
          type: string
        appliedTax:
          description: Taxes associated with the Bill Item.
          type: array
          items:
            $ref: '#/components/schemas/CustomerBillItemTax'
        appliedFee:
          type: array
          items:
            description: Fees associated with the Bill Item.
            $ref: '#/components/schemas/CustomerBillItemFee'
        customerBillItemType:
          description: The type of charge related to the Bill Item.
          $ref: '#/components/schemas/MEFPriceType'
        description:
          description: A text description of the charge.
          type: string
        periodCoverage:
          description: The start and end dates of Billing for the Bill Item.
          $ref: '#/components/schemas/TimePeriod'
        product:
          description:
            The reference to the Product that is the subject of the Item.
          $ref: '#/components/schemas/ProductRef'
        productOrderItem:
          description:
            Identifier of the POI with reference to the Product Order.
          $ref: '#/components/schemas/MEFProductOrderItemRef'
        productName:
          description:
            The name of the Product that is the subject of the Bill Item.
          type: string
        state:
          description: The state of the Bill Item.
          $ref: '#/components/schemas/CustomerBillItemStateType'
        taxExcludedAmount:
          description: >-
            The amount of money of the charge before taxes and fees are
            calculated and applied
          $ref: '#/components/schemas/Money'
        unit:
          description: >-
            The rate per unit for the Bill determined during or after the
            Billing Process.
          type: string
        unitRate:
          description: >-
            The rate per unit for the Bill determined during or after the
            Billing Process.
          $ref: '#/components/schemas/Money'
        unitQuantity:
          description: The number of units.
          type: number
      required:
        - appliedFee
        - appliedTax
        - customerBillItemType
        - description
        - id
        - periodCoverage
        - product
        - productName
        - productOrderItem
        - state
        - taxExcludedAmount
        - unit
        - unitQuantity
        - unitRate
    CustomerBillItemFee:
      description: Fees associated with the Bill Item.
      type: object
      properties:
        category:
          description: >-
            The category of the Fee. One of the following: - recurring -
            nonRecurring - other
          $ref: '#/components/schemas/CustomerBillItemFeeCategory'
        description:
          description: A description of the type of Fee.
          type: string
        rate:
          description: The rate at which the Fee is calculated.
          type: number
          format: float
        amount:
          description: The amount of money of the Fee.
          $ref: '#/components/schemas/Money'
    CustomerBillItemFeeCategory:
      description: |
        The category of the Fee. One of the following:
        - recurring
        - nonRecurring
        - other
      type: string
      enum:
        - recurring
        - nonRecurring
        - other
    CustomerBillItemRef:
      description: |
        A reference to a Customer Bill resource.
      type: object
      properties:
        href:
          description: |
            Hyperlink to the referenced Customer Bill.
          type: string
        id:
          description: Identifier of the referenced Customer Bill.
          type: string
      required:
        - id
    CustomerBillItemStateType:
      description: |
        The state of the Bill Item.

        | state                      | MEF 134 name               | Description                                                                                                                                                                   |
        | -------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | `credit`                   | CREDIT                     | The Seller has agreed with the Buyer that disputed charges are in error and has provided a credit for the amount in error.                                                    |
        | `disputeBeingInvestigated` | DISPUTE_BEING_INVESTIGATED | A Buyer has disputed charges included in a Bill and those charges are in the Sellers Dispute Process. Disputes cannot exit the dispute process until the Dispute is resolved. |
        | `generated`                | GENERATED                  | A Bill that has been created based on the completion of a Billing Cycle and a Bill Notification has been sent to the Buyer.                                                   |
        | `paymentDue`               | PAYMENT_DUE                | The Seller has completed their dispute process and they are expecting payment from the Buyer.                                                                                 |
        | `settled`                  | SETTLED                    | A Bill for which all payment due has been received or for which payment is due.                                                                                               |
        | `withdrawn`                | WITHDRAWN                  | A Seller has agreed with the Buyer that disputed charges are in error and has withdrawn the Bill.                                                                            |
      type: string
      enum:
        - credit
        - disputeBeingInvestigated
        - generated
        - paymentDue
        - settled
        - withDrawn
    CustomerBillItemTax:
      description: >-
        The applied billing tax rate represents the taxes applied billing rate
        it refers to. It is calculated during the billing process.
      type: object
      properties:
        category:
          description: The category of the Tax.
          $ref: '#/components/schemas/CustomerBillItemTaxCategory'
        description:
          description: A description of the type of Tax.
          type: string
        rate:
          description: The rate at which the Tax is calculated.
          type: number
          format: float
        amount:
          description: The amount of money of the Tax.
          $ref: '#/components/schemas/Money'
    CustomerBillItemTaxCategory:
      description: |-
        The category of the Tax. One of the following:
          - country
          - state
          - county
          - city
          - other
      type: string
      enum:
        - country
        - state
        - county
        - city
        - other
    CustomerBillRunType:
      description: |
        The Billing cycle as set by the Seller.

        | Value      | MEF 134   | Description                                                                                                  |
        | ---------- | --------- | ------------------------------------------------------------------------------------------------------------ |
        | `onCycle`  | On_Cycle  | Bill created as a result of the normal Invoicing Cycle                                                       | 
        | `offCycle` | Off_Cycle | Bill created outside the normal Invoicing Cycle.  This may be based on a Buyer request or for other reasons. |
      type: string
      enum:
        - onCycle
        - offCycle
    CustomerBillStateType:
      description: |
        The state of the Bill.

        | state                     | MEF 134 name               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
        | -----------------------   | ----------------------     | ------------------------------------------------------------------------------------------------------------------------------|
        | `generated`               | GENERATED                  | A Bill that has been created based on the completion of an Billing Cycle and an Bill Notification has been sent to the Buyer. |
        | `paymentDue`              | PAYMENT_DUE                | The Seller has completed their dispute process and they are expecting payment from the Buyer                                  |
        | `settled`                 | SETTLED                    | A Bill for which all payment due has been received or for which payment is due.             

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-cantata-billing-management-openapi.yml