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

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

In general, we can consider the various use cases listed based on the operation you want to perform.

It is assumed that you have completed the following.

• Enabling Access to Industry APIs
• Ensuring that the required licenses and data packs are installed. For more information, refer Before you begin.

Following block diagram provides a sequence of operations involved.

NOTE:

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

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

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

Refer Retrieve ProductOrder by ID

Field orderLineItemId is present for every ProductOrderItem in response.

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

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

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

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

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

Refer List All Product Orders

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

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

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

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

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

NOTE:

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

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

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

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

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

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

From Summer'25 these use cases are supported.

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.

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

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.

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

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

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

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

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

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

You can update these top-level attributes.

• channel
• description
• externalId
• note
• requestedCompletionDate
• requestedStartDate

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.

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

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.

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

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.

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

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.

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

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.

This is the sample notification event.