--- schema_version: "1" id: 011b68911b2ea16d3e0a85d9173cecb9ab60b71b1b73b7fd97fa204512937f8b title: TMF671 v4 Promotion Management collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/industries-integrations/comms/references/generated-api-specs/tmf671v4.md canonical_url: https://developer.salesforce.com/docs/industries/communications/references/tmf671v4 source_site: developer.salesforce.com content_type: documentation content_hash: 2ba449f99fbdcd5a4eace820bfac608019c487a37670915938dfca676f661666 products: - Communications Cloud TM Forum API - Industries Integrations --- TMF671 v4 Promotion Management # TMF671 v4 Promotion Management The Promotion Management API enables the configuration and management of promotions, including discounts, vouchers, bonuses, or gifts, for customers who meet specific eligibility criteria. It supports setup and maintenance of promotional rules and details, while the application of these promotions is handled by the enterprise platform. This API empowers businesses to drive sales through targeted promotional offers as part of larger campaigns or specific sales strategies. **Version:** v1. Protocols: https. ## Operations ### GET List Promotions `GET /promotion` Retrieves a list of Promotion entities. Attribute selection is enabled for first-level attributes and filtering is supported for name. #### Parameters * `fields` (query, string) fields for attribute selection. * `name` (query, string) Name of the promotion * `offset` (query, integer) Specifies the requested index for the start of the resources to be included in the response. * `pageLimit` (query, integer) Specifies the requested number of the resources to be included in the response. * `pageInfo` (query, boolean) Enables customer to get pageinformation with GET response. * `Authorization` (header, string, required) Specifies the bearer token to use for the authentication of request. * `Domain-Name` (header, string, required) Specifies the domain name to use with the URL path received from the userinfo API. * `Version` (header, string, required) Specifies the version to use with the URL path. #### Responses * **200** successfully retrieved the promotion list Media type: `application/json`. Schema: `array of promotion`. Array of `promotion`. * **404** Resource not found. Media type: `application/json`. Schema: `Error`. _Example_ ``` code: NOT_FOUND reason: There are no matching resource. ``` * **500** Internal server error Media type: `application/json`. Schema: `Error`. _Example_ ``` code: "500" reason: Internal server error ``` ### POST Create Promotion `POST /promotion` Creates a Promotion entity. #### Parameters * `Authorization` (header, string, required) Specifies the bearer token to use for the authentication of request. * `Domain-Name` (header, string, required) Specifies the domain name to use with the URL path received from the userinfo API. * `Version` (header, string, required) Specifies the version to use with the URL path. #### Request body Media type: `application/json`. Schema: `promotion_create`. Specifies the Promotion to be created. _Example_ ``` { "id": "TMF671PostRequest124", "name": "TMF671Promo", "description": "TMF671Promo", "validFor": { "startDateTime": "Tue Nov 12 05:17:00 GMT 2024" }, "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" } ] } ] } ] } ``` #### Responses * **201** Created the Promotion resource. Media type: `application/json`. Schema: `promotion`. _Example_ ``` { "id": "TMF671PostRequest124", "href": "/connect/comms/promotionmanagement/v5/promotion/TMF671PostRequest124", "name": "TMF671Promo", "description": "TMF671Promo", "lifecycleStatus": false, "lastUpdate": "Tue Nov 12 05:17:00 GMT 2024", "validFor": { "startDateTime": "Tue Nov 12 05:17:00 GMT 2024", "endDateTime": "null" }, "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" } ], "@type": "Promotion" } ``` * **400** There was an issue with your request. Media type: `application/json`. Schema: `Error`. _Example_ ``` code: "400" reason: Specify the required parameter in the payload- required item(s) missing. ``` * **404** Resource not found. Media type: `application/json`. Schema: `Error`. _Example_ ``` code: "404" reason: We couldn't find the Account in your salesforce org. ``` * **500** Internal server error Media type: `application/json`. Schema: `Error`. _Example_ ``` code: "500" reason: Internal server error ``` ### GET Get Promotion by ID `GET /promotion/{id}` Retrieves a Promotion entity. #### Parameters * `id` (path, string, required) * `Authorization` (header, string, required) Specifies the bearer token to use for the authentication of request. * `Domain-Name` (header, string, required) Specifies the domain name to use with the URL path received from the userinfo API. * `Version` (header, string, required) Specifies the version to use with the URL path. #### Responses * **200** successfully retrieved the promotion Media type: `application/json`. Schema: `promotion`. _Example: same as POST /promotion 201 response._ * **404** Resource not found. Media type: `application/json`. Schema: `Error`. _Example_ ``` code: NOT_FOUND reason: There are no matching resource. ``` * **500** Internal server error Media type: `application/json`. Schema: `Error`. _Example_ ``` code: "500" reason: Internal server error ``` ## Schemas ### promotion * `id` (_string_, required) Unique identifier of promotion. * `description` (_string_) Details about the purpose of this promotion. * `lastUpdate` (_string_) Latest update date of promotion. * `lifecycleStatus` (_boolean_) Value of promotion status. * `name` (_string_, required) Name of promotion. * `promotionType` (_string_) Type of promotion. The basic type are :1. Award - Gift or free unit is given to the party. 2. Discount - Deduct from an account, debt or charge. 3. Reduction - Bring down the quantity or value or something. However, other types of promotion can be used. * `validFor` (_object_, required) The period for which the promotion is valid. Includes all fields of `validForRef`. * `href` (_string_, required) Hyperlink reference to the promotion * `pattern` (_array of object_) list of patterns Includes all fields of `patternRef`. ### Error Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx) * `code` (_string_, required) Application relevant detail, defined in the API or a common list. * `reason` (_string_, required) Explanation of the reason for the error which can be shown to a client user. ### promotion\_create * `id` (_string_, required) Unique identifier of promotion. * `description` (_string_) Details about the purpose of this promotion. * `lifecycleStatus` (_boolean_) Value of promotion status. * `name` (_string_, required) Name of promotion. * `promotionType` (_string_) Type of promotion. The basic type are 1. Award - Gift or free unit is given to the party. 2. Discount - Deduct from an account, debt or charge. 3. Reduction - Bring down the quantity or value or something. However, other types of promotion can be used. * `validFor` (_object_, required) The period for which the promotion is valid. Includes all fields of `validForRef`. * `pattern` (_array of object_) list of patterns Includes all fields of `patternRef`. ### validForRef * `startDateTime` (_string_, required) The time from which the promotion is valid. * `endDateTime` (_string_) The time for which the promotion is valid. ### patternRef * `@type` (_string_) The class type of the actual resource (for type extension). * `action` (_array of object_, required) A list of promotion actions (PromotionAction \[1..\*\]). Action of the promotion. When the customer meets the conditions in the promotion pattern, the customer can be given the benefits in the action. Includes all fields of `promotionActionRef`. * `criteriaGroup` (_array of object_, required) A list of promotion criteria groups (PromotionCriteriaGroup \[1..\*\]). Set of group criteria to promotion. Fulfilling these criteria, parties will receive benefits. Includes all fields of `promotionCriteriaGroupRef`. * `id` (_string_) Unique identifier of promotion pattern. * `name` (_string_) Name of the pattern / rule * `priority` (_number_) Priority of the pattern ### promotionActionRef * `@type` (_string_) The class type of the actual resource (for type extension). * `actionEntityRef` (_object_) An entity reference (EntityRef). It refers to the entity that is impacted by the promotion action. • When the Promotion type is Award, the actionEntityRef is the party account; • When the Promotion type is Discount, it is the product offering; • When the Promotion type is Reduction, it is the product offering also. Includes all fields of `promotionActionEntityRef`. * `actionType` (_string_, required) it is an action type, If the type is "IssueVoucher" then actionType will be 7 and if the type is "ProvideDiscount" then we will check discountType field under rewardDetails , if it is "PercentageOff" the the actionType will be 8, else if it is "AmountOff" then the actionType will be 10 * `actionValue` (_string_, required) When the Promotion type is Award, it means the amount or value of the awards decided by actionType; • When the Promotion type is Discount, it means the value of the discount; • When the Promotion type is Reduction, it means the value of the reduced money. * `id` (_string_) unique identifier ### promotionCriteriaGroupRef * `@type` (_string_) The class type of the actual resource (for type extension). * `criteria` (_array of object_, required) A list of promotion criteria (PromotionCriteria \[1..\*\]). Set of criteria to be followed by all parties. Includes all fields of `promotionCriteriaRef`. * `criteriaLogicalRelationship` (_string_) Logical relation followed by all criteria (Default value "And"). * `groupName` (_string_) Name of the group to be easily identified. * `id` (_string_) Unique Identifier(Sequence Number). ### promotionActionEntityRef * `@type` (_string_) When sub-classing, this defines the sub-class Extensible name. * `href` (_string_) An uri (Uri). Hyperlink reference * `name` (_string_, required) Name of the related entity. * `id` (_string_) unique identifier ### promotionCriteriaRef * `@type` (_string_) The class type of the actual resource (for type extension). * `criteriaOperator` (_string_) Logic operator of this criteria instruction :'=' or '>' or '<' or '>=' or '<=' or '<>'. or 'In' or 'Not In' * `criteriaParameter` (_string_) The parameter (factor) of the criteria. The basic factors are abstracted from these data sources. And there are several detail parameters. * `criteriaValue` (_string_) The value is filled for the comparison of the criteria. * `id` (_string_) unique identifier (sequence Number)