---
schema_version: "1"
id: 01a88f4bbec47749900cf07283a20cece06c29bd833194d221336d6a61716b15
title: Overview
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/industries-integrations/comms/guides/TMF622/TMF622v4-use-cases.md
canonical_url: https://developer.salesforce.com/docs/industries/communications/guide/TMF622v4-use-cases.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 7de73f0e01de9e68879019cbae87011993ec628e72d1128ff47a0dab4b7a8518
products:
  - Communications Cloud TM Forum API
  - Industries Integrations
---
# 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.
<!-- Following block diagram provides a high-level overview of how the various components are involved in handling TMF 622 API operations (GET, POST, PATCH).

![TMF622 Components](https://developer.salesforce.com/media/TMF622.png "TMF622 Components")-->

- 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](#tmf622-v4-use-cases) listed based on the operation you want to perform.

**important:** Starting from the Winter ’27 release, only the Direct Access option will be supported. The MuleSoft gateway option will be deprecated, and customers must update their integrations to use the Connect/Apex REST endpoints for continued access to the inbound APIs.

## Assumptions

It is assumed that you have completed the following.

- [Enabling Access to Industry APIs](https://help.salesforce.com/s/articleView?id=sf.access_industry_api.htm&type=5)
- Ensuring that the required licenses and data packs are installed. For more information, refer [Before you begin](https://developer.salesforce.com/docs/industries/communications/guide/TMF622.html#before-you-begin).

## Sequence of Operations

Following block diagram provides a sequence of operations involved.
![Sequence](https://developer.salesforce.com/media/Sequence_622.png "Sequence of Operations")

**NOTE:**

- For mandatory fields and resource mappings, refer [TMF622 v4 Resource Mappings](https://developer.salesforce.com/docs/industries/communications/guide/tmf622_resource_mapping.html).
- For more information on supported Integration Procedures, Data Raptors, Apex Interfaces, Custom Metadata, refer [Extend TMF622 API](https://developer.salesforce.com/docs/industries/communications/guide/extend_tmf622_apis.html) documentation.
- TMF622 works only if Standard Cart APIs are enabled.

## TMF622 v4 Use Cases

| I want to<br> <div style="width:290px"></div>                                                                                                                                                             | Request Type<br> <div style="width:150px"></div>                          | Example URL<br>                                                                                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Retrieve and display details of a particular product order.<br>                                                                                                                                           | [GET by ID](#get-by-id)                                                   | _{https<nolink>://MyDomainLoginUrl}_/services/apexrest/_{namespace}_/tmforum/productopenapi/v1/productorder/_{ID}_<br><br>**NOTE:** <br>For invalid product order ID, you will receive HTTP 404 error.<br>                                                                                                                 |
| Based on the provided field values, retrieve and display details of a particular product order ID.<br>                                                                                                    | [GET by ID and Fields](#get-by-id-and-fields)<br>                         | _{https<nolink>://MyDomainLoginUrl}_/services/apexrest/_{namespace}_/tmforum/productopenapi/v1/productorder/_{ID}_?fields=description,state,externalId,note,requestedCompletionDate,requestedStartDate,channel,orderDate,id,href<br><br>**NOTE:** <br>The requested fields will be part of output, if they have value.<br> |
| List all the product orders present in the system.<br>                                                                                                                                                    | [GET List](#get-list)<br>                                                 | _{https<nolink>://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.<br> | [GET List by Fields and Filtering](#get-list-by-fields-and-filtering)<br> | _{https<nolink>://MyDomainLoginUrl}_/services/apexrest/_{namespace}_/tmforum/productopenapi/v1/productorder?fields=state=Activated&fields=state,channel<br><br>**NOTE:** <br>The requested fields will be part of output, if they have value.<br>                                                                          |
| 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.<br>                         | [GET List by Limit and Offset](#get-list-by-limit-and-offset)<br>         | _{https<nolink>://MyDomainLoginUrl}_/services/apexrest/_{namespace}_/tmforum/productopenapi/v1/productorder?limit=10&offset=3<br>                                                                                                                                                                                          |
| Create a new product order by providing the required details.<br>                                                                                                                                         | [POST](#post)<br>                                                         | _{https<nolink>://MyDomainLoginUrl}_/services/apexrest/_{namespace}_/tmforum/productopenapi/v1/productorder                                                                                                                                                                                                                |
| Update A product order by providing the required details.<br>                                                                                                                                             | [PATCH](#patch)<br>                                                       | _{https<nolink>://MyDomainLoginUrl}_/services/apexrest/_{namespace}_/tmforum/productopenapi/v1/productorder/_{ID}_<br>                                                                                                                                                                                                     |

## 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](https://developer.salesforce.com/docs/industries/communications/references/tmf622?meta=Get%2BProduct%2BOrder)

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

```
{
    "channel": [
        {
            "role": "Used channel for order capture",
            "name": "Online chanel",
            "id": "1"
        }
    ],
    "note": [
        {
            "text": "This is a TMF product order illustration",
            "id": "1",
            "date": "2019-04-30T08:13:59.509Z",
            "author": "Jean Pontus"
        }
    ],
    "productOrderItem": [
        {
            "productOffering": {
                "id": "SIMCard"
            },
            "orderLineItemId": "802xx000001nfhfAAA",
            "quantity": 4.00,
            "id": "101",
            "action": "Add",
            "@type": "ProductOrderItem"
        },
        {
            "productOffering": {
                "id": "iphone15"
            },
            "productOrderItemRelationship": [
                {
                    "relationshipType": "bundles",
                    "id": "101"
                }
            ],
            "orderLineItemId": "802xx000001nfhgAAA",
            "quantity": 1.00,
            "id": "100",
            "action": "Add",
            "@type": "ProductOrderItem"
        }
    ],
    "relatedParty": [
        {
            "name": "TMF622",
            "id": "123",
            "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Account/001xx000003GfJrAAK",
            "@type": "RelatedParty",
            "role": "Billing"
        }
    ],
    "state": "Draft",
    "requestedStartDate": "2019-05-03T00:00:00.000+0000",
    "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
    "orderDate": "2025-05-19T08:48:59.000+0000",
    "id": "00000262",
    "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Order/801xx000003GhtXAAS",
    "externalId": "PO-456",
    "description": "Product Order illustration sample-updated"
}
```

## 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

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

```

## 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](https://developer.salesforce.com/docs/industries/communications/references/tmf622?meta=List%2BProduct%2BOrders)

## 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

```

200
{
    "PageInfo": "Page 1",
    "PageSize": 50,
    "result": [
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJTVIA2",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJcDIAU",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJkNIAU",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJkcIAE",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJkmIAE",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJkrIAE",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJkwIAE",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJl1IAE",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlBIAU",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlGIAU",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlQIAU",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlaIAE",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlfIAE",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlkIAE",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlpIAE",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJluIAE",
            "state": "Activated"
        },
        {
            "channel": "Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lL5cIAE",
            "state": "Activated"
        },
        {
            "channel": "Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lL6GIAU",
            "state": "Activated"
        },
        {
            "channel": "Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lLTPIA2",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lLTyIAM",
            "state": "Activated"
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lLU8IAM",
            "state": "Activated"
        },
        {
            "channel": "Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMHOIA2",
            "state": "Activated"
        },
        {
            "channel": "Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMHTIA2",
            "state": "Activated"
        },
        {
            "channel": "Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMIHIA2",
            "state": "Activated"
        },
        {
            "channel": "Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMIMIA2",
            "state": "Activated"
        },
        {
            "channel": "Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMg0IAE",
            "state": "Activated"
        },
        {
            "channel": "name: Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMg5IAE",
            "state": "Activated"
        },
        {
            "channel": "name: Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lMgUIAU",
            "state": "Activated"
        },
        {
            "channel": "name: Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lOFDIA2",
            "state": "Activated"
        },
        {
            "channel": "name: Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lOGaIAM",
            "state": "Activated"
        },
        {
            "channel": "name: Online chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lOHsIAM",
            "state": "Activated"
        },
        {
            "channel": "name: Offline chanel",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lOIlIAM",
            "state": "Activated"
        }
    ]
}

```

## 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

```

200 OK
{
    "PageInfo": "Page 3",
    "PageSize": 10,
    "result": [
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlVIAU",
            "id": "00006988",
            "orderDate": "2023-06-14T06:18:55.000+0000",
            "state": "Draft",
            "relatedParty": [
                {
                    "@type": "RelatedParty",
                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000FDDn6IAH",
                    "id": "CD656092",
                    "name": "Burlington Textiles Corp of America"
                }
            ]
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlaIAE",
            "id": "00006989",
            "orderDate": "2023-06-14T06:19:37.000+0000",
            "state": "Activated",
            "relatedParty": [
                {
                    "@type": "RelatedParty",
                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000FDDn6IAH",
                    "id": "CD656092",
                    "name": "Burlington Textiles Corp of America"
                }
            ],
            "productOrderItem": [
                {
                    "@type": "ProductOrderItem",
                    "action": "Add",
                    "id": "0ff363a6-f064-3135-0e25-0ca26d002941",
                    "quantity": 1.00
                }
            ]
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlfIAE",
            "id": "00006990",
            "orderDate": "2023-06-14T06:23:29.000+0000",
            "state": "Activated",
            "relatedParty": [
                {
                    "@type": "RelatedParty",
                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000FDDn6IAH",
                    "id": "CD656092",
                    "name": "Burlington Textiles Corp of America"
                }
            ],
            "productOrderItem": [
                {
                    "@type": "ProductOrderItem",
                    "action": "Add",
                    "id": "6af7348d-a1c4-fce6-88b2-dc4418a2b059",
                    "quantity": 1.00
                }
            ]
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlkIAE",
            "id": "00006991",
            "orderDate": "2023-06-14T06:25:11.000+0000",
            "state": "Activated",
            "relatedParty": [
                {
                    "@type": "RelatedParty",
                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000FDDn6IAH",
                    "id": "CD656092",
                    "name": "Burlington Textiles Corp of America"
                }
            ],
            "productOrderItem": [
                {
                    "@type": "ProductOrderItem",
                    "action": "Add",
                    "id": "ab8b12a3-a78a-02df-be28-608491311b21",
                    "quantity": 1.00
                }
            ]
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJlpIAE",
            "id": "00006992",
            "orderDate": "2023-06-14T06:27:24.000+0000",
            "state": "Activated",
            "relatedParty": [
                {
                    "@type": "RelatedParty",
                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000FDDn6IAH",
                    "id": "CD656092",
                    "name": "Burlington Textiles Corp of America"
                }
            ],
            "productOrderItem": [
                {
                    "@type": "ProductOrderItem",
                    "action": "Add",
                    "id": "f07b8f51-1ff4-0b25-e607-f5ec54ab637d",
                    "quantity": 1.00
                }
            ]
        },
        {
            "channel": "Call Center",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lJluIAE",
            "id": "00006993",
            "orderDate": "2023-06-14T06:28:50.000+0000",
            "state": "Activated",
            "relatedParty": [
                {
                    "@type": "RelatedParty",
                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000FDDn6IAH",
                    "id": "CD656092",
                    "name": "Burlington Textiles Corp of America"
                }
            ],
            "productOrderItem": [
                {
                    "@type": "ProductOrderItem",
                    "action": "Add",
                    "id": "f07b8f51-1ff4-0b25-e607-f5ec54ab637d",
                    "quantity": 1.00
                }
            ]
        },
        {
            "channel": "Online chanel",
            "description": "Product Order illustration sample",
            "externalId": "PO-456",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lL5XIAU",
            "id": "00008020",
            "note": "id:1;date:2019-04-30T08:13:59.509Z;text:This is a TMF product order illustration",
            "orderDate": "2023-06-23T08:58:34.000+0000",
            "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
            "requestedStartDate": "2019-05-03T00:00:00.000+0000",
            "state": "Draft",
            "relatedParty": [
                {
                    "@type": "RelatedParty",
                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000HZDL0IAP",
                    "id": "CD1234",
                    "name": "Acme"
                }
            ]
        },
        {
            "channel": "Online chanel",
            "description": "Product Order illustration sample",
            "externalId": "PO-456",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lL5cIAE",
            "id": "00008021",
            "note": "id:1;date:2019-04-30T08:13:59.509Z;text:This is a TMF product order illustration",
            "orderDate": "2023-06-23T09:01:57.000+0000",
            "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
            "requestedStartDate": "2019-05-03T00:00:00.000+0000",
            "state": "Activated",
            "relatedParty": [
                {
                    "@type": "RelatedParty",
                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000HZDL0IAP",
                    "id": "CD1234",
                    "name": "Acme"
                }
            ],
            "productOrderItem": [
                {
                    "@type": "ProductOrderItem",
                    "action": "Add",
                    "id": "f07b8f51-1ff4-0b25-e607-f5ec54ab637d",
                    "quantity": 1.00
                }
            ]
        },
        {
            "channel": "Online chanel",
            "description": "Product Order illustration sample new",
            "externalId": "PO-456",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lL6GIAU",
            "id": "00008022",
            "note": "id:1;date:2019-04-30T08:13:59.509Z;text:This is a TMF product order illustration",
            "orderDate": "2023-06-23T09:30:51.000+0000",
            "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
            "requestedStartDate": "2019-05-03T00:00:00.000+0000",
            "state": "Activated",
            "relatedParty": [
                {
                    "@type": "RelatedParty",
                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000HZDL0IAP",
                    "id": "CD1234",
                    "name": "Acme"
                }
            ],
            "productOrderItem": [
                {
                    "@type": "ProductOrderItem",
                    "action": "Add",
                    "id": "f07b8f51-1ff4-0b25-e607-f5ec54ab637d",
                    "quantity": 1.00
                }
            ]
        },
        {
            "channel": "Online chanel",
            "description": "Product Order illustration sample",
            "externalId": "PO-456",
            "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Order/801Do000001lLTPIA2",
            "id": "00008403",
            "note": "id:1;date:2019-04-30T08:13:59.509Z;text:This is a TMF product order illustration",
            "orderDate": "2023-06-27T10:22:03.000+0000",
            "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
            "requestedStartDate": "2019-05-03T00:00:00.000+0000",
            "state": "Activated",
            "relatedParty": [
                {
                    "@type": "RelatedParty",
                    "href": "/services/apexrest/vlocity_tmf/tmforum/productopenapi/v1/Account/001Do00000HZDL0IAP",
                    "id": "CD1234",
                    "name": "Acme"
                }
            ],
            "productOrderItem": [
                {
                    "@type": "ProductOrderItem",
                    "action": "Add",
                    "id": "f07b8f51-1ff4-0b25-e607-f5ec54ab637d",
                    "quantity": 1.00
                }
            ]
        }
    ]
}

```

## 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. <br>

**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.

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

## 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.

1. Initial Order Creation: Use a POST request to create the base order with its initial items. Submit the cart when `submitCart=true`.
2. Adding First Set of Child Items: A PATCH (1) request is used to add the first set of child items and their associated attributes.
3. Adding Second Set of Child Items: A subsequent PATCH (2) request adds the second set of child items and their attributes.
4. 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

```
{
    "@type": "ProductOrder",
    "category": "B2C product order",
    "description": "Product Order illustration sample",
    "externalId": "PO-461",
    "note": [
    {
        "author": "Jean Pontus",
        "date": "2019-04-30T08:13:59.509Z",
        "id": "1",
        "text": "This is a TMF product order illustration"
    }
    ],
    "priority": "1",
    "productOrderItem": [
    {
        "productOffering": {
        "id": "Corporate_Mobile_Fleet_Plan_20579"
        },
        "productOrderItemRelationship": [
        {
            "relationshipType": "bundles",
            "id": "500"
        },
        {
            "relationshipType": "bundles",
            "id": "501"
        }
        ],
        "quantity": 5,
        "id": "100",
        "action": "Add",
        "@type": "ProductOrderItem"
    },
    {
        "productOffering": {
        "id": "SIM_Management_Portal_20579"
        },
        "quantity": 3,
        "id": "500",
        "action": "modify",
        "@type": "ProductOrderItem"
    },
    {
        "productOffering": {
        "id": "Premium_Device_Upgrade_20579"
        },
        "quantity": 5,
        "id": "501",
        "action": "Add",
        "@type": "ProductOrderItem"
    },
    {
        "productOffering": {
        "id": "Mobile_Device_Management_MDM_20579"
        },
        "quantity": 5,
        "id": "600",
        "action": "Add",
        "@type": "ProductOrderItem"
    },
    {
        "productOffering": {
        "id": "Additional_WiFi_Extender_20579"
        },
        "quantity": 1,
        "id": "800",
        "action": "Add",
        "@type": "ProductOrderItem",

        "product": {
        "productCharacteristic": [
            {
            "name": "TMF_Speed_ATTR_27762",
            "value": 8
            },
            {
            "name": "PHONECOLOR",
            "value": "RED"
            }
        ]
        }
    }
    ],
    "relatedParty": [
    {
        "@referredType": "account",
        "@type": "RelatedParty",
        "id": "ACCT-NC050",
        "name": "NovaCore Dynamics"
    }
    ],
    "requestedCompletionDate": "2025-05-17T08:13:59.506Z",
    "requestedStartDate": "2025-05-17T08:13:59.506Z"
}
```

#### Sample Response

```
{
   "note": [
       {
           "text": "This is a TMF product order illustration",
           "id": "1",
           "date": "2019-04-30T08:13:59.509Z",
           "author": "Jean Pontus"
       }
   ],
   "productOrderItem": [
       {
           "productOffering": {
               "id": "Corporate_Mobile_Fleet_Plan_20579"
           },
           "productOrderItemRelationship": [
               {
                   "relationshipType": "bundles",
                   "id": "801"
               },
               {
                   "relationshipType": "bundles",
                   "id": "500"
               },
               {
                   "relationshipType": "bundles",
                   "id": "802"
               },
               {
                   "relationshipType": "bundles",
                   "id": "501"
               }
           ],
           "quantity": 5.00,
           "orderLineItemId": "802LT000014cDHZYA2",
           "id": "100",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Corporate_Mobile_Line_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014cDHaYAM",
           "id": "801",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Mobile_Device_Management_MDM_20579"
           },
           "quantity": 5.00,
           "orderLineItemId": "802LT000014cDHbYAM",
           "id": "600",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "product": {
               "productCharacteristic": [
                   {
                       "value": 8,
                       "name": "TMF_Speed_ATTR_27762"
                   },
                   {
                       "value": "RED",
                       "name": "PHONECOLOR"
                   }
               ]
           },
           "productOffering": {
               "id": "Additional_WiFi_Extender_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014cDHcYAM",
           "id": "800",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "SIM_Management_Portal_20579"
           },
           "quantity": 3.00,
           "orderLineItemId": "802LT000014cDHdYAM",
           "id": "500",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "International_Calling_Package_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014cDHeYAM",
           "id": "802",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Premium_Device_Upgrade_20579"
           },
           "quantity": 5.00,
           "orderLineItemId": "802LT000014cDHfYAM",
           "id": "501",
           "action": "Add",
           "@type": "ProductOrderItem"
       }
   ],
   "relatedParty": [
       {
           "name": "NovaCore Dynamics",
           "id": "ACCT-NC050",
           "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000ldjtRYAQ",
           "@type": "RelatedParty",
           "role": "Consumer"
       }
   ],
   "state": "Activated",
   "requestedStartDate": "2025-05-17T00:00:00.000+0000",
   "requestedCompletionDate": "2025-05-17T00:00:00.000+0000",
   "orderDate": "2025-08-13T10:39:25.000+0000",
   "id": "00000469",
   "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000n6uCzYAI",
   "externalId": "PO-461",
   "description": "Product Order illustration sample"
}
```

### 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

```
{
    "submitCart": false,
    "@type": "ProductOrder",
    "category": "B2C product order",
    "description": "Product Order illustration sample",
    "externalId": "PO-461",
    "note": [
    {
        "author": "Jean Pontus",
        "date": "2019-04-30T08:13:59.509Z",
        "id": "1",
        "text": "This is a TMF product order illustration"
    }
    ],
    "priority": "1",
    "productOrderItem": [
    {
        "productOffering": {
        "id": "Corporate_Mobile_Fleet_Plan_20579"
        },
        "productOrderItemRelationship": [
        {
            "relationshipType": "bundles",
            "id": "500"
        },
        {
            "relationshipType": "bundles",
            "id": "501"
        }
        ],
        "quantity": 5,
        "id": "100",
        "action": "Add",
        "@type": "ProductOrderItem"
    },
    {
        "productOffering": {
        "id": "SIM_Management_Portal_20579"
        },
        "quantity": 3,
        "id": "500",
        "action": "modify",
        "@type": "ProductOrderItem"
    },
    {
        "productOffering": {
        "id": "Premium_Device_Upgrade_20579"
        },
        "quantity": 5,
        "id": "501",
        "action": "Add",
        "@type": "ProductOrderItem"
    },
    {
        "productOffering": {
        "id": "Mobile_Device_Management_MDM_20579"
        },
        "quantity": 5,
        "id": "600",
        "action": "Add",
        "@type": "ProductOrderItem"
    },
    {
        "productOffering": {
        "id": "Additional_WiFi_Extender_20579"
        },
        "quantity": 1,
        "id": "800",
        "action": "Add",
        "@type": "ProductOrderItem",

        "product": {
        "productCharacteristic": [
            {
            "name": "TMF_Speed_ATTR_27762",
            "value": 8
            },
            {
            "name": "PHONECOLOR",
            "value": "RED"
            }
        ]
        }
    }
    ],
    "relatedParty": [
    {
        "@referredType": "account",
        "@type": "RelatedParty",
        "id": "ACCT-NC050",
        "name": "NovaCore Dynamics"
    }
    ],
    "requestedCompletionDate": "2025-05-17T08:13:59.506Z",
    "requestedStartDate": "2025-05-17T08:13:59.506Z"
}
```

#### Sample Response

```
{
   "note": [
       {
           "text": "This is a TMF product order illustration",
           "id": "1",
           "date": "2019-04-30T08:13:59.509Z",
           "author": "Jean Pontus"
       }
   ],
   "productOrderItem": [
       {
           "productOffering": {
               "id": "Corporate_Mobile_Line_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014cDSrYAM",
           "id": "801",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "SIM_Management_Portal_20579"
           },
           "quantity": 3.00,
           "orderLineItemId": "802LT000014cDSsYAM",
           "id": "500",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Mobile_Device_Management_MDM_20579"
           },
           "quantity": 5.00,
           "orderLineItemId": "802LT000014cDStYAM",
           "id": "600",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "International_Calling_Package_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014cDSuYAM",
           "id": "802",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "product": {
               "productCharacteristic": [
                   {
                       "value": 8,
                       "name": "TMF_Speed_ATTR_27762"
                   },
                   {
                       "value": "RED",
                       "name": "PHONECOLOR"
                   }
               ]
           },
           "productOffering": {
               "id": "Additional_WiFi_Extender_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014cDSvYAM",
           "id": "800",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Corporate_Mobile_Fleet_Plan_20579"
           },
           "productOrderItemRelationship": [
               {
                   "relationshipType": "bundles",
                   "id": "801"
               },
               {
                   "relationshipType": "bundles",
                   "id": "500"
               },
               {
                   "relationshipType": "bundles",
                   "id": "802"
               },
               {
                   "relationshipType": "bundles",
                   "id": "501"
               }
           ],
           "quantity": 5.00,
           "orderLineItemId": "802LT000014cDSwYAM",
           "id": "100",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Premium_Device_Upgrade_20579"
           },
           "quantity": 5.00,
           "orderLineItemId": "802LT000014cDSxYAM",
           "id": "501",
           "action": "Add",
           "@type": "ProductOrderItem"
       }
   ],
   "relatedParty": [
       {
           "name": "NovaCore Dynamics",
           "id": "ACCT-NC050",
           "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000ldjtRYAQ",
           "@type": "RelatedParty",
           "role": "Consumer"
       }
   ],
   "state": "Draft",
   "requestedStartDate": "2025-05-17T00:00:00.000+0000",
   "requestedCompletionDate": "2025-05-17T00:00:00.000+0000",
   "orderDate": "2025-08-13T10:47:07.000+0000",
   "id": "00000470",
   "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000n6uT7YAI",
   "externalId": "PO-461",
   "description": "Product Order illustration sample"
}
```

**From Summer'25 these use cases are supported.**

<!--## Configurable Product Ordering with Mandatory and Optional Items

Users can create an order with a root product that includes a mandatory child item and an optional child item.
With this you can provide:

- Bundled Product Offerings: Enables the creation of product bundles. For example, phone with a mandatory charger and optional headphones.

- Flexible Customization: Users can tailor their orders by choosing whether or not to include optional items.

- Upselling Opportunities: Optional items can be used for upselling. For example, extended warranty, premium packaging.

- Streamlined Ordering Process: Ensures that required components (mandatory items) are never missed while giving flexibility for extras.

- Dynamic Pricing Models: Price can be adjusted dynamically based on optional selections.

- Improved User Experience: Simplifies complex product configurations for customers.

Consider a root product `Mobile Plan` with

- A mandatory child item `SIM Card`
- An optional child item `IPhone 16`
- An optional child item `Data Booster Add On`

### Sample Request

```
{
    "@type": "ProductOrder",
    "category": "B2C product order",
    "channel": [
        {
            "id": "1",
            "name": "Online chanel",
            "role": "Used channel for order capture"
        }
    ],
    "description": "Product Order illustration sample",
    "externalId": "PO-456",
    "note": [
        {
            "author": "Jean Pontus",
            "date": "2019-04-30T08:13:59.509Z",
            "id": "1",
            "text": "This is a TMF product order illustration"
        }
    ],
    "priority": "1",
    "productOrderItem": [
        {
            "@type": "ProductOrderItem",
            "action": "add",
            "id": "101",
            "quantity": 1,
            "productOffering": {
                "id": "MobilePlan"
            },
            "productOrderItemRelationship": [
                {
                    "id": "102",
                    "relationshipType": "bundles"
                },
                {
                    "id": "103",
                    "relationshipType": "bundles"
                }
            ]
        },
        {
            "@type": "ProductOrderItem",
            "action": "add",
            "id": "102",
            "quantity": 2,
            "productOffering": {
                "id": "IPhone16"
            },
            "product": {
                "productCharacteristic": [
                    {
                        "value": "White",
                        "name": "color"
                    }
                ]
            }
        },
        {
            "@type": "ProductOrderItem",
            "action": "add",
            "id": "103",
            "quantity": 3,
            "productOffering": {
                "id": "DataBoosterAddOn"
            }
        }
    ],
    "relatedParty": [
        {
            "id": "CD123",
            "name": "TMFAcc"
        }
    ],
    "requestedCompletionDate": "2019-05-02T08:13:59.506Z",
    "requestedStartDate": "2019-05-03T08:13:59.506Z"
}

```

### Sample Response

```
{
    "channel": [
        {
            "role": "Used channel for order capture",
            "name": "Online chanel",
            "id": "1"
        }
    ],
    "note": [
        {
            "text": "This is a TMF product order illustration",
            "id": "1",
            "date": "2019-04-30T08:13:59.509Z",
            "author": "Jean Pontus"
        }
    ],
    "productOrderItem": [
        {
            "productOffering": {
                "id": "MobilePlan"
            },
            "productOrderItemRelationship": [
                {
                    "relationshipType": "bundles",
                    "id": "104"
                },
                {
                    "relationshipType": "bundles",
                    "id": "103"
                },
                {
                    "relationshipType": "bundles",
                    "id": "102"
                }
            ],
            "quantity": 1.00,
            "id": "101",
            "action": "Add",
            "@type": "ProductOrderItem"
        },
        {
            "productOffering": {
                "id": "SIMCard"
            },
            "quantity": 1.00,
            "id": "104",
            "action": "Add",
            "@type": "ProductOrderItem"
        },
        {
            "productOffering": {
                "id": "DataBoosterAddOn"
            },
            "quantity": 3.00,
            "id": "103",
            "action": "Add",
            "@type": "ProductOrderItem"
        },
        {
            "product": {
                "productCharacteristic": [
                    {
                        "value": "White",
                        "name": "color"
                    }
                ]
            },
            "productOffering": {
                "id": "IPhone16"
            },
            "quantity": 2.00,
            "id": "102",
            "action": "Add",
            "@type": "ProductOrderItem"
        }
    ],
    "relatedParty": [
        {
            "name": "TMFAcc",
            "id": "CD123",
            "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Account/001xx000003Glh1AAC",
            "@type": "RelatedParty",
            "role": "Billing"
        }
    ],
    "state": "Activated",
    "requestedStartDate": "2019-05-03T00:00:00.000+0000",
    "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
    "orderDate": "2025-04-02T04:12:38.000+0000",
    "id": "00000592",
    "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Order/801xx000003H0rLAAS",
    "externalId": "PO-456",
    "description": "Product Order illustration sample"
}
```
-->

### 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.

**note:** - 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.

#### Sample URL

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

#### Sample Request

```
{
  "submitCart": false,
  "@type": "ProductOrder",
  "category": "B2C product order",
  "channel": [
    {
      "id": "1",
      "name": "Online chanel",
      "role": "Used channel for order capture"
    }
  ],
  "description": "Product Order illustration sample",
  "externalId": "OrderRootBundleHasOptionalProducts",
  "note": [
    {
      "author": "Jean Pontus",
      "date": "2019-04-30T08:13:59.509Z",
      "id": "1",
      "text": "This is a TMF product order illustration"
    }
  ],
  "priority": "1",
  "productOrderItem": [
    {
      "@type": "ProductOrderItem",
      "action": "modify",
      "id": "101",
      "quantity": 1,
      "productOffering": {
        "id": "Corporate_Mobile_Fleet_Plan_20579"
      },
      "product": {
        "id": "02iLT0000004kx7YAA"
      }
    }
    ],
  "relatedParty": [
    {
      "@referredType": "account",
      "@type": "RelatedParty",
      "id": "ACCT-NL032",
      "name": "NeoLogic Systems"
    }
  ],
  "requestedCompletionDate": "2025-05-02T08:13:59.506Z",
  "requestedStartDate": "2024-05-03T08:13:59.506Z"
}

```

#### Sample Response

```
{
  "productOrderItem": [
    {
      "productOffering": {
        "id": "Corporate_Mobile_Line_20579"
      },
      "quantity": 1,
      "orderLineItemId": "802LT000014SO7pYAG",
      "id": "102",
      "action": "Existing",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "Corporate_Mobile_Fleet_Plan_20579"
      },
      "productOrderItemRelationship": [
        {
          "relationshipType": "bundles",
          "id": "102"
        },
        {
          "relationshipType": "bundles",
          "id": "103"
        },
        {
          "relationshipType": "bundles",
          "id": "104"
        },
        {
          "relationshipType": "bundles",
          "id": "105"
        },
        {
          "relationshipType": "bundles",
          "id": "106"
        }
      ],
      "quantity": 1,
      "orderLineItemId": "802LT000014SO7qYAG",
      "id": "101",
      "action": "Change",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "SIM_Management_Portal_20579"
      },
      "quantity": 1,
      "orderLineItemId": "802LT000014SO7rYAG",
      "id": "103",
      "action": "Existing",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "International_Calling_Package_20579"
      },
      "quantity": 1,
      "orderLineItemId": "802LT000014SO7sYAG",
      "id": "104",
      "action": "Existing",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "Premium_Device_Upgrade_20579"
      },
      "quantity": 2,
      "orderLineItemId": "802LT000014SO7tYAG",
      "id": "106",
      "action": "Existing",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "SIM_Management_Portal_20579"
      },
      "quantity": 2,
      "orderLineItemId": "802LT000014SO7uYAG",
      "id": "105",
      "action": "Existing",
      "@type": "ProductOrderItem"
    }
  ],
  "relatedParty": [
    {
      "name": "NeoLogic Systems",
      "id": "ACCT-NL032",
      "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000lZlPBYA0",
      "@type": "RelatedParty",
      "role": "Consumer"
    }
  ],
  "state": "Draft",
  "requestedStartDate": "2025-07-12T06:37:12.000+0000",
  "orderDate": "2025-07-12T06:27:08.000+0000",
  "id": "00000347",
  "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000lc9DhYAI"
}
```

### 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

```
{
   "@type": "ProductOrder",
   "category": "B2C product order",
   "channel": [
       {
           "id": "1",
           "name": "Online chanel",
           "role": "Used channel for order capture"
       }
   ],
   "description": "Product Order illustration sample",
   "externalId": "PO-456",
   "note": [
       {
           "author": "Jean Pontus",
           "date": "2019-04-30T08:13:59.509Z",
           "id": "1",
           "text": "This is a TMF product order illustration"
       }
   ],
   "priority": "1",
   "productOrderItem": [
       {
           "@type": "ProductOrderItem",
           "action": "add",
           "id": "101",
           "quantity": 1,
           "productOffering": {
               "id": "MobilePlan"
           },
           "productOrderItemRelationship": [
               {
                   "id": "102",
                   "relationshipType": "bundles"
               }
           ]
       },
       {
           "@type": "ProductOrderItem",
           "action": "add",
           "id": "102",
           "quantity": 1,
           "productOffering": {
               "id": "IPhone16"
           },
           "product": {
               "productCharacteristic": [
                   {
                       "value": "White",
                       "name": "color"
                   }
               ]
           }
       },
       {
           "@type": "ProductOrderItem",
           "action": "add",
           "id": "110",
           "quantity": 1,
           "productOffering": {
               "id": "BroadbandInternetGamingPlan"
           }
       }
   ],
   "relatedParty": [
       {
           "id": "CD123",
           "name": "TMFAcc"
       }
   ],
   "requestedCompletionDate": "2019-05-02T08:13:59.506Z",
   "requestedStartDate": "2019-05-03T08:13:59.506Z"
}

```

#### Sample Response

```
{
   "channel": [
       {
           "role": "Used channel for order capture",
           "name": "Online chanel",
           "id": "1"
       }
   ],
   "note": [
       {
           "text": "This is a TMF product order illustration",
           "id": "1",
           "date": "2019-04-30T08:13:59.509Z",
           "author": "Jean Pontus"
       }
   ],
   "productOrderItem": [
       {
           "productOffering": {
               "id": "SIMCard"
           },
           "quantity": 1.00,
           "id": "111",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "CPE"
           },
           "quantity": 1.00,
           "id": "113",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "BroadbandInternetGamingPlan"
           },
           "productOrderItemRelationship": [
               {
                   "relationshipType": "bundles",
                   "id": "112"
               },
               {
                   "relationshipType": "bundles",
                   "id": "113"
               }
           ],
           "quantity": 1.00,
           "id": "110",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "MobilePlan"
           },
           "productOrderItemRelationship": [
               {
                   "relationshipType": "bundles",
                   "id": "111"
               },
               {
                   "relationshipType": "bundles",
                   "id": "102"
               }
           ],
           "quantity": 1.00,
           "id": "101",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "InternetAccess"
           },
           "quantity": 1.00,
           "id": "112",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "product": {
               "productCharacteristic": [
                   {
                       "value": "White",
                       "name": "color"
                   }
               ]
           },
           "productOffering": {
               "id": "IPhone16"
           },
           "quantity": 1.00,
           "id": "102",
           "action": "Add",
           "@type": "ProductOrderItem"
       }
   ],
   "relatedParty": [
       {
           "name": "TMFAcc",
           "id": "CD123",
           "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Account/001xx000003Glh1AAC",
           "@type": "RelatedParty",
           "role": "Billing"
       }
   ],
   "state": "Activated",
   "requestedStartDate": "2019-05-03T00:00:00.000+0000",
   "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
   "orderDate": "2025-04-02T04:15:18.000+0000",
   "id": "00000593",
   "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Order/801xx000003H0sxAAC",
   "externalId": "PO-456",
   "description": "Product Order illustration sample"
}

