The TMF637 API provides a standardized mechanism to retrieve product inventory information. TMF637 API manages Product resources, where a Product represents an instance of a Product Offering subscribed to by a party (such as a customer). In the Salesforce context, these products correspond to customer-purchased offerings that are represented as Account Assets.
<!-- The following block diagram provides a high-level view of the components involved in handling the TMF 637 API (GET) operation when bypassing the MuleSoft gateway. -->You can currently perform the following operation on the Product resource using the TMF637 API.
- Retrieval of a product or a collection of products depending on filter criteria
In general, we can consider the various use cases listed based on the operation you want to perform.
important: Starting from the Winter ’27 release, only the Direct Access option will be supported. The MuleSoft gateway option will be deprecated, and customers must update their integrations to use the Connect/Apex REST endpoints for continued access to the inbound APIs.
Assumptions
It is assumed that you have completed the following.
- Enabling Access to Industry APIs
- Ensuring that the required licenses and data packs are installed. For more information, see Before you begin.
Sequence of Operations
Following block diagram provides a sequence of operations involved.
NOTE:
- For mandatory fields and resource mappings, refer TMF637 Resource Mappings
- For more information on supported Integration Procedures, Data Raptors, Apex Interfaces, Custom Metadata, refer Extend TMF637 API.
Use Cases
| I want to <br> <div style="width:290px"></div> | Request Type<br> <div style="width:290px"></div> | Example URL<br> |
|---|---|---|
| Retrieve and display details of a requested product entity | GET by ID | {https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/product/{ID}<br><br>NOTE:<br>For invalid product ID, you will receive HTTP 404 error. |
| Based on the provided field values, retrieve and display details of a particular product ID. For example, name of the product, and description. | GET by ID and Fields<br> | {https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/product/{ID}?fields=name,description<br> |
| List all the products present in the inventory. | GET List<br> | {https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/product<br> |
| List all the product present in the inventory based on the provided field values. | GET List with Fields<br> | {https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/product?fields=name,isBundle,isCustomerVisible,orderDate,description,status,productSerialNumber,startDate<br> |
| List all the products present in the inventory based on the provided field values and filter applied. | GET List by Fields and Filtering<br> | {https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/product?status=Ready for review&name=Testing Asset&productSerialNumber=123&fields=name,isBundle,isCustomerVisible,orderDate,description,status,productSerialNumber,startDate |
| Limit the number of products to a maximum of specified limit and display results from the page specified by an offset. | GET List by limit and offset<br> | {https<nolink>://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/product?limit=1&offset=3<br> |
GET by ID
Consider you want to retrieve details of the product ID = 1b55a381-1782-56d6-a90a-2030798d6e4b
NOTE:
- vlocity__cmtAssetReferenceId__c is used as unique identifier.
- Sample response is considering V2 model is disabled. If enabled, the valueType in productCharacteristic will not appear.
- The field
terminationDateis supported only if the LifecycleManagement license is present. Specifically, the Addon License AssetLifecycleManagementAddon should be present. - The Product Characteristics are mapped to Asset.AttributeSelectedValues__c if V2 attributes are enabled.
Sample URL
https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/1b55a381-1782-56d6-a90a-2030798d6e4b
Sample Response
200 OK
{
"PageInfo": "Page 1",
"PageSize": 50,
"result": {
"isBundle": "Simple",
"isCustomerVisible": true,
"productSpecification": {
"id": "01tDp000000Ogk5IAC",
"name": "Cisco Firepower789"
},
"productOffering": {
"id": "01tDp000000OgkAIAS",
"name": "Cisco Firepower789"
},
"orderDate": "2019-05-03",
"productOrderItem": [
{
"productOrderId": "00000100",
"orderItemAction": "Add",
"orderItemId": "0000000001"
}
],
"description": "new desc",
"id": "1b55a381-1782-56d6-a90a-2030798d6e4b",
"name": "TMForum",
"productSerialNumber": "xyz",
"startDate": "2024-05-05",
"status": "Active",
"relatedParty": [
{
"id": "CD451791",
"name": "Test Sh1",
"@referredType": "Account"
}
],
"billingAccount": {
"id": "001Dp000002RdyXIAS",
"name": "TMForum"
},
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/1b55a381-1782-56d6-a90a-2030798d6e4b",
"productPrice": [
{
"priceType": "One-time",
"price": {
"taxIncludedAmount": {
"value": 0.00000
}
},
"name": "a3GDp000000LbKe"
}
],
"productCharacteristic": [
{
"name": "B2CCmex_ATTR_DATA_CHAR",
"value": "25 GB",
"valueType": "Text"
},
{
"name": "B2CCmex_ATTR_HASDISCOUNT_CHAR",
"value": "false",
"valueType": "Checkbox"
},
{
"name": "B2CCmex_ATTR_MMS",
"valueType": "Number"
},
{
"name": "B2CCmex_ATTR_PAYMENT_OPTION_CHAR",
"value": "Prepaid",
"valueType": "Picklist"
},
{
"name": "B2CCmex_ATTR_SMS_CHAR",
"value": "500",
"valueType": "Text"
},
{
"name": "B2CCmex_ATTR_TANGIBLE_CHAR",
"value": "false",
"valueType": "Checkbox"
},
{
"name": "B2CCmex_ATTR_VOICE_CHAR",
"value": "500",
"valueType": "Text"
}
]
}
}
GET by ID and Fields
Consider you want to retrieve details of the product ID = 1b55a381-1782-56d6-a90a-2030798d6e4b and get the name and description details in the output.
NOTE:
- Id, href, productOffering details are always returned, if present.
Sample URL
https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/1b55a381-1782-56d6-a90a-2030798d6e4b?fields=name,description
Sample Response
200 OK
{
"PageInfo": "Page 1",
"PageSize": 50,
"result": {
"description": "new desc",
"id": "1b55a381-1782-56d6-a90a-2030798d6e4b",
"name": "TMForum",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/1b55a381-1782-56d6-a90a-2030798d6e4b"
}
}
GET List
Consider you want to retrieve details of all the product resources in the inventory. A product resource, represents a customer-purchased offering as an Account Asset.
Sample URL
https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product
NOTE:
- Sample response assumes there are 3 products in the inventory, displays all the sub-resources, if present.
- Sample response is considering V2 model is disabled. If enabled, the
valueTypein productCharacteristic will not appear.
Sample Response
200 OK
{
"PageInfo": "Page 1",
"PageSize": 50,
"result": [
{
"isBundle": "Simple",
"isCustomerVisible": true,
"productSpecification": {
"id": "01tDp000000Ogk5IAC",
"name": "Cisco Firepower789"
},
"productOffering": {
"id": "01tDp000000Ogk0IAC",
"name": "Cisco Firepower789"
},
"description": "New DESC",
"id": "99394f76-7187-c384-b50a-de213527ecd9",
"name": "Testing Asset",
"productSerialNumber": "123",
"status": "Ready for review",
"relatedParty": [
{
"name": "Testing Asset",
"@referredType": "Account"
}
],
"billingAccount": {
"id": "001Dp000002RdyXIAS",
"name": "TMForum"
},
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/99394f76-7187-c384-b50a-de213527ecd9",
"productPrice": [
{
"priceType": "One-time",
"price": {
"taxIncludedAmount": {
"value": 0.00000
}
},
"name": "a3GDp000000LbKU"
}
],
"productCharacteristic": [
{
"name": "B2CCmex_ATTR_DATA_CHAR",
"value": "50 GB",
"valueType": "Text"
},
{
"name": "B2CCmex_ATTR_HASDISCOUNT_CHAR",
"value": "true",
"valueType": "Checkbox"
},
{
"name": "B2CCmex_ATTR_MMS",
"value": 20,
"valueType": "Number"
},
{
"name": "B2CCmex_ATTR_PAYMENT_OPTION_CHAR",
"value": "Postpaid",
"valueType": "Picklist"
},
{
"name": "B2CCmex_ATTR_SMS_CHAR",
"value": "500",
"valueType": "Text"
},
{
"name": "B2CCmex_ATTR_TANGIBLE_CHAR",
"value": "false",
"valueType": "Checkbox"
},
{
"name": "B2CCmex_ATTR_VOICE_CHAR",
"value": "500",
"valueType": "Text"
}
]
},
{
"description": "hey",
"id": "ed5feda3-b2fe-f590-c253-cd3ad81eae40",
"name": "New Asset",
"productSerialNumber": "112233",
"relatedParty": [
{
"id": "CC213425",
"name": "Pyramid Construction Inc.",
"@referredType": "Account"
}
],
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/ed5feda3-b2fe-f590-c253-cd3ad81eae40"
},
{
"isBundle": "Simple",
"isCustomerVisible": true,
"productSpecification": {
"id": "01tDp000000Ogk5IAC",
"name": "Cisco Firepower789"
},
"productOffering": {
"id": "01tDp000000OgkAIAS",
"name": "Cisco Firepower789"
},
"orderDate": "2019-05-03",
"productOrderItem": [
{
"productOrderId": "00000100",
"orderItemAction": "Add",
"orderItemId": "0000000001"
}
],
"description": "new desc",
"id": "1b55a381-1782-56d6-a90a-2030798d6e4b",
"name": "TMForum",
"productSerialNumber": "xyz",
"startDate": "2024-05-05",
"status": "Active",
"relatedParty": [
{
"id": "CD451791",
"name": "Test Sh1",
"@referredType": "Account"
}
],
"billingAccount": {
"id": "001Dp000002RdyXIAS",
"name": "TMForum"
},
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/1b55a381-1782-56d6-a90a-2030798d6e4b",
"productPrice": [
{
"priceType": "One-time",
"price": {
"taxIncludedAmount": {
"value": 0.00000
}
},
"name": "a3GDp000000LbKe"
}
],
"productCharacteristic": [
{
"name": "B2CCmex_ATTR_DATA_CHAR",
"value": "25 GB",
"valueType": "Text"
},
{
"name": "B2CCmex_ATTR_HASDISCOUNT_CHAR",
"value": "false",
"valueType": "Checkbox"
},
{
"name": "B2CCmex_ATTR_MMS",
"valueType": "Number"
},
{
"name": "B2CCmex_ATTR_PAYMENT_OPTION_CHAR",
"value": "Prepaid",
"valueType": "Picklist"
},
{
"name": "B2CCmex_ATTR_SMS_CHAR",
"value": "500",
"valueType": "Text"
},
{
"name": "B2CCmex_ATTR_TANGIBLE_CHAR",
"value": "false",
"valueType": "Checkbox"
},
{
"name": "B2CCmex_ATTR_VOICE_CHAR",
"value": "500",
"valueType": "Text"
}
]
}
]
}
GET List with Fields
Consider you want to retrieve all the product resources by applying the requested fields.
Sample URL
https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product?fields=name,isBundle,isCustomerVisible,orderDate,description,status,productSerialNumber,startDate
NOTE:
- The requested fields will be part of output if they have value.
- The sample output is assuming the total product resources in the system is 3.
- Sample response is considering V2 model is disabled. If enabled, the
valueTypein productCharacteristic will not appear. - Id, href, productOffering are always returned, if present.
- Sub-resources are not supported as field selection.
Sample Response
200 OK
{
"PageInfo": "Page 1",
"PageSize": 50,
"result": [
{
"isBundle": "Simple",
"isCustomerVisible": true,
"productOffering": {
"id": "01tDp000000Ogk0IAC"
},
"description": "New DESC",
"id": "99394f76-7187-c384-b50a-de213527ecd9",
"name": "Testing Asset",
"productSerialNumber": "123",
"status": "Ready for review",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/99394f76-7187-c384-b50a-de213527ecd9"
},
{
"description": "hey",
"id": "ed5feda3-b2fe-f590-c253-cd3ad81eae40",
"name": "New Asset",
"productSerialNumber": "112233",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/ed5feda3-b2fe-f590-c253-cd3ad81eae40"
},
{
"orderDate": "2019-05-03",
"isBundle": "Simple",
"isCustomerVisible": true,
"productOffering": {
"id": "01tDp000000OgkAIAS"
},
"description": "new desc",
"id": "1b55a381-1782-56d6-a90a-2030798d6e4b",
"name": "TMForum",
"productSerialNumber": "xyz",
"startDate": "2024-05-05",
"status": "Active",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/1b55a381-1782-56d6-a90a-2030798d6e4b"
}
]
}
GET List by Fields and Filtering
Consider you want to retrieve all the product resources by specified filter.
Sample URL
https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product?status=Ready for review&name=Testing Asset&productSerialNumber=123&fields=name,isBundle,isCustomerVisible,orderDate,description,status,productSerialNumber,startDate
NOTE:
- Filtering is supported on both standard and custom fields of the Asset object and its sub-resources, such as Product2 and Account.
- You can filter on all fields based on user-provided input, except for fields of type Long Text Area, Geolocation, Text Area (Rich), and Text (Encrypted).
- Recommendation for filtering for description.
- Use full word search.
- Wildcard are only for suffix. For example, to search ‘Sample’, use description=Sam or description=Sampl
- Id, href, productOffering are always returned, if present.
Perform the following steps to add custom fields on resources and sub-resources.
- From the Object Manager tab in Setup, select Asset entity. Click New.
- Select the
Data Typeand addField Label,LengthandField Nameand provide appropriate permissions and save the custom entity. - Add sub-resources/custom fields in the Data Mapper.
- Open
TMFTMForumProductIntegration Procedure, selectTMFTMForumTransformProductRequestData Mapper. - Add the required input mapping.
- Open
Here's the sample URL for the custom field on product2, which is a sub-resource on asset. This returns valid list of assets.
https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product?complianceCertificate=ABC12345
Sample Response
200 OK
{
"PageInfo": "Page 1",
"PageSize": 50,
"result": {
"isBundle": "Simple",
"isCustomerVisible": true,
"productOffering": {
"id": "01tDp000000Ogk0IAC"
},
"description": "New DESC",
"id": "99394f76-7187-c384-b50a-de213527ecd9",
"name": "Testing Asset",
"productSerialNumber": "123",
"status": "Ready for review",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/99394f76-7187-c384-b50a-de213527ecd9"
}
}
GET List by Limit and Offset
Consider you want to retrieve perform the following.
- Limit the number of products to a maximum of specified limit
- Display results from the page specified by an offset
From Winter’26 release, pagination is supported for TMF 637. With pagination, you can now retrieve more than 2,000 records, with a maximum limit of 50,000 records.
note: For better performance and readability, we recommend keeping the limit value below 100 when used with offset. For example, using limit=50 and offset=200 is more efficient than limit=200 and offset=50.
Sample URL
https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product?limit=10&offset=3200
Sample Response
200 OK
{
"PageInfo": "Page 3200",
"PageSize": 10,
"result": [
{
"description": "my Description",
"id": "b6f7e1ac-f0f2-fefd-c960-600866f20803",
"name": "Test Asset 5935",
"status": "Ready for review",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/b6f7e1ac-f0f2-fefd-c960-600866f20803",
"relatedParty": [
{
"@referredType": "Account",
"id": "CD736025",
"name": "University of Arizona"
}
]
},
{
"description": "my Description",
"id": "6fc0aad1-cf3f-2b63-eabd-b50d2b6b529e",
"name": "Test Asset 5936",
"status": "Ready for review",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/6fc0aad1-cf3f-2b63-eabd-b50d2b6b529e",
"relatedParty": [
{
"@referredType": "Account",
"id": "CD736025",
"name": "University of Arizona"
}
]
},
{
"description": "my Description",
"id": "17d59688-1d82-12a0-2f23-956544b45e25",
"name": "Test Asset 5937",
"status": "Ready for review",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/17d59688-1d82-12a0-2f23-956544b45e25",
"relatedParty": [
{
"@referredType": "Account",
"id": "CD736025",
"name": "University of Arizona"
}
]
},
{
"description": "my Description",
"id": "8d32a740-5d97-6063-ed1a-3e2b2a729033",
"name": "Test Asset 5938",
"status": "Ready for review",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/8d32a740-5d97-6063-ed1a-3e2b2a729033",
"relatedParty": [
{
"@referredType": "Account",
"id": "CD736025",
"name": "University of Arizona"
}
]
},
{
"description": "my Description",
"id": "1510c226-2c01-3b47-01f1-00a119204afd",
"name": "Test Asset 5939",
"status": "Ready for review",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/1510c226-2c01-3b47-01f1-00a119204afd",
"relatedParty": [
{
"@referredType": "Account",
"id": "CD736025",
"name": "University of Arizona"
}
]
},
{
"description": "my Description",
"id": "375b1082-a25d-1961-aa74-2756eefae385",
"name": "Test Asset 5940",
"status": "Ready for review",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/375b1082-a25d-1961-aa74-2756eefae385",
"relatedParty": [
{
"@referredType": "Account",
"id": "CD736025",
"name": "University of Arizona"
}
]
},
{
"description": "my Description",
"id": "9918e2e0-4169-4523-33f9-0a2af8c3678d",
"name": "Test Asset 5941",
"status": "Ready for review",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/9918e2e0-4169-4523-33f9-0a2af8c3678d",
"relatedParty": [
{
"@referredType": "Account",
"id": "CD736025",
"name": "University of Arizona"
}
]
},
{
"description": "my Description",
"id": "3e032288-c5c8-3d0c-62e6-8eec67977e04",
"name": "Test Asset 5942",
"status": "Ready for review",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/3e032288-c5c8-3d0c-62e6-8eec67977e04",
"relatedParty": [
{
"@referredType": "Account",
"id": "CD736025",
"name": "University of Arizona"
}
]
},
{
"description": "my Description",
"id": "a9713445-5ce6-e597-b9a3-ab50046e3f7e",
"name": "Test Asset 5943",
"status": "Ready for review",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/a9713445-5ce6-e597-b9a3-ab50046e3f7e",
"relatedParty": [
{
"@referredType": "Account",
"id": "CD736025",
"name": "University of Arizona"
}
]
},
{
"description": "my Description",
"id": "75f205db-ca7e-546f-6c3c-77372f91381a",
"name": "Test Asset 5944",
"status": "Ready for review",
"href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/75f205db-ca7e-546f-6c3c-77372f91381a",
"relatedParty": [
{
"@referredType": "Account",
"id": "CD736025",
"name": "University of Arizona"
}
]
}
]
}