MEF Product Order API

openapi: 3.2.0
info:
  title: Mef Product Order API
  version: '1.0'
  description: 'Operations tagged productOrder across 2 of this provider''s published API definitions: mef-lso-cantata-product-order-management-openapi.yml, mef-lso-sonata-product-order-management-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{serverBase}/mefApi/cantata/productOrderingManagement/v6/
  variables:
    serverBase:
      description: The base of Seller's URL.
      default: mplify.net
- url: https://{serverBase}/mefApi/sonata/productOrderingManagement/v11/
  variables:
    serverBase:
      description: The base of Seller's URL.
      default: mplify.net
tags:
- name: productOrder
paths:
  /productOrder:
    get:
      tags:
      - productOrder
      summary: Lists or finds ProductOrder objects
      description: This operation lists or finds ProductOrder entities
      operationId: listProductOrder
      parameters:
      - name: state
        in: query
        description: State of the Product Order
        required: false
        schema:
          type: string
          enum:
          - acknowledged
          - assessingCancellation
          - cancelled
          - completed
          - failed
          - held.assessingCharge
          - inProgress
          - partial
          - pending.assessingModification
          - pendingCancellation
          - rejected
      - name: externalId
        in: query
        description: A number that uniquely identifies an order within the Buyer's enterprise.
        required: false
        schema:
          type: string
      - name: projectId
        in: query
        description: An identifier that is used to group Product Orders that represent a unit of functionality that is important to a Buyer.
        required: false
        schema:
          type: string
      - name: orderDate.gt
        in: query
        description: Date when the order was created greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: orderDate.lt
        in: query
        description: Date when the order was created lesser than
        required: false
        schema:
          type: string
          format: date-time
      - name: completionDate.gt
        in: query
        description: Effective completion date greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: completionDate.lt
        in: query
        description: Effective completion date lesser than
        required: false
        schema:
          type: string
          format: date-time
      - name: itemRequestedCompletionDate.gt
        in: query
        description: This is requested date to get this Product Order Item completed greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: itemRequestedCompletionDate.lt
        in: query
        description: This is requested date to get this Product Order Item completed lesser than
        required: false
        schema:
          type: string
          format: date-time
      - name: itemExpectedCompletionDate.gt
        in: query
        description: Seller planned completion date of the Product Order Item, greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: itemExpectedCompletionDate.lt
        in: query
        description: Seller planned completion date of the Product Order Item, lesser than
        required: false
        schema:
          type: string
          format: date-time
      - name: cancellationDate.gt
        in: query
        description: order cancellation date greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: cancellationDate.lt
        in: query
        description: order cancellation date lesser than
        required: false
        schema:
          type: string
          format: date-time
      - 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 the responding entity represents more than one Seller.
        required: false
        schema:
          type: string
      - name: offset
        in: query
        description: Requested index for start of item to be provided in response requested by the client. Note that the index starts with "0".
        required: false
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: Requested number of items to be provided in response requested by client
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)
          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 items. E.g. if there are 50 matching items 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 items included in the response
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductOrder_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 the 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'
    post:
      tags:
      - productOrder
      summary: Creates a ProductOrder
      description: This operation creates a ProductOrder entity.
      operationId: createProductOrder
      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 the responding entity represents more than one Seller.
        required: false
        schema:
          type: string
      requestBody:
        description: The ProductOrder to be created
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ProductOrder_Create'
        required: true
      responses:
        '201':
          description: Created (https://tools.ietf.org/html/rfc7231#section-6.3.2)
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ProductOrder'
        '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 the 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'
    servers:
    - url: https://{serverBase}/mefApi/cantata/productOrderingManagement/v6/
      variables:
        serverBase:
          description: The base of Seller's URL.
          default: mplify.net
  /productOrder/{id}:
    get:
      tags:
      - productOrder
      summary: Retrieves a ProductOrder by ID
      description: This operation retrieves a ProductOrder entity.
      operationId: retrieveProductOrder
      parameters:
      - name: id
        in: path
        description: Identifier of the ProductOrder
        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:
        '200':
          description: OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ProductOrder'
        '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'
    patch:
      tags:
      - productOrder
      summary: Updates partially a ProductOrder
      description: This operation updates partially a ProductOrder entity.
      operationId: patchProductOrder
      parameters:
      - name: id
        in: path
        description: Identifier of the ProductOrder
        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
      requestBody:
        description: The ProductOrder to be updated
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ProductOrder_Update'
        required: true
      responses:
        '200':
          description: Updated (https://tools.ietf.org/html/rfc7231#section-6.3.1)
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ProductOrder'
        '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'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error409'
        '422':
          description: Unprocessable entity due to the 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'
        '501':
          description: Method not implemented.
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error501'
    servers:
    - url: https://{serverBase}/mefApi/cantata/productOrderingManagement/v6/
      variables:
        serverBase:
          description: The base of Seller's URL.
          default: mplify.net
components:
  schemas:
    RelatedPlaceRefOrQueryWithSubUnit:
      description: Allows pointing to a place by referring a GeographicAddress, GeographicSite, or providing GeographicAddress by value. It also provides additional information like the `role` the place plays for given Product, `subUnit` to provide more detailed information about the precise location of the installation and `contact` needed access to this place.
      type: object
      properties:
        place:
          description: A place described by reference to Geographic Address, Geographic Site or by Geographic Address Representations.
          $ref: '#/components/schemas/PlaceRefOrQuery'
        role:
          description: Role of this place. The values that can be specified here are described by Product Specification (e.g. "INSTALL_LOCATION").
          type: string
        subUnit:
          description: A list of zero or more sub units included within the boundary of the `place` for this POQ Item. This is a list to allow complex sub-unit information such as SUITE 42 ROOM A
          type: array
          items:
            $ref: '#/components/schemas/SubUnit'
        contact:
          description: The person to call to get access to this place in case such access is required to complete the evaluation of this POQ Item.
          type: array
          items:
            $ref: '#/components/schemas/ContactInformation'
      required:
      - place
      - role
    TimeUnit:
      description: 'Represents a unit of time.

        '
      type: string
      enum:
      - seconds
      - minutes
      - businessHours
      - calendarHours
      - businessDays
      - calendarDays
      - months
      - years
    ProductRelationship:
      description: A relationship to an existing Product. The requirements for usage for given Product are described in the Product Specification.
      type: object
      properties:
        href:
          description: Hyperlink to the product in Seller's inventory that is referenced Hyperlink MAY be used when providing a response by the Seller Hyperlink MUST be ignored by the Seller in case it is provided by the Buyer in a request
          type: string
        id:
          description: unique identifier of the related Product
          type: string
        relationshipType:
          description: 'Specifies the type (nature) of the relationship to the related Product. The nature of required relationships varies for Products of different types. For example, a UNI or ENNI Product may not have any relationships, but an Access E-Line may have two mandatory relationships (related to the UNI on one end and the ENNI on the other). More complex Products such as multipoint IP or Firewall Products may have more complex relationships. As a result, the allowed and mandatory `relationshipType` values are defined in the Product Specification.

            '
          type: string
      required:
      - id
      - relationshipType
    MEFProductOrderStateChange:
      description: Holds the State notification reasons and associated date the State changed, populated by the server
      type: object
      properties:
        changeDate:
          description: The date on when the state was reached
          type: string
          format: date-time
        changeReason:
          description: Additional comment related to state change
          type: string
        state:
          description: Reached state
          $ref: '#/components/schemas/MEFProductOrderStateType'
    Note:
      description: Extra information about a given entity. Only useful in processes involving human interaction. Not applicable for the automated process.
      type: object
      properties:
        author:
          description: Author of the note
          type: string
        date:
          description: Date the Note was created
          type: string
          format: date-time
        id:
          description: Identifier of the note within its containing entity (may or may not be globally unique, depending on provider implementation)
          type: string
        source:
          description: Indicates if the note is from Buyer or Seller
          $ref: '#/components/schemas/MEFBuyerSellerType'
        text:
          description: Text of the note
          type: string
      required:
      - author
      - date
      - id
      - source
      - text
    ProductOrder_Create:
      allOf:
      - $ref: '#/components/schemas/ProductOrder_Common'
      - description: 'A Product Order is a type of order which  can  be used to place an order between a customer and a service provider or between a service provider and a partner and vice versa, Skipped properties: id,href,completionDate,orderDate,state,stateChange,cancellationDate,cancellationReason

          '
        type: object
        properties:
          productOrderItem:
            description: 'Items contained in the Product Order.

              '
            type: array
            minItems: 1
            items:
              $ref: '#/components/schemas/MEFProductOrderItem_Create'
        required:
        - productOrderItem
    ContactInformation:
      description: Contact data for a person or organization that is involved in the product offering qualification. In a given context it is always specified by the Seller (e.g. Seller Contact Information) or by the Buyer.
      type: object
      properties:
        number:
          description: Phone number
          type: string
        emailAddress:
          description: Email address
          type: string
        postalAddress:
          description: Identifies the postal address of the person or office to be contacted.
          $ref: '#/components/schemas/FieldedAddressRepresentation'
        organization:
          description: The organization or company that the contact belongs to
          type: string
        name:
          description: Name of the contact
          type: string
        numberExtension:
          description: Phone number extension
          type: string
      required:
      - emailAddress
      - name
      - number
    PlaceRefOrQuery:
      description: A place described by reference to Geographic Address, Geographic Site or by Geographic Address Representations.
      type: object
      discriminator:
        propertyName: '@type'
        mapping:
          GeographicAddressRef: '#/components/schemas/GeographicAddressRef'
          GeographicSiteRef: '#/components/schemas/GeographicSiteRef'
          GeographicAddress_Query: '#/components/schemas/GeographicAddress_Query'
      oneOf:
      - $ref: '#/components/schemas/GeographicAddressRef'
      - $ref: '#/components/schemas/GeographicSiteRef'
      - $ref: '#/components/schemas/GeographicAddress_Query'
    GeographicAddressRef:
      description: 'A reference to a Geographic Address resource available through Address Validation API.

        '
      type: object
      properties:
        href:
          description: 'Hyperlink to the referenced Address. Hyperlink MAY be used by the Seller in responses. Hyperlink MUST be ignored by the Seller in case it is provided by the Buyer in a request.

            '
          type: string
        id:
          description: Identifier of the referenced Geographic Address. This identifier is assigned during a successful address validation request (Geographic Address Management API)
          type: string
        '@type':
          description: Used to unambiguously designate the class type when using `oneOf`
          type: string
          enum:
          - GeographicAddressRef
      required:
      - '@type'
      - id
    MEFProductOrderItem_Common:
      description: 'An identified part of the order. A product order is decomposed into one or more order items. This type holds the attributes common to request and response representation of the Product Order Item.

        '
      type: object
      properties:
        action:
          description: Action to be applied to the product referred by this Product Order Item
          $ref: '#/components/schemas/MEFProductActionType'
        agreementName:
          description: The name of the Agreement which is referenced for the Product Order Item.
          type: string
        billingAccount:
          description: Billing account information for the billing account the Buyer wants used for the Product Order Item
          $ref: '#/components/schemas/MEFBillingAccountRef'
        coordinatedAction:
          description: The interval after the completion of one or more related Product Order Items that this Product Order Item can be started or completed
          type: array
          items:
            $ref: '#/components/schemas/MEFOrderItemCoordinatedAction'
        endCustomerName:
          description: The name of the End Customer, either a business name or an individual name depending on the end customer.
          type: string
        expediteIndicator:
          description: Indicates that expedited treatment is requested. Set by the Buyer. If this is set to TRUE, the Buyer sets the Requested Completion Date to the expedited date. See MEF 57.2 section 7.3 for a description of the interaction between the Buyer and the Seller.
          type: boolean
          default: false
        id:
          description: 'A Buyer provided identifier to identify Product Order Items and to be able to relate them to one another. This is set by the Buyer and is unique within the Product Order. Examples of Reference Identifier could be 1, 2, 3 or A, B, C. The Reference Identifier can be reused in multiple Product Orders to identify a Product Order Item within that Product Order.

            '
          type: string
        note:
          description: 'Free form text to clarify or explain the Product Order Item. Only new notes can be entered. The Buyer and Seller cannot modify an existing Note. The Buyer creates a Note when creating the Product Order Item or when updating it. The Seller may add notes at any time. This is not to be used to inform the Seller of Actions that the Buyer wishes performed.

            '
          type: array
          items:
            $ref: '#/components/schemas/Note'
        product:
          description: The Buyer's existing Product for which the Product Order is being requested. Set by the Buyer if the Product Action is modify or delete.
          $ref: '#/components/schemas/MEFProductRefOrValueOrder'
        productOfferingQualificationItem:
          description: The POQ and POQ Item associated to this Product Order Item. The relation may be required by the Seller. In that case, this is a mandatory field. If the Seller does not require the POQ Item reference, then this is an optional attribute.
          $ref: '#/components/schemas/ProductOfferingQualificationItemRef'
        productOrderItemRelationship:
          description: The relationship between Product Order Items in the Product Order.
          type: array
          items:
            $ref: '#/components/schemas/OrderItemRelationship'
        quoteItem:
          description: The Quote Item associated to this Product Order Item. The Quote Item reference may be required by the Seller. In that case, this is a mandatory field. If the Seller does not require the Quote, then this is an optional attribute.
          $ref: '#/components/schemas/MEFQuoteItemRef'
        relatedBuyerPON:
          description: Identifies the Buyer Purchase Order Number that is related to this Product Order.
          type: string
        relatedContactInformation:
          description: 'Contact information of an individual or organization playing a role for this Order Item.

            The rule for mapping a represented attribute

            value to a `role` is to use the _lowerCamelCase_ pattern e.g.

            - Buyer Product Order Item Contact: `role=buyerProductOrderItemContact`

            - Buyer Implementation Contact: `role=buyerImplementationContact`

            - Buyer Technical Contact: `role=buyerTechnicalContact`

            - Buyer Billing Contact: `role=buyerBillingContact`

            - Buyer Fault Contact: `role=buyerFaultContact`

            - Seller Fault Contact: `role=sellerFaultContact`

            - Buyer GDPR Contact: `role=buyerGDPRContact`

            - Seller GDPR Contact: `role=sellerGDPRContact`'
          type: array
          items:
            $ref: '#/components/schemas/RelatedContactInformation'
        requestedCompletionDate:
          description: Identifies the Buyer's desired due date (requested delivery date)
          type: string
          format: date-time
        requestedItemTerm:
          description: Requested term of the Product Order Item
          $ref: '#/components/schemas/MEFItemTerm'
        tspRestorationPriority:
          description: 'Within the United States, indicates the provisioning and restoration priority as defined under the TSP Service Vendor Handbook. The valid values are defined in ATIS OBF document: ATIS-0404001.

            '
          type: string
      required:
      - action
      - id
      - product
      - requestedCompletionDate
    Duration:
      description: A Duration in a given unit of time e.g. 3 hours, or 5 days.
      type: object
      properties:
        amount:
          description: Duration (number of seconds, minutes, hours, etc.)
          type: integer
          minimum: 0
        units:
          description: Time unit enumerated
          $ref: '#/components/schemas/TimeUnit'
      required:
      - amount
      - units
    TerminationError:
      description: This indicates an error that caused an Item to be terminated. The code and propertyPath should be used like in Error422.
      type: object
      properties:
        code:
          description: "One of the following error codes:\n  - missingProperty: The property the Seller has expected is not present in the payload\n  - invalidValue: The property has an incorrect value\n  - invalidFormat: The property value does not comply with the expected value format\n  - referenceNotFound: The object referenced by the property cannot be identified in the Seller system\n  - unexpectedProperty: Additional property, not expected by the Seller has been provided\n  - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold.\n  - otherIssue: Other problem was identified (detailed information provided in a reason)\n"
          $ref: '#/components/schemas/Error422Code'
        propertyPath:
          description: 'A pointer to a particular property of the payload that caused the validation issue. It is highly recommended that this property should be used.

            Defined using JavaScript Object Notation (JSON) Pointer (https://tools.ietf.org/html/rfc6901).

            '
          type: string
        value:
          description: Text to describe the reason of the termination.
          type: string
    MEFOrderItemCoordinatedAction:
      description: The interval after the completion of one or more related Order Items that this Order Item can be started or completed
      type: object
      properties:
        coordinatedActionDelay:
          description: The period of time for which the coordinated action is delayed.
          $ref: '#/components/schemas/Duration'
        coordinationDependency:
          description: A dependency between the Order Item and a related Order Item
          $ref: '#/components/schemas/MEFOrderItemCoordinationDependencyType'
        itemId:
          description: Specifies Order Item that is to be coordinated with this Order Item.
          type: string
      required:
      - coordinatedActionDelay
      - coordinationDependency
      - itemId
    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
    MEFProductConfiguration:
      description: MEFProductConfiguration is used as an extension point for MEF specific product/service payload.  The `@type` attribute is used as a discriminator
      type: object
      properties:
        '@type':
          description: The name of the type, defined in the JSON schema specified  above, for the product that is the subject of the Product Order Request. The named type must be a subclass of MEFProductConfiguration.
          type: string
      required:
      - '@type'
      discriminator:
        propertyName: '@type'
    LabelRepresentation:
      description: A unique identifier controlled by a generally accepted independent administrative authority that specifies a fixed geographical location.
      type: object
      properties:
        label:
          description: The unique reference to an Geographic Address assigned by the Administrative Authority.
          type: string
        administrativeAuthority:
          description: The organization or standard from the organization that administers this Geographic Address Label ensuring it is unique within the Administrative Authority.
          type: string
        language:
          description: The language in which the label is expressed. Based on ISO 639:2023
          type: string
          minLength: 2
          maxL

# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-productorder-api-openapi.yml