openapi: 3.0.1 info: title: Billing Notification description: > **This file forms part of Mplify 141.1** 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: - Generate Invoice Notifications 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/customerBillNotification/v3/' variables: serverBase: description: The base of Buyer's URL. default: mplify.net tags: - name: Notification listeners description: | The Buyer's endpoint to send particular event types notifications to. paths: /listener/customerBillCreateEvent: post: tags: - Notification listeners summary: Client listener for customerBillCreateEvent description: Client listener for receiving the billCreatedEvent notification operationId: listen to Customer Bill Create Event parameters: - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the Buyer. MUST be specified in the request 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 when the responding entity represents more than one Seller. required: false schema: type: string requestBody: description: The event data content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/CustomerBillCreateEvent' required: true responses: '204': description: 'No Content (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' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' /listener/customerBillStateChangeEvent: post: tags: - Notification listeners summary: Client listener for customerBillStateChangeEvent description: >- Client listener for receiving the customerBillStateChangeEvent notification operationId: listen to customer Bill State Change Event parameters: - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the Buyer. MUST be specified in the request 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 when the responding entity represents more than one Seller. required: false schema: type: string requestBody: description: The event data content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/CustomerBillStateChangeEvent' required: true responses: '204': description: 'No Content (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' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' components: schemas: CustomerBillCreateEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: eventType: description: Indicates the type of the event. type: string enum: - customerBillCreateEvent event: description: | A reference to the object that is source of the notification. $ref: '#/components/schemas/CustomerBillCreateEventPayload' required: - event - eventType CustomerBillCreateEventPayload: description: The identifier of the Bill being subject of this event. type: object properties: id: description: ID of the Bill attributed by quoting system type: string href: description: Hyperlink to access the Bill type: string required: - id CustomerBillStateChangeEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: eventType: description: Indicates the type of the event. type: string enum: - customerBillStateChangeEvent event: description: | A reference to the object that is source of the notification. $ref: '#/components/schemas/CustomerBillStateChangeEventPayload' required: - event - eventType CustomerBillStateChangeEventPayload: description: The identifier of the Bill being subject of this event. type: object properties: id: description: ID of the Bill attributed by quoting system type: string href: description: Hyperlink to access the Bill type: string state: description: The state of the Bill. $ref: '#/components/schemas/CustomerBillStateType' required: - id - state 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. | | type: string enum: - generated - paymentDue - settled Error: description: > Standard Class used to describe API response error Not intended to be used directly. The `code` in the HTTP header is used as a discriminator for the type of error returned in runtime. type: object properties: message: description: >- Text that provides mode details and corrective actions related to the error. This can be shown to a client user. type: string reason: description: >- Text that explains the reason for the error. This can be shown to a client user. type: string maxLength: 255 referenceError: description: URL pointing to documentation describing the error type: string format: uri required: - reason Error400: description: 'Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)' allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: >- One of the following error codes: - missingQueryParameter: The URI is missing a required query-string parameter - missingQueryValue: The URI is missing a required query-string parameter value - invalidQuery: The query section of the URI is invalid. - invalidBody: The request has an invalid body $ref: '#/components/schemas/Error400Code' required: - code Error400Code: description: >- One of the following error codes: - missingQueryParameter: The URI is missing a required query-string parameter - missingQueryValue: The URI is missing a required query-string parameter value - invalidQuery: The query section of the URI is invalid. - invalidBody: The request has an invalid body type: string enum: - missingQueryParameter - missingQueryValue - invalidQuery - invalidBody Error401: description: 'Unauthorized. (https://tools.ietf.org/html/rfc7235#section-3.1)' allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: >- One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired $ref: '#/components/schemas/Error401Code' required: - code Error401Code: description: |- One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired type: string enum: - missingCredentials - invalidCredentials Error403: description: >- Forbidden. This code indicates that the server understood the request but refuses to authorize it. (https://tools.ietf.org/html/rfc7231#section-6.5.3) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: |- This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users $ref: '#/components/schemas/Error403Code' required: - code Error403Code: description: |- This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users type: string enum: - accessDenied - forbiddenRequester - tooManyUsers Error500: description: >- Internal Server Error. (https://tools.ietf.org/html/rfc7231#section-6.6.1) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: >- The following error code: - internalError: Internal server error - the server encountered an unexpected condition that prevented it from fulfilling the request. type: string enum: - internalError required: - code Event: description: >- Event class is used to describe information structure used for notification. type: object properties: eventId: description: Id of the event type: string eventTime: description: Date-time when the event occurred type: string format: date-time eventType: description: The type of the notification. type: string event: description: The event linked to the involved resource object type: object required: - event - eventId - eventTime - eventType