Commitments API - Documentation

Owned by Former user (Deleted)
Last updated: 2021-09-10 by Nicole Jünger
11 min read

 

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

  • ADvendio__Media_Campaign__c: ADvendio__SelectedCommitment__c record

  • ADvendio__Ad_Price__c

  • (for advanced mode) ADvendio__from_Date__c

  • (for advanced mode) ADvendio__until_Date__c

  • ADvendio__Media_Campaign__r.ADvendio__Commitment__c,ADvendio__AgencyEarningCommitment__c,ADvendio__ThirdPartyCommitment__c or ADvendio__Media_Campaign__c

  • ADvendio__Ad_Price__c

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

  • Quantity__c

  • Rate_Discount_4__c

  • Rate_Discount_4_Name__c

  • CommitmentRelevant__c

  • ConditionApplied__c

  • Quantity__c

  • Rate_Discount_4__c

  • Rate_Discount_4_Name__c

  • CommitmentRelevant__c

  • ConditionApplied__c

Special Discount

  • Rate_Discount_4__c

  • Rate_Discount_4_Name__c

  • ConditionApplied__c

  • ADvendio__AppliedCommitmentCondition__c

  • Rate_Discount_4__c

  • Rate_Discount_4_Name__c

  • SpecialDiscountCondition__c (deprecated)

  • SpecialDiscountCondition__r (deprecated)

  • ConditionApplied__c

Scaled Discount

  • Rate_Discount_4__c

  • Rate_Discount_4_Name__c

  • Rate_Discount_3_custom__c

  • Rate_Discount_2_custom__c

  • ConditionApplied__c

  • ADvendio__AppliedCommitmentCondition__c

  • Rate_Discount_4__c

  • Rate_Discount_3_custom__c

  • Rate_Discount_2_custom__c

  • SpecialDiscountCondition__c (deprecated)

  • Rate_Discount_4_Name__c

  • ScaledDiscountCondition__c (deprecated)

  • ScaledDiscountCondition__r (deprecated)

  • ConditionApplied__c

AgencyEarnings

  • ADvendio__AgencyEarnings__c

  • ADvendio__AppliedCommitmentCondition__c

  • ADvendio__AgencyEarnings__c

  • ADvendio__AgencyEarningsCondition__c (deprecated)

  • ADvendio__AgencyEarningsCondition__r (deprecated)

Third Party Discount

  • ThirdPartyCommissionCustom__c

  • ConditionApplied__c

  • ADvendio__AppliedCommitmentCondition__c

  • ThirdPartyCommissionCustom__c

  • TPCCondition__c (deprecated)

  • TPCCondition__r (deprecated)

  • ConditionApplied__c

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