MEF LSO Sonata Product Inventory Management

openapi: 3.0.1
info:
  title: Product Inventory Management
  description: |
    **This file forms part of Mplify 116.1**

    This API implements Business Requirements described in MEF 81 and MEF 81.0.1

    It allows the Buyer to retrieve the information about existing Product
    instances from Seller's Product Inventory.

    List of supported use cases:

    - Retrieve Product List

    - Retrieve Product by Identifier

    Copyright 2025 Mplify Alliance and its contributors.

    This file includes content based on the TM Forum Product Inventory
    Management API (TMF637 v4.0.0) available at
    https://github.com/tmforum-apis/TMF637_ProductInventory, 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: 8.0.0
servers:
  - url: 'https://{serverBase}/mefApi/sonata/productInventory/v8/'
    variables:
      serverBase:
        description: The base of Seller's URL.
        default: mplify.net
tags:
  - name: product
  - name: events subscription
paths:
  /product:
    get:
      tags:
        - product
      summary: List or find Product objects
      description: This operation lists or finds Product entities
      operationId: listProduct
      parameters:
        - name: status
          in: query
          description: The status of the product
          required: false
          schema:
            $ref: '#/components/schemas/MEFProductStatusType'
        - name: productSpecificationId
          in: query
          description: A reference to a product spec by id
          required: false
          schema:
            type: string
        - name: productOfferingId
          in: query
          description: A reference to a product offering by id
          required: false
          schema:
            type: string
        - name: externalId
          in: query
          description: A reference to the externalId provided in the order
          required: false
          schema:
            type: string
        - name: geographicAddressId
          in: query
          description:
            A Geographic Address identifier which is associated to the product
          required: false
          schema:
            type: string
        - name: geographicSiteId
          in: query
          description: A site identifier which is associated to the product
          required: false
          schema:
            type: string
        - name: relatedProductId
          in: query
          description: >-
            This criteria allows to retrieve all Product records with a Product
            Relationship to a specified Product.

            E.g. All Products related to Product with ID 5
          required: false
          schema:
            type: string
        - name: billingAccountId
          in: query
          description: The Billing Account associated with the Product.
          required: false
          schema:
            type: string
        - name: productOrderId
          in: query
          description: Identifies Product Order associated with the Product
          required: false
          schema:
            type: string
        - name: startDate.lt
          in: query
          description:
            Less than the date that is the initial install date for the Product
          required: false
          schema:
            type: string
            format: date-time
        - name: startDate.gt
          in: query
          description: >-
            Greater than the date that is the initial install date for the
            Product
          required: false
          schema:
            type: string
            format: date-time
        - name: lastUpdateDate.lt
          in: query
          description: >-
            Less than date that the last change affecting this Product was
            completed
          required: false
          schema:
            type: string
            format: date-time
        - name: lastUpdateDate.gt
          in: query
          description: >-
            Greater than the date that the last change affecting this Product
            was completed
          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 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 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/MEFProduct_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'
  '/product/{id}':
    get:
      tags:
        - product
      summary: Retrieves a Product by ID
      description: This operation retrieves a Product entity.
      operationId: retrieveProduct
      parameters:
        - name: id
          in: path
          description: Identifier of the Product
          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/MEFProduct'
        '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'
