Open APIs

 View Only
  • 1.  TMF 679 - Product Offering Qualification V5 ProductOfferingRef

    TM Forum Member
    Posted Oct 02, 2024 11:29
    Edited by Anastasios Sarantis Oct 03, 2024 05:32

    Hello everyone,

    I would like to understand why the specification includes "ProductOfferingRef" as a resource instead of "ProductOfferingRefOrValue."

    I was hoping the POQ would return a list of Product Offerings along with their prices.

    In our case, the Product Offering Prices are not sourced from the Product Catalogue. I would like to have the associated prices listed with the offerings, but I’m unable to do so since we only have "ProductOfferingRef" instead of "ProductOfferingValue," where I could include the Product Offering Price.

    I did notice "ProductRefOrValue" is available, but not "ProductOfferingRefOrValue."

    Is there a specific rationale behind this choice, or is it an oversight?

    Thank you.







    ------------------------------
    Anastasios Sarantis
    CityFibre
    ------------------------------



  • 2.  RE: TMF 679 - Product Offering Qualification V5 ProductOfferingRef

    TM Forum Member
    Posted Oct 03, 2024 10:13

    Hi,

    very good question, we have implemented TMF679 for "modify product" Intent (using Check resource) and we'll soon start the next phase and add the "change product" intent (using Query resource), where the API will present a list of qualified product offerings with "product prices" (not product offering price).

    Maybe we should work together!

    I have yet to go into the details of this API for prices and product offering, but I don't disagree that the way the entities "Product" and "Product Offering" and their ref/ReforValue are modelled does feel incomplete.

    i was hopin the POQ to return a list of Product offerings and their prices to be honest :( 

    The API does list product offerings:

    "qualifiedProductOfferingItem": [
        {
          "@type": "QueryProductOfferingQualificationItem",
          "productOffering": {
            "id": "DPI89",
            "name": "European Data Plan - 20 GB",
            "href": "https://host:port/productCatalogManagement/v5/productOffering/DPI89",
            "@type": "ProductOfferingRef"
          },
          "id": "1"
        },
        {
          "@type": "QueryProductOfferingQualificationItem",
          "productOffering": {
            "id": "DPI90",
            "name": "European Data Plan - 50 GB",
            "href": "https://host:port/productCatalogManagement/v5/productOffering/DPI90",
            "@type": "ProductOfferingRef"
          },
          "id": "2"
        },

    Price are available under the "Product" node.

    Unfortunately the YAML file and user guide don't offer any examples for the  "Product" node to help confirm what "product" means here.
     

    one possibility is that you get a list of product offerings in the node productOffering and then the same list is also present in the product node (where you will also get prices). It's not ideal, though.

    Another possibility is to abstract the "product" node and use polymorphism to have several product types:

    the product represents a sellable product offering:

     "qualifiedProductOfferingItem": [
        {
          "@type": "QueryProductOfferingQualificationItem",
          "Product": {
            "name": "Offer 1",
            "@type": "ProductOfferingRef",
    "@baseType": "Product", "productPrice": {
    "price": { "dutyFreeAmount": { "unit": "string", "value": 39
    [...]

    the product represents a promotion:

     "qualifiedProductOfferingItem": [
        {
          "@type": "QueryProductOfferingQualificationItem",
          "Product": {
            "name": "Offer 1",
            "@type": "PromotionRef",
    "@baseType": "Product", "productPrice": {
    "price": { "dutyFreeAmount": { "unit": "string", "value": 789
    [...]

    the product represents a product offering instance in inventory:

    (we use this today to check "modify product" intent)

     "qualifiedProductOfferingItem": [
        {
          "@type": "QueryProductOfferingQualificationItem",
          "Product": {
            "name": "Offer 1",
            "@type": "ProductRef",
    "@baseType": "Product", "productPrice": {
    "price": { "dutyFreeAmount": { "unit": "string", "value": 39
    [...]

    in IG1228, you have use case: "Use Case UC002: Browse B2C catalogue" that should match your business case. However it's unclear if prices are provided as the UI mockup don't show any prices



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Lyse Platform
    ------------------------------



  • 3.  RE: TMF 679 - Product Offering Qualification V5 ProductOfferingRef

    TM Forum Member
    Posted Oct 04, 2024 06:21
    Edited by Anastasios Sarantis Oct 04, 2024 07:35

    Hello Matthieu,

    Thank you for your response. i agree we could work together on this one . 

    Yes, I understand from them  that there is a listing of product offerings, but unfortunately, they are represented as "ProductOfferingRefs," as you pointed out.

    The API currently lists product offerings as follows:

     
    "qualifiedProductOfferingItem": [
        {
          "@type": "QueryProductOfferingQualificationItem",
          "productOffering": {
            "id": "DPI89",
            "name": "European Data Plan - 20 GB",
            "href": "https://host:port/productCatalogManagement/v5/productOffering/DPI89",
            "@type": "ProductOfferingRef"
          },
          "id": "1"
        },
        {
          "@type": "QueryProductOfferingQualificationItem",
          "productOffering": {
            "id": "DPI90",
            "name": "European Data Plan - 50 GB",
            "href": "https://host:port/productCatalogManagement/v5/productOffering/DPI90",
            "@type": "ProductOfferingRef"
          },
          "id": "2"
        },

    Prices are currently available under the "Product" node, as you've observed.

    As far as I know, a "ProductOffering" represents what is offered to the customer and is maintained in the Product Catalogue, whereas a "Product" refers to what the customer already owns and is managed in the Product Inventory.

    While there are workarounds to pull product prices into product offering prices as you do here ... but why to do that since you got already the "productOffering" as resource there ... 

     "qualifiedProductOfferingItem": [
        {
          "@type": "QueryProductOfferingQualificationItem",
          "Product": {
            "name": "Offer 1",
            "@type": "ProductRef",        "@baseType": "Product",
            "productPrice": {          "price": {
                  "dutyFreeAmount": {
                    "unit": "string",
                    "value": 39[...]


     I believe that since the API is called Product Offering Qualification, the primary resource should be "ProductOffering" rather than "Product."

    I understand the inclusion of "ProductRefOrValue" for flexibility, but I think we also need to include "ProductOfferingRefOrValue" to avoid using an unrelated resource for pricing information.

    How can we best present this issue to TMF you think?

    Thanks!
    Tassos



    ------------------------------
    Anastasios Sarantis
    CityFibre
    ------------------------------



  • 4.  RE: TMF 679 - Product Offering Qualification V5 ProductOfferingRef

    TM Forum Member
    Posted Oct 04, 2024 09:11

    Yes, I understand from them  that there is a listing of product offerings, but unfortunately, they are represented as "ProductOfferingRefs," as you pointed out.

    What is the issue with ProductOfferingRefs?

    is it just because you don't have the product price or the product offering price?

    As for the <product> definition, I don't disagree with you, you're right, on paper (also confirmed by GB922). but I have 2 reflections:

    • A "product" in the product inventory represents either a product specification OR a product offering, not just the latter. 
    • a "product" cannot only represent an instance in the product inventory as many tangible products will never go into the inventory:
      • accesorries such as phone charger, cable, remote control, game consoles etc

    If "product" exclusively represent instances in the inventory, TMF679, and pretty much all product/sales APIs are doomed.
    also, the name of the API is wrong, because you must be able to qualify "product", not just "product offering". For instance, we qualify "product" with TMF679 when customer wants to modify them (increase bandwidth, add options...) or transfer them to a new address etc, even when the product's related product offering is end of sales.

    My initial thought is to consider "product" as an base type (abstract) and I will use @Type to indicate if it's an instance from the product inventory or from the product catalogue (PO or PS). 

    my 2 cents

    PS: next discussion is the difference between "product offering price" and "product price"? :-)



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Lyse Platform
    ------------------------------



  • 5.  RE: TMF 679 - Product Offering Qualification V5 ProductOfferingRef

    TM Forum Member
    Posted Oct 07, 2024 10:37
    Edited by Anastasios Sarantis Oct 07, 2024 11:43

    Hello Matthiew 

    What is the issue with ProductOfferingRefs?

    is it just because you don't have the product price or the product offering price?

    To address your question: yes, I don't have access to the Product Offering Price (POP).

    For me , the "product price" refers to the price of a product that a customer has already purchased and is stored in the Product Inventory. In contrast, the "Product Offering Price" is the price offered to a customer for a particular product offering, which should be maintained separately.

    • A "product" in the product inventory represents either a product specification OR a product offering, not just the latter. 

    As per TMF's guidance:

     "Products" are  "Product Specifications"; the way in which they are offered into the market "Product Offerings" (in product catalogue); and the way in which they are maintained ( in product Inventory )and perform while in use "Products". Typically, we store all product offerings in the Product Catalogue, not in the Product Inventory.

    also, the name of the API is wrong, because you must be able to qualify "product", not just "product offering"

     I believe the original intention of the API design might have been more focused on product offerings.

    The flexibility of the API means you can use it as needed; however, my issue is that I couldn't find the "ProductOfferingPrice." This is why I'm requesting the inclusion of "ProductOfferingRefOrValue" instead of just "ProductOfferingRef."

    Using "ProductPrice" in this context isn't ideal, as it has a different meaning in our stack.

    I hope this explanation clarifies my concerns.

    best regards 
    Tassos



    ------------------------------
    Anastasios Sarantis
    CityFibre
    ------------------------------



  • 6.  RE: TMF 679 - Product Offering Qualification V5 ProductOfferingRef

    TM Forum Member
    Posted Oct 08, 2024 06:06

    The goal of TMF679 is not to expose the ProductOfferingPrice, but rather to show what the customer will actually pay. This is the purpose of productPrice.

    As stated in GB922 Product (Figure Pr.32 - Product Price):

    When an enterprise agrees to deliver a product, one or more ProductOfferingPrices may be identified as applicable. These are then associated with one or more ProductPrices for the product.

    Example:

    Offer ABC is associated with 3 ProductOfferingPrices in the catalogue:

    • €59 regular price
    • €49 special price for customers with a benefit card (pensioners, students, teachers, etc.)
    • 5% discount if ordered online

    When a customer browses the web and sees qualified product offerings, including offer ABC, the customer should not be expected to calculate the final price themselves.

    With your ProductOfferingPrice-only approach, the API would return offer ABC with three associated ProductOfferingPrice entities, requiring the customer to figure out the final price. Instead, TMF679 should return a productPrice attribute reflecting the actual amount the customer will pay (€56.05, i.e., €59 minus 5% for ordering online).

    This is why you need a POST request to compute the productPrice, rather than a GET request which simply reads the price from the catalogue without considering contextual factors.

    Keep in mind that ProductPrice is used across all pre- and post-sales APIs (Quote/Cart → Product Configurator → Product Order → Product Inventory → Billing).

    The change you're proposing may be difficult to justify, especially given the lack of a TMF679 owner (Ludovic) since the previous one left three years ago, and TMF has yet to appoint a new lead. (there is post somewhere in this community that I created for a similar question and Ludovic explained me the reason to use 679 and not 620 for pricing.)

    Alternatively, you could customise this API or create a new API that orchestrates both TMF620 and TMF679 to handle the necessary data mutation and orchestration.



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Lyse Platform
    ------------------------------



  • 7.  RE: TMF 679 - Product Offering Qualification V5 ProductOfferingRef

    TM Forum Member
    Posted Oct 08, 2024 08:16

    Hello Matthieu,

    Yes, I am familiar with Ludovic from Orange. However, I believe there is an issue here as this approach does not seem to align with SID . As I mentioned, while I could technically use the "ProductPrice" attribute, it is not applicable for my context.

    I understand that dynamic pricing is being applied to the product offerings, but I respectfully disagree with the interpretation. Based on your example:

    The Offer ABC is associated with three distinct ProductOfferingPrices in the catalogue:

    • Regular Price: €59
    • Special Price for customers with a benefit card (e.g., pensioners, students, teachers): €49
    • 5% Discount if ordered online

    All of these represent variations of ProductOfferingPrices. Even if the final price is dynamically determined or based on specific rules, it is still an "aggregated" or "selected" Product Offering Price, not the actual Product Price that was charged.

    As you mentioned, the ProductPrice is used consistently across various pre- and post-sales APIs (Quote/Cart → Product Configurator → Product Order → Product Inventory → Billing), and reflects the final charged amount. This is different from Product Offering Prices, which are contextual prices linked to the offering itself.

    That said, I understand that you might want to use the API in a way that suits your use case. While it is technically feasible to implement it this way, I believe it is critical that users are not restricted from using ProductOfferingPrice over ProductPrice, particularly when the primary resource of the API is the ProductOffering

    Best regards,
    Tassos



    ------------------------------
    Anastasios Sarantis
    CityFibre
    ------------------------------



  • 8.  RE: TMF 679 - Product Offering Qualification V5 ProductOfferingRef

    TM Forum Member
    Posted Oct 09, 2024 05:56

    Hi,

    I understand that dynamic pricing is being applied to the product offerings, but I respectfully disagree with the interpretation

    I'm pretty sure that's not what I wrote nor meant. "Dynamic prices" (productPrice) are applied to product, never to product offerings!

    Sorry if I made you believe this, English is not my 1st language.

    Only POP are associated to product offerings.

    It looks like you have a specific use case, and you should consider changing the API schema to suit your needs. our Vendors and our company use TMF APis and we both change the schema to expose new capabilities. It's pretty fast.



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Lyse Platform
    ------------------------------