```

<!--## Configure Product Orders with Mandatory Items and Optional Bundles

Users can create an order that includes root products, that contain mandatory child items and an optional bundle product.
With this you can provide:

- Flexible Bundled Product Configuration: Allows users to order a product with required components and optionally enhance it with bundled add-ons.
- Enhanced Product Personalization: Supports creating more tailored product offerings by mixing core functionality with optional enhancements.
- Dynamic Pricing and Promotions: Optional bundles can trigger discounts or promotions when selected with the root product.
- Simplified Inventory Management: Allows better planning for both fixed and flexible components of a product.

### Limitations

- No Runtime Attribute Configuration: Users cannot configure attributes at runtime. Orders with mandatory runtime-configurable attributes will fail at submission.
- No Quantity or Billing Account Overrides: Users cannot override the quantity of order items or change the billing account.
- No Price Adjustments: Pricing cannot be overridden using manual adjustments.
- No Pre-Validation in TMF622 POST: The TMF622 POST API does not perform cart validation before submission; products are submitted directly once added to the cart.

Consider a root product `Broadband Internet Gaming Plan` with

- A mandatory child item `SIM Card`
- An optional child items `Internet Access` and `CPE`
- An optional child item `GamingKit`, which is a bundle product with mandatory child items `Gaming Keyboard` and `Gaming Console`

### Sample Request

```
{
    "@type": "ProductOrder",
    "category": "B2C product order",
    "channel": [
        {
            "id": "1",
            "name": "Online chanel",
            "role": "Used channel for order capture"
        }
    ],
    "description": "Product Order illustration sample",
    "externalId": "PO-456",
    "note": [
        {
            "author": "Jean Pontus",
            "date": "2019-04-30T08:13:59.509Z",
            "id": "1",
            "text": "This is a TMF product order illustration"
        }
    ],
    "priority": "1",
    "productOrderItem": [
        {
            "@type": "ProductOrderItem",
            "action": "add",
            "id": "101",
            "quantity": 1,
            "productOffering": {
                "id": "BroadbandInternetGamingPlan"
            },
            "productOrderItemRelationship": [
                {
                    "id": "102",
                    "relationshipType": "bundles"
                }
            ]
        },
        {
            "@type": "ProductOrderItem",
            "action": "add",
            "id": "102",
            "quantity": 1,
            "productOffering": {
                "id": "GamingKit"
            }
        }
    ],
    "relatedParty": [
        {
            "id": "CD123",
            "name": "TMFAcc"
        }
    ],
    "requestedCompletionDate": "2019-05-02T08:13:59.506Z",
    "requestedStartDate": "2019-05-03T08:13:59.506Z"
}
```

### Sample Response

```
{
    "channel": [
        {
            "role": "Used channel for order capture",
            "name": "Online chanel",
            "id": "1"
        }
    ],
    "note": [
        {
            "text": "This is a TMF product order illustration",
            "id": "1",
            "date": "2019-04-30T08:13:59.509Z",
            "author": "Jean Pontus"
        }
    ],
    "productOrderItem": [
        {
            "productOffering": {
                "id": "CPE"
            },
            "quantity": 1.00,
            "id": "104",
            "action": "Add",
            "@type": "ProductOrderItem"
        },
        {
            "productOffering": {
                "id": "BroadbandInternetGamingPlan"
            },
            "productOrderItemRelationship": [
                {
                    "relationshipType": "bundles",
                    "id": "103"
                },
                {
                    "relationshipType": "bundles",
                    "id": "104"
                },
                {
                    "relationshipType": "bundles",
                    "id": "102"
                }
            ],
            "quantity": 1.00,
            "id": "101",
            "action": "Add",
            "@type": "ProductOrderItem"
        },
        {
            "productOffering": {
                "id": "InternetAccess"
            },
            "quantity": 1.00,
            "id": "103",
            "action": "Add",
            "@type": "ProductOrderItem"
        },
        {
            "productOffering": {
                "id": "GamingKit"
            },
            "productOrderItemRelationship": [
                {
                    "relationshipType": "bundles",
                    "id": "105"
                },
                {
                    "relationshipType": "bundles",
                    "id": "106"
                }
            ],
            "quantity": 1.00,
            "id": "102",
            "action": "Add",
            "@type": "ProductOrderItem"
        },
        {
            "productOffering": {
                "id": "GamingKeyboard"
            },
            "quantity": 1.00,
            "id": "105",
            "action": "Add",
            "@type": "ProductOrderItem"
        },
        {
            "productOffering": {
                "id": "GamingConsole"
            },
            "quantity": 1.00,
            "id": "106",
            "action": "Add",
            "@type": "ProductOrderItem"
        }
    ],
    "relatedParty": [
        {
            "name": "TMFAcc",
            "id": "CD123",
            "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Account/001xx000003Glh1AAC",
            "@type": "RelatedParty",
            "role": "Billing"
        }
    ],
    "state": "Activated",
    "requestedStartDate": "2019-05-03T00:00:00.000+0000",
    "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
    "orderDate": "2025-04-02T03:39:28.000+0000",
    "id": "00000582",
    "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Order/801xx000003H0cpAAC",
    "externalId": "PO-456",
    "description": "Product Order illustration sample"
}
``` -->

### 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

```
{
   "@type": "ProductOrder",
   "category": "B2C product order",
   "channel": [
       {
           "id": "1",
           "name": "Online chanel",
           "role": "Used channel for order capture"
       }
   ],
   "description": "Product Order illustration sample",
   "externalId": "PO-456",
   "note": [
       {
           "author": "Jean Pontus",
           "date": "2019-04-30T08:13:59.509Z",
           "id": "1",
           "text": "This is a TMF product order illustration"
       }
   ],
   "priority": "1",
   "productOrderItem": [
       {
           "@type": "ProductOrderItem",
           "action": "add",
           "id": "101",
           "quantity": 1,
           "productOffering": {
               "id": "MobilePlan"
           },
           "productOrderItemRelationship": [
               {
                   "id": "102",
                   "relationshipType": "bundles"
               },
               {
                   "id": "103",
                   "relationshipType": "bundles"
               }
           ]
       },
       {
           "@type": "ProductOrderItem",
           "action": "add",
           "id": "102",
           "quantity": 2,
           "productOffering": {
               "id": "IPhone16"
           },
           "product": {
               "productCharacteristic": [
                   {
                       "value": "White",
                       "name": "color"
                   }
               ]
           }
       },
       {
           "@type": "ProductOrderItem",
           "action": "add",
           "id": "103",
           "quantity": 3,
           "productOffering": {
               "id": "IPhone16"
           },
           "product": {
               "productCharacteristic": [
                   {
                       "value": "Black",
                       "name": "color"
                   }
               ]
           }
       }
   ],
   "relatedParty": [
       {
           "id": "CD123",
           "name": "TMFAcc"
       }
   ],
   "requestedCompletionDate": "2019-05-02T08:13:59.506Z",
   "requestedStartDate": "2019-05-03T08:13:59.506Z"
}

