Product Specification Use Cases

I want to <br> <div style="width:120px"></div>	Request Type <br> <div style="width:290px"></div>	Example URL <br> <div style="width:290px"></div>
Retrieve and display details of a requested product specification.	GET by ID	{https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification/{ID}<br><br>NOTE:<br>For invalid category ID, you will receive HTTP 404 error.
Based on the provided field values, retrieve and display details of a particular product specification ID.	GET by ID and Fields	{https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification/{ID}?fields=name,description,isBundle
List all the product specifications present in the system.	GET List	{https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification
List all the product specifications present in the system<br>based on the provided field values.	GET List with Fields	{https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?fields=name,description,isBundle<br>
List all the product specifications present in the inventory based on the provided field values and filter applied.	GET List by Fields and Filtering	{https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?fields=name,description,isBundle&isBundle=false
Limit the number of product specification to a maximum of specified limit and<br>display results from the page specified by an offset.	GET List by limit and offset	{https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?limit=2&offset=2<br>
Create a product specification.	POST	{https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification<br>
Update a product specification.	PATCH	{https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification/{ID}<br>
Delete a product specification.	DELETE	{https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification/{ID}<br>

GET by ID

Consider you want to retrieve details of a product specification from the inventory.

Context-Based Override Resolution

The TMF620 Product Catalog Management API now supports accurate resolution of product configurations, attributes, and pricing within specific bundle contexts through enhanced override handling capabilities.

What's Changed

Previously, when retrieving product details from bundled product hierarchies, the API would:

Return duplicate records for child products that were overridden at multiple hierarchy levels
Resolve child product attributes using only the immediate parent context

The enhanced API now correctly resolves a single, contextually accurate representation of products and their configurations based on the specified bundle hierarchy.

Key Capabilities

The API supports three types of context-specific overrides:

Child Item Overrides: Retrieve bundle-specific child product configurations, including quantity, selling periods, and inclusion/exclusion rules
Attribute Overrides: Access characteristic values (such as data balance, speed, or capacity) that differ within specific bundle contexts
Price List Entry Overrides: Retrieve bundle-specific pricing instead of standard product pricing

New Query Parameters

Three new query parameters enable context-based resolution:

Parameter	Type	Description
`handleOverrides`	Boolean	Controls override resolution behavior. When `true`, returns only contextually relevant overrides; when `false` or omitted, returns all configurations including base and overridden values.
`parentContext`	String	The unique product ID of the root or bundle product providing context for override resolution.
`hierarchy`	String	The complete path from root product to target product, used when a child product appears multiple times in the bundle structure. Format: `rootProductId<parentProductId<childProductId`

Usage Examples

Consider a product hierarchy: Triple Play Bundle → Internet Services → Fiber Internet 1Gbps

Example 1: Retrieve standalone product with all attributes (default behavior)

GET /productSpecification/{productId}

Returns all attributes (base + all overridden values from all contexts)

Example 2: Retrieve product with base attributes only

GET /productSpecification/{productId}?handleOverrides=true

Returns only the base product attributes without any overrides

Example 3: Retrieve product in specific bundle context

GET /productSpecification/{productId}?handleOverrides=true&parentContext={bundleProductId}

Returns the product with attributes and configurations as overridden within the specified parent bundle

Example 4: Retrieve product with explicit hierarchy path

GET /productSpecification/{productId}?handleOverrides=true&hierarchy={rootId}<{parentId}<{productId}

Returns the product resolved through the specified hierarchy path, useful when a product appears multiple times in the bundle structure

important: - When handleOverrides is set to true, the API retrieves all overridden price list entries regardless of hierarchy position within the bundle

Accurate override resolution requires passing the correct parentContext or hierarchy parameters
Without context parameters, the API defaults to standalone product resolution
Context-based resolution applies to GET operations on the productSpecification resource

GET by ID and Fields

Consider you want to retrieve details of the product specification ID = f58d3bce-e229-74c5-6a4c-40aa68714c53 and get the name, description and isBundle details in the output.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification/f58d3bce-e229-74c5-6a4c-40aa68714c53?fields=name,description,isBundle

Sample Response

200 OK
{
  {
 "PageInfo": "Page 1 of 1",
 "PageSize": 50,
 "result": {
 "description": "Airtel Wifi Router with 1000Mbps Bandwidth",
 "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/0b1a75ff-f9ee-2547-2c57-e2f27b860356",
 "isBundle": false,
 "name": "Airtel Wifi Router"
 }
}
}

GET List

Consider you want to retrieve details of all the product specifications in the inventory.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification

Sample Response

200 OK
{
"PageInfo": "Page 1 of 1",
"PageSize": 50,
"result": [
{
"description": "Powerful product that integrates with a firewall",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/01tDo000000iAgBIAU",
"id": "8a8befe1-e6d5-fafc-c909-ae32eda09d53",
"isBundle": true,
"lastUpdate": "2023-08-24T06:53:57.000+0000",
"lifecycleStatus": "Active",
"name": "PostManTestProductSpecifcation- 462757",
"productNumber": "CSC-340-NGFW",
"version": "2.0",
"validFor": {
"endDateTime": "2022-11-24T16:42:23.000+0000",
"startDateTime": "2020-09-23T00:00:00.000+0000"
}
},
{
"description": "Product with email security, network traffic analysis, network access control and CASB.",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/01tDo000000iAgGIAU",
"id": "07a3cca9-45c5-3957-9b31-52031fe02481",
"isBundle": true,
"lastUpdate": "2023-08-24T06:54:03.000+0000",
"lifecycleStatus": "Active",
"name": "PostManTestProductSpecifcation- 462757",
"productNumber": "CSC-340-NGFW",
"version": "2.0",
"validFor": {
"endDateTime": "2022-11-24T16:42:23.000+0000",
"startDateTime": "2020-09-23T00:00:00.000+0000"
}
},
{
"description": "Postpaid Add On from workbeanch 1",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/01tDo000000iAg6IAE",
"id": "54132fad-ab30-3a05-e6a3-a26f5e072d86",
"isBundle": false,
"lastUpdate": "2023-09-07T08:42:12.000+0000",
"lifecycleStatus": "Inactive",
"name": "Postpaid Addon from workbeanch 1",
"productNumber": "CSC-340-NGFW",
"version": "2.0",
"validFor": {
"endDateTime": "2024-04-25T00:00:00.000+0000",
"startDateTime": "2021-08-24T00:00:00.000+0000"
}
}
]
}

GET List with Fields

Consider you want to retrieve all the product specifications by applying the requested fields.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?fields=name,description,isBundle

Sample Response

200 OK

{
"PageInfo": "Page 1 of 1",
"PageSize": 50,
"result": [
{
"description": "Airtel Wifi Router with 1000Mbps Bandwidth",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/01tDo000000iAfhIAE",
"isBundle": false,
"name": "Airtel Wifi Router"
},
{
"description": "Airtel Wifi Router with 1000Mbps Bandwidth",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/01tDo000000iAfmIAE",
"isBundle": false,
"name": "Airtel Wifi Router"
},
{
"description": "Airtel Wifi Router with 1000Mbps Bandwidth",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/01tDo000000iAfrIAE",
"isBundle": false,
"name": "Airtel Wifi Router"
}
]
}

GET List by Fields and Filtering

Consider you want to retrieve all the product specifications by a specified filter.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?fields=name,description,isBundle&isBundle=false

Sample Response

200 OK
{
"PageInfo": "Page 1 of 1",
"PageSize": 50,
"result": [
{
"description": "Airtel Wifi Router with 1000Mbps Bandwidth",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/01tDo000000iAfhIAE",
"lifecycleStatus": "Active",
"name": "Airtel Wifi Router"
},
{
"description": "Airtel Wifi Router with 1000Mbps Bandwidth",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/01tDo000000iAfmIAE",
"lifecycleStatus": "Active",
"name": "Airtel Wifi Router"
},
{
"description": "Airtel Wifi Router with 1000Mbps Bandwidth",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/01tDo000000iAfrIAE",
"lifecycleStatus": "Active",
"name": "Airtel Wifi Router"
}
]
}

GET List by limit and offset

Consider you want to retrieve perform the following.

Limit the number of product specifications to a maximum of specified limit
Display results from the page specified by an offset

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?offset=1&limit=2

Sample Response

200 OK

{
"PageInfo": "Page 1 of 4",
"PageSize": 2,
"result": [
{
"description": "Airtel Wifi Router with 1000Mbps Bandwidth",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productOffering/01tDo000000iAfhIAE",
"id": "0b1a75ff-f9ee-2547-2c57-e2f27b860356",
"isBundle": false,
"isSellable": true,
"lastUpdate": "2023-08-24T06:49:33.000+0000",
"lifecycleStatus": "Active",
"name": "Airtel Wifi Router",
"productNumber": "Airtel_Wifi_Router",
"version": "1.0",
"validFor": {
"endDateTime": "2022-08-25T00:00:00.000+0000",
"startDateTime": "2022-05-23T00:00:00.000+0000"
},
"productOfferingPrice": [
{
"version": "1.0",
"priceType": "One-time",
"href": "/services/data/v57.0/sobjects/vlocity_cmt__PriceListEntry__c/a3GDo0000008rT3MAI",
"isBundle": false,
"name": "a3GDo0000008rT3",
"price": {
"amount": "0"
}
}
]
},
{
"description": "Airtel Wifi Router with 1000Mbps Bandwidth",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productOffering/01tDo000000iAfmIAE",
"id": "829c48a3-6b85-5d49-1f1f-9589b7d42816",
"isBundle": false,
"isSellable": true,
"lastUpdate": "2023-08-24T06:49:46.000+0000",
"lifecycleStatus": "Active",
"name": "Airtel Wifi Router",
"productNumber": "Airtel_Wifi_Router",
"version": "1.0",
"validFor": {
"endDateTime": "2022-08-25T00:00:00.000+0000",
"startDateTime": "2022-05-23T00:00:00.000+0000"
},
"productOfferingPrice": [
{
"version": "1.0",
"priceType": "One-time",
"href": "/services/data/v57.0/sobjects/vlocity_cmt__PriceListEntry__c/a3GDo0000008rT8MAI",
"isBundle": false,
"name": "a3GDo0000008rT8",
"price": {
"amount": "0"
}
}
]
}
]
}

POST

Consider you want to create a new product specification.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification

Sample Request

{
"name" : "sample name",
"description" : "description text",
"validFor": {
"startDateTime": "2020-11-24T00:00:00Z",
"endDateTime": "2022-11-24T00:00:00Z"
},
"bundledProductSpecification": [
{
"id": "0d321a21-c07f-4067-7bed-edd8156bb05d",
"name": "Root Offer"
}
],
"productSpecificationRelationship": [
{
"id": "e9b4e4b2-ea11-edfc-81c4-e2fc245410b1",
"relationshipType": "OptionalFor",
"name": "demo pricing"
}
],
"productSpecCharacteristic": [
{
"productSpecCharacteristicValue": [
{
"valueType": "Text"
}
],
"valueType": "Text",
"name": "Attribute Text",
"displayName": "Attribute Text",
"description": "Attribute desc",
"configurable": false
}
],
"attachment": [
{
"url": "/servlet/servlet.FileDownload?file=0154x000000qUGEAA2",
"name": "image 511",
"description": "desc 4"
}
]
}

Sample Response

200 OK

{
    "productNumber": "19Aug-ParentProduct-01 updated",
    "name": "sample name",
    "lifecycleStatus": "Active",
    "lastUpdate": "2023-01-10T14:03:27.000+0000",
    "isSellable": true,
    "isBundle": false,
    "id": "1be8a7d6-287e-b8ea-a6f3-e05b909d4357",
    "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productOffering/01t4x000004EpeQAAS",
    "description": "description updated 123",
    "validFor": {
    "startDateTime": "2020-08-24T00:00:00.000+0000",
    "endDateTime": "2024-03-25T00:00:00.000+0000"
    },
    "productSpecificationRelationship": [
        {
        "id": "e9b4e4b2-ea11-edfc-81c4-e2fc245410b1",
        "relationshipType": "OptionalFor",
        "name": "demo pricing"
        }
    ],
    "bundledProductSpecification": [
        {
        "id": "0d321a21-c07f-4067-7bed-edd8156bb05d",
        "name": "Root Offer"
        }
    ],
    "productSpecCharacteristic": [
        {
            "productSpecCharacteristicValue": [
                {
                    "valueType": "Text"
                }
            ],
            "valueType": "Text",
            "name": "Attribute Text",
            "displayName": "Attribute Text",
            "description": "Attribute desc",
            "configurable": false
        }
    ],
    "attachment": [
            {
                "url": "/servlet/servlet.FileDownload?file=0154x000000qUGEAA2",
                "name": "image 511",
                "id": "a1gRO0000000MqjYAE",
                "href": "/services/data/v48.0/sobjects/vlocity_cmt__VlocityAttachment__c/a1gRO0000000MqjYAE",
                "description": "desc 4"
            }
    ]
}

PATCH

Consider for the product offer ID = f58d3bce-e229-74c5-6a4c-40aa68714c53 you want to update first level attributes and sub-resources.

Sample URL

Sample Request

{
"name": "Updated - Name",
"description" : "updated description"
}

Sample Response

{
 "productNumber": "test number",
 "name": "Updated - Name",
 "lifecycleStatus": "Inactive",
 "lastUpdate": "2023-09-27T10:07:16.000+0000",
 "isBundle": false,
 "id": "f58d3bce-e229-74c5-6a4c-40aa68714c53",
 "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/01tDo000000i4CaIAI",
 "description": "updated description"
}

DELETE

Consider you want to delete a product offering ID: 3830.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/3830

Sample Response

204 No content