Open APIs

Expand all | Collapse all

TMF-620 price change scenario

  • 1.  TMF-620 price change scenario

    Posted Aug 27, 2021 10:04
    Hi all,

    we are implementing TMF-620 product catalog API and are wondering how to handle a recurring price (subscription fee) alteration scenario.

    ProductOfferingPrice element has, among other attributes, identity (id), time validity (validFor) and monetary value (price: Money).
    We need full price history in the product catalog. In case we change the monetary value (i.e. increase/decrease the monthly subscription fee), this will result into a new ProductOfferingPrice element with a new identity (id).

    As far as product catalog is concerned, this isn't an issue. A product offering (e.g. broadband bundle) gets 2 ProductOfferingPrice elements (prior to price alteration and after the price alteration). However, this is a major issue for the product inventory (TMF-637). ProductPrice element represents assignments of prices to product instances ("subscriptions"). We don't want to reprovision all ProductPrices whenever we change a price in the catalog due to new ProductOfferingPrice elements.

    How to approach this problem? A possible solution would be to create a bundle ProductOfferingPrice which comprises several component/atomic ProductOfferingPrices, each for its validity period. Instances (ProductPrice) would only reference bundle ProductOfferingPrices. The billing system would then obtain appropriate atomic ProductOfferingPrices from the catalog, depending on the billing period.
    Is there a more straightforward solution?

    BR,
    Bostjan

    ------------------------------
    Bostjan Keber
    Marand d.o.o.
    ------------------------------


  • 2.  RE: TMF-620 price change scenario

    TM Forum Member
    Posted Aug 30, 2021 15:47
    TMF637 has a PATCH Product operation, can this work?

    Do you need historic and up-to-date prices and price alterations at product inventory level?
    might be better to get them from billing (along with other billing/pricing/payment related information)

    ------------------------------
    Matthieu Hattab
    Altibox AS
    ------------------------------



  • 3.  RE: TMF-620 price change scenario

    Posted Aug 30, 2021 12:04
    Edited by Tomáš Hajný Aug 30, 2021 12:04
    Hi Bostjan,

    I don't think that a change of monetary value in ProductOfferingPrice implies creation of a completely different instance with different id (after all, there's an event defined for attribute value changes). Is there anything preventing you to create a different version with different lifecycle status and different time validity, but the same id?

    Just my 2 cents

    Tomas

    ------------------------------
    Tomáš Hajný
    ČD - Telematika
    ------------------------------



  • 4.  RE: TMF-620 price change scenario

    Posted Aug 31, 2021 12:54
     I think that shouldn't require a new ProductOfferingPrice, in a case of entity with a new identifier.

    pluri sistemas


    ------------------------------
    Pluri Sistemas
    TO BE VERIFIED
    ------------------------------



  • 5.  RE: TMF-620 price change scenario

    TM Forum Member
    Posted Sep 01, 2021 05:28
    Edited by Matthieu Hattab Sep 01, 2021 10:01

    I'm still unclear by your use of price alteration, which is a also a TMF SID entity but it is different than ProductOfferingPrice
    I guess you just mean ProductOfferingPrice.

    You wrote about a "major issue" with product inventory and that ProductOfferingPrice entities and id no longer have a unique identifier which violates the OpenAPI specification.

    you can avoid that.

    we change our prices (only for change in market strategy, or yearly price increase) as follow:
    1. We update a product offering by adding new productofferingprice. This means:
       1.1 we set an End Date on the latest price (Price N)
       1.2 we add a new productofferingprice (Price N+1) with Price N+1 From Date = Price N End Date + 1 day

    (PS: we also update an existing productofferingprice if its start date is in the future)

    2. the change is propagated to Billing and CPQ

    Yes we have multiple productofferingprice ids per productoffering Id and that's ok. only one (or zero) Id will ever be valid at any time. no violation possible here.

    EDIT:
    when a system needs a price, they provide the product offering Id and a date, and the product catalogue can only find 1 productofferingprice.

    billing is a bit more peculiar because it works with billing period (a month,  year) so it queries productofferingprice with a range of date (1st of the period until last day of the period) and will fetch 1 to many productofferingprice, then it's just a simple matter of prorating the price across the billing period.

    We never touch product inventory because of a price change.



    ------------------------------
    Matthieu Hattab
    Altibox AS
    ------------------------------



  • 6.  RE: TMF-620 price change scenario

    Posted Aug 30, 2021 17:03
    Edited by Bostjan Keber Aug 30, 2021 17:03
    No, the product inventory doesn't need a full price history. Product inventory only references ProductOfferingPrice entities for each product instance (ProductPrice entity). In case of price change, I don't want to invoke patch product through TMF-637.

    I believe the product catalog is the master data management for ProductSpecs, ProductOfferings, and Prices. As such, it should maintain a full price history and then provide this information to all consumers (e.g. billing, CPQ, OMS, etc.). It's true, however, that some of these consumers only need current prices and probably billing is the only system that needs full price history.

    I agree about the payments and bill/invoice previews. This is in the domain of the billing system.

    ------------------------------
    Bostjan Keber
    Marand d.o.o.
    ------------------------------



  • 7.  RE: TMF-620 price change scenario

    Posted Aug 30, 2021 13:40
    Hi, Tomaš!

    Thanks for your reply! I agree that updating monetary value on a given timepoint shouldn't require a new ProductOfferingPrice entity with a new identifier.

    Let's say I use ProductOfferingPrice patch operation to update the validity and monetary value of a recurring charge id = 100, validFor=1/1/2021 - 1/1/9999, price=10 EUR. The patch operation sets validFor to 15/8/2021 - 1/1/9999 and price to 11 EUR. I need full price history, so I can't simply override old values. The operation should handle timelines appropriately, so the new price timeline is:
    |1/1/2021 - 14/8/2021 | 10 EUR |
    |15/8/2021 - 1/1/9999 | 11 EUR |

    • Now I get 2 ProductOfferingPrice entities and id is no longer a unique identifier which violates the OpenAPI specification.
    • To fix the uniqueness issue, let's say I make a new version and set deprecated lifecycle status on the old entity and active status on the new entity; GET operation will only return the active version to ensure id uniqueness.
    When I run the billing cycle for august 2021, I need both entities to correctly calculate the monthly fee (prorated), and the version prior to 15/8/2021 is no longer available. Version/ValidFor are not part of unique identifier to query POP entities...

    ------------------------------
    Bostjan Keber
    Marand d.o.o.
    ------------------------------



  • 8.  RE: TMF-620 price change scenario

    Posted Sep 01, 2021 09:54
    Thank you, Matthieu. This is the crucial piece of information:
    when a system needs a price, they provide the product offering Id and a date, and the product catalogue can only only find 1 productoffering.

    In our internal discussion, we came to the same conclusion. Date input argument is required to obtain a single price.

    Regarding product inventory impact... TMF-637 suggests that ProductPrice entity references ProductOfferingPrice. As you described, changing a price creates a new ProductOfferingPrice element (and adds it to the list of ProductOfferingPrices of a particular Offering). We implemented this the same way. Now, in the product inventory, recurring charges usually have ProductPrices with open time intervals (they are valid for months or even years), so referencing a specific ProductOfferingprice (with validity and amount) is problematic. In reality, our inventory references the Price entity and this is also in line with the TMF-637. Price entity isn't exposed through TMF-620 (only ProductOfferingPrice), though, so I had some difficulties with end-to-end scenarios.

    I guess we will implement extensions to the core product catalog API to support specific use-cases as they arise.

    ------------------------------
    Bostjan Keber
    Marand d.o.o.
    ------------------------------



  • 9.  RE: TMF-620 price change scenario

    TM Forum Member
    Posted Sep 03, 2021 05:00

    can you clarify what you mean by "Price Entity"? I do see a entity  called "Price" in TMF637 (see pic below) but it's the equivalent as ProductPriceValue in TMF620.
    I looked at the ressource models in both APIs for the product domain and they look practically identical.

    ProductPrice does reference ProductOfferingprice Id. but you can have multiple ProductPrice, therefore multiple ProductOfferingprice Id.

    See my redacted comparison below.
    The 2 models


    If Product Inventory needs the latest prices and/or keep a price history you should be able to do it:
    At design time, Marketeer maintain prices and publish them.
    TMF620 publishes the new prices to other domains, 3rd parties etc. (there is also an event (Product Offering Price Create Event) that, I presume, the API can use to trigger the price update (POST /productOfferingPrice))
    and if you need prices for a specific period, then you can filter by date/ValidFor



    ------------------------------
    Matthieu Hattab
    Altibox AS
    ------------------------------



  • 10.  RE: TMF-620 price change scenario

    Posted Sep 03, 2021 07:19
    Edited by Tomáš Hajný Sep 03, 2021 07:18
    I believe that the idea to create new ProductOfferingPrices doesn't the address original point raised by Bostjan, in particular the fact that you might need to update many Product instances in the Product Inventory to change the reference from existing Products to a new ProductPrice ("many" may easily be millions or more here). That's why I asked whether it wasn't possible to update the existing ProductPrice (create new version with new validity) rather than creating a new one. Bostjan correctly mentioned that the Product Catalog API doesn't provide an option to get older versions and thus the history (which is still necessary for certain use cases). However, I still believe that my proposal should be feasible under certain conditions. In particular, it means that use cases requiring the history need to maintain (copy of) the history on their side based on published change events (in addition to the Create event mentioned by you, there's an Update event as well). Admittedly, you'd still need some kind of reconciliation process in order to make sure that no event are missed and the copy is completely consistent with its source in the Product Catalog. Yes, this reconciliation isn't supported by the API (and it might be useful to add such support). However, I believe that it's still a better solution than retrieving all prices including their history from the Product Catalog on demand in the particular use cases requiring all the information including the history.

    Tomas

    ------------------------------
    Tomáš Hajný
    ČD - Telematika
    ------------------------------



  • 11.  RE: TMF-620 price change scenario

    Posted Sep 03, 2021 10:25
    Thank you both, Tomaš and Matthieu, for your inputs!

    I checked TMF-637 again and found the explanation of the Price entity:
    Price sub-resource
    Provides all amounts (tax included, duty free, tax rate), used currency and percentage to apply for Price Alteration.
    So, the purpose of Price in ProductPrice is to support the use-case of price alterations (discounts, allowances) and not (recurring) charges as I initially thought.

    In our internal implementation, we use ProductOfferingPrice as a link between ProductOffering and Price. Price is an abstract entity that may represent different charges (1-time, recurring) and alterations (discounts, allowances,...) and defines rules and logic for the billing system. Price has a list of amounts, each amount has a validity period. So, a combination of Price.id and a timepoint gives you an actual amount (or discount amount/percentage in case of discounts). Not exactly a 1:1 mapping to TMF spec, but the mapping is feasible.


    ------------------------------
    Bostjan Keber
    Marand d.o.o.
    ------------------------------



  • 12.  RE: TMF-620 price change scenario

    TM Forum Member
    Posted Sep 05, 2021 11:03
    A very interesting discussion, sorry I was on vacation so couldn't step in before.
    The "textbook" solution (in my opinion) is indeed to use Product Offering Price versions, so you would have the same ID but create a new version each time you need to change the actual money amount of the POP. In this way you don't need to change the POP reference in the Product Inventory, it continues to point at the same POP.
    When you need to calculate a price, e.g. for proration, you'd need to retrieve the relevant POP versions, using GET with a filter on validFor, as mentioned above by Matthieu. At least in principle, an implementation of TMF620 can support GET with this filter.
    And if you have chosen to implement POP embedded within Product Offering (the older TMF620 style), then your Product Offering would be versioned, and you'd filter the PO by validFor.

    Price Alteration is definitely not the way to go for this.

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 13.  RE: TMF-620 price change scenario

    TM Forum Member
    Posted Sep 05, 2021 20:40
    Quoting Jonathan Goldberg's post:

    "The "textbook" solution (in my opinion) is indeed to use Product Offering Price versions, so you would have the same ID but create a new version each time you need to change the actual money amount of the POP. In this way you don't need to change the POP reference in the Product Inventory, it continues to point at the same POP."

    This would imply that if using REST API, this would be PATCH on the Product Offering Price object ID with a new price amount and version number. The problem with that is that we would lose traceability on price change history.

    We would retain price change history if an new Product Offering Price object was created (using HTTP POST) with appropriate start date, which would create a new product offering price which supersedes the previous product offering price. Of course if the product inventory record has to point to the new product offering price, it would have to be PATCHed to point to the new product offering price ID.

    I guess a decision needs to be made based on requirements to retain price change history.


    ------------------------------
    Richard Loo
    Telstra Corporation
    ------------------------------



  • 14.  RE: TMF-620 price change scenario

    Posted Sep 06, 2021 03:55
    Edited by Tomáš Hajný Sep 06, 2021 03:56
    As already mentioned by Jonathan, you should keep the history in case of an update (PATCH) as well. As far as I can see, the only missing piece (not directly supported by Open API at the moment) is possibility to retrieve the complete history for a given ProductOfferingPrice / list of them at once (e.g. for the reconciliation scenario mentioned in my previous post, or for mass download triggered from the billing system before running processing for a billing cycle).

    Tomas

    ------------------------------
    Tomáš Hajný
    ČD - Telematika
    ------------------------------



  • 15.  RE: TMF-620 price change scenario

    TM Forum Member
    Posted Sep 06, 2021 04:06
    To clarify what I said: "you would have the same ID but create a new version each time"

    This is done by POST, not PATCH. You are not updating the current POP, but rather creating a new one with a new version number. Effectively, the "primary key" for catalog entities is the combination of ID and Version.
    Look at the Version section towards the end of the user guide for TMF620, where version handling for catalog entities is described in more detail.

    Hope it helps


    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 16.  RE: TMF-620 price change scenario

    TM Forum Member
    Posted Sep 07, 2021 19:14
    Thanks for the explanation Jonathan. I will check it out and try it.

    ------------------------------
    Richard Loo
    Telstra Corporation
    ------------------------------



  • 17.  RE: TMF-620 price change scenario

    TM Forum Member
    Posted 19 days ago
    What you are suggesting will not work. POST to TMF620 /productOfferingPrice  does not accept id as property (ie the API assigns the id on POST, not the client, which I believe is correct REST API behaviour)

    ------------------------------
    Richard Loo
    Telstra Corporation
    ------------------------------



  • 18.  RE: TMF-620 price change scenario

    TM Forum Member
    Posted 17 days ago
    Hi Richard
    This is a defect in the published assets for the catalog APIs (including TMF620). The intention of the section that I referred to is clearly to allow creation (i.e. POST) of new versions.
    There is already an open defect report for this https://projects.tmforum.org/jira/browse/AP-2390 - people who are members of the Open API project can open this link to see the details.
    It doesn't look like it will be fixed in v4x, unfortunately.​​

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------