---
schema_version: "1"
id: 1ed4061a3bee623d095bb95b951b52ecb6bb939d0115deccb545f3ce893b5ac4
title: Overview
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/industries-integrations/comms/guides/TMF671/TMF671use-cases.md
canonical_url: https://developer.salesforce.com/docs/industries/communications/guide/TMF671use-cases.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: eac7fb457f7dcb5449c14d9f0deae481305cc28f194a1dbea0b2d944ce15be68
products:
- Communications Cloud TM Forum API
- Industries Integrations
---
# Overview
- The TMF671 API offers a standardized way for service providers to configure and manage promotions. Using the TMF671 API, service providers can determine, based on predefined criteria, whether promotions such as additional discounts, vouchers, bonuses, or gifts can be applied.
- The execution of promotions is the responsibility of the enterprise platform that applies the discounts, vouchers, bonuses, or gifts, based on the information retrieved from the TMF671 API.
- Using TMF671 API you can perform these operations on customer account.
- Retrieve the list of promotions from the system
- Get the promotion details
- Create a promotion
**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 these.
- [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.
## Sequence of Operations
Following block diagram provides a sequence of operations involved.
**NOTE:**
- For mandatory fields and resource mappings, refer [TMF671 v4 Resource Mappings](https://developer.salesforce.com/docs/industries/communications/Resource_mappings/tmf671_resource_mapping.md).
## Use Cases
| I want to | Request Type | Example URL |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Retrieve and display details of a particular promotion. | [GET by ID](#get-by-id) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/promotionManagement/v4/promotion/{promotionCode}
_
**NOTE:**
For invalid customer ID, you receive HTTP 404 error. |
| Based on the provided field values, retrieve and display details of promotion. | [GET with Fields](#get-with-fields) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/promotionManagement/v4/promotion?fields=name_
**NOTE:**
The requested fields are part of output, if they have value. |
| List all the promotions present in the system. | [GET List](#get-list) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/promotionManagement/v4/promotion_ |
| List promotion details present in the system based on the filter applied. | [GET List with Filtering](#get-list-with-filtering) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/promotionManagement/v4/promotion?name={name}_
**NOTE:**
The requested fields are part of output, if they have value. |
| List promotions, limit the number of promotions to a maximum of specified limit, and
starts the results display from page specified by offset. | [GET List by limit and offset](#get-list-by-limit-and-offset) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/promotionManagement/v4/promotion?offset=2&pageLimit=2&pageinfo=true_
|
| Create a new promotion by providing the required details. | [POST](#post) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/promotionManagement/v4/promotion
_
**NOTE:**
A new customer account gets created based on the values mentioned for the mandatory fields. |
### GET by ID
Consider you want to retrieve details of a particular promotion.
#### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v63.0/connect/comms/promotionManagement/v4/promotion/TMF671PostRequest10`
#### Sample Response
```
Response - 200 OK
{
"id": "TMF671PostRequest10",
"href": "/connect/comms/promotionmanagement/v5/promotion/TMF671PostRequest10",
"name": "CustomButtonsStep",
"lifecycleStatus": false,
"lastUpdate": "Fri Nov 08 04:59:52 GMT 2024",
"validFor": {
"startDateTime": "Sun Nov 10 04:54:00 GMT 2024",
"endDateTime": "null"
},
"pattern": [
{
"id": "TMF",
"name": "runtime_industries_ups__Build_Your_Own_Promotion_TMF",
"action": [
{
"id": "AmountOff",
"actionType": "10",
"actionValue": "20",
"@type": "PromotionAction"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "productId",
"criteriaValue": "abc",
"@type": "PromotionCriteria"
}
]
}
],
"@type": "PromotionPattern",
"priority" : 1
}
],
"@type": "Promotion"
}
```
### GET with Fields
Consider you want to retrieve details of the promotion and get these details in the output.
- name
#### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v63.0/connect/comms/promotionManagement/v4/promotion?fields=name`
#### Sample Response
```
[
{
"validFor": {
"startDateTime": "null",
"endDateTime": "null"
},
"@type": "Promotion",
"lastUpdate": "null",
"name": "TMF671PostRequest2",
"href": "/connect/comms/promotionmanagement/v5/promotion/${id}"
},
{
"validFor": {
"startDateTime": "null",
"endDateTime": "null"
},
"@type": "Promotion",
"lastUpdate": "null",
"name": "TMF671PostRequest3",
"href": "/connect/comms/promotionmanagement/v5/promotion/${id}"
},
{
"validFor": {
"startDateTime": "null",
"endDateTime": "null"
},
"@type": "Promotion",
"lastUpdate": "null",
"name": "CustomButtonsStep",
"href": "/connect/comms/promotionmanagement/v5/promotion/${id}"
}
]
```
### GET List
Consider there are multiple promotions in the system and you want to list all of them.
#### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v63.0/connect/comms/promotionManagement/v4/promotion`
#### Sample Response
```
[
{
"lifecycleStatus": false,
"validFor": {
"startDateTime": "Fri Jan 10 00:00:00 GMT 2025",
"endDateTime": "null"
},
"@type": "Promotion",
"lastUpdate": "Fri Nov 08 03:48:44 GMT 2024",
"name": "TMF671Testing2",
"pattern": [
{
"id": "Request102",
"name": "runtime_industries_ups__Build_Your_Own_Promotion_Request102",
"action": [
{
"id": "VoucherName",
"actionType": "7",
"actionValue": "2Xaxx0000000001CAA",
"@type": "PromotionAction"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "voucherCode",
"criteriaValue": "XYZ",
"@type": "PromotionCriteria"
}
]
}
],
"priority" : 2,
"@type": "PromotionPattern"
}
],
"description": "TMF671Testing2",
"id": "TMF671Testing2",
"href": "/connect/comms/promotionmanagement/v5/promotion/TMF671Testing2"
},
{
"lifecycleStatus": false,
"validFor": {
"startDateTime": "Fri Jan 10 00:00:00 GMT 2025",
"endDateTime": "null"
},
"@type": "Promotion",
"lastUpdate": "Fri Nov 08 04:19:11 GMT 2024",
"name": "TMF671PostRequest1",
"pattern": [
{
"id": "Request1",
"name": "runtime_industries_ups__Build_Your_Own_Promotion_Request1",
"action": [
{
"id": "VoucherName",
"actionType": "7",
"actionValue": "2Xaxx0000000001CAA",
"@type": "PromotionAction"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "voucherCode",
"criteriaValue": "XYZ",
"@type": "PromotionCriteria"
}
]
}
],
"@type": "PromotionPattern",
"priority" : 4,
}
],
"description": "TMF671Promo",
"id": "TMF671PostRequest1",
"href": "/connect/comms/promotionmanagement/v5/promotion/TMF671PostRequest1"
},
{
"lifecycleStatus": false,
"validFor": {
"startDateTime": "Fri Jan 10 00:00:00 GMT 2025",
"endDateTime": "null"
},
"@type": "Promotion",
"lastUpdate": "Fri Nov 08 04:20:23 GMT 2024",
"name": "TMF671PostRequest2",
"pattern": [
{
"id": "Request2",
"name": "runtime_industries_ups__Build_Your_Own_Promotion_Request2",
"action": [
{
"id": "PercentageOff",
"actionType": "8",
"actionValue": "4",
"@type": "PromotionAction"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "voucherCode",
"criteriaValue": "XYZ",
"@type": "PromotionCriteria"
}
]
}
],
"priority" : 1
"@type": "PromotionPattern"
}
],
"description": "TMF671Promo",
"id": "TMF671PostRequest2",
"href": "/connect/comms/promotionmanagement/v5/promotion/TMF671PostRequest2"
}
]
```
### GET List with Filtering
Consider you want to retrieve all the promotions present in the system with applied filter values.
#### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v63.0/connect/comms/promotionManagement/v4/promotion?name=CustomButtonsStep`
#### Sample Response
```
status : 200
[
{
"lifecycleStatus": false,
"validFor": {
"startDateTime": "Sun Nov 10 04:54:00 GMT 2024",
"endDateTime": "null"
},
"@type": "Promotion",
"lastUpdate": "Fri Nov 08 04:59:52 GMT 2024",
"name": "CustomButtonsStep",
"pattern": [
{
"id": "TMF",
"name": "runtime_industries_ups__Build_Your_Own_Promotion_TMF",
"action": [
{
"id": "AmountOff",
"actionType": "10",
"actionValue": "20",
"@type": "PromotionAction"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "productId",
"criteriaValue": "abc",
"@type": "PromotionCriteria"
}
]
}
],
"priority" : 8
"@type": "PromotionPattern"
}
],
"id": "TMF671PostRequest10",
"href": "/connect/comms/promotionmanagement/v5/promotion/TMF671PostRequest10"
}
]
```
### GET List by limit and offset
Consider you want to
- Retrieve a list of promotions
- Limit the number of promotions to a maximum of specified limit
- Start the results display from page specified by offset
#### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v63.0/connect/comms/promotionManagement/v4/promotion?offset=2&pageLimit=2&pageinfo=true`
**NOTE:** If there are multiple quotes, the above pagination query - limit=2&offset=70 will start display from page 70 and will have 2 records.
#### Sample Response
```
{
"currentPage": 2,
"totalPageSize" : 5,
"recordList" : [
{
"lifecycleStatus": false,
"validFor": {
"startDateTime": "Fri Jan 10 00:00:00 GMT 2025",
"endDateTime": "null"
},
"@type": "Promotion",
"lastUpdate": "Fri Nov 08 03:48:44 GMT 2024",
"name": "TMF671Testing2",
"pattern": [
{
"id": "Request102",
"name": "runtime_industries_ups__Build_Your_Own_Promotion_Request102",
"action": [
{
"id": "VoucherName",
"actionType": "7",
"actionValue": "2Xaxx0000000001CAA",
"@type": "PromotionAction"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "voucherCode",
"criteriaValue": "XYZ",
"@type": "PromotionCriteria"
}
]
}
],
"@type": "PromotionPattern"
"priority" : 1
}
],
"description": "TMF671Testing2",
"id": "TMF671Testing2",
"href": "/connect/comms/promotionmanagement/v5/promotion/TMF671Testing2"
},
{
"lifecycleStatus": false,
"validFor": {
"startDateTime": "Fri Jan 10 00:00:00 GMT 2025",
"endDateTime": "null"
},
"@type": "Promotion",
"lastUpdate": "Fri Nov 08 04:20:23 GMT 2024",
"name": "TMF671PostRequest2",
"pattern": [
{
"id": "Request2",
"name": "runtime_industries_ups__Build_Your_Own_Promotion_Request2",
"action": [
{
"id": "PercentageOff",
"actionType": "8",
"actionValue": "4",
"@type": "PromotionAction"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "voucherCode",
"criteriaValue": "XYZ",
"@type": "PromotionCriteria"
}
]
}
],
"@type": "PromotionPattern",
"priority" : 5
}
],
"description": "TMF671Promo",
"id": "TMF671PostRequest2",
"href": "/connect/comms/promotionmanagement/v5/promotion/TMF671PostRequest2"
}
]
}
```
### POST
Consider you want to create a new promotion with full payload.
#### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v63.0/connect/comms/promotionManagement/v4/promotion`
#### Sample Request 1 ActionId: VoucherName
```
{
"id": "TMF671PostRequest1",
"name": "TMF671PostRequest1",
"description": "TMF671Promo",
"validFor": {
"startDateTime": "1/10/2025"
},
"pattern": [
{
"id": "Vaibhav",
"name": "Request1",
"priority": 24,
"action": [
{
"id": "VoucherName",
"actionType": "7",
"actionValue": "2Xaxx0000000001CAA"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "voucherCode",
"criteriaValue": "XYZ"
}
]
}
]
}
]
}
```
#### Sample Response
```
status 201
{
"id": "TMF671PostRequest1",
"href": "/connect/comms/promotionmanagement/v5/promotion/TMF671PostRequest1",
"name": "TMF671PostRequest1",
"description": "TMF671Promo",
"lifecycleStatus": false,
"lastUpdate": "Fri Nov 08 04:19:11 GMT 2024",
"validFor": {
"startDateTime": "Fri Jan 10 00:00:00 GMT 2025",
"endDateTime": "null"
},
"pattern": [
{
"id": "Pattern1",
"name": "runtime_industries_ups__Build_Your_Own_Promotion_Request1",
"action": [
{
"id": "VoucherName",
"actionType": "7",
"actionValue": "2Xaxx0000000001CAA",
"@type": "PromotionAction"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "voucherCode",
"criteriaValue": "XYZ",
"@type": "PromotionCriteria"
}
]
}
],
"@type": "PromotionPattern"
}
],
"@type": "Promotion"
}
```
#### Sample Request 2 actionId: PercentageOff
```
{
"id": "TMF671PostRequest2",
"name": "TMF671PostRequest2",
"description": "TMF671Promo",
"validFor": {
"startDateTime": "1/10/2025"
},
"pattern": [
{
"id": "Pattern1",
"name": "Request2",
"priority": 25,
"action": [
{
"id": "PercentageOff",
"actionType": "8",
"actionValue": "4"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "voucherCode",
"criteriaValue": "XYZ"
}
]
}
]
}
]
}
```
#### Sample Response
```
status 201
{
"id": "TMF671PostRequest2",
"href": "/connect/comms/promotionmanagement/v5/promotion/TMF671PostRequest2",
"name": "TMF671PostRequest2",
"description": "TMF671Promo",
"lifecycleStatus": false,
"lastUpdate": "Fri Nov 08 04:20:23 GMT 2024",
"validFor": {
"startDateTime": "Fri Jan 10 00:00:00 GMT 2025",
"endDateTime": "null"
},
"pattern": [
{
"id": "Pattern1",
"name": "runtime_industries_ups__Build_Your_Own_Promotion_Request2",
"action": [
{
"id": "PercentageOff",
"actionType": "8",
"actionValue": "4",
"@type": "PromotionAction"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "voucherCode",
"criteriaValue": "XYZ",
"@type": "PromotionCriteria"
}
]
}
],
"@type": "PromotionPattern"
}
],
"@type": "Promotion"
}
```
#### Sample Request 3 AccountId: AmountOff
```
{
"id": "TMF671PostRequest2",
"name": "TMF671PostRequest2",
"description": "TMF671Promo",
"validFor": {
"startDateTime": "1/10/2025"
},
"pattern": [
{
"id": "Pattern1",
"name": "Request2",
"priority": 25,
"action": [
{
"id": "PercentageOff",
"actionType": "8",
"actionValue": "4"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "voucherCode",
"criteriaValue": "XYZ"
}
]
}
]
}
]
}
```
#### Sample Response
```
status 201
{
"id": "TMF671PostRequest2",
"href": "/connect/comms/promotionmanagement/v5/promotion/TMF671PostRequest2",
"name": "TMF671PostRequest2",
"description": "TMF671Promo",
"lifecycleStatus": false,
"lastUpdate": "Fri Nov 08 04:20:23 GMT 2024",
"validFor": {
"startDateTime": "Fri Jan 10 00:00:00 GMT 2025",
"endDateTime": "null"
},
"pattern": [
{
"id": "Pattern1",
"name": "runtime_industries_ups__Build_Your_Own_Promotion_Request2",
"action": [
{
"id": "PercentageOff",
"actionType": "8",
"actionValue": "4",
"@type": "PromotionAction"
}
],
"criteriaGroup": [
{
"id": "1",
"criteriaLogicalRelationship": "1",
"groupName": "NewCriteria",
"criteria": [
{
"id": "1",
"criteriaOperator": "Equals",
"criteriaParameter": "voucherCode",
"criteriaValue": "XYZ",
"@type": "PromotionCriteria"
}
]
}
],
"@type": "PromotionPattern"
}
],
"@type": "Promotion"
}
```