MEF Billing Management (Mef Lso Cantata Billing Management)
MEF Billing Management from MEF — 5 path(s) described in OpenAPI.
OpenAPI Specification
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