MEF Product Offering API

openapi: 3.2.0
info:
  title: Mef Product Offering API
  version: 4.0.1
  description: 'Operations tagged productOffering across 2 of this provider''s published API definitions: mef-lso-cantata-product-catalog-openapi.yml, mef-lso-sonata-product-catalog-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://{serverBase}/mefApi/cantata/productCatalog/v4/
  variables:
    serverBase:
      description: The base of Buyer's URL.
      default: mplify.net
- url: http://{serverBase}/mefApi/sonata/productCatalog/v4/
  variables:
    serverBase:
      description: The base of Buyer's URL.
      default: mplify.net
tags:
- name: productOffering
paths:
  /productOffering:
    get:
      tags:
      - productOffering
      summary: List or find Product Offering objects
      description: This operation list or find ProductOffering entities
      operationId: listProductOffering
      parameters:
      - name: name
        in: query
        description: The commercial name of the Product Offering
        required: false
        schema:
          type: string
      - name: lastUpdate.gt
        in: query
        description: The date and time the Product Offering was created or most recently updated, greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: lastUpdate.lt
        in: query
        description: The date and time the Product Offering was created or most recently updated, less than
        required: false
        schema:
          type: string
          format: date-time
      - name: lifecycleStatus
        in: query
        description: Lifecycle Status of the Product Offering
        required: false
        schema:
          $ref: '#/components/schemas/ProductOfferingLifecycleStatusType'
      - name: agreement
        in: query
        description: The name of the Seller's offer arrangement (such as a framework agreement).  **Note:** The list of allowable values for agreements should be negotiated between the Buyer and the Seller, during the integration phase. Ultimately it will be the enumerated set of values (it's problematic to define the enumerated values globally for any operator).
        required: false
        schema:
          type: string
      - name: channel
        in: query
        description: "The names of the sales channels through which the Product Offering is made available to the Buyer to order. **Note:** The list of allowable values for selling channels should be negotiated between the Buyer and the Seller, during the integration phase.  Ultimately it will be the enumerated set of values (it's problematic to define\n the enumerated values globally for any operator)."
        required: false
        schema:
          type: string
      - name: marketSegment
        in: query
        description: The names of the market segments  targeted for the Product Offering. **Note:** The list of allowable values for selling market segments should be negotiated between the Buyer and the Seller, during the integration phase.  Ultimately it will be the enumerated set of values (it's problematic to define the enumerated values globally for any operator).
        required: false
        schema:
          type: string
      - name: region.countryCode
        in: query
        description: Country where the products are offered by the Seller to potential Buyers.
        required: false
        schema:
          type: string
      - name: isBundle
        in: query
        description: Determines whether a productOffering represents a single productOffering (false), or a bundle of productOfferings (true).
        required: false
        schema:
          type: boolean
      - name: isSellable
        in: query
        description: A flag indicating if this product offer can be sold stand-alone for sale or not. If this flag is false it indicates that the offer can only be sold within a bundle.
        required: false
        schema:
          type: boolean
      - name: category.id
        in: query
        description: Identifier of the Category that Product Offering is the direct or transitive member of. Direct member - there is a direct relation between Category and Product Offering. Transitive member - there is a relation between one of the sub-categories and Product Offering.
        required: false
        schema:
          type: string
      - name: productSpecification.id
        in: query
        description: A Product Specification Reference to the detailed description of the specifications and attributes defining all of the Product Offering characteristics.
        required: false
        schema:
          type: string
      - name: buyerId
        in: query
        description: The unique identifier of the organization that is acting as 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 the start of an 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 the 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/ProductOffering_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':
          content:
            application/json;charset=utf-8:
              schema:
                items:
                  $ref: '#/components/schemas/Error422'
                type: array
          description: Unprocessable entity due to the business validation problems
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
    servers:
    - url: http://{serverBase}/mefApi/cantata/productCatalog/v4/
      variables:
        serverBase:
          description: The base of Buyer's URL.
          default: mplify.net
  /productOffering/{id}:
    get:
      tags:
      - productOffering
      summary: Retrieves a ProductOffering by ID
      description: This operation retrieves a ProductOffering entity. Attribute selection is enabled for all first level attributes.
      operationId: retrieveProductOffering
      parameters:
      - name: id
        in: path
        description: Identifier of the ProductOffering
        required: true
        schema:
          type: string
      - name: buyerId
        in: query
        description: The unique identifier of the organization that is acting as 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/ProductOffering'
        '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'
    servers:
    - url: http://{serverBase}/mefApi/cantata/productCatalog/v4/
      variables:
        serverBase:
          description: The base of Buyer's URL.
          default: mplify.net
components:
  schemas:
    Context:
      description: Context that is defined as a two-dimensional vector of Business Function and Product Action.
      type: object
      properties:
        productAction:
          description: Defines Product Action to which the given context applies. `all` Applies for all supported Product Action for a given Product Offering. This attribute does not apply for `businessFunction=productInventory`. `remove` does not apply here, since this Product Action only includes a Product Identifier.
          $ref: '#/components/schemas/ProductActionMask'
        businessFunction:
          description: Defines Business Function to which the given context applies. `all` Applies for all supported Business Functions for a given Product Offering.
          $ref: '#/components/schemas/BusinessFunctionMask'
      required:
      - businessFunction
    TimeUnit:
      description: 'Represents a unit of time.

        '
      type: string
      enum:
      - seconds
      - minutes
      - businessHours
      - calendarHours
      - businessDays
      - calendarDays
      - months
      - years
    ProductOffering_Find:
      allOf:
      - $ref: '#/components/schemas/ProductOffering_Common'
      - description: Represents entities that are launched from the provider of the catalog, this resource includes pricing information.
        required:
        - category
        - channel
        - id
        - isBundle
        - isSellable
        - lastUpdate
        - lifecycleStatus
        - marketSegment
        - name
        - productSpecification
        - region
    PlaceRelationshipConstraint:
      description: Allows definition and constraining of PlaceRelationship that can be specified for the ordered Product.
      type: object
      properties:
        relationshipRole:
          description: Specifies the nature of the relationship between the Product Offering and Place. This must be one of the roles as defined in the related Product Specification. For example, `INSTALL_LOCATION`.
          type: string
        isModifiable:
          description: Specifies if the Place Relationship can be modified on an active Product.
          type: boolean
        minCardinality:
          description: The minimum required number of PlaceRelationships of given relationshipRole that must configured for ordered Product. For example, as specified in the 'Relationship Between Entities' Section of MEF 106. `0` means the relation is optional.
          type: integer
          minimum: 0
        maxCardinality:
          description: The maximum required number of PlaceRelationships of given relationshipRole that must configured for ordered Product. For example, as specified in the 'Relationship Between Entities' Section of MEF 106. `-1` stands for infinity i.e. any number of instances of the given type could be related to the considered instance.
          type: integer
          minimum: -1
      required:
      - isModifiable
      - maxCardinality
      - minCardinality
      - relationshipRole
    ProductRelationshipConstraint:
      description: Allows definition and constraining of Product Relationship that can be specified for the ordered Product.
      type: object
      properties:
        productSpecification:
          description: The identifier of the associated Product Specification to define the allowable target Product types
          type: string
        relationshipType:
          description: Specifies the nature of productRelationship between Products. This must be one of the relationshipTypes as defined by the main product specification.
          type: string
        isModifiable:
          description: Specifies if the Product Relationship can be modified on an active Product.
          type: boolean
        minCardinality:
          description: The minimum required number of ProductRelationships (of given relationshipType and target productSpecification) that must configured for ordered Product. For example, as specified in the 'Relationship Between Entities' Section of MEF 106. `0` means the relation is optional.
          type: integer
          minimum: 0
        maxCardinality:
          description: The maximum required number of ProductRelationships (of given relationshipType and target productSpecification) that must configured for ordered Product. `-1` stands for infinity i.e. any number of instances of the given type could be related to the considered instance.
          type: integer
          minimum: -1
      required:
      - productSpecification
      - relationshipType
      - isModifiable
      - minCardinality
      - maxCardinality
    ProductCategoryRef:
      description: Represents the reference to Category
      type: object
      properties:
        id:
          description: Unique (within the Seller domain) identifier for the Category
          type: string
        href:
          description: Hyperlink to access the Category
          type: string
          format: uri
      required:
      - id
    ProductOfferingPrice:
      type: object
      description: 'Is based on both the basic cost to develop and produce products and the enterprises policy on revenue targets. This price may be further revised through discounting (a Product Offering Price that reflects an alteration). The price, applied for a productOffering may also be influenced by the productOfferingTerm, the customer selected, eg: a productOffering can be offered with multiple terms, like commitment periods for the contract. The price may be influenced by this productOfferingTerm. A productOffering may be cheaper with a 24 month commitment than with a 12 month commitment.'
      properties:
        description:
          type: string
          description: Description of the productOfferingPrice
        lastUpdate:
          type: string
          format: date-time
          description: the last update time of this ProductOfferingPrice
        validFor:
          description: The date range that the ProductOfferingPrice is applicable
          $ref: '#/components/schemas/TimePeriod'
        bundledProductOffering:
          description: The identifier of a Product Offering within the Bundle to which this Product Offering Price applies. This indicates that this is the unit price per one instance of the Bundled Product Offering.
          $ref: '#/components/schemas/ProductOfferingRef'
        region:
          description: 'The areas where the Price is applicable. If region is an empty list, it implies that the Price is not region-restricted

            '
          type: array
          items:
            $ref: '#/components/schemas/Region'
        note:
          description: A set of comments for additional information.
          type: array
          items:
            $ref: '#/components/schemas/Note'
        priceType:
          description: Indicates if the price is for recurring, non-recurring, or usage based charges
          $ref: '#/components/schemas/MEFPriceType'
        recurringChargePeriod:
          description: Used for a recurring charge to indicate a period
          $ref: '#/components/schemas/Duration'
        unitOfMeasure:
          description: 'Unit of Measure if price depending on it (Gb, SMS volume, etc..) MEF: if Quote Item Price Type equals usageBased'
          type: string
        price:
          description: The value the List Price for the Product Offering.
          $ref: '#/components/schemas/Price'
        priceModifier:
          description: Related price discounts.
          type: array
          items:
            $ref: '#/components/schemas/PriceModifier'
      required:
      - description
      - lastUpdate
      - validFor
      - priceType
      - price
    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
    ProductOfferingContextualInfo:
      description: Used for the cases when the schema must be differentiated per the defined Context, where Context is built as a pair - a Business Function (e.g. Quote) and Product Action (e.g. add). Those product schemas are created by applying the constraints to Product Schemas defined in the Product Specification. If provided, Contextual info MUST cover every possible combination of Product Actions and Business Functions (if there are no differences per function or per action then use wildcard - 'all' -  and reuse the value of Product Offering Specification attribute).
      type: object
      properties:
        contextSchema:
          description: Product Schema that is defined for the given Context. Schema MUST be compliant with JSON scheme standard.
          $ref: '#/components/schemas/SchemaRefOrValue'
        context:
          description: Context that is defined as a two-dimensional vector of Business Function and Product Action.
          $ref: '#/components/schemas/Context'
      required:
      - context
      - contextSchema
    Region:
      description: Specifies a region
      type: object
      properties:
        city:
          description: City in which the Product can be provided
          type: string
        locality:
          description: An area of defined or undefined present boundaries within a local authority or other legislatively defined area, usually rural or semi-rural in nature. Should only be specified by a Seller for a Product Offering that is not available Country wide
          type: string
        stateOrProvince:
          description: The State or Province in the region is located. Should only be specified by a Seller for a Product Offering that is not available Country wide.
          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
      required:
      - countryCode
    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
    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
    PriceModifier:
      description: The Price Modifier allows specifying promotional (via Price Modifier Deal Reference) and/or volume based pricing discounts. For example, if only Minimum Quantity is specified, then the Price Modifier is a volume based discount, and if only Price Modifier Deal Reference is set then the Price Modifier is a form of promo code, and if both are set then the Pricer Modifier is a form of promo code with a minimum purchase requirement.
      type: object
      properties:
        description:
          type: string
          description: Description of the Price Modifier
        lastUpdate:
          type: string
          format: date-time
          description: The last update time of this Price Modifier
        validFor:
          description: The date range that the Price Modifier is applicable
          $ref: '#/components/schemas/TimePeriod'
        region:
          description: 'Allows constraining the Regions where the Price Modifier is applicable. Only the Regions that need to be constraint should be included (since this is inherited from the Product Offering Price).

            '
          type: array
          items:
            $ref: '#/components/schemas/Region'
        minimumQuantity:
          type: integer
          minimum: 1
          description: The minimum quantity of the associated Product Offering required to receive the price reduction.
        reductionPercentage:
          description: The amount of price discount, expressed as a percentage. A value of 5 represents a 5% price reduction. This attribute may only be set if the discountedPrice is not set.
          type: number
          minimum: 0
          maximum: 100
        discountedPrice:
          description: The associated discounted price. This attribute may only be set if the reductionPercentage is not set.
          $ref: '#/components/schemas/Price'
        dealReference:
          type: string
          description: A pre-agreed pricing modifier reference that the Seller is offering which may impact the pricing (for example, a Promo Code). This Price Modifier is applicable when the fulfillment of the associated Product Offering satisfies this pre-agreed Deal Reference.
      required:
      - description
      - lastUpdate
      - validFor
    DataSizeUnit:
      description: The unit of measure in the data size.
      type: string
      enum:
      - BYTES
      - KBYTES
      - MBYTES
      - GBYTES
      - TBYTES
      - PBYTES
      - EBYTES
      - ZBYTES
      - YBYTES
    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
    SchemaRefOrValue:
      description: Reference to the JSON schema location or the exact value of the JSON schema. **Note:** One of the properties must be provided i.e. schemaLocation or schema.
      type: object
      properties:
        schema:
          description: Raw JSON schema value.
          type: string
        schemaLocation:
          description: This field provides a link to the schema describing the target product
          type: string
          format: uri
    Error401Code:
      description: 'One of the following error codes:

        - missingCredentials: No credentials provided.

        - invalidCredentials: Provided credentials are invalid or expired'
      type: string
      enum:
      - missingCredentials
      - invalidCredentials
    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
    ProductSpecificationRef:
      description: Product Specification reference.
      type: object
      properties:
        id:
          description: Unique (within the Seller domain) identifier for the Product Specification.
          type: string
        href:
          description: Hyperlink to access the Product Specification
          type: string
      required:
      - id
    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
    Price:
      description: Provides all amounts (tax included, duty-free, tax rate) and used currency of a Price
      type: object
      properties:
        taxRate:
          description: 'Price Tax Rate. Unit: [%]. E.g. value 16 stand for 16% tax.'
          type: number
          format: float
        taxIncludedAmount:
          description: All taxes included amount (expressed in the given currency)
          $ref: '#/components/schemas/Money'
        dutyFreeAmount:
          description: All taxes excluded amount (expressed in the given currency)
          $ref: '#/components/schemas/Money'
      required:
      - dutyFreeAmount
    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
    AttachmentValue:
      description: Complements the description of an element (for instance a product) through video, pictures...
      type: object
      properties:
        author:
          description: The name of the person or organization who added the Attachment.
          type: string
        creationDate:
          description: The date the Attachment was added.
          type: string
          format: date-time
        description:
          description: A narrative text describing the content of the attachment
          type: string
        mimeType:
          description: Attachment mime type such as extension file for video, picture and document
          type: string
        name:
          description: The name of the attachment
          type: string
        size:
          description: The size of the attachment.
          $ref: '#/components/schemas/MEFByteSize'
        source:
          description: Indicates if the attachment was added by the Buyer or the Seller.
          $ref: '#/components/schemas/MEFBuyerSellerType'
  

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