Commitments API - Documentation
- 1 1. REST web service
- 1.1 1.1. URL
- 1.2 1.2. Method
- 1.3 1.3. URL Params
- 1.4 1.4. Data Params
- 1.5 1.5. Success Response
- 1.6 1.6. Error Response
- 1.7 1.7. Logic
- 1.8 1.8. Examples
- 1.8.1 1.8.1. Get a Session-ID
- 1.8.1.1 1.8.1.1.1. Get a Session ID
- 1.8.2 1.8.2. Connected App
- 1.8.3 1.8.3. Simple request
- 1.8.4 1.8.4. Usage in Apex
- 1.8.1 1.8.1. Get a Session-ID
- 2 2. Global Apex Methods
In order to use the Commitments API, your Salesforce Org needs to have API usage activated through having an API usage License.
The Commitments API is implemented as Apex class and is exposed as REST web service by using Salesforce standard functionality (see Apex Developer Guide for more information). For general information about the dynamic pricing feature, see 4.16 Commitments. The Apply Commitments functionality finds and sets the matching conditions and applies the discounts from the matching Commitment Condition
1. REST web service
1.1. URL
https://<my-domain-name>.my.salesforce.com/services/apexrest/ADvendio/ADvendio__Campaign_Item__c/ApplyCommitments/
1.2. Method
PATCH
1.3. URL Params
1.4. Data Params
A JSON object with the attribute campaignItems, containing a JSON serialized list of Campaign Items.
Example: { "campaignItems":[{<Campaign Item>}, ...]}
1.5. Success Response
Code: 200
Content: A JSON serialized list of the Campaign Items from the request body, but now with updated discount and Commitment Condition fields.
Example: [{<Campaign Item>}, ...]
1.6. Error Response
See Salesforce Apex REST Documentation
1.7. Logic
1.7.1. Matching logic
A Commitment Condition matches if all criteria (Commitment Condition fields) match. If the Commitment Condition field is empty, it matches all Campaign Item values.
ADvendio__CommitmentCondition__c | ADvendio__Campaign_Item__c | Matching |
|---|---|---|
ADvendio__AdvertisingMedium__c | ADvendio__Ad_price__r.ADvendio__Ad_Spec__r.ADvendio__Placement__r.ADvendio__Site__c | equals |
ADvendio__MediaDifferentiation__c | ADvendio__Ad_price__r.ADvendio__Ad_Spec__r.ADvendio__Ad_Type__r.ADvendio__MediaDifferentiation__c | equals |
ADvendio__MediaSegment__c | ADvendio__Ad_price__r.ADvendio__Ad_Spec__r.ADvendio__Placement__r.ADvendio__MediaSegment__c | equals |
ADvendio__MediaType__c | ADvendio__Ad_price__r.ADvendio__Ad_Spec__r.ADvendio__Placement__r.ADvendio__Site__r.ADvendio__MediaType__c | equals |
ADvendio__Unit__c | ADvendio__Ad_price__r.ADvendio__PriceUnit__c | equals |
ADvendio__AdPrice__c | ADvendio__Ad_price__c | equals |
ADvendio__AdSpec__c | ADvendio__Ad_price__r.ADvendio__Ad_Spec__c | equals |
ADvendio__AdType__c | ADvendio__Ad_price__r.ADvendio__Ad_Spec__r.ADvendio__Ad_Type__c | equals |
ADvendio__Placement__c | ADvendio__Ad_price__r.ADvendio__Ad_Spec__r.ADvendio__Placement__c | equals |
ADvendio__Content__c | ADvendio__SelectedContents__r | contains |
ADvendio__PageEquivalency__c | ADvendio__Ad_price__r.ADvendio__Ad_Spec__r.ADvendio__Ad_Type__r.ADvendio__PageEquivalency__c | equals |
1.7.2. Required fields/records
ADvendio version 2.140 and higher | ADvendio version 2.139 and below |
|---|---|
|
|
Fields referenced by the Ad Price (Ad Spec, Ad Type, Placement, Site ...) are automatically queried if not set.
1.7.3. Fields set/Records created by ApplyCommitments method
Depending on the linked Commitments and the matching Commitment Condition the following fields will be written and related records will be created:
| ADvendio version 2.140 and higher | ADvendio version 2.139 and below |
|---|---|---|
Rebate in Kind |
|
|
Special Discount |
|
|
Scaled Discount |
|
|
AgencyEarnings |
|
|
Third Party Discount |
|
|
1.8. Examples
1.8.1. Get a Session-ID
1.8.1.1.1. Get a Session ID
curl -v https://login.salesforce.com/services/oauth2/token -d "grant_type=password" -d "client_id=<CLIENT_ID>" -d "client_secret=<CLIENT_SECRET>" -d "username=<USER_NAME>" -d "password=<PASSWORD+TOKEN>" -H 'X-PrettyPrint:1'1.8.2. Connected App
Get CLIENT_ID and CLIENT_SECRET from any connected app or create a new app in your org: App Manager -> New Connected App
1.8.3. Simple request
| Simple Request (For Advanced Commitments Enabled and Advanced Commitments Not Enabled) | Simple request (Not Advanced Commitments): ADvendio version 2.139 and below |
|---|---|---|
| A simple request with a Commitment and Commitment Conditions matching the Campaign Item / Ad Price. Call Dynamic Pricing web service: curl <https://<my-domain-name>.my.salesforce.com/services/apexrest/ADvendio/ADvendio__Campaign_Item__c/ApplyCommitments/> -H 'Authorization: Bearer <SESSION_ID>' -H "Content-Type: application/json" -H 'X-PrettyPrint:1' -d @requestBody.txt --request PATCH | A simple request with a Commitment and Commitment Conditions matching the Campaign Item / Ad Price Call Dynamic Pricing web service: curl <https://<my-domain-name>.my.salesforce.com/services/apexrest/ADvendio/ADvendio__Campaign_Item__c/ApplyCommitments/> -H 'Authorization: Bearer <SESSION_ID>' -H "Content-Type: application/json" -H 'X-PrettyPrint:1' -d @requestBody.txt --request PATCH |
ADvendio version | 2.140 and higher | 2.139 and below |
requestBody.txt | {
"campaignItems": [
{
"ADvendio__from_Date__c": "2021-03-01",
"ADvendio__until_Date__c": "2021-03-31",
"ADvendio__Ad_Price__c": "a0Q1X000001ek13UAA",
"ADvendio__Media_Campaign__r": {
"ADvendio__SelectedCommitments__r": {
"totalSize": 1,
"done": true,
"records": [
{
"ADvendio__Commitment__c": "a0v1X0000050YiLQAU"
}
]
}
}
}
]
} | {
"campaignItems":[
{
"ADvendio__Ad_Price__c":"a0HA000000SNYF4MAP",
"ADvendio__Media_Campaign__r":{
"ADvendio__Commitment__c":"a252K000003Jf5aQAC"
}
}
]
}
|
Response | [
{
"attributes": {
"type": "ADvendio__Campaign_Item__c"
},
"ADvendio__AppliedCommitmentConditions__r": {
"totalSize": 1,
"done": true,
"records": [
{
"attributes": {
"type": "ADvendio__AppliedCommitmentCondition__c"
},
"ADvendio__CampaignItem__c": null,
"ADvendio__CommitmentCondition__c": "a0t1X000002DHhSQAW"
}
]
},
"ADvendio__from_Date__c": "2021-03-01",
"ADvendio__until_Date__c": "2021-03-31",
"ADvendio__Ad_Price__r": {
"attributes": {
"type": "ADvendio__Ad_price__c",
"url": "/services/data/v45.0/sobjects/ADvendio__Ad_price__c/a0Q1X000001ek13UAA"
},
"ADvendio__NoThirdPartyCommission__c": false,
"ADvendio__NoAgencyComission__c": false,
"ADvendio__NoCustomerDiscount__c": false,
"ADvendio__PriceUnit__c": "Page Equivalency",
"ADvendio__NoAgencyDiscount__c": false,
"ADvendio__Ad_Spec__c": "a0O1X000006H07KUAS",
"ADvendio__Ad_Spec__r": {
"attributes": {
"type": "ADvendio__Ad_Specs__c",
"url": "/services/data/v45.0/sobjects/ADvendio__Ad_Specs__c/a0O1X000006H07KUAS"
},
"ADvendio__NoThirdPartyCommission__c": false,
"ADvendio__Placement__r": {
"attributes": {
"type": "ADvendio__Placement__c",
"url": "/services/data/v45.0/sobjects/ADvendio__Placement__c/a1y1X000000f2zIQAQ"
},
"Id": "a1y1X000000f2zIQAQ",
"ADvendio__Site__c": "a2a1X000003SAz1QAG",
"ADvendio__MediaSegment__c": "Magazine",
"ADvendio__Site__r": {
"attributes": {
"type": "ADvendio__Site__c",
"url": "/services/data/v45.0/sobjects/ADvendio__Site__c/a2a1X000003SAz1QAG"
},
"ADvendio__MediaType__c": "Print",
"Id": "a2a1X000003SAz1QAG"
}
},
"ADvendio__No_Agency_Discount__c": false,
"ADvendio__NoAgencyComission__c": false,
"ADvendio__No_Customer_Discount__c": false,
"ADvendio__Placement__c": "a1y1X000000f2zIQAQ",
"RecordTypeId": "0121X000002H7PRQA0",
"ADvendio__Ad_Type__c": "a0P1X0000047XMRUA2",
"ADvendio__Ad_Type__r": {
"attributes": {
"type": "ADvendio__Ad_Type__c",
"url": "/services/data/v45.0/sobjects/ADvendio__Ad_Type__c/a0P1X0000047XMRUA2"
},
"Id": "a0P1X0000047XMRUA2"
},
"Id": "a0O1X000006H07KUAS"
},
"Id": "a0Q1X000001ek13UAA"
},
"ADvendio__Rate_Discount_4__c": 10.0,
"ADvendio__ConditionApplied__c": true,
"ADvendio__Ad_Price__c": "a0Q1X000001ek13UAA",
"ADvendio__Media_Campaign__r": {
"attributes": {
"type": "ADvendio__MediaCampaign__c"
},
"ADvendio__SelectedCommitments__r": {
"totalSize": 1,
"done": true,
"records": [
{
"attributes": {
"type": "ADvendio__SelectedCommitment__c"
},
"ADvendio__Commitment__c": "a0v1X0000050YiLQAU"
}
]
}
},
"ADvendio__Rate_Discount_4_Name__c": "Commitment"
}
]
| [
{
"attributes" : {
"type" : "ADvendio__Campaign_Item__c"
},
"ADvendio__Ad_Price__r" : {
"attributes" : {
"type" : "ADvendio__Ad_price__c",
"url" : "/services/data/v45.0/sobjects/ADvendio__Ad_price__c/a0HA000000SNYF4MAP"
},
"ADvendio__NoThirdPartyCommission__c" : false,
"ADvendio__NoCustomerDiscount__c" : false,
"ADvendio__NoAgencyDiscount__c" : false,
"ADvendio__Ad_Spec__c" : "a0FA000000LsEviMAF",
"ADvendio__Ad_Spec__r" : {
"attributes" : {
"type" : "ADvendio__Ad_Specs__c",
"url" : "/services/data/v45.0/sobjects/ADvendio__Ad_Specs__c/a0FA000000LsEviMAF"
},
"ADvendio__NoThirdPartyCommission__c" : false,
"ADvendio__No_Agency_Discount__c" : false,
"ADvendio__Placement__r" : {
"attributes" : {
"type" : "ADvendio__Placement__c",
"url" : "/services/data/v45.0/sobjects/ADvendio__Placement__c/a1MA000000BQWW1MAP"
},
"Id" : "a1MA000000BQWW1MAP",
"ADvendio__MediaSegment__c" : "InApp",
"ADvendio__Site__c" : "a1kA0000002oO2NIAU",
"ADvendio__Site__r" : {
"attributes" : {
"type" : "ADvendio__Site__c",
"url" : "/services/data/v45.0/sobjects/ADvendio__Site__c/a1kA0000002oO2NIAU"
},
"ADvendio__MediaType__c" : "TV",
"Id" : "a1kA0000002oO2NIAU"
}
},
"ADvendio__No_Customer_Discount__c" : false,
"ADvendio__Placement__c" : "a1MA000000BQWW1MAP",
"ADvendio__Ad_Type__c" : "a0GA0000016Ec4aMAC",
"Id" : "a0FA000000LsEviMAF",
"ADvendio__Ad_Type__r" : {
"attributes" : {
"type" : "ADvendio__Ad_Type__c",
"url" : "/services/data/v45.0/sobjects/ADvendio__Ad_Type__c/a0GA0000016Ec4aMAC"
},
"ADvendio__MediaDifferentiation__c" : "InStream",
"Id" : "a0GA0000016Ec4aMAC"
}
},
"Id" : "a0HA000000SNYF4MAP"
},
"ADvendio__Rate_Discount_2_custom__c" : 5.00000000000,
"ADvendio__Ad_Price__c" : "a0HA000000SNYF4MAP",
"ADvendio__ConditionApplied__c" : true,
"ADvendio__Media_Campaign__r" : {
"attributes" : {
"type" : "ADvendio__MediaCampaign__c"
},
"ADvendio__Commitment__c" : "a252K000003Jf5aQAC"
},
"ADvendio__ScaledDiscountCondition__r" : {
"attributes" : {
"type" : "ADvendio__CommitmentCondition__c",
"url" : "/services/data/v45.0/sobjects/ADvendio__CommitmentCondition__c/a222K000002Im1KQAS"
},
"Id" : "a222K000002Im1KQAS",
"Name" : "Scaled Discount Level 1",
"RecordTypeId" : "012A00000012lJfIAI",
"ADvendio__AdPrice__c" : "a0HA000000SNYF4MAP",
"ADvendio__CashDiscountAdvertiser__c" : 5.00000000000,
"ADvendio__CashDiscountAgency__c" : 5.00000000000,
"ADvendio__Commitment__c" : "a252K000003Jf5aQAC",
"ADvendio__Progressive__c" : false,
"ADvendio__RebateInKindUnitsAvailable__c" : 0.00,
"ADvendio__ScaledDiscountFrom__c" : 0.00,
"ADvendio__ScaledDiscountTo__c" : 1000.00,
"ADvendio__TotalRebateInKindUnitsEarned__c" : 0.00,
"ADvendio__TotalRevenue__c" : 902.50,
"ADvendio__TotalRevenueApplied__c" : 0.00,
"ADvendio__TotalUnitCount__c" : 1,
"ADvendio__TotalUnitCountApplied__c" : 0,
"ADvendio__PackageHeaderMatchingRelevant__c" : false
},
"ADvendio__Rate_Discount_3_custom__c" : 5.00000000000,
"ADvendio__ScaledDiscountCondition__c" : "a222K000002Im1KQAS"
}
]
|
1.8.4. Usage in Apex
List<ADvendio__Campaign_Item__c> cis = ...
cis = ADvendio.CommitmentsApplier.applyCommitments(cis);
2. Global Apex Methods
Global Apex methods for commitments are under the global Apex class CommitmentService. As mentioned in the beginning of this page, the API usage License is mandatory, otherwise an exception will be thrown.
2.1. CommitmentService Methods
2.1.1. getMatchingRebateInKindConditions
Returns the matching Rebate In Kind and Rebate In Kind Percent Commitment Condition for each provided campaign item Id. If multiple match are found for a single Campaign Item Id, the one with higher priority (Check this page about matching: https://advendio.atlassian.net/wiki/x/B4C2H) is selected and returned.
Signature
global static Map<Id,ADvendio__CommitmentCondition__c> getMatchingRebateInKindConditions(List<Id> campaignItemIds)
Parameters
campaignItemIds
List<Id>: List of ADvendio Campaign Item Ids.
Return Value
Map<Id,ADvendio__CommitmentCondition__c>
Example
List<Id> campaignItemIds = new List<Id>{'a0xFg000003REOXIA4',...,'a0xFg000003REOXI287'}; // <-- Replace with a REAL Campaign Item IDs from your org
Map<Id,ADvendio__CommitmentCondition__c> idsWithMatchingRebateInKind = ADvendio.CommitmentService.getMatchingRebateInKindConditions(campaignItemIds);2.1.2. getMatchingVariableDiscountConditions
Returns the matching Variable Discount Commitment Condition for each provided campaign item Id. If multiple match are found for a single Campaign Item Id, the one with higher priority (Check this page about matching: https://advendio.atlassian.net/wiki/x/B4C2H) is selected and returned. If a Variable Discount has a linked Shared Revenue Scale Commitment Condition, it will be included in the matching Variable Discount as a related object (ADvendio__SharedRevenue__r)
Signature
global static Map<Id,ADvendio__CommitmentCondition__c> getMatchingVariableDiscountConditions(List<Id> campaignItemIds)
Parameters
campaignItemIds
List<Id>: List of ADvendio Campaign Item Ids.
Return Value
Map<Id,ADvendio__CommitmentCondition__c>
Example
List<Id> campaignItemIds = new List<Id>{'a0xFg000003REOXIA4',...,'a0xFg000003REOXI287'}; // <-- Replace with a REAL Campaign Item IDs from your org
Map<Id,ADvendio__CommitmentCondition__c> idsWithMatchingVariableDiscount = ADvendio.CommitmentService.getMatchingVariableDiscountConditions(campaignItemIds);2.1.3. getAvailableRebateInKindConditionsForApplication
Based on an Campaign Item Id and its quantity, it returns a list of Rebate In Kind and Rebate In Kind Percent Commitment Condition records that matches (Check this page about matching: https://advendio.atlassian.net/wiki/x/B4C2H) and have available units for application based on the provided quantity.
Signature
global static List<CommitmentCondition__c> getAvailableRebateInKindConditionsForApplication(Id campaignItemId, Decimal campaignItemQuantity)
Parameters
campaignItemId
Id: Id of an ADvendio Campaign Items.campaignItemQuantity
Decimal: Quantity of Campaign Item
Return Value
List<CommitmentCondition__c>