Hi there,
I hope you're all well. We're currently implementing Quote Management, Product Ordering, and Product Inventory flows based on TMF Open APIs, and we've come across a few points where documentation and examples suggest one approach, but we're unsure whether alternative approaches are equally valid or even preferable.
I'd be grateful for your insights on the following:
1) Flat vs Nested Structure for Bundled Products
In the official examples for Quote, ProductOrder, and ProductInventory, bundled items are usually represented using a flat productOrderItem array, with relationships marked via productOrderItemRelationship.type = "bundles".
However, the productOrderItem and quoteItem schemas also support nesting. Since our product catalog is modelled with a nested bundle structure (parent ProductOffering containing child offerings), it feels more natural and cleaner to mirror this in orders and quotes via nesting.
Is nesting an equally valid and recommended approach to represent bundled products, especially when it reflects the hierarchy of the catalog? Are there cases where one method is preferred over the other?
Nested structure as it appears in product catalog:
"quoteItem": [
{
"id": "1",
"@type": "QuoteItem",
"action": "add",
"quantity": 1,
"productOffering": {
"@type": "ProductOfferingRef",
"id": "<UID_FOR_MSB_BUNDLE>",
"name": "Managed Security Box Bundle"
},
"quoteItem": [
{
"@type": "QuoteItem",
"id": "1.1",
"action": "add",
"productOffering": {
"@type": "ProductOfferingRef",
"id": "<UID_FOR_MSB>",
"name": "Managed Security Box"
},
"quantity": 1
},
{
"@type": "QuoteItem",
"id": "1.2",
"action": "add",
"productOffering": {
"@type": "ProductOfferingRef",
"id": "<UID_FOR_COMMITMENT>",
"name": "Commitment"
},
"quantity": 1
}
]
}
]
Flat structure as appears in open api examples:
"quoteItem": [
{
"@type": "QuoteItem",
"id": "1",
"action": "add",
"productOffering": {
"@type": "ProductOfferingRef",
"id": "<UID_FOR_MSB_BUNDLE>",
"name": "Managed Security Box Bundle"
},
"quantity": 1,
"quoteItemRelationship": [
{
"@type": "QuoteItemRelationship",
"id": "2",
"relationshipType": "bundles"
},
{
"@type": "QuoteItemRelationship",
"id": "3",
"relationshipType": "bundles"
}
]
},
{
"@type": "QuoteItem",
"id": "2",
"action": "add",
"productOffering": {
"@type": "ProductOfferingRef",
"id": "<UID_FOR_MSB>",
"name": "Managed Security Box"
}
},
{
"@type": "QuoteItem",
"id": "3",
"action": "add",
"productOffering": {
"@type": "ProductOfferingRef",
"id": "<UID_FOR_COMMITMENT>",
"name": "Shipping"
},
"quantity": 1
}
]
2) Difference Between item.price and item.product.price in quote and product order
We've noticed that both quoteItem and productOrderItem support placing price either directly on the item or under the nested product field.
What's the semantic or functional difference between item.price and item.product.price in the context of TMF APIs? When should one be preferred over the other?
3) Difference Between item.productOffering and item.product.productOffering in quote and product order
Similarly, we see both productOffering on the item level and within the product object. Could you clarify the distinction between item.productOffering and item.product.productOffering?
Are both required in certain cases, or is one merely a convenience reference? What's the best practice here?
Many thanks in advance for any guidance you can offer. We appreciate the work that has gone into these APIs and just want to ensure we're applying them in the most compliant and future-proof way.
Kind Regards,
M.
------------------------------
Martin Barnas
T-Mobile Czech & Slovak Telekom, a.s.
------------------------------