```

#### Sample Response

```
{
   "channel": [
       {
           "role": "Used channel for order capture",
           "name": "Online chanel",
           "id": "1"
       }
   ],
   "note": [
       {
           "text": "This is a TMF product order illustration",
           "id": "1",
           "date": "2019-04-30T08:13:59.509Z",
           "author": "Jean Pontus"
       }
   ],
   "productOrderItem": [
       {
           "productOffering": {
               "id": "SIMCard"
           },
           "quantity": 1.00,
           "id": "104",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "MobilePlan"
           },
           "productOrderItemRelationship": [
               {
                   "relationshipType": "bundles",
                   "id": "104"
               },
               {
                   "relationshipType": "bundles",
                   "id": "102"
               },
               {
                   "relationshipType": "bundles",
                   "id": "103"
               }
           ],
           "quantity": 1.00,
           "id": "101",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "product": {
               "productCharacteristic": [
                   {
                       "value": "White",
                       "name": "color"
                   }
               ]
           },
           "productOffering": {
               "id": "IPhone16"
           },
           "quantity": 2.00,
           "id": "102",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "product": {
               "productCharacteristic": [
                   {
                       "value": "Black",
                       "name": "color"
                   }
               ]
           },
           "productOffering": {
               "id": "IPhone16"
           },
           "quantity": 3.00,
           "id": "103",
           "action": "Add",
           "@type": "ProductOrderItem"
       }
   ],
   "relatedParty": [
       {
           "name": "TMFAcc",
           "id": "CD123",
           "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Account/001xx000003Glh1AAC",
           "@type": "RelatedParty",
           "role": "Billing"
       }
   ],
   "state": "Activated",
   "requestedStartDate": "2019-05-03T00:00:00.000+0000",
   "requestedCompletionDate": "2019-05-02T00:00:00.000+0000",
   "orderDate": "2025-04-02T04:53:04.000+0000",
   "id": "00000595",
   "href": "/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/Order/801xx000003H0uaAAC",
   "externalId": "PO-456",
   "description": "Product Order illustration sample"
}