components:
  schemas:
    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
    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
    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:
        reason:
          description: >-
            Text that explains the reason for the error. This can be shown to a
            client user.
          type: string
          maxLength: 255
        message:
          description: >-
            Text that provides 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. 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
    Error404:
      description: >-
        Resource for the requested path not found.
        (https://tools.ietf.org/html/rfc7231#section-6.5.4)
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              description: >-
                The following error code:

                - notFound: A current representation for the target resource not
                found
              type: string
              enum:
                - notFound
          required:
            - code
    Error422:
      description: >-
        Unprocessable entity due to a business validation problem.
        (https://tools.ietf.org/html/rfc4918#section-11.2)
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              description: |
                One of the following error codes:
                  - missingProperty: The property the Seller has expected is not present in the payload
                  - invalidValue: The property has an incorrect value
                  - invalidFormat: The property value does not comply with the expected value format
                  - referenceNotFound: The object referenced by the property cannot be identified in the Seller system
                  - unexpectedProperty: Additional property, not expected by the Seller has been provided
                  - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold.
                  - otherIssue: Other problem was identified (detailed information provided in a reason)
              $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
          required:
            - code
    Error422Code:
      description: |
        One of the following error codes:
          - missingProperty: The property the Seller has expected is not present in the payload
          - invalidValue: The property has an incorrect value
          - invalidFormat: The property value does not comply with the expected value format
          - referenceNotFound: The object referenced by the property cannot be identified in the Seller system
          - unexpectedProperty: Additional property, not expected by the Seller has been provided
          - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold.
          - otherIssue: Other problem was identified (detailed information provided in a reason)
      type: string
      enum:
        - missingProperty
        - invalidValue
        - invalidFormat
        - referenceNotFound
        - unexpectedProperty
        - tooManyRecords
        - otherIssue
    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
    FieldedAddressRepresentation:
      description: >-
        A type of Address that has a discrete field and value for each type of
        boundary or identifier down to the lowest level of detail. For example
        "street number" is one field, "street name" is another field, etc.
      type: object
      properties:
        streetNr:
          description: >-
            Number identifying a specific property on a public street. It may be
            combined with streetNrLast for ranged addresses.
          type: string
        streetNrSuffix:
          description: >-
            The first street number suffix (in a street number range) or the
            suffix for the street number if there is no range
          type: string
        streetNrLast:
          description:
            Last number in a range of street numbers allocated to an Address
          type: string
        streetNrLastSuffix:
          description: Last street number suffix for a ranged Address
          type: string
        streetPreDirection:
          description:
            The direction of the street that appears before the Street Name
          type: string
        streetName:
          description: Name of the street or other street type
          type: string
        streetType:
          description: >-
            The type of street (e.g., alley, avenue, boulevard, brae, crescent,
            drive, highway, lane, terrace, parade, place, tarn, way, wharf)
          type: string
        streetPostDirection:
          description: >-
            A modifier denoting a relative direction that appears after the
            Street Name.
          type: string
        poBox:
          description: Number identifying a specific location in a post office.
          type: string
        locality:
          description: >-
            An area of defined or undefined boundaries within a local authority
            or other legislatively defined area.
          type: string
        city:
          description: City in which the Address is located.
          type: string
        postcode:
          description: >-
            A descriptor for a postal delivery area used to speed and simplify
            the delivery of mail (also known as zip code)
          type: string
        postcodeExtension:
          description: >-
            The extension used on a postal code. Note: there are different use
            codes for this attribute depending upon the country.
          type: string
        stateOrProvince:
          description: The State or Province in which the Address is located.
          type: string
        countryCode:
          description: >-
            Country in which the Address is located, defined using two
            characters as defined in ISO 3166
          type: string
          minLength: 2
          maxLength: 2
        subUnit:
          description: >-
            The Sub Unit represented as a list. This is a list to allow complex
            sub-unit information such as SUITE 42 ROOM A
          type: array
          items:
            $ref: '#/components/schemas/SubUnit'
        buildingName:
          description: >
            The well-known name of a building that is located at this Address
            (e.g., where there is one Address for a campus).
          type: string
        privateStreetNumber:
          description: Street number on a private street within the Address.
          type: string
        privateStreetName:
          description: >-
            Private streets internal to a property (e.g., a university) may have
            internal names that are not recorded by the land title office.
          type: string
        language:
          description: >-
            The language in which the address is expressed. It MUST use the ISO
            639:2023 two letter code 639:2023
          type: string
          minLength: 2
          maxLength: 2
    FormattedAddressRepresentation:
      description:
        'A freeform text representation agreed to by the Buyer and Seller. '
      type: object
      properties:
        formattedAddress:
          description: >-
            A formatted Address Representation that contains a non-fielded
            address.
          type: string
        language:
          description: >-
            The language in which the address is expressed. Based on ISO
            639:2023
          type: string
          minLength: 2
          maxLength: 2
      required:
        - formattedAddress
    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
    GeographicAddress_Query:
      description: >-
        A list of representations being a subset of Geographic Address entity.
        This is to be used when providing a list of representations to validate
        or search for a Geographic Address
      type: object
      properties:
        fieldedAddressRepresentation:
          description: A list of Fielded Address representations
          type: array
          items:
            $ref: '#/components/schemas/FieldedAddressRepresentation'
        formattedAddressRepresentation:
          description: A list of Formatted Address representations
          type: array
          items:
            $ref: '#/components/schemas/FormattedAddressRepresentation'
        geographicPointRepresentation:
          description: A list of Geographic Point Address representations
          type: array
          items:
            $ref: '#/components/schemas/GeographicPointRepresentation'
        labelRepresentation:
          description: A list of Label Address representations
          type: array
          items:
            $ref: '#/components/schemas/LabelRepresentation'
        '@type':
          description:
            Used to unambiguously designate the class type when using `oneOf`
          type: string
          enum:
            - GeographicAddress_Query
      required:
        - '@type'
      minProperties: 2
    GeographicPointRepresentation:
      description: >
        A GeographicPointRepresentation defines a geographic point through
        coordinates.
      type: object
      properties:
        spatialRef:
          description: >-
            The spatial reference system used to determine the coordinates. The
            system used and the value of this field are to be agreed during the
            onboarding process.
          type: string
        latitude:
          description:
            The latitude expressed in the format specified by the `spacialRef`
          type: string
        longitude:
          description:
            The longitude expressed in the format specified by the `spacialRef`
          type: string
        elevation:
          description:
            The elevation expressed in the format specified by the `spacialRef`
          type: string
      required:
        - latitude
        - longitude
        - spatialRef
    GeographicSiteRef:
      description: >
        A reference to a Geographic Site resource available through Service Site
        API
      type: object
      properties:
        href:
          description: >
            Hyperlink to the referenced Site. 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 Site.
          type: string
        '@type':
          description:
            Used to unambiguously designate the class type when using `oneOf`
          type: string
          enum:
            - GeographicSiteRef
      required:
        - '@type'
        - id
    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 a 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
          maxLength: 2
      required:
        - administrativeAuthority
        - label
    MEFBillingAccountRef:
      description: A reference to the Buyer's Billing Account
      type: object
      properties:
        id:
          description: >-
            Identifies the buyer's billing account to which the recurring and
            non-recurring charges for this order or order item will be billed.
            Required if the Buyer has more than one Billing Account with the
            Seller and for all new Product Orders.
          type: string
      required:
        - id
    MEFEndOfTermAction:
      description: The action the Seller will take once the term expires.
      type: string
      enum:
        - roll
        - autoDisconnect
        - autoRenew
    MEFItemTerm:
      description: The term of the Item
      type: object
      properties:
        duration:
          description: Duration of the term
          $ref: '#/components/schemas/Duration'
        endOfTermAction:
          description: >-
            The action that needs to be taken by the Seller once the term
            expires
          $ref: '#/components/schemas/MEFEndOfTermAction'
        name:
          description: Name of the term
          type: string
        description:
          description: Description of the term
          type: string
        rollInterval:
          description: >-
            The recurring period that the Buyer is willing to pay to the end of
            upon disconnecting the Product after the original term has expired.
          $ref: '#/components/schemas/Duration'
      required:
        - duration
        - endOfTermAction
        - name
    MEFPriceType:
      description:
        Indicates if the price is for recurring or non-recurring charges.
      type: string
      enum:
        - recurring
        - nonRecurring
        - usageBased
    MEFProduct:
      description:
        A product is realized as one or more service(s) and / or resource(s).
      type: object
      properties:
        id:
          description: Unique identifier of the product
          type: string
        href:
          description: Reference of the product
          type: string
        startDate:
          description: >-
            Is the date from which the product starts. Start date is when
            the product is active for the first time (when the install in the
            product order has been processed).
          type: string
          format: date-time
        externalId:
          description: Buyer identifier of the product
          type: string
        status:
          description: The lifecycle status of the product.
          $ref: '#/components/schemas/MEFProductStatusType'
        statusChange:
          description: status change for the Product
          type: array
          items:
            $ref: '#/components/schemas/MEFProductStatusChange'
        lastUpdateDate:
          description: Latest date when the product has been updated.
          type: string
          format: date-time
        agreementName:
          description: >-
            Name of the agreement. The name is unique between the Buyer and the
            Seller.
          type: string
        productSpecification:
          description: A reference to a Product Specification of the Product
          $ref: '#/components/schemas/ProductSpecificationRef'
        place:
          description: >-
            A list of locations that are related to the Product. For example an
            installation location
          type: array
          items:
            $ref: '#/components/schemas/RelatedPlaceRefOrQuery'
        productOffering:
          description: >-
            A particular Product Offering defines the technical and commercial
            attributes and behaviors of a Product.
          $ref: '#/component

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-sonata-product-inventory-management-openapi.yml