Overview

The TMF622 API provides a standardized client interface to Order Intake Systems for creating, tracking, and managing product orders as a result of an issue or problem identified by a customer or another system.

Consider you have purchased a new product. A product order is created based on a product offering that is defined in a catalog (POST). The product offering identifies the product or set of products that are available to a you, and includes characteristics such as pricing, product options and market. You can also check the status of the product order or access all the product orders from the system (GET) and also update (PATCH) the details.

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, refer Before you begin.

Sequence of Operations

Following block diagram provides a sequence of operations involved.

NOTE:

For mandatory fields and resource mappings, refer TMF622 v4 Resource Mappings.
For more information on supported Integration Procedures, Data Raptors, Apex Interfaces, Custom Metadata, refer Extend TMF622 API documentation.
TMF622 works only if Standard Cart APIs are enabled.

TMF622 v4 Use Cases

I want to	Request Type	Example URL
Retrieve and display details of a particular product order.	GET by ID	{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productorder/{ID} NOTE: For invalid product order ID, you will receive HTTP 404 error.
Based on the provided field values, retrieve and display details of a particular product order ID.	GET by ID and Fields	{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productorder/{ID}?fields=description,state,externalId,note,requestedCompletionDate,requestedStartDate,channel,orderDate,id,href NOTE: The requested fields will be part of output, if they have value.
List all the product orders present in the system.	GET List	{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productorder
List all the product orders present in the system based on the provided field values and filter applied. For example, list all the product orders with status = Activated,state, and channel details.	GET List by Fields and Filtering	{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productorder?fields=state=Activated&fields=state,channel NOTE: The requested fields will be part of output, if they have value.
List product orders based on the date of creation, limit the number of product orders to a maximum of specified limit, and display results from the page specified by offset.	GET List by Limit and Offset	{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productorder?limit=10&offset=3
Create a new product order by providing the required details.	POST	{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productorder
Update A product order by providing the required details.	PATCH	{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productorder/{ID}

GET by ID

Consider you want to retrieve details of a particular product order. For example, product order ID = 00004122. Fields that can be filtered:

id
state
orderDate

Sample URL

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

Sample Response

Refer Retrieve ProductOrder by ID

Field orderLineItemId is present for every ProductOrderItem in response.

Sample URL

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

Sample Response

1{
2    "channel": [
3        {
4            "role": "Used channel for order capture",
5            "name": "Online chanel",
6            "id": "1"
7        }
8    ],
9    "note": [
10        {
11            "text": "This is a TMF product order illustration",
12            "id": "1",
13            "date": "2019-04-30T08:13:59.509Z",
14            "author": "Jean Pontus"
15        }
16    ],
17    "productOrderItem": [
18        {
19            "productOffering": {
20                "id": "SIMCard"
21            },
22            "orderLineItemId": "802xx000001nfhfAAA",
23            "quantity": 4.00,
24            "id": "101",
25            "action": "Add",
26            "@type": "ProductOrderItem"
27        },
28        {
29            "productOffering": {
30                "id": "iphone15"
31            },
32            "productOrderItemRelationship": [
33                {
34                    "relationshipType": "bundles",
35                    "id": "101"
36                }
37            ],
38            "orderLineItemId": "802xx000001nfhgAAA",
39            "quantity": 1.00,
40            "id": "100",
41            "action": "Add",
42            "@type": "ProductOrderItem"
43        }
44    ],
45    "relatedParty": [
46        {
47            "name": "TMF622",
48            "id": "123",
49            "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Account/001xx000003GfJrAAK",
50            "@type": "RelatedParty",
51            "role": "Billing"
52        }
53    ],
54    "state": "Draft",
55    "requestedStartDate": "2019-05-03T00:00:00.000+0000",
56    "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
57    "orderDate": "2025-05-19T08:48:59.000+0000",
58    "id": "00000262",
59    "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Order/801xx000003GhtXAAS",
60    "externalId": "PO-456",
61    "description": "Product Order illustration sample-updated"
62}

GET by ID and Fields

Consider you want to retrieve details of the product order ID = 00005220 and get the following details in the output.

description
state
externalId
note
requestedCompletionDate
requestedStartDate
channel
orderDate
id
href

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productorder/00005220?fields=description,state,externalId,note,requestedCompletionDate,requestedStartDate,channel,orderDate,id,href

Sample Response

1200
2{
3    "PageInfo": "Page 1",
4    "PageSize": 50,
5    "result": {
6        "channel": "Online chanel",
7        "description": "Product Order illustration sample",
8        "externalId": "PO-456",
9        "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001j7x2IAA",
10        "id": "00005220",
11        "note": "id:1;date:2019-04-30T08:13:59.509Z;text:This is a TMF product order illustration",
12        "orderDate": "2023-05-17T17:17:09.000+0000",
13        "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
14        "requestedStartDate": "2019-05-03T00:00:00.000+0000",
15        "state": "Draft"
16    }
17}

GET List

Consider there are multiple product orders in the system and you want to list all of them.

Sample URL

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

Sample Response

Refer List All Product Orders

GET List by Fields and Filtering

Consider you want to retrieve all the active product orders present in the system with applied filter values.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productorder?state=Activated&fields=state,channel

Sample Response

1200
2{
3    "PageInfo": "Page 1",
4    "PageSize": 50,
5    "result": [
6        {
7            "channel": "Call Center",
8            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJTVIA2",
9            "state": "Activated"
10        },
11        {
12            "channel": "Call Center",
13            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJcDIAU",
14            "state": "Activated"
15        },
16        {
17            "channel": "Call Center",
18            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJkNIAU",
19            "state": "Activated"
20        },
21        {
22            "channel": "Call Center",
23            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJkcIAE",
24            "state": "Activated"
25        },
26        {
27            "channel": "Call Center",
28            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJkmIAE",
29            "state": "Activated"
30        },
31        {
32            "channel": "Call Center",
33            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJkrIAE",
34            "state": "Activated"
35        },
36        {
37            "channel": "Call Center",
38            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJkwIAE",
39            "state": "Activated"
40        },
41        {
42            "channel": "Call Center",
43            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJl1IAE",
44            "state": "Activated"
45        },
46        {
47            "channel": "Call Center",
48            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlBIAU",
49            "state": "Activated"
50        },
51        {
52            "channel": "Call Center",
53            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlGIAU",
54            "state": "Activated"
55        },
56        {
57            "channel": "Call Center",
58            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlQIAU",
59            "state": "Activated"
60        },
61        {
62            "channel": "Call Center",
63            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlaIAE",
64            "state": "Activated"
65        },
66        {
67            "channel": "Call Center",
68            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlfIAE",
69            "state": "Activated"
70        },
71        {
72            "channel": "Call Center",
73            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlkIAE",
74            "state": "Activated"
75        },
76        {
77            "channel": "Call Center",
78            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlpIAE",
79            "state": "Activated"
80        },
81        {
82            "channel": "Call Center",
83            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJluIAE",
84            "state": "Activated"
85        },
86        {
87            "channel": "Online chanel",
88            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lL5cIAE",
89            "state": "Activated"
90        },
91        {
92            "channel": "Online chanel",
93            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lL6GIAU",
94            "state": "Activated"
95        },
96        {
97            "channel": "Online chanel",
98            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lLTPIA2",
99            "state": "Activated"
100        },
101        {
102            "channel": "Call Center",
103            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lLTyIAM",
104            "state": "Activated"
105        },
106        {
107            "channel": "Call Center",
108            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lLU8IAM",
109            "state": "Activated"
110        },
111        {
112            "channel": "Online chanel",
113            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMHOIA2",
114            "state": "Activated"
115        },
116        {
117            "channel": "Online chanel",
118            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMHTIA2",
119            "state": "Activated"
120        },
121        {
122            "channel": "Online chanel",
123            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMIHIA2",
124            "state": "Activated"
125        },
126        {
127            "channel": "Online chanel",
128            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMIMIA2",
129            "state": "Activated"
130        },
131        {
132            "channel": "Online chanel",
133            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMg0IAE",
134            "state": "Activated"
135        },
136        {
137            "channel": "name: Online chanel",
138            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMg5IAE",
139            "state": "Activated"
140        },
141        {
142            "channel": "name: Online chanel",
143            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMgUIAU",
144            "state": "Activated"
145        },
146        {
147            "channel": "name: Online chanel",
148            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lOFDIA2",
149            "state": "Activated"
150        },
151        {
152            "channel": "name: Online chanel",
153            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lOGaIAM",
154            "state": "Activated"
155        },
156        {
157            "channel": "name: Online chanel",
158            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lOHsIAM",
159            "state": "Activated"
160        },
161        {
162            "channel": "name: Offline chanel",
163            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lOIlIAM",
164            "state": "Activated"
165        }
166    ]
167}

GET List by Limit and Offset

Consider you want to retrieve list of products and apply required pagination query.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productorder?limit=10&offset=3

NOTE: If the total products are 22, the above pagination query - limit=10&offset=3 will start display from page 3 and will have 2 records

Sample Response

1200 OK
2{
3    "PageInfo": "Page 3",
4    "PageSize": 10,
5    "result": [
6        {
7            "channel": "Call Center",
8            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlVIAU",
9            "id": "00006988",
10            "orderDate": "2023-06-14T06:18:55.000+0000",
11            "state": "Draft",
12            "relatedParty": [
13                {
14                    "@type": "RelatedParty",
15                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000FDDn6IAH",
16                    "id": "CD656092",
17                    "name": "Burlington Textiles Corp of America"
18                }
19            ]
20        },
21        {
22            "channel": "Call Center",
23            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlaIAE",
24            "id": "00006989",
25            "orderDate": "2023-06-14T06:19:37.000+0000",
26            "state": "Activated",
27            "relatedParty": [
28                {
29                    "@type": "RelatedParty",
30                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000FDDn6IAH",
31                    "id": "CD656092",
32                    "name": "Burlington Textiles Corp of America"
33                }
34            ],
35            "productOrderItem": [
36                {
37                    "@type": "ProductOrderItem",
38                    "action": "Add",
39                    "id": "0ff363a6-f064-3135-0e25-0ca26d002941",
40                    "quantity": 1.00
41                }
42            ]
43        },
44        {
45            "channel": "Call Center",
46            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlfIAE",
47            "id": "00006990",
48            "orderDate": "2023-06-14T06:23:29.000+0000",
49            "state": "Activated",
50            "relatedParty": [
51                {
52                    "@type": "RelatedParty",
53                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000FDDn6IAH",
54                    "id": "CD656092",
55                    "name": "Burlington Textiles Corp of America"
56                }
57            ],
58            "productOrderItem": [
59                {
60                    "@type": "ProductOrderItem",
61                    "action": "Add",
62                    "id": "6af7348d-a1c4-fce6-88b2-dc4418a2b059",
63                    "quantity": 1.00
64                }
65            ]
66        },
67        {
68            "channel": "Call Center",
69            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlkIAE",
70            "id": "00006991",
71            "orderDate": "2023-06-14T06:25:11.000+0000",
72            "state": "Activated",
73            "relatedParty": [
74                {
75                    "@type": "RelatedParty",
76                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000FDDn6IAH",
77                    "id": "CD656092",
78                    "name": "Burlington Textiles Corp of America"
79                }
80            ],
81            "productOrderItem": [
82                {
83                    "@type": "ProductOrderItem",
84                    "action": "Add",
85                    "id": "ab8b12a3-a78a-02df-be28-608491311b21",
86                    "quantity": 1.00
87                }
88            ]
89        },
90        {
91            "channel": "Call Center",
92            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlpIAE",
93            "id": "00006992",
94            "orderDate": "2023-06-14T06:27:24.000+0000",
95            "state": "Activated",
96            "relatedParty": [
97                {
98                    "@type": "RelatedParty",
99                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000FDDn6IAH",
100                    "id": "CD656092",
101                    "name": "Burlington Textiles Corp of America"
102                }
103            ],
104            "productOrderItem": [
105                {
106                    "@type": "ProductOrderItem",
107                    "action": "Add",
108                    "id": "f07b8f51-1ff4-0b25-e607-f5ec54ab637d",
109                    "quantity": 1.00
110                }
111            ]
112        },
113        {
114            "channel": "Call Center",
115            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJluIAE",
116            "id": "00006993",
117            "orderDate": "2023-06-14T06:28:50.000+0000",
118            "state": "Activated",
119            "relatedParty": [
120                {
121                    "@type": "RelatedParty",
122                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000FDDn6IAH",
123                    "id": "CD656092",
124                    "name": "Burlington Textiles Corp of America"
125                }
126            ],
127            "productOrderItem": [
128                {
129                    "@type": "ProductOrderItem",
130                    "action": "Add",
131                    "id": "f07b8f51-1ff4-0b25-e607-f5ec54ab637d",
132                    "quantity": 1.00
133                }
134            ]
135        },
136        {
137            "channel": "Online chanel",
138            "description": "Product Order illustration sample",
139            "externalId": "PO-456",
140            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lL5XIAU",
141            "id": "00008020",
142            "note": "id:1;date:2019-04-30T08:13:59.509Z;text:This is a TMF product order illustration",
143            "orderDate": "2023-06-23T08:58:34.000+0000",
144            "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
145            "requestedStartDate": "2019-05-03T00:00:00.000+0000",
146            "state": "Draft",
147            "relatedParty": [
148                {
149                    "@type": "RelatedParty",
150                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000HZDL0IAP",
151                    "id": "CD1234",
152                    "name": "Acme"
153                }
154            ]
155        },
156        {
157            "channel": "Online chanel",
158            "description": "Product Order illustration sample",
159            "externalId": "PO-456",
160            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lL5cIAE",
161            "id": "00008021",
162            "note": "id:1;date:2019-04-30T08:13:59.509Z;text:This is a TMF product order illustration",
163            "orderDate": "2023-06-23T09:01:57.000+0000",
164            "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
165            "requestedStartDate": "2019-05-03T00:00:00.000+0000",
166            "state": "Activated",
167            "relatedParty": [
168                {
169                    "@type": "RelatedParty",
170                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000HZDL0IAP",
171                    "id": "CD1234",
172                    "name": "Acme"
173                }
174            ],
175            "productOrderItem": [
176                {
177                    "@type": "ProductOrderItem",
178                    "action": "Add",
179                    "id": "f07b8f51-1ff4-0b25-e607-f5ec54ab637d",
180                    "quantity": 1.00
181                }
182            ]
183        },
184        {
185            "channel": "Online chanel",
186            "description": "Product Order illustration sample new",
187            "externalId": "PO-456",
188            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lL6GIAU",
189            "id": "00008022",
190            "note": "id:1;date:2019-04-30T08:13:59.509Z;text:This is a TMF product order illustration",
191            "orderDate": "2023-06-23T09:30:51.000+0000",
192            "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
193            "requestedStartDate": "2019-05-03T00:00:00.000+0000",
194            "state": "Activated",
195            "relatedParty": [
196                {
197                    "@type": "RelatedParty",
198                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000HZDL0IAP",
199                    "id": "CD1234",
200                    "name": "Acme"
201                }
202            ],
203            "productOrderItem": [
204                {
205                    "@type": "ProductOrderItem",
206                    "action": "Add",
207                    "id": "f07b8f51-1ff4-0b25-e607-f5ec54ab637d",
208                    "quantity": 1.00
209                }
210            ]
211        },
212        {
213            "channel": "Online chanel",
214            "description": "Product Order illustration sample",
215            "externalId": "PO-456",
216            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lLTPIA2",
217            "id": "00008403",
218            "note": "id:1;date:2019-04-30T08:13:59.509Z;text:This is a TMF product order illustration",
219            "orderDate": "2023-06-27T10:22:03.000+0000",
220            "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
221            "requestedStartDate": "2019-05-03T00:00:00.000+0000",
222            "state": "Activated",
223            "relatedParty": [
224                {
225                    "@type": "RelatedParty",
226                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000HZDL0IAP",
227                    "id": "CD1234",
228                    "name": "Acme"
229                }
230            ],
231            "productOrderItem": [
232                {
233                    "@type": "ProductOrderItem",
234                    "action": "Add",
235                    "id": "f07b8f51-1ff4-0b25-e607-f5ec54ab637d",
236                    "quantity": 1.00
237                }
238            ]
239        }
240    ]
241}

POST

Consider you want to create a new product order. To create a new product order by sending a POST request to your API (integrated with Salesforce), ensure all required fields and references are correctly handled.

NOTE:

Include relatedParty in the payload as account is mandatory in Salesforce for product order creation.
Configure PriceList in Metadata.
Supported TMForumProductOrderMethods: GET,POST,PATCH.
PriceList must include valid entries for product offers in the sample request.
Submit the cart when submitCart=true or when submitCart is not provided in the payload.
ProductCode as externalId(Replaces GlobalKey__c)
- Do not use GlobalKey__c anymore to identify products.
- You must now use ProductCode as the externalID to identify product offerings.
- Ensure that your client application uses ProductCode in requests.

To create an order with multiple child items in a bundle, or to update an existing draft order, use the PATCH API call.

Important

Limitations

POST method doesn’t validate the cart in advance. The order is submitted after the products are added to the cart.
POST API calls requests have a limit on the number of child items that can be processed.
This limit is dynamic and depends on factors such as:
- The number of attributes per item.
- The complexity of the product hierarchy.
- The total payload size.
Large or complex requests may exceed processing limits, so split the order creation into smaller, manageable API calls.

This flow demonstrates the process of creating and submitting an order with multiple sets of items and attributes.

Initial Order Creation: Use a POST request to create the base order with its initial items. Submit the cart when submitCart=true.
Adding First Set of Child Items: A PATCH (1) request is used to add the first set of child items and their associated attributes.
Adding Second Set of Child Items: A subsequent PATCH (2) request adds the second set of child items and their attributes.
Finalizing and Submitting the Order: The final PATCH request adds any remaining items and submits the order.

These scenarios supported by POST API calls.

Scenario 1: Create an order

Best suited for initial order creation where the payload is small and does not require multiple child items or complex bundle structures.

Sample URL

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

Sample Request

1{
2    "@type": "ProductOrder",
3    "category": "B2C product order",
4    "description": "Product Order illustration sample",
5    "externalId": "PO-461",
6    "note": [
7    {
8        "author": "Jean Pontus",
9        "date": "2019-04-30T08:13:59.509Z",
10        "id": "1",
11        "text": "This is a TMF product order illustration"
12    }
13    ],
14    "priority": "1",
15    "productOrderItem": [
16    {
17        "productOffering": {
18        "id": "Corporate_Mobile_Fleet_Plan_20579"
19        },
20        "productOrderItemRelationship": [
21        {
22            "relationshipType": "bundles",
23            "id": "500"
24        },
25        {
26            "relationshipType": "bundles",
27            "id": "501"
28        }
29        ],
30        "quantity": 5,
31        "id": "100",
32        "action": "Add",
33        "@type": "ProductOrderItem"
34    },
35    {
36        "productOffering": {
37        "id": "SIM_Management_Portal_20579"
38        },
39        "quantity": 3,
40        "id": "500",
41        "action": "modify",
42        "@type": "ProductOrderItem"
43    },
44    {
45        "productOffering": {
46        "id": "Premium_Device_Upgrade_20579"
47        },
48        "quantity": 5,
49        "id": "501",
50        "action": "Add",
51        "@type": "ProductOrderItem"
52    },
53    {
54        "productOffering": {
55        "id": "Mobile_Device_Management_MDM_20579"
56        },
57        "quantity": 5,
58        "id": "600",
59        "action": "Add",
60        "@type": "ProductOrderItem"
61    },
62    {
63        "productOffering": {
64        "id": "Additional_WiFi_Extender_20579"
65        },
66        "quantity": 1,
67        "id": "800",
68        "action": "Add",
69        "@type": "ProductOrderItem",
70
71        "product": {
72        "productCharacteristic": [
73            {
74            "name": "TMF_Speed_ATTR_27762",
75            "value": 8
76            },
77            {
78            "name": "PHONECOLOR",
79            "value": "RED"
80            }
81        ]
82        }
83    }
84    ],
85    "relatedParty": [
86    {
87        "@referredType": "account",
88        "@type": "RelatedParty",
89        "id": "ACCT-NC050",
90        "name": "NovaCore Dynamics"
91    }
92    ],
93    "requestedCompletionDate": "2025-05-17T08:13:59.506Z",
94    "requestedStartDate": "2025-05-17T08:13:59.506Z"
95}

Sample Response

1{
2   "note": [
3       {
4           "text": "This is a TMF product order illustration",
5           "id": "1",
6           "date": "2019-04-30T08:13:59.509Z",
7           "author": "Jean Pontus"
8       }
9   ],
10   "productOrderItem": [
11       {
12           "productOffering": {
13               "id": "Corporate_Mobile_Fleet_Plan_20579"
14           },
15           "productOrderItemRelationship": [
16               {
17                   "relationshipType": "bundles",
18                   "id": "801"
19               },
20               {
21                   "relationshipType": "bundles",
22                   "id": "500"
23               },
24               {
25                   "relationshipType": "bundles",
26                   "id": "802"
27               },
28               {
29                   "relationshipType": "bundles",
30                   "id": "501"
31               }
32           ],
33           "quantity": 5.00,
34           "orderLineItemId": "802LT000014cDHZYA2",
35           "id": "100",
36           "action": "Add",
37           "@type": "ProductOrderItem"
38       },
39       {
40           "productOffering": {
41               "id": "Corporate_Mobile_Line_20579"
42           },
43           "quantity": 1.00,
44           "orderLineItemId": "802LT000014cDHaYAM",
45           "id": "801",
46           "action": "Add",
47           "@type": "ProductOrderItem"
48       },
49       {
50           "productOffering": {
51               "id": "Mobile_Device_Management_MDM_20579"
52           },
53           "quantity": 5.00,
54           "orderLineItemId": "802LT000014cDHbYAM",
55           "id": "600",
56           "action": "Add",
57           "@type": "ProductOrderItem"
58       },
59       {
60           "product": {
61               "productCharacteristic": [
62                   {
63                       "value": 8,
64                       "name": "TMF_Speed_ATTR_27762"
65                   },
66                   {
67                       "value": "RED",
68                       "name": "PHONECOLOR"
69                   }
70               ]
71           },
72           "productOffering": {
73               "id": "Additional_WiFi_Extender_20579"
74           },
75           "quantity": 1.00,
76           "orderLineItemId": "802LT000014cDHcYAM",
77           "id": "800",
78           "action": "Add",
79           "@type": "ProductOrderItem"
80       },
81       {
82           "productOffering": {
83               "id": "SIM_Management_Portal_20579"
84           },
85           "quantity": 3.00,
86           "orderLineItemId": "802LT000014cDHdYAM",
87           "id": "500",
88           "action": "Add",
89           "@type": "ProductOrderItem"
90       },
91       {
92           "productOffering": {
93               "id": "International_Calling_Package_20579"
94           },
95           "quantity": 1.00,
96           "orderLineItemId": "802LT000014cDHeYAM",
97           "id": "802",
98           "action": "Add",
99           "@type": "ProductOrderItem"
100       },
101       {
102           "productOffering": {
103               "id": "Premium_Device_Upgrade_20579"
104           },
105           "quantity": 5.00,
106           "orderLineItemId": "802LT000014cDHfYAM",
107           "id": "501",
108           "action": "Add",
109           "@type": "ProductOrderItem"
110       }
111   ],
112   "relatedParty": [
113       {
114           "name": "NovaCore Dynamics",
115           "id": "ACCT-NC050",
116           "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000ldjtRYAQ",
117           "@type": "RelatedParty",
118           "role": "Consumer"
119       }
120   ],
121   "state": "Activated",
122   "requestedStartDate": "2025-05-17T00:00:00.000+0000",
123   "requestedCompletionDate": "2025-05-17T00:00:00.000+0000",
124   "orderDate": "2025-08-13T10:39:25.000+0000",
125   "id": "00000469",
126   "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000n6uCzYAI",
127   "externalId": "PO-461",
128   "description": "Product Order illustration sample"
129}

Scenario 2: Create cart processing based on submitCart parameter

If submitCart is included in the payload, the cart is submitted only when submitCart=true. Do not submit if submitCart=false.

Sample URL

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

Sample Request

1{
2    "submitCart": false,
3    "@type": "ProductOrder",
4    "category": "B2C product order",
5    "description": "Product Order illustration sample",
6    "externalId": "PO-461",
7    "note": [
8    {
9        "author": "Jean Pontus",
10        "date": "2019-04-30T08:13:59.509Z",
11        "id": "1",
12        "text": "This is a TMF product order illustration"
13    }
14    ],
15    "priority": "1",
16    "productOrderItem": [
17    {
18        "productOffering": {
19        "id": "Corporate_Mobile_Fleet_Plan_20579"
20        },
21        "productOrderItemRelationship": [
22        {
23            "relationshipType": "bundles",
24            "id": "500"
25        },
26        {
27            "relationshipType": "bundles",
28            "id": "501"
29        }
30        ],
31        "quantity": 5,
32        "id": "100",
33        "action": "Add",
34        "@type": "ProductOrderItem"
35    },
36    {
37        "productOffering": {
38        "id": "SIM_Management_Portal_20579"
39        },
40        "quantity": 3,
41        "id": "500",
42        "action": "modify",
43        "@type": "ProductOrderItem"
44    },
45    {
46        "productOffering": {
47        "id": "Premium_Device_Upgrade_20579"
48        },
49        "quantity": 5,
50        "id": "501",
51        "action": "Add",
52        "@type": "ProductOrderItem"
53    },
54    {
55        "productOffering": {
56        "id": "Mobile_Device_Management_MDM_20579"
57        },
58        "quantity": 5,
59        "id": "600",
60        "action": "Add",
61        "@type": "ProductOrderItem"
62    },
63    {
64        "productOffering": {
65        "id": "Additional_WiFi_Extender_20579"
66        },
67        "quantity": 1,
68        "id": "800",
69        "action": "Add",
70        "@type": "ProductOrderItem",
71
72        "product": {
73        "productCharacteristic": [
74            {
75            "name": "TMF_Speed_ATTR_27762",
76            "value": 8
77            },
78            {
79            "name": "PHONECOLOR",
80            "value": "RED"
81            }
82        ]
83        }
84    }
85    ],
86    "relatedParty": [
87    {
88        "@referredType": "account",
89        "@type": "RelatedParty",
90        "id": "ACCT-NC050",
91        "name": "NovaCore Dynamics"
92    }
93    ],
94    "requestedCompletionDate": "2025-05-17T08:13:59.506Z",
95    "requestedStartDate": "2025-05-17T08:13:59.506Z"
96}

Sample Response

1{
2   "note": [
3       {
4           "text": "This is a TMF product order illustration",
5           "id": "1",
6           "date": "2019-04-30T08:13:59.509Z",
7           "author": "Jean Pontus"
8       }
9   ],
10   "productOrderItem": [
11       {
12           "productOffering": {
13               "id": "Corporate_Mobile_Line_20579"
14           },
15           "quantity": 1.00,
16           "orderLineItemId": "802LT000014cDSrYAM",
17           "id": "801",
18           "action": "Add",
19           "@type": "ProductOrderItem"
20       },
21       {
22           "productOffering": {
23               "id": "SIM_Management_Portal_20579"
24           },
25           "quantity": 3.00,
26           "orderLineItemId": "802LT000014cDSsYAM",
27           "id": "500",
28           "action": "Add",
29           "@type": "ProductOrderItem"
30       },
31       {
32           "productOffering": {
33               "id": "Mobile_Device_Management_MDM_20579"
34           },
35           "quantity": 5.00,
36           "orderLineItemId": "802LT000014cDStYAM",
37           "id": "600",
38           "action": "Add",
39           "@type": "ProductOrderItem"
40       },
41       {
42           "productOffering": {
43               "id": "International_Calling_Package_20579"
44           },
45           "quantity": 1.00,
46           "orderLineItemId": "802LT000014cDSuYAM",
47           "id": "802",
48           "action": "Add",
49           "@type": "ProductOrderItem"
50       },
51       {
52           "product": {
53               "productCharacteristic": [
54                   {
55                       "value": 8,
56                       "name": "TMF_Speed_ATTR_27762"
57                   },
58                   {
59                       "value": "RED",
60                       "name": "PHONECOLOR"
61                   }
62               ]
63           },
64           "productOffering": {
65               "id": "Additional_WiFi_Extender_20579"
66           },
67           "quantity": 1.00,
68           "orderLineItemId": "802LT000014cDSvYAM",
69           "id": "800",
70           "action": "Add",
71           "@type": "ProductOrderItem"
72       },
73       {
74           "productOffering": {
75               "id": "Corporate_Mobile_Fleet_Plan_20579"
76           },
77           "productOrderItemRelationship": [
78               {
79                   "relationshipType": "bundles",
80                   "id": "801"
81               },
82               {
83                   "relationshipType": "bundles",
84                   "id": "500"
85               },
86               {
87                   "relationshipType": "bundles",
88                   "id": "802"
89               },
90               {
91                   "relationshipType": "bundles",
92                   "id": "501"
93               }
94           ],
95           "quantity": 5.00,
96           "orderLineItemId": "802LT000014cDSwYAM",
97           "id": "100",
98           "action": "Add",
99           "@type": "ProductOrderItem"
100       },
101       {
102           "productOffering": {
103               "id": "Premium_Device_Upgrade_20579"
104           },
105           "quantity": 5.00,
106           "orderLineItemId": "802LT000014cDSxYAM",
107           "id": "501",
108           "action": "Add",
109           "@type": "ProductOrderItem"
110       }
111   ],
112   "relatedParty": [
113       {
114           "name": "NovaCore Dynamics",
115           "id": "ACCT-NC050",
116           "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000ldjtRYAQ",
117           "@type": "RelatedParty",
118           "role": "Consumer"
119       }
120   ],
121   "state": "Draft",
122   "requestedStartDate": "2025-05-17T00:00:00.000+0000",
123   "requestedCompletionDate": "2025-05-17T00:00:00.000+0000",
124   "orderDate": "2025-08-13T10:47:07.000+0000",
125   "id": "00000470",
126   "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000n6uT7YAI",
127   "externalId": "PO-461",
128   "description": "Product Order illustration sample"
129}

From Summer’25 these use cases are supported.

Scenario 3: Create asset-to-order

Users can create a new order using the asset ID from the payload, including the asset with updated attributes provided. This enables seamless ordering of updated configurations based on existing assets. The assetToOrder flow supports only the modify action.

For upgrades, pass only the root asset ID in the POST request. In an upgrade scenario, you cannot add a new product in the same POST payload. Use the PATCH API on the same order to add a new product.
Use the PATCH API to update the created order with “submitCart”: false and “actions”: “modify”. Refer to the PATCH API for details.

Note

Sample URL

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

Sample Request

1{
2  "submitCart": false,
3  "@type": "ProductOrder",
4  "category": "B2C product order",
5  "channel": [
6    {
7      "id": "1",
8      "name": "Online chanel",
9      "role": "Used channel for order capture"
10    }
11  ],
12  "description": "Product Order illustration sample",
13  "externalId": "OrderRootBundleHasOptionalProducts",
14  "note": [
15    {
16      "author": "Jean Pontus",
17      "date": "2019-04-30T08:13:59.509Z",
18      "id": "1",
19      "text": "This is a TMF product order illustration"
20    }
21  ],
22  "priority": "1",
23  "productOrderItem": [
24    {
25      "@type": "ProductOrderItem",
26      "action": "modify",
27      "id": "101",
28      "quantity": 1,
29      "productOffering": {
30        "id": "Corporate_Mobile_Fleet_Plan_20579"
31      },
32      "product": {
33        "id": "02iLT0000004kx7YAA"
34      }
35    }
36    ],
37  "relatedParty": [
38    {
39      "@referredType": "account",
40      "@type": "RelatedParty",
41      "id": "ACCT-NL032",
42      "name": "NeoLogic Systems"
43    }
44  ],
45  "requestedCompletionDate": "2025-05-02T08:13:59.506Z",
46  "requestedStartDate": "2024-05-03T08:13:59.506Z"
47}

Sample Response

1{
2  "productOrderItem": [
3    {
4      "productOffering": {
5        "id": "Corporate_Mobile_Line_20579"
6      },
7      "quantity": 1,
8      "orderLineItemId": "802LT000014SO7pYAG",
9      "id": "102",
10      "action": "Existing",
11      "@type": "ProductOrderItem"
12    },
13    {
14      "productOffering": {
15        "id": "Corporate_Mobile_Fleet_Plan_20579"
16      },
17      "productOrderItemRelationship": [
18        {
19          "relationshipType": "bundles",
20          "id": "102"
21        },
22        {
23          "relationshipType": "bundles",
24          "id": "103"
25        },
26        {
27          "relationshipType": "bundles",
28          "id": "104"
29        },
30        {
31          "relationshipType": "bundles",
32          "id": "105"
33        },
34        {
35          "relationshipType": "bundles",
36          "id": "106"
37        }
38      ],
39      "quantity": 1,
40      "orderLineItemId": "802LT000014SO7qYAG",
41      "id": "101",
42      "action": "Change",
43      "@type": "ProductOrderItem"
44    },
45    {
46      "productOffering": {
47        "id": "SIM_Management_Portal_20579"
48      },
49      "quantity": 1,
50      "orderLineItemId": "802LT000014SO7rYAG",
51      "id": "103",
52      "action": "Existing",
53      "@type": "ProductOrderItem"
54    },
55    {
56      "productOffering": {
57        "id": "International_Calling_Package_20579"
58      },
59      "quantity": 1,
60      "orderLineItemId": "802LT000014SO7sYAG",
61      "id": "104",
62      "action": "Existing",
63      "@type": "ProductOrderItem"
64    },
65    {
66      "productOffering": {
67        "id": "Premium_Device_Upgrade_20579"
68      },
69      "quantity": 2,
70      "orderLineItemId": "802LT000014SO7tYAG",
71      "id": "106",
72      "action": "Existing",
73      "@type": "ProductOrderItem"
74    },
75    {
76      "productOffering": {
77        "id": "SIM_Management_Portal_20579"
78      },
79      "quantity": 2,
80      "orderLineItemId": "802LT000014SO7uYAG",
81      "id": "105",
82      "action": "Existing",
83      "@type": "ProductOrderItem"
84    }
85  ],
86  "relatedParty": [
87    {
88      "name": "NeoLogic Systems",
89      "id": "ACCT-NL032",
90      "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000lZlPBYA0",
91      "@type": "RelatedParty",
92      "role": "Consumer"
93    }
94  ],
95  "state": "Draft",
96  "requestedStartDate": "2025-07-12T06:37:12.000+0000",
97  "orderDate": "2025-07-12T06:27:08.000+0000",
98  "id": "00000347",
99  "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000lc9DhYAI"
100}

Scenario 4: Create multi-root products with mandatory items

Users can create an order that includes multiple root products that contain mandatory child items. With this you can provide:

Multi-Product Orders with Dependencies: Enables placing orders with several complex products that each require their own mandatory components.
Efficient Bulk Ordering: Useful in B2B or procurement scenarios where multiple products (with required parts) are ordered at once.
Product Family Support: Supports selling sets or families of related products that must include specific parts. For example, printer + required cartridge, camera + required battery.
Improved Order Validation: Prevents incomplete orders by enforcing required child items for each Root Product.
Facilitates Accurate Quoting and Invoicing: Ensures all cost-driving components are part of the order, reducing confusion or disputes.

Consider a root product Mobile Plan with mandatory child item SIM Card and another root product Broadband Internet Gaming Plan with mandatory child items Internet Access and CPE.

Sample URL

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

Sample Request

1{
2   "@type": "ProductOrder",
3   "category": "B2C product order",
4   "channel": [
5       {
6           "id": "1",
7           "name": "Online chanel",
8           "role": "Used channel for order capture"
9       }
10   ],
11   "description": "Product Order illustration sample",
12   "externalId": "PO-456",
13   "note": [
14       {
15           "author": "Jean Pontus",
16           "date": "2019-04-30T08:13:59.509Z",
17           "id": "1",
18           "text": "This is a TMF product order illustration"
19       }
20   ],
21   "priority": "1",
22   "productOrderItem": [
23       {
24           "@type": "ProductOrderItem",
25           "action": "add",
26           "id": "101",
27           "quantity": 1,
28           "productOffering": {
29               "id": "MobilePlan"
30           },
31           "productOrderItemRelationship": [
32               {
33                   "id": "102",
34                   "relationshipType": "bundles"
35               }
36           ]
37       },
38       {
39           "@type": "ProductOrderItem",
40           "action": "add",
41           "id": "102",
42           "quantity": 1,
43           "productOffering": {
44               "id": "IPhone16"
45           },
46           "product": {
47               "productCharacteristic": [
48                   {
49                       "value": "White",
50                       "name": "color"
51                   }
52               ]
53           }
54       },
55       {
56           "@type": "ProductOrderItem",
57           "action": "add",
58           "id": "110",
59           "quantity": 1,
60           "productOffering": {
61               "id": "BroadbandInternetGamingPlan"
62           }
63       }
64   ],
65   "relatedParty": [
66       {
67           "id": "CD123",
68           "name": "TMFAcc"
69       }
70   ],
71   "requestedCompletionDate": "2019-05-02T08:13:59.506Z",
72   "requestedStartDate": "2019-05-03T08:13:59.506Z"
73}

Sample Response

1{
2   "channel": [
3       {
4           "role": "Used channel for order capture",
5           "name": "Online chanel",
6           "id": "1"
7       }
8   ],
9   "note": [
10       {
11           "text": "This is a TMF product order illustration",
12           "id": "1",
13           "date": "2019-04-30T08:13:59.509Z",
14           "author": "Jean Pontus"
15       }
16   ],
17   "productOrderItem": [
18       {
19           "productOffering": {
20               "id": "SIMCard"
21           },
22           "quantity": 1.00,
23           "id": "111",
24           "action": "Add",
25           "@type": "ProductOrderItem"
26       },
27       {
28           "productOffering": {
29               "id": "CPE"
30           },
31           "quantity": 1.00,
32           "id": "113",
33           "action": "Add",
34           "@type": "ProductOrderItem"
35       },
36       {
37           "productOffering": {
38               "id": "BroadbandInternetGamingPlan"
39           },
40           "productOrderItemRelationship": [
41               {
42                   "relationshipType": "bundles",
43                   "id": "112"
44               },
45               {
46                   "relationshipType": "bundles",
47                   "id": "113"
48               }
49           ],
50           "quantity": 1.00,
51           "id": "110",
52           "action": "Add",
53           "@type": "ProductOrderItem"
54       },
55       {
56           "productOffering": {
57               "id": "MobilePlan"
58           },
59           "productOrderItemRelationship": [
60               {
61                   "relationshipType": "bundles",
62                   "id": "111"
63               },
64               {
65                   "relationshipType": "bundles",
66                   "id": "102"
67               }
68           ],
69           "quantity": 1.00,
70           "id": "101",
71           "action": "Add",
72           "@type": "ProductOrderItem"
73       },
74       {
75           "productOffering": {
76               "id": "InternetAccess"
77           },
78           "quantity": 1.00,
79           "id": "112",
80           "action": "Add",
81           "@type": "ProductOrderItem"
82       },
83       {
84           "product": {
85               "productCharacteristic": [
86                   {
87                       "value": "White",
88                       "name": "color"
89                   }
90               ]
91           },
92           "productOffering": {
93               "id": "IPhone16"
94           },
95           "quantity": 1.00,
96           "id": "102",
97           "action": "Add",
98           "@type": "ProductOrderItem"
99       }
100   ],
101   "relatedParty": [
102       {
103           "name": "TMFAcc",
104           "id": "CD123",
105           "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Account/001xx000003Glh1AAC",
106           "@type": "RelatedParty",
107           "role": "Billing"
108       }
109   ],
110   "state": "Activated",
111   "requestedStartDate": "2019-05-03T00:00:00.000+0000",
112   "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
113   "orderDate": "2025-04-02T04:15:18.000+0000",
114   "id": "00000593",
115   "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Order/801xx000003H0sxAAC",
116   "externalId": "PO-456",
117   "description": "Product Order illustration sample"
118}

Scenario 5: Create multiple line items with unique product attributes

Users can create an order containing the same product multiple times as separate order line items, where each line item can have different attribute values. With this you can support:

Product Personalization Per Line Item: Enables customers to customize the same product differently. For example, color, size, and engraving for each instance.
Custom Configurations in a Single Order: Useful when the same product is needed with varying configurations or features. For example, different software modules, finishes, or specifications.
Support for Multi-Unit Custom Orders: Allows ordering several units of the same product for different purposes, departments, or users, each with unique attributes.
Improved Order Accuracy: Reduces confusion by separating variations of the same product into distinct lines rather than combining them with shared attributes.

Consider adding the iPhone 16 product to the order twice, with the these variations:

iPhone 16, Color: White
iPhone 16, Color: Black

Sample URL

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

Sample Request

1{
2   "@type": "ProductOrder",
3   "category": "B2C product order",
4   "channel": [
5       {
6           "id": "1",
7           "name": "Online chanel",
8           "role": "Used channel for order capture"
9       }
10   ],
11   "description": "Product Order illustration sample",
12   "externalId": "PO-456",
13   "note": [
14       {
15           "author": "Jean Pontus",
16           "date": "2019-04-30T08:13:59.509Z",
17           "id": "1",
18           "text": "This is a TMF product order illustration"
19       }
20   ],
21   "priority": "1",
22   "productOrderItem": [
23       {
24           "@type": "ProductOrderItem",
25           "action": "add",
26           "id": "101",
27           "quantity": 1,
28           "productOffering": {
29               "id": "MobilePlan"
30           },
31           "productOrderItemRelationship": [
32               {
33                   "id": "102",
34                   "relationshipType": "bundles"
35               },
36               {
37                   "id": "103",
38                   "relationshipType": "bundles"
39               }
40           ]
41       },
42       {
43           "@type": "ProductOrderItem",
44           "action": "add",
45           "id": "102",
46           "quantity": 2,
47           "productOffering": {
48               "id": "IPhone16"
49           },
50           "product": {
51               "productCharacteristic": [
52                   {
53                       "value": "White",
54                       "name": "color"
55                   }
56               ]
57           }
58       },
59       {
60           "@type": "ProductOrderItem",
61           "action": "add",
62           "id": "103",
63           "quantity": 3,
64           "productOffering": {
65               "id": "IPhone16"
66           },
67           "product": {
68               "productCharacteristic": [
69                   {
70                       "value": "Black",
71                       "name": "color"
72                   }
73               ]
74           }
75       }
76   ],
77   "relatedParty": [
78       {
79           "id": "CD123",
80           "name": "TMFAcc"
81       }
82   ],
83   "requestedCompletionDate": "2019-05-02T08:13:59.506Z",
84   "requestedStartDate": "2019-05-03T08:13:59.506Z"
85}

Sample Response

1{
2   "channel": [
3       {
4           "role": "Used channel for order capture",
5           "name": "Online chanel",
6           "id": "1"
7       }
8   ],
9   "note": [
10       {
11           "text": "This is a TMF product order illustration",
12           "id": "1",
13           "date": "2019-04-30T08:13:59.509Z",
14           "author": "Jean Pontus"
15       }
16   ],
17   "productOrderItem": [
18       {
19           "productOffering": {
20               "id": "SIMCard"
21           },
22           "quantity": 1.00,
23           "id": "104",
24           "action": "Add",
25           "@type": "ProductOrderItem"
26       },
27       {
28           "productOffering": {
29               "id": "MobilePlan"
30           },
31           "productOrderItemRelationship": [
32               {
33                   "relationshipType": "bundles",
34                   "id": "104"
35               },
36               {
37                   "relationshipType": "bundles",
38                   "id": "102"
39               },
40               {
41                   "relationshipType": "bundles",
42                   "id": "103"
43               }
44           ],
45           "quantity": 1.00,
46           "id": "101",
47           "action": "Add",
48           "@type": "ProductOrderItem"
49       },
50       {
51           "product": {
52               "productCharacteristic": [
53                   {
54                       "value": "White",
55                       "name": "color"
56                   }
57               ]
58           },
59           "productOffering": {
60               "id": "IPhone16"
61           },
62           "quantity": 2.00,
63           "id": "102",
64           "action": "Add",
65           "@type": "ProductOrderItem"
66       },
67       {
68           "product": {
69               "productCharacteristic": [
70                   {
71                       "value": "Black",
72                       "name": "color"
73                   }
74               ]
75           },
76           "productOffering": {
77               "id": "IPhone16"
78           },
79           "quantity": 3.00,
80           "id": "103",
81           "action": "Add",
82           "@type": "ProductOrderItem"
83       }
84   ],
85   "relatedParty": [
86       {
87           "name": "TMFAcc",
88           "id": "CD123",
89           "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Account/001xx000003Glh1AAC",
90           "@type": "RelatedParty",
91           "role": "Billing"
92       }
93   ],
94   "state": "Activated",
95   "requestedStartDate": "2019-05-03T00:00:00.000+0000",
96   "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
97   "orderDate": "2025-04-02T04:53:04.000+0000",
98   "id": "00000595",
99   "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Order/801xx000003H0uaAAC",
100   "externalId": "PO-456",
101   "description": "Product Order illustration sample"
102}

PATCH

From Winter’26 release, PATCH API call enhancements allow customers to efficiently add number of child items by breaking the order creation process into smaller, manageable API calls (1 POST API call and multiple PATCH API calls).

Support for Child Items

The PATCH API now enables you to include child items and their attributes within a request payload, leveraging defined relationships.
This supports hierarchical order structures as per TMF specification, facilitating parent-child relationships for bundled products or nested product configurations.
Attributes for both parent and child items can be passed in the same structure, preserving the relationship context.

Limitations

Each PATCH API call is subject to payload size restrictions.
Optimize each request to remain within:
- Maximum allowed payload size
- Processing complexity thresholds
Large attribute sets or deeply nested hierarchies may necessitate splitting into multiple PATCH requests.

These scenarios supported by PATCH API calls.

Scenario 1: Updating top-level order details

You can update these top-level attributes.

channel
description
externalId
note
requestedCompletionDate
requestedStartDate

For sample URL and payload details, refer to Scenario 2.

Note

Scenario 2: Modify product order items

Use the following scenarios to add new products or bundles to an order:

Add a New Product to the Order
- “action”: “Add”
Add a Root Bundle Product to the Order
- Add an Optional Child Product
  - “action”: “Add” (for both root bundle and child)
- Update an Existing Mandatory Child Product
  - “action”: “add” (for root bundle)
  - “action”: “modify” (for mandatory child)

Here’s the payload details for the above mentioned actions.

Sample URL

https://sdb27tmf.test1.my.pc-rnd.salesforce.com/services/apexrest/devops001gs0/tmforum/productopenapi/v1/productorder/00000470

Sample Request

1{
2   "@type": "ProductOrder",
3   "category": "B2C product order",
4   "description": "Updated Product Order illustration sample",
5   "externalId": "PO-462",
6   "note": [
7       {
8           "author": "Jean Pontus",
9           "date": "2022-04-30T08:13:59.509Z",
10           "id": "1",
11           "text": "This is a TMF product order illustration"
12       }
13   ],
14   "priority": "1",
15   "productOrderItem": [
16       {
17           "productOffering": {
18               "id": "Premium_Device_Upgrade_20579"
19           },
20           "quantity": 2,
21           "id": "301",
22           "action": "Add",
23           "@type": "ProductOrderItem"
24       },
25       {
26           "productOffering": {
27               "id": "Ultimate_Connectivity_Bundle_20579"
28           },
29           "quantity": 2,
30           "id": "500",
31           "action": "Add",
32           "@type": "ProductOrderItem",
33           "productOrderItemRelationship": [
34               {
35                   "relationshipType": "bundles",
36                   "id": "501"
37               },
38               {
39                   "relationshipType": "bundles",
40                   "id": "502"
41               }
42           ]
43       },
44       {
45           "productOffering": {
46               "id": "Premium_Support_20579"
47           },
48           "quantity": 2,
49           "id": "501",
50           "action": "Add",
51           "@type": "ProductOrderItem"
52       },
53       {
54           "productOffering": {
55               "id": "4K_TV_Subscription_20579"
56           },
57           "quantity": 2,
58           "id": "502",
59           "action": "modify",
60           "@type": "ProductOrderItem"
61       }
62   ],
63   "relatedParty": [
64       {
65           "@referredType": "account",
66           "@type": "RelatedParty",
67           "id": "ACCT-GC015",
68           "name": "GreenCore Analytics"
69       }
70   ],
71   "requestedCompletionDate": "2025-07-17T08:13:59.506Z",
72   "requestedStartDate": "2025-06-17T08:13:59.506Z"
73}

Sample Response

1{
2   "note": [
3       {
4           "text": "This is a TMF product order illustration",
5           "id": "1",
6           "date": "2022-04-30T08:13:59.509Z",
7           "author": "Jean Pontus"
8       }
9   ],
10   "productOrderItem": [
11       {
12           "productOffering": {
13               "id": "Corporate_Mobile_Line_20579"
14           },
15           "quantity": 1.00,
16           "orderLineItemId": "802LT000014cDSrYAM",
17           "id": "505",
18           "action": "Add",
19           "@type": "ProductOrderItem"
20       },
21       {
22           "productOffering": {
23               "id": "SIM_Management_Portal_20579"
24           },
25           "quantity": 3.00,
26           "orderLineItemId": "802LT000014cDSsYAM",
27           "id": "506",
28           "action": "Add",
29           "@type": "ProductOrderItem"
30       },
31       {
32           "productOffering": {
33               "id": "International_Calling_Package_20579"
34           },
35           "quantity": 1.00,
36           "orderLineItemId": "802LT000014cDSuYAM",
37           "id": "507",
38           "action": "Add",
39           "@type": "ProductOrderItem"
40       },
41       {
42           "product": {
43               "productCharacteristic": [
44                   {
45                       "value": 10,
46                       "name": "TMF_Speed_ATTR_27762"
47                   },
48                   {
49                       "value": "RED",
50                       "name": "PHONECOLOR"
51                   }
52               ]
53           },
54           "productOffering": {
55               "id": "Additional_WiFi_Extender_20579"
56           },
57           "quantity": 2.00,
58           "orderLineItemId": "802LT000014cDSvYAM",
59           "id": "510",
60           "action": "Add",
61           "@type": "ProductOrderItem"
62       },
63       {
64           "productOffering": {
65               "id": "Corporate_Mobile_Fleet_Plan_20579"
66           },
67           "productOrderItemRelationship": [
68               {
69                   "relationshipType": "bundles",
70                   "id": "505"
71               },
72               {
73                   "relationshipType": "bundles",
74                   "id": "506"
75               },
76               {
77                   "relationshipType": "bundles",
78                   "id": "507"
79               },
80               {
81                   "relationshipType": "bundles",
82                   "id": "508"
83               },
84               {
85                   "relationshipType": "bundles",
86                   "id": "509"
87               }
88           ],
89           "quantity": 4.00,
90           "orderLineItemId": "802LT000014cDSwYAM",
91           "id": "504",
92           "action": "Add",
93           "@type": "ProductOrderItem"
94       },
95       {
96           "productOffering": {
97               "id": "Premium_Device_Upgrade_20579"
98           },
99           "quantity": 5.00,
100           "orderLineItemId": "802LT000014cDSxYAM",
101           "id": "508",
102           "action": "Add",
103           "@type": "ProductOrderItem"
104       },
105       {
106           "productOffering": {
107               "id": "Mobile_Device_Management_MDM_20579"
108           },
109           "quantity": 1.00,
110           "orderLineItemId": "802LT000014dUeXYAU",
111           "id": "509",
112           "action": "Add",
113           "@type": "ProductOrderItem"
114       },
115       {
116           "productOffering": {
117               "id": "Ultimate_Connectivity_Bundle_20579"
118           },
119           "productOrderItemRelationship": [
120               {
121                   "relationshipType": "bundles",
122                   "id": "503"
123               },
124               {
125                   "relationshipType": "bundles",
126                   "id": "502"
127               },
128               {
129                   "relationshipType": "bundles",
130                   "id": "501"
131               }
132           ],
133           "quantity": 2.00,
134           "orderLineItemId": "802LT000014dUhlYAE",
135           "id": "500",
136           "action": "Add",
137           "@type": "ProductOrderItem"
138       },
139       {
140           "productOffering": {
141               "id": "4K_TV_Subscription_20579"
142           },
143           "quantity": 2.00,
144           "orderLineItemId": "802LT000014dUhmYAE",
145           "id": "502",
146           "action": "Add",
147           "@type": "ProductOrderItem"
148       },
149       {
150           "productOffering": {
151               "id": "Fiber_Internet_500Mbps_20579"
152           },
153           "quantity": 1.00,
154           "orderLineItemId": "802LT000014dUhnYAE",
155           "id": "503",
156           "action": "Add",
157           "@type": "ProductOrderItem"
158       },
159       {
160           "productOffering": {
161               "id": "Premium_Device_Upgrade_20579"
162           },
163           "quantity": 2.00,
164           "orderLineItemId": "802LT000014dUhoYAE",
165           "id": "301",
166           "action": "Add",
167           "@type": "ProductOrderItem"
168       },
169       {
170           "productOffering": {
171               "id": "Premium_Support_20579"
172           },
173           "quantity": 2.00,
174           "orderLineItemId": "802LT000014dUhpYAE",
175           "id": "501",
176           "action": "Add",
177           "@type": "ProductOrderItem"
178       }
179   ],
180   "relatedParty": [
181       {
182           "name": "NovaCore Dynamics",
183           "id": "ACCT-NC050",
184           "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000ldjtRYAQ",
185           "@type": "RelatedParty",
186           "role": "Consumer"
187       }
188   ],
189   "state": "Draft",
190   "requestedStartDate": "2025-06-17T08:13:59.000+0000",
191   "requestedCompletionDate": "2025-07-17T08:13:59.000+0000",
192   "orderDate": "2025-08-13T10:47:07.000+0000",
193   "id": "00000470",
194   "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000n6uT7YAI",
195   "externalId": "PO-462",
196   "description": "Updated Product Order illustration sample"
197}

Use the following scenarios to modify bundles, update order items, or delete items from the cart:

Modify an Existing Root Bundle Product to Add a Child Product with Attributes
- “action”: “modify”
Update ProductOrderItem Quantities and Attributes
- “action”: “modify”
Delete ProductOrderItems from the Cart
- “action”: “delete”

Here’s the payload details for the above mentioned actions.

Sample URL

https://sdb27tmf.test1.my.pc-rnd.salesforce.com/services/apexrest/devops001gs0/tmforum/productopenapi/v1/productorder/00000470

Sample Request

1{
2 "@type": "ProductOrder",
3 "category": "B2C product order",
4 "description": "Updated Product Order illustration sample",
5 "externalId": "PO-462",
6 "note": [
7   {
8     "author": "Jean Pontus",
9     "date": "2022-04-30T08:13:59.509Z",
10     "id": "1",
11     "text": "This is a TMF product order illustration"
12   }
13 ],
14 "priority": "1",
15 "productOrderItem": [
16   {
17     "productOffering": {
18       "id": "Corporate_Mobile_Fleet_Plan_20579"
19     },
20     "productOrderItemRelationship": [
21       {
22         "relationshipType": "bundles",
23         "id": "101"
24       }
25     ],
26     "quantity": 4,
27     "orderLineItemId": "802LT000014cDSwYAM",
28     "id": "100",
29     "action": "modify",
30     "@type": "ProductOrderItem"
31   },
32   {
33     "productOffering": {
34       "id": "Mobile_Device_Management_MDM_20579"
35     },
36     "quantity": 2,
37     "id": "101",
38     "action": "Add",
39     "@type": "ProductOrderItem"
40   },
41   {
42     "productOffering": {
43       "id": "Additional_WiFi_Extender_20579"
44     },
45     "quantity": 2,
46     "id": "900",
47     "action": "modify",
48     "@type": "ProductOrderItem",
49     "orderLineItemId": "802LT000014cDSvYAM",
50     "product": {
51       "productCharacteristic": [
52         {
53           "name": "TMF_Speed_ATTR_27762",
54           "value": 10
55         },
56         {
57           "name": "PHONECOLOR",
58           "value": "RED"
59         }
60       ]
61     }
62   },
63   {
64     "productOffering": {
65       "id": "Mobile_Device_Management_MDM_20579"
66     },
67     "quantity": 1,
68     "orderLineItemId": "802LT000014cDStYAM",
69     "id": "998",
70     "action": "delete",
71     "@type": "ProductOrderItem"
72   }
73 ],
74 "relatedParty": [
75   {
76     "@referredType": "account",
77     "@type": "RelatedParty",
78     "id": "ACCT-GC015",
79     "name": "GreenCore Analytics"
80   }
81 ],
82 "requestedCompletionDate": "2025-07-17T08:13:59.506Z",
83 "requestedStartDate": "2025-06-17T08:13:59.506Z"
84}

Sample Response

1{
2  "note": [
3    {
4      "text": "This is a TMF product order illustration",
5      "id": "1",
6      "date": "2022-04-30T08:13:59.509Z",
7      "author": "Jean Pontus"
8    }
9  ],
10  "productOrderItem": [
11    {
12      "productOffering": {
13        "id": "Corporate_Mobile_Line_20579"
14      },
15      "quantity": 1,
16      "orderLineItemId": "802LT000014cDSrYAM",
17      "id": "101",
18      "action": "Add",
19      "@type": "ProductOrderItem"
20    },
21    {
22      "productOffering": {
23        "id": "SIM_Management_Portal_20579"
24      },
25      "quantity": 3,
26      "orderLineItemId": "802LT000014cDSsYAM",
27      "id": "102",
28      "action": "Add",
29      "@type": "ProductOrderItem"
30    },
31    {
32      "productOffering": {
33        "id": "International_Calling_Package_20579"
34      },
35      "quantity": 1,
36      "orderLineItemId": "802LT000014cDSuYAM",
37      "id": "103",
38      "action": "Add",
39      "@type": "ProductOrderItem"
40    },
41    {
42      "product": {
43        "productCharacteristic": [
44          {
45            "value": 10,
46            "name": "TMF_Speed_ATTR_27762"
47          },
48          {
49            "value": "RED",
50            "name": "PHONECOLOR"
51          }
52        ]
53      },
54      "productOffering": {
55        "id": "Additional_WiFi_Extender_20579"
56      },
57      "quantity": 2,
58      "orderLineItemId": "802LT000014cDSvYAM",
59      "id": "106",
60      "action": "Add",
61      "@type": "ProductOrderItem"
62    },
63    {
64      "productOffering": {
65        "id": "Corporate_Mobile_Fleet_Plan_20579"
66      },
67      "productOrderItemRelationship": [
68        {
69          "relationshipType": "bundles",
70          "id": "101"
71        },
72        {
73          "relationshipType": "bundles",
74          "id": "102"
75        },
76        {
77          "relationshipType": "bundles",
78          "id": "103"
79        },
80        {
81          "relationshipType": "bundles",
82          "id": "104"
83        },
84        {
85          "relationshipType": "bundles",
86          "id": "105"
87        }
88      ],
89      "quantity": 4,
90      "orderLineItemId": "802LT000014cDSwYAM",
91      "id": "100",
92      "action": "Add",
93      "@type": "ProductOrderItem"
94    },
95    {
96      "productOffering": {
97        "id": "Premium_Device_Upgrade_20579"
98      },
99      "quantity": 5,
100      "orderLineItemId": "802LT000014cDSxYAM",
101      "id": "104",
102      "action": "Add",
103      "@type": "ProductOrderItem"
104    },
105    {
106      "productOffering": {
107        "id": "Mobile_Device_Management_MDM_20579"
108      },
109      "quantity": 1,
110      "orderLineItemId": "802LT000014dUeXYAU",
111      "id": "105",
112      "action": "Add",
113      "@type": "ProductOrderItem"
114    }
115  ],
116  "relatedParty": [
117    {
118      "name": "NovaCore Dynamics",
119      "id": "ACCT-NC050",
120      "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000ldjtRYAQ",
121      "@type": "RelatedParty",
122      "role": "Consumer"
123    }
124  ],
125  "state": "Draft",
126  "requestedStartDate": "2025-06-17T08:13:59.000+0000",
127  "requestedCompletionDate": "2025-07-17T08:13:59.000+0000",
128  "orderDate": "2025-08-13T10:47:07.000+0000",
129  "id": "00000470",
130  "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000n6uT7YAI",
131  "externalId": "PO-462",
132  "description": "Updated Product Order illustration sample"
133}

Scenario 3: Patch-based pricing and validation

You can perform these actions in this scenario.

For pricing, the order line item must already exist in the order, and orderLineItemId is mandatory.
Action is not required for pricing; include itemPrice → priceAlteration with valid pricing details.
For recurring charges, name, recurringChargePeriod, and applicationDuration are required. If a matching time plan exists, it will be used; otherwise, one will be created. For time policy, an existing policy with the given name will be used; if not found, a new one will be created with StartTimePolicy = Activation Start and EndTimePolicy = End of Plan Duration.
Apply pricing on order items one at a time.

Sample URL

https://sdb27tmf.test1.my.pc-rnd.salesforce.com/services/apexrest/devops001gs0/tmforum/productopenapi/v1/productorder/00000470

Sample Request

1{
2   "productOrderItem": [
3       {
4           "@type": "ProductOrderItem",
5           "id": "103",
6           "action": "modify",
7           "orderLineItemId": "802LT000014cDSvYAM",
8           "quantity": 2,
9           "productOffering": {
10               "id": "Additional_WiFi_Extender_20579"
11           },
12           "itemPrice": [
13               {
14                   "priceAlteration": [
15                       {
16                           "priceType": "recurring",
17                           "name": "TP-1Y",
18                           "recurringChargePeriod": "year",
19                           "applicationDuration": 2,
20                           "price": {
21                               "percentage": -30,
22                               "@type": "price"
23                           }
24                       }
25                   ]
26               }
27           ]
28       }
29   ]
30}

Sample Response

1{
2   "note": [
3       {
4           "text": "This is a TMF product order illustration",
5           "id": "1",
6           "date": "2022-04-30T08:13:59.509Z",
7           "author": "Jean Pontus"
8       }
9   ],
10   "productOrderItem": [
11       {
12           "productOffering": {
13               "id": "Corporate_Mobile_Line_20579"
14           },
15           "quantity": 1.00,
16           "orderLineItemId": "802LT000014cDSrYAM",
17           "id": "106",
18           "action": "Add",
19           "@type": "ProductOrderItem"
20       },
21       {
22           "productOffering": {
23               "id": "SIM_Management_Portal_20579"
24           },
25           "quantity": 3.00,
26           "orderLineItemId": "802LT000014cDSsYAM",
27           "id": "107",
28           "action": "Add",
29           "@type": "ProductOrderItem"
30       },
31       {
32           "productOffering": {
33               "id": "International_Calling_Package_20579"
34           },
35           "quantity": 1.00,
36           "orderLineItemId": "802LT000014cDSuYAM",
37           "id": "108",
38           "action": "Add",
39           "@type": "ProductOrderItem"
40       },
41       {
42           "product": {
43               "productCharacteristic": [
44                   {
45                       "value": 10,
46                       "name": "TMF_Speed_ATTR_27762"
47                   },
48                   {
49                       "value": "RED",
50                       "name": "PHONECOLOR"
51                   }
52               ]
53           },
54           "itemPrice": [
55               {
56                   "priceAlteration": [
57                       {
58                           "price": {
59                               "percentage": -30.0,
60                               "@type": "price"
61                           },
62                           "priceType": "recurring"
63                       }
64                   ]
65               }
66           ],
67           "productOffering": {
68               "id": "Additional_WiFi_Extender_20579"
69           },
70           "quantity": 2.00,
71           "orderLineItemId": "802LT000014cDSvYAM",
72           "id": "111",
73           "action": "Add",
74           "@type": "ProductOrderItem"
75       },
76       {
77           "productOffering": {
78               "id": "Corporate_Mobile_Fleet_Plan_20579"
79           },
80           "productOrderItemRelationship": [
81               {
82                   "relationshipType": "bundles",
83                   "id": "106"
84               },
85               {
86                   "relationshipType": "bundles",
87                   "id": "107"
88               },
89               {
90                   "relationshipType": "bundles",
91                   "id": "108"
92               },
93               {
94                   "relationshipType": "bundles",
95                   "id": "109"
96               },
97               {
98                   "relationshipType": "bundles",
99                   "id": "110"
100               }
101           ],
102           "quantity": 4.00,
103           "orderLineItemId": "802LT000014cDSwYAM",
104           "id": "105",
105           "action": "Add",
106           "@type": "ProductOrderItem"
107       },
108       {
109           "productOffering": {
110               "id": "Premium_Device_Upgrade_20579"
111           },
112           "quantity": 5.00,
113           "orderLineItemId": "802LT000014cDSxYAM",
114           "id": "109",
115           "action": "Add",
116           "@type": "ProductOrderItem"
117       },
118       {
119           "productOffering": {
120               "id": "Mobile_Device_Management_MDM_20579"
121           },
122           "quantity": 1.00,
123           "orderLineItemId": "802LT000014dUeXYAU",
124           "id": "110",
125           "action": "Add",
126           "@type": "ProductOrderItem"
127       },
128       {
129           "productOffering": {
130               "id": "Ultimate_Connectivity_Bundle_20579"
131           },
132           "productOrderItemRelationship": [
133               {
134                   "relationshipType": "bundles",
135                   "id": "102"
136               },
137               {
138                   "relationshipType": "bundles",
139                   "id": "103"
140               },
141               {
142                   "relationshipType": "bundles",
143                   "id": "104"
144               }
145           ],
146           "quantity": 2.00,
147           "orderLineItemId": "802LT000014dUhlYAE",
148           "id": "101",
149           "action": "Add",
150           "@type": "ProductOrderItem"
151       },
152       {
153           "productOffering": {
154               "id": "4K_TV_Subscription_20579"
155           },
156           "quantity": 2.00,
157           "orderLineItemId": "802LT000014dUhmYAE",
158           "id": "103",
159           "action": "Add",
160           "@type": "ProductOrderItem"
161       },
162       {
163           "productOffering": {
164               "id": "Fiber_Internet_500Mbps_20579"
165           },
166           "quantity": 1.00,
167           "orderLineItemId": "802LT000014dUhnYAE",
168           "id": "102",
169           "action": "Add",
170           "@type": "ProductOrderItem"
171       },
172       {
173           "productOffering": {
174               "id": "Premium_Device_Upgrade_20579"
175           },
176           "quantity": 2.00,
177           "orderLineItemId": "802LT000014dUhoYAE",
178           "id": "100",
179           "action": "Add",
180           "@type": "ProductOrderItem"
181       },
182       {
183           "productOffering": {
184               "id": "Premium_Support_20579"
185           },
186           "quantity": 2.00,
187           "orderLineItemId": "802LT000014dUhpYAE",
188           "id": "104",
189           "action": "Add",
190           "@type": "ProductOrderItem"
191       }
192   ],
193   "relatedParty": [
194       {
195           "name": "NovaCore Dynamics",
196           "id": "ACCT-NC050",
197           "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000ldjtRYAQ",
198           "@type": "RelatedParty",
199           "role": "Consumer"
200       }
201   ],
202   "state": "Draft",
203   "requestedStartDate": "2025-06-17T08:13:59.000+0000",
204   "requestedCompletionDate": "2025-07-17T08:13:59.000+0000",
205   "orderDate": "2025-08-13T10:47:07.000+0000",
206   "id": "00000470",
207   "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000n6uT7YAI",
208   "externalId": "PO-462",
209   "description": "Updated Product Order illustration sample"
210}

Scenario 4: Submit order via Patch (State Update)

Use the PATCH API call to submit an order by updating its state. A successful submission triggers asset creation and the fulfillment process for the associated account.

Sample URL

https://sdb27tmf.test1.my.pc-rnd.salesforce.com/services/apexrest/devops001gs0/tmforum/productopenapi/v1/productorder/00000470

Sample Request

1{
2 "state": "Activated"
3}

Sample Response

1{
2  "note": [
3    {
4      "text": "This is a TMF product order illustration",
5      "id": "1",
6      "date": "2022-04-30T08:13:59.509Z",
7      "author": "Jean Pontus"
8    }
9  ],
10  "productOrderItem": [
11    {
12      "productOffering": {
13        "id": "Corporate_Mobile_Line_20579"
14      },
15      "quantity": 1,
16      "orderLineItemId": "802LT000014cDSrYAM",
17      "id": "106",
18      "action": "Add",
19      "@type": "ProductOrderItem"
20    },
21    {
22      "productOffering": {
23        "id": "SIM_Management_Portal_20579"
24      },
25      "quantity": 3,
26      "orderLineItemId": "802LT000014cDSsYAM",
27      "id": "107",
28      "action": "Add",
29      "@type": "ProductOrderItem"
30    },
31    {
32      "productOffering": {
33        "id": "International_Calling_Package_20579"
34      },
35      "quantity": 1,
36      "orderLineItemId": "802LT000014cDSuYAM",
37      "id": "108",
38      "action": "Add",
39      "@type": "ProductOrderItem"
40    },
41    {
42      "product": {
43        "productCharacteristic": [
44          {
45            "value": 10,
46            "name": "TMF_Speed_ATTR_27762"
47          },
48          {
49            "value": "RED",
50            "name": "PHONECOLOR"
51          }
52        ]
53      },
54      "itemPrice": [
55        {
56          "priceAlteration": [
57            {
58              "price": {
59                "percentage": -30,
60                "@type": "price"
61              },
62              "priceType": "recurring"
63            }
64          ]
65        }
66      ],
67      "productOffering": {
68        "id": "Additional_WiFi_Extender_20579"
69      },
70      "quantity": 2,
71      "orderLineItemId": "802LT000014cDSvYAM",
72      "id": "111",
73      "action": "Add",
74      "@type": "ProductOrderItem"
75    },
76    {
77      "productOffering": {
78        "id": "Corporate_Mobile_Fleet_Plan_20579"
79      },
80      "productOrderItemRelationship": [
81        {
82          "relationshipType": "bundles",
83          "id": "106"
84        },
85        {
86          "relationshipType": "bundles",
87          "id": "107"
88        },
89        {
90          "relationshipType": "bundles",
91          "id": "108"
92        },
93        {
94          "relationshipType": "bundles",
95          "id": "109"
96        },
97        {
98          "relationshipType": "bundles",
99          "id": "110"
100        }
101      ],
102      "quantity": 4,
103      "orderLineItemId": "802LT000014cDSwYAM",
104      "id": "105",
105      "action": "Add",
106      "@type": "ProductOrderItem"
107    },
108    {
109      "productOffering": {
110        "id": "Premium_Device_Upgrade_20579"
111      },
112      "quantity": 5,
113      "orderLineItemId": "802LT000014cDSxYAM",
114      "id": "109",
115      "action": "Add",
116      "@type": "ProductOrderItem"
117    },
118    {
119      "productOffering": {
120        "id": "Mobile_Device_Management_MDM_20579"
121      },
122      "quantity": 1,
123      "orderLineItemId": "802LT000014dUeXYAU",
124      "id": "110",
125      "action": "Add",
126      "@type": "ProductOrderItem"
127    },
128    {
129      "productOffering": {
130        "id": "Ultimate_Connectivity_Bundle_20579"
131      },
132      "productOrderItemRelationship": [
133        {
134          "relationshipType": "bundles",
135          "id": "102"
136        },
137        {
138          "relationshipType": "bundles",
139          "id": "103"
140        },
141        {
142          "relationshipType": "bundles",
143          "id": "104"
144        }
145      ],
146      "quantity": 2,
147      "orderLineItemId": "802LT000014dUhlYAE",
148      "id": "101",
149      "action": "Add",
150      "@type": "ProductOrderItem"
151    },
152    {
153      "productOffering": {
154        "id": "4K_TV_Subscription_20579"
155      },
156      "quantity": 2,
157      "orderLineItemId": "802LT000014dUhmYAE",
158      "id": "103",
159      "action": "Add",
160      "@type": "ProductOrderItem"
161    },
162    {
163      "productOffering": {
164        "id": "Fiber_Internet_500Mbps_20579"
165      },
166      "quantity": 1,
167      "orderLineItemId": "802LT000014dUhnYAE",
168      "id": "102",
169      "action": "Add",
170      "@type": "ProductOrderItem"
171    },
172    {
173      "productOffering": {
174        "id": "Premium_Device_Upgrade_20579"
175      },
176      "quantity": 2,
177      "orderLineItemId": "802LT000014dUhoYAE",
178      "id": "100",
179      "action": "Add",
180      "@type": "ProductOrderItem"
181    },
182    {
183      "productOffering": {
184        "id": "Premium_Support_20579"
185      },
186      "quantity": 2,
187      "orderLineItemId": "802LT000014dUhpYAE",
188      "id": "104",
189      "action": "Add",
190      "@type": "ProductOrderItem"
191    }
192  ],
193  "relatedParty": [
194    {
195      "name": "NovaCore Dynamics",
196      "id": "ACCT-NC050",
197      "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000ldjtRYAQ",
198      "@type": "RelatedParty",
199      "role": "Consumer"
200    }
201  ],
202  "state": "Activated",
203  "requestedStartDate": "2025-06-17T08:13:59.000+0000",
204  "requestedCompletionDate": "2025-07-17T08:13:59.000+0000",
205  "orderDate": "2025-08-13T10:47:07.000+0000",
206  "id": "00000470",
207  "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000n6uT7YAI",
208  "externalId": "PO-462",
209  "description": "Updated Product Order illustration sample"
210}

Inbound Notification

The Inbound Notification system updates the order status in Salesforce. When the order status changes, a notification event can be pushed to Salesforce through the exposed inbound endpoint. The system accepts the event and returns a 200 response code to the sender.

Notification Event Structure

This is the sample notification event.

1{
2"eventId": "001",
3"eventType": "ProductOrderStateChangeEvent",
4"event": {
5"productOrder": {
6"id": "00000407",
7"state": "Activated"
8}
9}
10}

Inbound Event Notifications Field Mappings

TMForum Field	Field Type	Is Mandatory by TMForum	TMForum Description	Salesforce Mapping
eventId	String	Yes	Event Id	-
eventType	String	Yes	Description of event type	-
productOrder	Object	No	Order details	Order
productOrder.id	String	Yes	Unique identifier of Order	Order.OrderNumber
productOrder	String	Yes	State of the Order	Order.Status

Error Messages

These are some sample 400 bad request responses.

Order is not submitted

1{
2"failureReason": "We couldn't submit the Product Order. Try again.",
3"overallResult": "failure"
4}

Invalid priceType

1{
2"failureReason": "We couldn't adjust the price of the Product Order. Try again.",
3"overallResult": "failure"
4}

Order is active and the user attempts to update it via PATCH

1{
2"failureReason": "Deactivate Status field for patching ProductOrderLineItem",
3"overallResult": "failure"
4}

Quantity is missing or less than 1

1{
2"failureReason": "SIM Card cannot have a quantity less than 1.",
3"overallResult": "failure"
4}