swagger: '2.0'
info:
title: API CustomerBill
description: |-
## TMF API Reference: TMF 678 - Customer bill Management
### Release: 19.5 - December 2019
The 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...
This API provides also operations to find and retrieve the details of applied customer billing rates presented on a customer bill.
Finally, this API allows to request in real-time a customer bill creation and to manage this request.
### Resources
- customerBill
- appliedCustomerBillingRate
- customerBillOnDemand
- billingCycle
### Operations
Customer Bill Management API performs the following operations :
- Retrieve a customer bill or a collection of customer bills depending on filter criteria.
- Partial update of a customer bill (for administration purposes).
- Retrieve an applied customer billing rate or a collection of applied customer billing rates depending on filter criteria.
- Create a customer bill on demand request, retrieve one or a collection of customer bill on demand request(s) depending on filter criteria.
- Manage notification of events on customer bill and customer bill on demand.
Copyright © TM Forum 2018. All Rights Reserved.
version: 4.0.0
host: serverRoot
basePath: /tmf-api/customerBillManagement/v4/
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/json;charset=utf-8
tags:
- name: customerBillOnDemand
- name: customerBill
- name: appliedCustomerBillingRate
- name: events subscription
paths:
/customerBillOnDemand:
get:
operationId: listCustomerBillOnDemand
summary: List or find CustomerBillOnDemand objects
description: This operation list or find CustomerBillOnDemand entities
tags:
- customerBillOnDemand
parameters:
- name: fields
description: Comma-separated properties to be provided in response
required: false
in: query
type: string
- name: offset
description: Requested index for start of resources to be provided in response
required: false
in: query
type: integer
- name: limit
description: Requested number of resources to be provided in response
required: false
in: query
type: integer
responses:
'200':
description: Success
headers:
X-Result-Count:
description: Actual number of items returned in the response body
type: integer
X-Total-Count:
description: Total number of items matching criteria
type: integer
schema:
type: array
items:
$ref: '#/definitions/CustomerBillOnDemand'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
post:
operationId: createCustomerBillOnDemand
summary: Creates a CustomerBillOnDemand
description: This operation creates a CustomerBillOnDemand entity.
tags:
- customerBillOnDemand
parameters:
- name: customerBillOnDemand
description: The CustomerBillOnDemand to be created
required: true
schema:
$ref: '#/definitions/CustomerBillOnDemand_Create'
in: body
responses:
'201':
description: Created
schema:
$ref: '#/definitions/CustomerBillOnDemand'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/customerBillOnDemand/{id}:
get:
operationId: retrieveCustomerBillOnDemand
summary: Retrieves a CustomerBillOnDemand by ID
description: This operation retrieves a CustomerBillOnDemand entity. Attribute selection is enabled for all first level attributes.
tags:
- customerBillOnDemand
parameters:
- name: id
description: Identifier of the CustomerBillOnDemand
required: true
type: string
in: path
- name: fields
description: Comma-separated properties to provide in response
required: false
type: string
in: query
responses:
'200':
description: Success
schema:
$ref: '#/definitions/CustomerBillOnDemand'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/customerBill:
get:
operationId: listCustomerBill
summary: List or find CustomerBill objects
description: This operation list or find CustomerBill entities
tags:
- customerBill
parameters:
- name: fields
description: Comma-separated properties to be provided in response
required: false
in: query
type: string
- name: offset
description: Requested index for start of resources to be provided in response
required: false
in: query
type: integer
- name: limit
description: Requested number of resources to be provided in response
required: false
in: query
type: integer
responses:
'200':
description: Success
headers:
X-Result-Count:
description: Actual number of items returned in the response body
type: integer
X-Total-Count:
description: Total number of items matching criteria
type: integer
schema:
type: array
items:
$ref: '#/definitions/CustomerBill'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/customerBill/{id}:
get:
operationId: retrieveCustomerBill
summary: Retrieves a CustomerBill by ID
description: This operation retrieves a CustomerBill entity. Attribute selection is enabled for all first level attributes.
tags:
- customerBill
parameters:
- name: id
description: Identifier of the CustomerBill
required: true
type: string
in: path
- name: fields
description: Comma-separated properties to provide in response
required: false
type: string
in: query
responses:
'200':
description: Success
schema:
$ref: '#/definitions/CustomerBill'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
patch:
operationId: patchCustomerBill
summary: Updates partially a CustomerBill
description: This operation updates partially a CustomerBill entity.
tags:
- customerBill
parameters:
- name: id
description: Identifier of the CustomerBill
required: true
type: string
in: path
- name: customerBill
description: The CustomerBill to be updated
required: true
schema:
$ref: '#/definitions/CustomerBill_Update'
in: body
responses:
'200':
description: Updated
schema:
$ref: '#/definitions/CustomerBill'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/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
type: string
- name: offset
description: Requested index for start of resources to be provided in response
required: false
in: query
type: integer
- name: limit
description: Requested number of resources to be provided in response
required: false
in: query
type: integer
responses:
'200':
description: Success
headers:
X-Result-Count:
description: Actual number of items returned in the response body
type: integer
X-Total-Count:
description: Total number of items matching criteria
type: integer
schema:
type: array
items:
$ref: '#/definitions/AppliedCustomerBillingRate'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/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
type: string
in: path
- name: fields
description: Comma-separated properties to provide in response
required: false
type: string
in: query
responses:
'200':
description: Success
schema:
$ref: '#/definitions/AppliedCustomerBillingRate'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/hub:
post:
operationId: registerListener
summary: Register a listener
description: Sets the communication endpoint address the service instance must use to deliver information about its health state, execution state, failures and metrics.
tags:
- events subscription
parameters:
- name: data
schema:
$ref: '#/definitions/EventSubscriptionInput'
required: true
in: body
description: Data containing the callback endpoint to deliver the information
responses:
'201':
description: Subscribed
schema:
$ref: '#/definitions/EventSubscription'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/hub/{id}:
delete:
operationId: unregisterListener
summary: Unregister a listener
description: Resets the communication endpoint address the service instance must use to deliver information about its health state, execution state, failures and metrics.
tags:
- events subscription
parameters:
- name: id
type: string
required: true
in: path
description: The id of the registered listener
responses:
'204':
description: Deleted
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method not allowed
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
definitions:
AccountBalance:
type: object
description: Balances linked to the account
required:
- amount
- balanceType
- validFor
properties:
balanceType:
type: string
description: 'Type of the balance : deposit balance, disputed balance, loyalty balance, receivable balance...'
amount:
$ref: '#/definitions/Money'
description: Balance amount
validFor:
$ref: '#/definitions/TimePeriod'
description: Balance validity period
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
Any: {}
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: '#/definitions/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
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: '#/definitions/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
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: '#/definitions/AppliedBillingTaxRate'
bill:
$ref: '#/definitions/BillRef'
billingAccount:
$ref: '#/definitions/BillingAccountRef'
characteristic:
type: array
items:
$ref: '#/definitions/AppliedBillingRateCharacteristic'
periodCoverage:
$ref: '#/definitions/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: '#/definitions/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: '#/definitions/Money'
taxIncludedAmount:
$ref: '#/definitions/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
AppliedPayment:
type: object
description: The applied payment is the result of lettering process. It enables to assign automatically or manually part of incoming payment amount to a bill.
properties:
appliedAmount:
$ref: '#/definitions/Money'
payment:
$ref: '#/definitions/PaymentRef'
'@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
Attachment:
type: object
description: Complements the description of an element (for instance a product) through video, pictures...
properties:
id:
type: string
description: Unique identifier for this particular attachment
href:
type: string
description: URI for this Attachment
attachmentType:
type: string
description: Attachment type such as video, picture
content:
type: string
description: The actual contents of the attachment object, if embedded, encoded as base64
description:
type: string
description: A narrative text describing the content of the attachment
mimeType:
type: string
description: Attachment mime type such as extension file for video, picture and document
name:
type: string
description: The name of the attachment
url:
type: string
description: Uniform Resource Locator, is a web page address (a subset of URI)
size:
$ref: '#/definitions/Quantity'
description: The size of the attachment.
validFor:
$ref: '#/definitions/TimePeriod'
description: The period of time for which the attachment is valid
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
AttachmentRef:
type: object
description: Attachment reference. An attachment complements the description of an element (for instance a product) through video, pictures
properties:
id:
type: string
description: Unique-Identifier for this attachment
href:
type: string
description: URL serving as reference for the attachment resource
description:
type: string
description: A narrative text describing the content of the attachment
name:
type: string
description: Name of the related entity.
url:
type: string
description: Link to the attachment media/content
'@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
AttachmentRefOrValue:
type: object
description: An attachment by value or by reference. For AttachmentRefOrValue, the attribute type,schemaLocation and referredType are related to the contained entity and not to AttchmentRefOrValue itself
properties:
id:
type: string
description: Unique identifier for this particular attachment
href:
type: string
description: URI for this Attachment
attachmentType:
type: string
description: Attachment type such as video, picture
content:
type: string
description: The actual contents of the attachment object, if embedded, encoded as base64
description:
type: string
description: A narrative text describing the content of the attachment
mimeType:
type: string
description: Attachment mime type such as extension file for video, picture and document
name:
type: string
description: The name of the attachment
url:
type: string
description: Uniform Resource Locator, is a web page address (a subset of URI)
size:
$ref: '#/definitions/Quantity'
description: The size of the attachment.
validFor:
$ref: '#/definitions/TimePeriod'
description: The period of time for which the attachment is valid
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
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
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
Characteristic:
type: object
description: Describes a given characteristic of an object or entity through a name/value pair.
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: '#/definitions/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
CustomerBill:
type: object
description: |-
The billing account receives all charges (recurring, one time and usage) of the offers and products assigned to it during order process. Periodically according to billing cycle specifications attached to the billing account or as a result of an event, a customer bill (aka invoice) is produced. This customer bill concerns different related parties which play a role on it : for example, a customer bill is produced by an operator, is sent to a bill receiver and has to be paid by a payer.
A payment method could be assigned to the customer bill to build the call of payment. Lettering process enables to assign automatically or manually incoming amount f
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-tmf-customer-bill-management.yml