```

## 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

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

### 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

```
{
   "@type": "ProductOrder",
   "category": "B2C product order",
   "description": "Updated Product Order illustration sample",
   "externalId": "PO-462",
   "note": [
       {
           "author": "Jean Pontus",
           "date": "2022-04-30T08:13:59.509Z",
           "id": "1",
           "text": "This is a TMF product order illustration"
       }
   ],
   "priority": "1",
   "productOrderItem": [
       {
           "productOffering": {
               "id": "Premium_Device_Upgrade_20579"
           },
           "quantity": 2,
           "id": "301",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Ultimate_Connectivity_Bundle_20579"
           },
           "quantity": 2,
           "id": "500",
           "action": "Add",
           "@type": "ProductOrderItem",
           "productOrderItemRelationship": [
               {
                   "relationshipType": "bundles",
                   "id": "501"
               },
               {
                   "relationshipType": "bundles",
                   "id": "502"
               }
           ]
       },
       {
           "productOffering": {
               "id": "Premium_Support_20579"
           },
           "quantity": 2,
           "id": "501",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "4K_TV_Subscription_20579"
           },
           "quantity": 2,
           "id": "502",
           "action": "modify",
           "@type": "ProductOrderItem"
       }
   ],
   "relatedParty": [
       {
           "@referredType": "account",
           "@type": "RelatedParty",
           "id": "ACCT-GC015",
           "name": "GreenCore Analytics"
       }
   ],
   "requestedCompletionDate": "2025-07-17T08:13:59.506Z",
   "requestedStartDate": "2025-06-17T08:13:59.506Z"
}
```

#### Sample Response

```
{
   "note": [
       {
           "text": "This is a TMF product order illustration",
           "id": "1",
           "date": "2022-04-30T08:13:59.509Z",
           "author": "Jean Pontus"
       }
   ],
   "productOrderItem": [
       {
           "productOffering": {
               "id": "Corporate_Mobile_Line_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014cDSrYAM",
           "id": "505",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "SIM_Management_Portal_20579"
           },
           "quantity": 3.00,
           "orderLineItemId": "802LT000014cDSsYAM",
           "id": "506",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "International_Calling_Package_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014cDSuYAM",
           "id": "507",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "product": {
               "productCharacteristic": [
                   {
                       "value": 10,
                       "name": "TMF_Speed_ATTR_27762"
                   },
                   {
                       "value": "RED",
                       "name": "PHONECOLOR"
                   }
               ]
           },
           "productOffering": {
               "id": "Additional_WiFi_Extender_20579"
           },
           "quantity": 2.00,
           "orderLineItemId": "802LT000014cDSvYAM",
           "id": "510",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Corporate_Mobile_Fleet_Plan_20579"
           },
           "productOrderItemRelationship": [
               {
                   "relationshipType": "bundles",
                   "id": "505"
               },
               {
                   "relationshipType": "bundles",
                   "id": "506"
               },
               {
                   "relationshipType": "bundles",
                   "id": "507"
               },
               {
                   "relationshipType": "bundles",
                   "id": "508"
               },
               {
                   "relationshipType": "bundles",
                   "id": "509"
               }
           ],
           "quantity": 4.00,
           "orderLineItemId": "802LT000014cDSwYAM",
           "id": "504",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Premium_Device_Upgrade_20579"
           },
           "quantity": 5.00,
           "orderLineItemId": "802LT000014cDSxYAM",
           "id": "508",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Mobile_Device_Management_MDM_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014dUeXYAU",
           "id": "509",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Ultimate_Connectivity_Bundle_20579"
           },
           "productOrderItemRelationship": [
               {
                   "relationshipType": "bundles",
                   "id": "503"
               },
               {
                   "relationshipType": "bundles",
                   "id": "502"
               },
               {
                   "relationshipType": "bundles",
                   "id": "501"
               }
           ],
           "quantity": 2.00,
           "orderLineItemId": "802LT000014dUhlYAE",
           "id": "500",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "4K_TV_Subscription_20579"
           },
           "quantity": 2.00,
           "orderLineItemId": "802LT000014dUhmYAE",
           "id": "502",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Fiber_Internet_500Mbps_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014dUhnYAE",
           "id": "503",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Premium_Device_Upgrade_20579"
           },
           "quantity": 2.00,
           "orderLineItemId": "802LT000014dUhoYAE",
           "id": "301",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Premium_Support_20579"
           },
           "quantity": 2.00,
           "orderLineItemId": "802LT000014dUhpYAE",
           "id": "501",
           "action": "Add",
           "@type": "ProductOrderItem"
       }
   ],
   "relatedParty": [
       {
           "name": "NovaCore Dynamics",
           "id": "ACCT-NC050",
           "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000ldjtRYAQ",
           "@type": "RelatedParty",
           "role": "Consumer"
       }
   ],
   "state": "Draft",
   "requestedStartDate": "2025-06-17T08:13:59.000+0000",
   "requestedCompletionDate": "2025-07-17T08:13:59.000+0000",
   "orderDate": "2025-08-13T10:47:07.000+0000",
   "id": "00000470",
   "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000n6uT7YAI",
   "externalId": "PO-462",
   "description": "Updated Product Order illustration sample"
}
```

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

```
{
 "@type": "ProductOrder",
 "category": "B2C product order",
 "description": "Updated Product Order illustration sample",
 "externalId": "PO-462",
 "note": [
   {
     "author": "Jean Pontus",
     "date": "2022-04-30T08:13:59.509Z",
     "id": "1",
     "text": "This is a TMF product order illustration"
   }
 ],
 "priority": "1",
 "productOrderItem": [
   {
     "productOffering": {
       "id": "Corporate_Mobile_Fleet_Plan_20579"
     },
     "productOrderItemRelationship": [
       {
         "relationshipType": "bundles",
         "id": "101"
       }
     ],
     "quantity": 4,
     "orderLineItemId": "802LT000014cDSwYAM",
     "id": "100",
     "action": "modify",
     "@type": "ProductOrderItem"
   },
   {
     "productOffering": {
       "id": "Mobile_Device_Management_MDM_20579"
     },
     "quantity": 2,
     "id": "101",
     "action": "Add",
     "@type": "ProductOrderItem"
   },
   {
     "productOffering": {
       "id": "Additional_WiFi_Extender_20579"
     },
     "quantity": 2,
     "id": "900",
     "action": "modify",
     "@type": "ProductOrderItem",
     "orderLineItemId": "802LT000014cDSvYAM",
     "product": {
       "productCharacteristic": [
         {
           "name": "TMF_Speed_ATTR_27762",
           "value": 10
         },
         {
           "name": "PHONECOLOR",
           "value": "RED"
         }
       ]
     }
   },
   {
     "productOffering": {
       "id": "Mobile_Device_Management_MDM_20579"
     },
     "quantity": 1,
     "orderLineItemId": "802LT000014cDStYAM",
     "id": "998",
     "action": "delete",
     "@type": "ProductOrderItem"
   }
 ],
 "relatedParty": [
   {
     "@referredType": "account",
     "@type": "RelatedParty",
     "id": "ACCT-GC015",
     "name": "GreenCore Analytics"
   }
 ],
 "requestedCompletionDate": "2025-07-17T08:13:59.506Z",
 "requestedStartDate": "2025-06-17T08:13:59.506Z"
}
```

#### Sample Response

```
{
  "note": [
    {
      "text": "This is a TMF product order illustration",
      "id": "1",
      "date": "2022-04-30T08:13:59.509Z",
      "author": "Jean Pontus"
    }
  ],
  "productOrderItem": [
    {
      "productOffering": {
        "id": "Corporate_Mobile_Line_20579"
      },
      "quantity": 1,
      "orderLineItemId": "802LT000014cDSrYAM",
      "id": "101",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "SIM_Management_Portal_20579"
      },
      "quantity": 3,
      "orderLineItemId": "802LT000014cDSsYAM",
      "id": "102",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "International_Calling_Package_20579"
      },
      "quantity": 1,
      "orderLineItemId": "802LT000014cDSuYAM",
      "id": "103",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "product": {
        "productCharacteristic": [
          {
            "value": 10,
            "name": "TMF_Speed_ATTR_27762"
          },
          {
            "value": "RED",
            "name": "PHONECOLOR"
          }
        ]
      },
      "productOffering": {
        "id": "Additional_WiFi_Extender_20579"
      },
      "quantity": 2,
      "orderLineItemId": "802LT000014cDSvYAM",
      "id": "106",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "Corporate_Mobile_Fleet_Plan_20579"
      },
      "productOrderItemRelationship": [
        {
          "relationshipType": "bundles",
          "id": "101"
        },
        {
          "relationshipType": "bundles",
          "id": "102"
        },
        {
          "relationshipType": "bundles",
          "id": "103"
        },
        {
          "relationshipType": "bundles",
          "id": "104"
        },
        {
          "relationshipType": "bundles",
          "id": "105"
        }
      ],
      "quantity": 4,
      "orderLineItemId": "802LT000014cDSwYAM",
      "id": "100",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "Premium_Device_Upgrade_20579"
      },
      "quantity": 5,
      "orderLineItemId": "802LT000014cDSxYAM",
      "id": "104",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "Mobile_Device_Management_MDM_20579"
      },
      "quantity": 1,
      "orderLineItemId": "802LT000014dUeXYAU",
      "id": "105",
      "action": "Add",
      "@type": "ProductOrderItem"
    }
  ],
  "relatedParty": [
    {
      "name": "NovaCore Dynamics",
      "id": "ACCT-NC050",
      "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000ldjtRYAQ",
      "@type": "RelatedParty",
      "role": "Consumer"
    }
  ],
  "state": "Draft",
  "requestedStartDate": "2025-06-17T08:13:59.000+0000",
  "requestedCompletionDate": "2025-07-17T08:13:59.000+0000",
  "orderDate": "2025-08-13T10:47:07.000+0000",
  "id": "00000470",
  "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000n6uT7YAI",
  "externalId": "PO-462",
  "description": "Updated Product Order illustration sample"
}
```

### 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

```
{
   "productOrderItem": [
       {
           "@type": "ProductOrderItem",
           "id": "103",
           "action": "modify",
           "orderLineItemId": "802LT000014cDSvYAM",
           "quantity": 2,
           "productOffering": {
               "id": "Additional_WiFi_Extender_20579"
           },
           "itemPrice": [
               {
                   "priceAlteration": [
                       {
                           "priceType": "recurring",
                           "name": "TP-1Y",
                           "recurringChargePeriod": "year",
                           "applicationDuration": 2,
                           "price": {
                               "percentage": -30,
                               "@type": "price"
                           }
                       }
                   ]
               }
           ]
       }
   ]
}

