MEF

MEF LSO Sonata Billing Management

Billing Management — the OpenAPI definition published by Mplify (formerly MEF) in the MEF LSO Sonata SDK, Kylie release. LSO Sonata is the Interface Reference Point between two Service Providers (Buyer and Seller), covering inter-provider business/product automation. 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-Sonata-SDK/kylie/productApi/billing/billingManagement.api.yaml

Specifications

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

Other Resources

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

OpenAPI Specification

mef-lso-sonata-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/sonata/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-sonata-billing-management-openapi.yml