MEF Product Ordering Notification (Mef Lso Cantata Product Order Notification)

openapi: 3.0.1
info:
  title: Product Ordering Notification
  description: >
    **This file forms part of Mplify 123.1** 

    This API implements Business Requirements described in MEF 57.2 and Mplify
    57.2.1


    Product Order Management allows the Buyer to request the Seller to initiate
    and complete the

    fulfillment process of an installation of a Product Offering, an update to

    an existing Product, or a disconnect of an existing Product at the address

    defined by the Buyer.


    List of supported Use Cases:


    - Send Notifications


    - Initiate Charge


    Copyright 2025 Mplify Alliance and its contributors


    This file includes content based on the TM Forum Product Order API (TMF622

    v4.0.0) available at https://github.com/tmforum-apis/TMF622_ProductOrder,

    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: 6.0.1
servers:
  - url: 'https://{serverBase}/mefApi/cantata/productOrderingNotification/v6/'
    variables:
      serverBase:
        description: The base of Buyer's URL.
        default: mplify.net
tags:
  - name: Notification listeners
    description: |
      The Seller's endpoint to send particular event types notifications to.
paths:
  /listener/productOrderStateChangeEvent:
    post:
      tags:
        - Notification listeners
      summary: Product Order State Change Notification endpoint
      description: >-
        This endpoint is used to receive notifications on Product Order state
        change
      operationId: productOrderStateChangeEvent
      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:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ProductOrderStateChangeEvent'
        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/productOrderItemStateChangeEvent:
    post:
      tags:
        - Notification listeners
      summary: Product Order Item State Change Notification endpoint
      description: >-
        This endpoint is used to receive notifications on Product Order Item
        state change
      operationId: productOrderItemStateChangeEvent
      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:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ProductOrderItemStateChangeEvent'
        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/productOrderItemExpectedCompletionDateSetEvent:
    post:
      tags:
        - Notification listeners
      summary:
        Product Order Item Expected Completion Date Set Notification endpoint
      description: >-
        This endpoint is used to receive notifications on Product Order Item
        Expected Completion Date Set
      operationId: productOrderItemExpectedCompletionDateSetEvent
      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:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: >-
                #/components/schemas/ProductOrderItemExpectedCompletionDateSetEvent
        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/productSpecificProductOrderItemMilestoneEvent:
    post:
      tags:
        - Notification listeners
      summary:
        Product Specific Product Order Item Milestone Notification endpoint
      description: >-
        This endpoint is used to receive notifications on Product Specific
        Product Order Item Milestone reached
      operationId: productSpecificProductOrderItemMilestoneEvent
      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:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: >-
                #/components/schemas/ProductSpecificProductOrderItemMilestoneEvent
        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/cancelProductOrderStateChangeEvent:
    post:
      tags:
        - Notification listeners
      summary: Cancel Product Order State Change Notification endpoint
      description: >-
        This endpoint is used to receive notifications on Cancel Product Order
        State Change Event
      operationId: cancelProductOrderStateChangeEvent
      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/CancelProductOrderStateChangeEvent'
        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/chargeCreateEvent:
    post:
      tags:
        - Notification listeners
      summary: Charge Create Notification endpoint
      description:
        This endpoint is used to receive notifications on Charge Create Event
      operationId: chargeCreateEvent
      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/ChargeCreateEvent'
        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/chargeStateChangeEvent:
    post:
      tags:
        - Notification listeners
      summary: Charge State Change Notification endpoint
      description: >-
        This endpoint is used to receive notifications on Charge state change
        event
      operationId: chargeStateChangeEvent
      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/ChargeStateChangeEvent'
        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/chargeTimeoutEvent:
    post:
      tags:
        - Notification listeners
      summary: Charge State Change Notification endpoint
      description:
        This endpoint is used to receive notifications on Charge timeout event
      operationId: chargeTimeoutEvent
      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/ChargeTimeoutEvent'
        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/modifyProductOrderItemRequestedDeliveryDateStateChangeEvent:
    post:
      tags:
        - Notification listeners
      summary: >-
        Modify Product Order Item Requested Delivery Date State Change
        Notification endpoint
      description: >-
        This endpoint is used to receive notifications on Modify Product Order
        Item Requested Delivery Date State Change Event
      operationId: modifyProductOrderItemRequestedDeliveryDateStateChangeEvent
      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/ModifyProductOrderItemRequestedDeliveryDateStateChangeEvent
        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:
    CancelProductOrderStateChangeEvent:
      allOf:
        - $ref: '#/components/schemas/Event'
        - type: object
          properties:
            eventType:
              description: |
                Indicates the type of the event.
              type: string
              enum:
                - cancelProductOrderStateChangeEvent
            event:
              description: |
                A reference to the object that is source of the notification.
              $ref: '#/components/schemas/CancelProductOrderStateChangeEventPayload'
          required:
            - event
            - eventType
    CancelProductOrderStateChangeEventPayload:
      description:
        The identifier of the Cancel Product Order being subject of this event.
      type: object
      properties:
        id:
          description: ID of the Cancel Product Order
          type: string
        href:
          description: Hyperlink to access the Cancel Product Order
          type: string
        state:
          description: The state reached
          $ref: '#/components/schemas/MEFChargeableTaskStateType'
      required:
        - id
        - state
    ChargeCreateEvent:
      allOf:
        - $ref: '#/components/schemas/Event'
        - type: object
          properties:
            eventType:
              description: |
                Indicates the type of the event.
              type: string
              enum:
                - chargeCreateEvent
            event:
              description: |
                A reference to the object that is source of the notification.
              $ref: '#/components/schemas/ChargeEventPayload'
          required:
            - event
            - eventType
    ChargeEventPayload:
      description: The identifier of the Charge being subject of this event.
      type: object
      properties:
        id:
          description: ID of the Charge
          type: string
        href:
          description: Hyperlink to access the Charge
          type: string
      required:
        - id
    ChargeStateChangeEvent:
      allOf:
        - $ref: '#/components/schemas/Event'
        - type: object
          properties:
            eventType:
              description: |
                Indicates the type of the event.
              type: string
              enum:
                - chargeStateChangeEvent
            event:
              description: |
                A reference to the object that is source of the notification.
              $ref: '#/components/schemas/ChargeStateChangeEventPayload'
          required:
            - event
            - eventType
    ChargeStateChangeEventPayload:
      description: The identifier of the Charge being subject of this event.
      type: object
      properties:
        id:
          description: ID of the Charge
          type: string
        href:
          description: Hyperlink to access the Charge
          type: string
        state:
          description: The state reached
          $ref: '#/components/schemas/MEFProductOrderChargeStateType'
      required:
        - id
        - state
    ChargeTimeoutEvent:
      allOf:
        - $ref: '#/components/schemas/Event'
        - type: object
          properties:
            eventType:
              description: |
                Indicates the type of the event.
              type: string
              enum:
                - chargeTimeoutEvent
            event:
              description: |
                A reference to the object that is source of the notification.
              $ref: '#/components/schemas/ChargeEventPayload'
          required:
            - event
            - eventType
    Error:
      description: >
        Standard Class used to describe API response error

        Not intended to be use directly. The `code` in the HTTP header is used
        as a discriminator for the type of error returned in runtime.
      type: object
      properties:
        reason:
          description: >-
            Text that explains the reason for error. This can be shown to a
            client user.
          type: string
          maxLength: 255
        message:
          description: >-
            Text that provide mode details and corrective actions related to the
            error. This can be shown to a client user.
          type: string
        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. (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
    MEFChargeableTaskStateType:
      description: |
        The states as defined by TMF622 and extended to meet MEF requirements.

        | Name                       | MEF 57.2 Name    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
        | -------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | inProgress.assessingCharge | ACCESSING_CHARGE | The Modify Product Order Item Requested Delivery Date request results in a Charge being initiated by the Seller. The Modify Product Order Item Requested Delivery Date remains in this state until the Charge is completed or withdrawn by the Seller. All charges within a Charge that was initiated due to a Modify Product Order Item Requested Delivery Date are considered Blocking charges. If any charge is not accepted by the Buyer, the Modify Product Order Item Requested Delivery Date moves from the `inProgress.assessingCharge` state to the `done.declined` state. |
        | acknowledged               | ACKNOWLEDGED     | A Modify Product Order Item Requested Delivery Date request has been received and has passed basic validation. The Modify Product Order Item Requested Delivery Date Identifier is assigned in the `acknowledged` state. Validation of Modify Product Order Item Requested Delivery Date attributes as applicable is completed in the `acknowledged` state.                                                                                                                                                                                                                         |
        | done                       | ACCEPTED         | A Modify Product Order Item Requested Delivery Date request has been received, passed all validations, if a Charge is associated all Charge Items have been accepted

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