Overview

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.

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.

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.

Important

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	Request Type	Example URL
Retrieve and display details of a requested product entity	GET by ID	{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/product/{ID} NOTE: 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	{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/product/{ID}?fields=name,description
List all the products present in the inventory.	GET List	{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/product
List all the product present in the inventory based on the provided field values.	GET List with Fields	{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/product?fields=name,isBundle,isCustomerVisible,orderDate,description,status,productSerialNumber,startDate
List all the products present in the inventory based on the provided field values and filter applied.	GET List by Fields and Filtering	{https://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	{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/product?limit=1&offset=3

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 terminationDate is 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

1200 OK
2
3{
4    "PageInfo": "Page 1",
5    "PageSize": 50,
6    "result": {
7        "isBundle": "Simple",
8        "isCustomerVisible": true,
9        "productSpecification": {
10            "id": "01tDp000000Ogk5IAC",
11            "name": "Cisco Firepower789"
12        },
13        "productOffering": {
14            "id": "01tDp000000OgkAIAS",
15            "name": "Cisco Firepower789"
16        },
17        "orderDate": "2019-05-03",
18        "productOrderItem": [
19            {
20                "productOrderId": "00000100",
21                "orderItemAction": "Add",
22                "orderItemId": "0000000001"
23            }
24        ],
25        "description": "new desc",
26        "id": "1b55a381-1782-56d6-a90a-2030798d6e4b",
27        "name": "TMForum",
28        "productSerialNumber": "xyz",
29        "startDate": "2024-05-05",
30        "status": "Active",
31        "relatedParty": [
32            {
33                "id": "CD451791",
34                "name": "Test Sh1",
35                "@referredType": "Account"
36            }
37        ],
38        "billingAccount": {
39            "id": "001Dp000002RdyXIAS",
40            "name": "TMForum"
41        },
42        "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/1b55a381-1782-56d6-a90a-2030798d6e4b",
43        "productPrice": [
44            {
45                "priceType": "One-time",
46                "price": {
47                    "taxIncludedAmount": {
48                        "value": 0.00000
49                    }
50                },
51                "name": "a3GDp000000LbKe"
52            }
53        ],
54        "productCharacteristic": [
55            {
56                "name": "B2CCmex_ATTR_DATA_CHAR",
57                "value": "25 GB",
58                "valueType": "Text"
59            },
60            {
61                "name": "B2CCmex_ATTR_HASDISCOUNT_CHAR",
62                "value": "false",
63                "valueType": "Checkbox"
64            },
65            {
66                "name": "B2CCmex_ATTR_MMS",
67                "valueType": "Number"
68            },
69            {
70                "name": "B2CCmex_ATTR_PAYMENT_OPTION_CHAR",
71                "value": "Prepaid",
72                "valueType": "Picklist"
73            },
74            {
75                "name": "B2CCmex_ATTR_SMS_CHAR",
76                "value": "500",
77                "valueType": "Text"
78            },
79            {
80                "name": "B2CCmex_ATTR_TANGIBLE_CHAR",
81                "value": "false",
82                "valueType": "Checkbox"
83            },
84            {
85                "name": "B2CCmex_ATTR_VOICE_CHAR",
86                "value": "500",
87                "valueType": "Text"
88            }
89        ]
90    }
91}

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

1200 OK
2
3{
4    "PageInfo": "Page 1",
5    "PageSize": 50,
6    "result": {
7        "description": "new desc",
8        "id": "1b55a381-1782-56d6-a90a-2030798d6e4b",
9        "name": "TMForum",
10        "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/1b55a381-1782-56d6-a90a-2030798d6e4b"
11    }
12}

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 valueType in productCharacteristic will not appear.

Sample Response

1200 OK
2
3{
4    "PageInfo": "Page 1",
5    "PageSize": 50,
6    "result": [
7        {
8            "isBundle": "Simple",
9            "isCustomerVisible": true,
10            "productSpecification": {
11                "id": "01tDp000000Ogk5IAC",
12                "name": "Cisco Firepower789"
13            },
14            "productOffering": {
15                "id": "01tDp000000Ogk0IAC",
16                "name": "Cisco Firepower789"
17            },
18            "description": "New DESC",
19            "id": "99394f76-7187-c384-b50a-de213527ecd9",
20            "name": "Testing Asset",
21            "productSerialNumber": "123",
22            "status": "Ready for review",
23            "relatedParty": [
24                {
25                    "name": "Testing Asset",
26                    "@referredType": "Account"
27                }
28            ],
29            "billingAccount": {
30                "id": "001Dp000002RdyXIAS",
31                "name": "TMForum"
32            },
33            "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/99394f76-7187-c384-b50a-de213527ecd9",
34            "productPrice": [
35                {
36                    "priceType": "One-time",
37                    "price": {
38                        "taxIncludedAmount": {
39                            "value": 0.00000
40                        }
41                    },
42                    "name": "a3GDp000000LbKU"
43                }
44            ],
45            "productCharacteristic": [
46                {
47                    "name": "B2CCmex_ATTR_DATA_CHAR",
48                    "value": "50 GB",
49                    "valueType": "Text"
50                },
51                {
52                    "name": "B2CCmex_ATTR_HASDISCOUNT_CHAR",
53                    "value": "true",
54                    "valueType": "Checkbox"
55                },
56                {
57                    "name": "B2CCmex_ATTR_MMS",
58                    "value": 20,
59                    "valueType": "Number"
60                },
61                {
62                    "name": "B2CCmex_ATTR_PAYMENT_OPTION_CHAR",
63                    "value": "Postpaid",
64                    "valueType": "Picklist"
65                },
66                {
67                    "name": "B2CCmex_ATTR_SMS_CHAR",
68                    "value": "500",
69                    "valueType": "Text"
70                },
71                {
72                    "name": "B2CCmex_ATTR_TANGIBLE_CHAR",
73                    "value": "false",
74                    "valueType": "Checkbox"
75                },
76                {
77                    "name": "B2CCmex_ATTR_VOICE_CHAR",
78                    "value": "500",
79                    "valueType": "Text"
80                }
81            ]
82        },
83        {
84            "description": "hey",
85            "id": "ed5feda3-b2fe-f590-c253-cd3ad81eae40",
86            "name": "New Asset",
87            "productSerialNumber": "112233",
88            "relatedParty": [
89                {
90                    "id": "CC213425",
91                    "name": "Pyramid Construction Inc.",
92                    "@referredType": "Account"
93                }
94            ],
95            "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/ed5feda3-b2fe-f590-c253-cd3ad81eae40"
96        },
97        {
98            "isBundle": "Simple",
99            "isCustomerVisible": true,
100            "productSpecification": {
101                "id": "01tDp000000Ogk5IAC",
102                "name": "Cisco Firepower789"
103            },
104            "productOffering": {
105                "id": "01tDp000000OgkAIAS",
106                "name": "Cisco Firepower789"
107            },
108            "orderDate": "2019-05-03",
109            "productOrderItem": [
110                {
111                    "productOrderId": "00000100",
112                    "orderItemAction": "Add",
113                    "orderItemId": "0000000001"
114                }
115            ],
116            "description": "new desc",
117            "id": "1b55a381-1782-56d6-a90a-2030798d6e4b",
118            "name": "TMForum",
119            "productSerialNumber": "xyz",
120            "startDate": "2024-05-05",
121            "status": "Active",
122            "relatedParty": [
123                {
124                    "id": "CD451791",
125                    "name": "Test Sh1",
126                    "@referredType": "Account"
127                }
128            ],
129            "billingAccount": {
130                "id": "001Dp000002RdyXIAS",
131                "name": "TMForum"
132            },
133            "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/1b55a381-1782-56d6-a90a-2030798d6e4b",
134            "productPrice": [
135                {
136                    "priceType": "One-time",
137                    "price": {
138                        "taxIncludedAmount": {
139                            "value": 0.00000
140                        }
141                    },
142                    "name": "a3GDp000000LbKe"
143                }
144            ],
145            "productCharacteristic": [
146                {
147                    "name": "B2CCmex_ATTR_DATA_CHAR",
148                    "value": "25 GB",
149                    "valueType": "Text"
150                },
151                {
152                    "name": "B2CCmex_ATTR_HASDISCOUNT_CHAR",
153                    "value": "false",
154                    "valueType": "Checkbox"
155                },
156                {
157                    "name": "B2CCmex_ATTR_MMS",
158                    "valueType": "Number"
159                },
160                {
161                    "name": "B2CCmex_ATTR_PAYMENT_OPTION_CHAR",
162                    "value": "Prepaid",
163                    "valueType": "Picklist"
164                },
165                {
166                    "name": "B2CCmex_ATTR_SMS_CHAR",
167                    "value": "500",
168                    "valueType": "Text"
169                },
170                {
171                    "name": "B2CCmex_ATTR_TANGIBLE_CHAR",
172                    "value": "false",
173                    "valueType": "Checkbox"
174                },
175                {
176                    "name": "B2CCmex_ATTR_VOICE_CHAR",
177                    "value": "500",
178                    "valueType": "Text"
179                }
180            ]
181        }
182    ]
183}

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 valueType in productCharacteristic will not appear.
Id, href, productOffering are always returned, if present.
Sub-resources are not supported as field selection.

Sample Response

1200 OK
2{
3    "PageInfo": "Page 1",
4    "PageSize": 50,
5    "result": [
6        {
7            "isBundle": "Simple",
8            "isCustomerVisible": true,
9            "productOffering": {
10                "id": "01tDp000000Ogk0IAC"
11            },
12            "description": "New DESC",
13            "id": "99394f76-7187-c384-b50a-de213527ecd9",
14            "name": "Testing Asset",
15            "productSerialNumber": "123",
16            "status": "Ready for review",
17            "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/99394f76-7187-c384-b50a-de213527ecd9"
18        },
19        {
20            "description": "hey",
21            "id": "ed5feda3-b2fe-f590-c253-cd3ad81eae40",
22            "name": "New Asset",
23            "productSerialNumber": "112233",
24            "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/ed5feda3-b2fe-f590-c253-cd3ad81eae40"
25        },
26        {
27            "orderDate": "2019-05-03",
28            "isBundle": "Simple",
29            "isCustomerVisible": true,
30            "productOffering": {
31                "id": "01tDp000000OgkAIAS"
32            },
33            "description": "new desc",
34            "id": "1b55a381-1782-56d6-a90a-2030798d6e4b",
35            "name": "TMForum",
36            "productSerialNumber": "xyz",
37            "startDate": "2024-05-05",
38            "status": "Active",
39            "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/1b55a381-1782-56d6-a90a-2030798d6e4b"
40        }
41    ]
42}

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.

Asset

Select the Data Type and add Field Label, Length and Field Name and provide appropriate permissions and save the custom entity.
Add sub-resources/custom fields in the Data Mapper.
- Open TMFTMForumProduct Integration Procedure, select TMFTMForumTransformProductRequest Data Mapper.
- Add the required input mapping.

Data mapping

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

1200 OK
2
3{
4    "PageInfo": "Page 1",
5    "PageSize": 50,
6    "result": {
7        "isBundle": "Simple",
8        "isCustomerVisible": true,
9        "productOffering": {
10            "id": "01tDp000000Ogk0IAC"
11        },
12        "description": "New DESC",
13        "id": "99394f76-7187-c384-b50a-de213527ecd9",
14        "name": "Testing Asset",
15        "productSerialNumber": "123",
16        "status": "Ready for review",
17        "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/99394f76-7187-c384-b50a-de213527ecd9"
18    }
19}

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.

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.

Note

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

1200 OK
2
3{
4  "PageInfo": "Page 3200",
5  "PageSize": 10,
6  "result": [
7    {
8      "description": "my Description",
9      "id": "b6f7e1ac-f0f2-fefd-c960-600866f20803",
10      "name": "Test Asset 5935",
11      "status": "Ready for review",
12      "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/b6f7e1ac-f0f2-fefd-c960-600866f20803",
13      "relatedParty": [
14        {
15          "@referredType": "Account",
16          "id": "CD736025",
17          "name": "University of Arizona"
18        }
19      ]
20    },
21    {
22      "description": "my Description",
23      "id": "6fc0aad1-cf3f-2b63-eabd-b50d2b6b529e",
24      "name": "Test Asset 5936",
25      "status": "Ready for review",
26      "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/6fc0aad1-cf3f-2b63-eabd-b50d2b6b529e",
27      "relatedParty": [
28        {
29          "@referredType": "Account",
30          "id": "CD736025",
31          "name": "University of Arizona"
32        }
33      ]
34    },
35    {
36      "description": "my Description",
37      "id": "17d59688-1d82-12a0-2f23-956544b45e25",
38      "name": "Test Asset 5937",
39      "status": "Ready for review",
40      "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/17d59688-1d82-12a0-2f23-956544b45e25",
41      "relatedParty": [
42        {
43          "@referredType": "Account",
44          "id": "CD736025",
45          "name": "University of Arizona"
46        }
47      ]
48    },
49    {
50      "description": "my Description",
51      "id": "8d32a740-5d97-6063-ed1a-3e2b2a729033",
52      "name": "Test Asset 5938",
53      "status": "Ready for review",
54      "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/8d32a740-5d97-6063-ed1a-3e2b2a729033",
55      "relatedParty": [
56        {
57          "@referredType": "Account",
58          "id": "CD736025",
59          "name": "University of Arizona"
60        }
61      ]
62    },
63    {
64      "description": "my Description",
65      "id": "1510c226-2c01-3b47-01f1-00a119204afd",
66      "name": "Test Asset 5939",
67      "status": "Ready for review",
68      "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/1510c226-2c01-3b47-01f1-00a119204afd",
69      "relatedParty": [
70        {
71          "@referredType": "Account",
72          "id": "CD736025",
73          "name": "University of Arizona"
74        }
75      ]
76    },
77    {
78      "description": "my Description",
79      "id": "375b1082-a25d-1961-aa74-2756eefae385",
80      "name": "Test Asset 5940",
81      "status": "Ready for review",
82      "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/375b1082-a25d-1961-aa74-2756eefae385",
83      "relatedParty": [
84        {
85          "@referredType": "Account",
86          "id": "CD736025",
87          "name": "University of Arizona"
88        }
89      ]
90    },
91    {
92      "description": "my Description",
93      "id": "9918e2e0-4169-4523-33f9-0a2af8c3678d",
94      "name": "Test Asset 5941",
95      "status": "Ready for review",
96      "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/9918e2e0-4169-4523-33f9-0a2af8c3678d",
97      "relatedParty": [
98        {
99          "@referredType": "Account",
100          "id": "CD736025",
101          "name": "University of Arizona"
102        }
103      ]
104    },
105    {
106      "description": "my Description",
107      "id": "3e032288-c5c8-3d0c-62e6-8eec67977e04",
108      "name": "Test Asset 5942",
109      "status": "Ready for review",
110      "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/3e032288-c5c8-3d0c-62e6-8eec67977e04",
111      "relatedParty": [
112        {
113          "@referredType": "Account",
114          "id": "CD736025",
115          "name": "University of Arizona"
116        }
117      ]
118    },
119    {
120      "description": "my Description",
121      "id": "a9713445-5ce6-e597-b9a3-ab50046e3f7e",
122      "name": "Test Asset 5943",
123      "status": "Ready for review",
124      "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/a9713445-5ce6-e597-b9a3-ab50046e3f7e",
125      "relatedParty": [
126        {
127          "@referredType": "Account",
128          "id": "CD736025",
129          "name": "University of Arizona"
130        }
131      ]
132    },
133    {
134      "description": "my Description",
135      "id": "75f205db-ca7e-546f-6c3c-77372f91381a",
136      "name": "Test Asset 5944",
137      "status": "Ready for review",
138      "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/product/75f205db-ca7e-546f-6c3c-77372f91381a",
139      "relatedParty": [
140        {
141          "@referredType": "Account",
142          "id": "CD736025",
143          "name": "University of Arizona"
144        }
145      ]
146    }
147  ]
148}