```

#### Sample Response

```
{
   "note": [
       {
           "text": "This is a TMF product order illustration",
           "id": "1",
           "date": "2022-04-30T08:13:59.509Z",
           "author": "Jean Pontus"
       }
   ],
   "productOrderItem": [
       {
           "productOffering": {
               "id": "Corporate_Mobile_Line_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014cDSrYAM",
           "id": "106",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "SIM_Management_Portal_20579"
           },
           "quantity": 3.00,
           "orderLineItemId": "802LT000014cDSsYAM",
           "id": "107",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "International_Calling_Package_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014cDSuYAM",
           "id": "108",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "product": {
               "productCharacteristic": [
                   {
                       "value": 10,
                       "name": "TMF_Speed_ATTR_27762"
                   },
                   {
                       "value": "RED",
                       "name": "PHONECOLOR"
                   }
               ]
           },
           "itemPrice": [
               {
                   "priceAlteration": [
                       {
                           "price": {
                               "percentage": -30.0,
                               "@type": "price"
                           },
                           "priceType": "recurring"
                       }
                   ]
               }
           ],
           "productOffering": {
               "id": "Additional_WiFi_Extender_20579"
           },
           "quantity": 2.00,
           "orderLineItemId": "802LT000014cDSvYAM",
           "id": "111",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Corporate_Mobile_Fleet_Plan_20579"
           },
           "productOrderItemRelationship": [
               {
                   "relationshipType": "bundles",
                   "id": "106"
               },
               {
                   "relationshipType": "bundles",
                   "id": "107"
               },
               {
                   "relationshipType": "bundles",
                   "id": "108"
               },
               {
                   "relationshipType": "bundles",
                   "id": "109"
               },
               {
                   "relationshipType": "bundles",
                   "id": "110"
               }
           ],
           "quantity": 4.00,
           "orderLineItemId": "802LT000014cDSwYAM",
           "id": "105",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Premium_Device_Upgrade_20579"
           },
           "quantity": 5.00,
           "orderLineItemId": "802LT000014cDSxYAM",
           "id": "109",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Mobile_Device_Management_MDM_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014dUeXYAU",
           "id": "110",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Ultimate_Connectivity_Bundle_20579"
           },
           "productOrderItemRelationship": [
               {
                   "relationshipType": "bundles",
                   "id": "102"
               },
               {
                   "relationshipType": "bundles",
                   "id": "103"
               },
               {
                   "relationshipType": "bundles",
                   "id": "104"
               }
           ],
           "quantity": 2.00,
           "orderLineItemId": "802LT000014dUhlYAE",
           "id": "101",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "4K_TV_Subscription_20579"
           },
           "quantity": 2.00,
           "orderLineItemId": "802LT000014dUhmYAE",
           "id": "103",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Fiber_Internet_500Mbps_20579"
           },
           "quantity": 1.00,
           "orderLineItemId": "802LT000014dUhnYAE",
           "id": "102",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Premium_Device_Upgrade_20579"
           },
           "quantity": 2.00,
           "orderLineItemId": "802LT000014dUhoYAE",
           "id": "100",
           "action": "Add",
           "@type": "ProductOrderItem"
       },
       {
           "productOffering": {
               "id": "Premium_Support_20579"
           },
           "quantity": 2.00,
           "orderLineItemId": "802LT000014dUhpYAE",
           "id": "104",
           "action": "Add",
           "@type": "ProductOrderItem"
       }
   ],
   "relatedParty": [
       {
           "name": "NovaCore Dynamics",
           "id": "ACCT-NC050",
           "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000ldjtRYAQ",
           "@type": "RelatedParty",
           "role": "Consumer"
       }
   ],
   "state": "Draft",
   "requestedStartDate": "2025-06-17T08:13:59.000+0000",
   "requestedCompletionDate": "2025-07-17T08:13:59.000+0000",
   "orderDate": "2025-08-13T10:47:07.000+0000",
   "id": "00000470",
   "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000n6uT7YAI",
   "externalId": "PO-462",
   "description": "Updated Product Order illustration sample"
}
```

### 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

```
{
 "state": "Activated"
}
```

#### Sample Response

```
{
  "note": [
    {
      "text": "This is a TMF product order illustration",
      "id": "1",
      "date": "2022-04-30T08:13:59.509Z",
      "author": "Jean Pontus"
    }
  ],
  "productOrderItem": [
    {
      "productOffering": {
        "id": "Corporate_Mobile_Line_20579"
      },
      "quantity": 1,
      "orderLineItemId": "802LT000014cDSrYAM",
      "id": "106",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "SIM_Management_Portal_20579"
      },
      "quantity": 3,
      "orderLineItemId": "802LT000014cDSsYAM",
      "id": "107",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "International_Calling_Package_20579"
      },
      "quantity": 1,
      "orderLineItemId": "802LT000014cDSuYAM",
      "id": "108",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "product": {
        "productCharacteristic": [
          {
            "value": 10,
            "name": "TMF_Speed_ATTR_27762"
          },
          {
            "value": "RED",
            "name": "PHONECOLOR"
          }
        ]
      },
      "itemPrice": [
        {
          "priceAlteration": [
            {
              "price": {
                "percentage": -30,
                "@type": "price"
              },
              "priceType": "recurring"
            }
          ]
        }
      ],
      "productOffering": {
        "id": "Additional_WiFi_Extender_20579"
      },
      "quantity": 2,
      "orderLineItemId": "802LT000014cDSvYAM",
      "id": "111",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "Corporate_Mobile_Fleet_Plan_20579"
      },
      "productOrderItemRelationship": [
        {
          "relationshipType": "bundles",
          "id": "106"
        },
        {
          "relationshipType": "bundles",
          "id": "107"
        },
        {
          "relationshipType": "bundles",
          "id": "108"
        },
        {
          "relationshipType": "bundles",
          "id": "109"
        },
        {
          "relationshipType": "bundles",
          "id": "110"
        }
      ],
      "quantity": 4,
      "orderLineItemId": "802LT000014cDSwYAM",
      "id": "105",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "Premium_Device_Upgrade_20579"
      },
      "quantity": 5,
      "orderLineItemId": "802LT000014cDSxYAM",
      "id": "109",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "Mobile_Device_Management_MDM_20579"
      },
      "quantity": 1,
      "orderLineItemId": "802LT000014dUeXYAU",
      "id": "110",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "Ultimate_Connectivity_Bundle_20579"
      },
      "productOrderItemRelationship": [
        {
          "relationshipType": "bundles",
          "id": "102"
        },
        {
          "relationshipType": "bundles",
          "id": "103"
        },
        {
          "relationshipType": "bundles",
          "id": "104"
        }
      ],
      "quantity": 2,
      "orderLineItemId": "802LT000014dUhlYAE",
      "id": "101",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "4K_TV_Subscription_20579"
      },
      "quantity": 2,
      "orderLineItemId": "802LT000014dUhmYAE",
      "id": "103",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "Fiber_Internet_500Mbps_20579"
      },
      "quantity": 1,
      "orderLineItemId": "802LT000014dUhnYAE",
      "id": "102",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "Premium_Device_Upgrade_20579"
      },
      "quantity": 2,
      "orderLineItemId": "802LT000014dUhoYAE",
      "id": "100",
      "action": "Add",
      "@type": "ProductOrderItem"
    },
    {
      "productOffering": {
        "id": "Premium_Support_20579"
      },
      "quantity": 2,
      "orderLineItemId": "802LT000014dUhpYAE",
      "id": "104",
      "action": "Add",
      "@type": "ProductOrderItem"
    }
  ],
  "relatedParty": [
    {
      "name": "NovaCore Dynamics",
      "id": "ACCT-NC050",
      "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Account/001LT00000ldjtRYAQ",
      "@type": "RelatedParty",
      "role": "Consumer"
    }
  ],
  "state": "Activated",
  "requestedStartDate": "2025-06-17T08:13:59.000+0000",
  "requestedCompletionDate": "2025-07-17T08:13:59.000+0000",
  "orderDate": "2025-08-13T10:47:07.000+0000",
  "id": "00000470",
  "href": "/services/apexrest/devops001gs0/tmforum/productopenapi/v1/Order/801LT00000n6uT7YAI",
  "externalId": "PO-462",
  "description": "Updated Product Order illustration sample"
}
```

## 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.

```
{
"eventId": "001",
"eventType": "ProductOrderStateChangeEvent",
"event": {
"productOrder": {
"id": "00000407",
"state": "Activated"
}
}
}
```

#### 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

  ```
  {
  "failureReason": "We couldn't submit the Product Order. Try again.",
  "overallResult": "failure"
  }
  ```

- Invalid priceType

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

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

  ```
  {
  "failureReason": "Deactivate Status field for patching ProductOrderLineItem",
  "overallResult": "failure"
  }
  ```

- Quantity is missing or less than 1

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