You can use this API to retrieve the incentives that your users want to apply automatically or manually to the products in their shopping cart or a particular bundle.

APISignature
getIncentivesForCart

webService static Apttus_CPQApi.CPQ.GetIncentivesForCartResponseDO getIncentivesForCart(Apttus_CPQApi.CPQ.GetIncentivesForCartRequestDO request)


Parameters
NameTypeDescription
requestApttus_CPQApi.CPQ.GetIncentivesForCartRequestDOThe request data object.
Request Data Object - Apttus_CPQApi.CPQ.GetIncentivesForCartRequestDO
BundleLineItemIdIdThe Id of the bundle on which promotions are to be applied.
CartIDIDThe Id of the cart, containing products on which the promotions are to be applied.
InclCouponsBooleanIndicates whether the coupons are included in the response.
Response Data Object - Apttus_CPQApi.CPQ.GetIncentivesForCartResponseDO
FieldTypeDescription
AppliedIncentivesList <AppliedIncentives>A list of incentives applied on the given bundle line item.
IncentiveCouponsList <IncentiveCoupons>A list of coupons available on the bundle line item.
IncentiveItemsList <IncentiveItems>A list of incentives by line item.
Incentives

List<Incentives>

A list of incentives available for the line item.
getAppliedIncentivesByItem()MapA list of incentives applied on a line item.
getCouponsByIncentive()MapA list of coupons in an incentive.
getIncentivesByItem()MapA list of incentives available for a line item.
Data Object - Apttus_Config2__Incentive__c
FieldTypeDescription
AccountScopeOperPicklistConsists of options such as Include and Exclude. These allow you to define a promotion by choosing to include or exclude an account.
AccountScopeLook upEnables you to define promotions for a particular Account. While defining a promotion, you can choose to include or exclude the Account based on which the promotion is applied.
AccountTypeScopeOperPicklistConsists of options such as Include and Exclude. These allow you to define a promotion by choosing to include or exclude an account type.
AccountTypeScopeLook upEnables you to define promotions for a particular Account type. While defining a promotion, you can choose to include or exclude the Account Type based on which the promotion is applied.
ActiveBooleanCan be set to Yes or No. Set it to Yes when you want a promotion to be applied and active for the criteria you specify. The Active flag on the promotions will be set using a workflow linked to approvals similar to what you would do for any other custom object approval. For example, you  can write a workflow rule to set the active status to true after the promotion is Approved (if approval is setup). Approvals set up would be similar to custom object approvals for any object.
ActiveBooleanCan be set to Yes or No. Set it to Yes when you want a promotion to be applied and active for the criteria you specify. The Active flag on the promotions will be set using a workflow linked to approvals similar to what you would do for any other custom object approval. For example, you  can write a workflow rule to set the active status to true after the promotion is Approved (if approval is setup). Approvals set up would be similar to custom object approvals for any object.
AutoApplyBooleanCan be set to Yes or No. Set it to Yes when you want a promotion to be automatically applied when a promotion criteria is fulfilled. Set it to No when you want the user to manually enter an Incentive Code to apply promotions.
CountryScopeOperPicklistConsists of options such as Include and Exclude. These allow you to control if you want to include or exclude a country for a particular promotion.
CountryScopeLook upEnables you to define promotions for a particular country. While defining a promotion you can choose to include or exclude a country. The country picklist must be defined for the Account object.
EffectiveDateDateStart Date from which the promotion is applicable.
ExpirationDateDateDate on which the promotion expires. It can be blank. It needs to be greater than the Start Date.
IncentiveCodeStringThis is the code that is used for applying the incentive. This code is captured on the order or proposal line items when an incentive is applied to the line item. By default, this value is set to Incentive Number, but is editable. The marketing team can also use this for marketing campaigns. When a promotion is not auto- applied, (that is, when the Auto Apply ? check box is deselected), the user can use the incentive code to avail a promotional offer.
IncentiveNumberAuto NumberSystem generated unique number for the Incentive. This differs from the Salesforce record id. When an active incentive is changed over time, the Incentive number remains same.
NameStringUser-specific name for the Incentive. This promotion name is displayed to the user wherever the Incentive information is displayed. For example, whenever a user looks-up the promotion information applicable to a specific product, the promotion name you provide here is displayed.
PriceListScopeOperPicklistBased on the selected Price List, you can control whether to include or exclude that particular price list and its products.
PriceListScopeLook upConsists of the price list for which you have defined promotions.
ProductFamilyScopeLook upConsists of a product family for which you have defined promotions.
ProductFamilyScopeOperPicklistBased on the selected Product Family, you can control whether to include or exclude that particular product family.
ProductScopeOperPicklistBased on the selected Product, you can control whether to include or exclude that product.
ProductScopeLook upConsists of the products for which you have defined promotions.
RegionScopeOperPicklistConsists of options such as Include and Exclude. These allow you to control if you want to include or exclude a region for a particular promotion.
RegionScopeLook upEnables you to define promotions for a particular region. While defining a promotion, you can choose to include or exclude a region. You must define the region picklist for the Account object.
UseTypePicklistThis picklist indicates whether the incentive is of type Promotion or Rebate. In our case, select Promotion.
SequenceNumberDefines the sequence in which incentives are applied, when there are more than one incentives.
StatusPicklistSpecifies the status of the Promotion, which is dependent on the promotion life cycle. After a promotion is approved, you can set the status of the approval as active.

Approvals on Promotions: Admins can set up approval processes and other workflows on promotions. Marketing managers can send promotions for approval and approvers can view the promotion, approve or reject the promotions with or without comments, and activate it.

StopProcessingMoreIncentivesBooleanIndicates if CPQ need not process other incentives if there are multiple incentives applicable at the same time.


Code Sample

This code sample enables you to retrieve incentives and coupons available in cart or a line item. You can also retrieve incentives that are applied on the cart or a line item.

// get incentive for cart
Apttus_CPQApi.CPQ.GetIncentivesForCartRequestDO request = new Apttus_CPQApi.CPQ.GetIncentivesForCartRequestDO();
request.CartId = configSO.Id; 
request.BundleLineItemId = bdlLineItemSO.Id;
request.InclCoupons = true;
Apttus_CPQApi.CPQ.GetIncentivesForCartResponseDO result2 = Apttus_CPQApi.CPQWebService.getIncentivesForCart(request); 

// incentives by item
Map<ID, List<Apttus_Config2_Incentive_c>> incentivesByItem = result2.getIncentivesByItem();
// applied incentives by item

Map<ID, List<Apttus_Config2_AdjustmentLineItem_c>> appliedIncentivesByItem = result2.getAppliedIncentivesByItem();
// incentive coupons by incentive

Map<ID, List<Apttus_Config2_IncentiveCoupon_c>> couponsByIncentive = result2.getCouponsByIncentive();
CODE

Integration Details

Use the following information in your integrations with CPQ Web Services API. Refer to Integrating Conga with External Systems for information on how to get started.

Response/Request XML

Example Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cpq="http://soap.sforce.com/schemas/class/Apttus_CPQApi/CPQWebService" xmlns:cpq1="http://soap.sforce.com/schemas/class/Apttus_CPQApi/CPQ">
   <soapenv:Header>
      <cpq:SessionHeader>
         <cpq:sessionId>00DZ000000NAEIA!ASAAQFRdZcUFQ8LrHGF_qYNN9deP0ee.07JRqgeS3IF8IIlzILBdAOPySGSkif1VBtALP6pryVNOXfhn0faHOpGsc9GFVLl0</cpq:sessionId>
      </cpq:SessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <cpq:getIncentivesForCart>
         <cpq:request>
            <cpq1:CartId>a1OZ0000002YdG6</cpq1:CartId>
			<cpq1:InclCoupons>true</cpq1:InclCoupons>
         </cpq:request>
      </cpq:getIncentivesForCart>
   </soapenv:Body>
</soapenv:Envelope>
XML

Example Response

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns="http://soap.sforce.com/schemas/class/Apttus_CPQApi/CPQWebService"
    xmlns:GetIncentivesForCartResponseDO="http://soap.sforce.com/schemas/class/Apttus_CPQApi/CPQ"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <getIncentivesForCartResponse>
            <result>
                <GetIncentivesForCartResponseDO:Incentives xsi:type="Apttus_Config2__Incentive__c">
                    <Id>a4O0v0000005FtMEAU</Id>
                    <Apttus_Config2__AccountScopeOper__c>in</Apttus_Config2__AccountScopeOper__c>
                    <Apttus_Config2__AccountScope__c>All</Apttus_Config2__AccountScope__c>
                    <Apttus_Config2__AccountTypeScopeOper__c>in</Apttus_Config2__AccountTypeScopeOper__c>
                    <Apttus_Config2__AccountTypeScope__c>All</Apttus_Config2__AccountTypeScope__c>
                    <Apttus_Config2__Active__c>true</Apttus_Config2__Active__c>
                    <Apttus_Config2__ApplicationMethod__c>Buy X Get X</Apttus_Config2__ApplicationMethod__c>
                    <Apttus_Config2__AutoApply__c>false</Apttus_Config2__AutoApply__c>
                    <Apttus_Config2__ContextType__c>Line Item</Apttus_Config2__ContextType__c>
                    <Apttus_Config2__CountryScopeOper__c>in</Apttus_Config2__CountryScopeOper__c>
                    <Apttus_Config2__CountryScope__c>All</Apttus_Config2__CountryScope__c>
                    <Apttus_Config2__EffectiveDate__c>2018-10-15</Apttus_Config2__EffectiveDate__c>
                    <Apttus_Config2__ExpirationDate__c>2025-10-31</Apttus_Config2__ExpirationDate__c>
                    <Apttus_Config2__IncentiveCode__c>ICT-002510</Apttus_Config2__IncentiveCode__c>
                    <Apttus_Config2__IncentiveNumber__c>ICT-002510.0</Apttus_Config2__IncentiveNumber__c>
                    <Apttus_Config2__PriceListScopeOper__c>in</Apttus_Config2__PriceListScopeOper__c>
                    <Apttus_Config2__PriceListScope__c>All</Apttus_Config2__PriceListScope__c>
                    <Apttus_Config2__ProductFamilyScopeOper__c>in</Apttus_Config2__ProductFamilyScopeOper__c>
                    <Apttus_Config2__ProductFamilyScope__c>All</Apttus_Config2__ProductFamilyScope__c>
                    <Apttus_Config2__ProductScopeOper__c>in</Apttus_Config2__ProductScopeOper__c>
                    <Apttus_Config2__ProductScope__c>All</Apttus_Config2__ProductScope__c>
                    <Apttus_Config2__RegionScopeOper__c>in</Apttus_Config2__RegionScopeOper__c>
                    <Apttus_Config2__RegionScope__c>All</Apttus_Config2__RegionScope__c>
                    <Apttus_Config2__Sequence__c>1</Apttus_Config2__Sequence__c>
                    <Apttus_Config2__Status__c>Draft</Apttus_Config2__Status__c>
                    <Apttus_Config2__StopProcessingMoreIncentives__c>true</Apttus_Config2__StopProcessingMoreIncentives__c>
                    <Apttus_Config2__SubUseType__c>Promotion</Apttus_Config2__SubUseType__c>
                    <Apttus_Config2__UseType__c>Promotion</Apttus_Config2__UseType__c>
                    <Name>002I-Auto Single Rate Type Promotion</Name>
                </GetIncentivesForCartResponseDO:Incentives>
                <GetIncentivesForCartResponseDO:Incentives xsi:type="Apttus_Config2__Incentive__c">
                    <Id>a4O0v0000005FtHEAU</Id>
                    <Apttus_Config2__AccountScopeOper__c>in</Apttus_Config2__AccountScopeOper__c>
                    <Apttus_Config2__AccountScope__c>All</Apttus_Config2__AccountScope__c>
                    <Apttus_Config2__AccountTypeScopeOper__c>in</Apttus_Config2__AccountTypeScopeOper__c>
                    <Apttus_Config2__AccountTypeScope__c>All</Apttus_Config2__AccountTypeScope__c>
                    <Apttus_Config2__Active__c>true</Apttus_Config2__Active__c>
                    <Apttus_Config2__ApplicationMethod__c>Buy X Get X</Apttus_Config2__ApplicationMethod__c>
                    <Apttus_Config2__AutoApply__c>false</Apttus_Config2__AutoApply__c>
                    <Apttus_Config2__ContextType__c>Line Item</Apttus_Config2__ContextType__c>
                    <Apttus_Config2__CountryScopeOper__c>in</Apttus_Config2__CountryScopeOper__c>
                    <Apttus_Config2__CountryScope__c>All</Apttus_Config2__CountryScope__c>
                    <Apttus_Config2__EffectiveDate__c>2018-10-14</Apttus_Config2__EffectiveDate__c>
                    <Apttus_Config2__ExpirationDate__c>2024-10-18</Apttus_Config2__ExpirationDate__c>
                    <Apttus_Config2__IncentiveCode__c>ICT-002509</Apttus_Config2__IncentiveCode__c>
                    <Apttus_Config2__IncentiveNumber__c>ICT-002509.0</Apttus_Config2__IncentiveNumber__c>
                    <Apttus_Config2__PriceListScopeOper__c>in</Apttus_Config2__PriceListScopeOper__c>
                    <Apttus_Config2__PriceListScope__c>All</Apttus_Config2__PriceListScope__c>
                    <Apttus_Config2__ProductFamilyScopeOper__c>in</Apttus_Config2__ProductFamilyScopeOper__c>
                    <Apttus_Config2__ProductFamilyScope__c>All</Apttus_Config2__ProductFamilyScope__c>
                    <Apttus_Config2__ProductScopeOper__c>in</Apttus_Config2__ProductScopeOper__c>
                    <Apttus_Config2__ProductScope__c>All</Apttus_Config2__ProductScope__c>
                    <Apttus_Config2__RegionScopeOper__c>in</Apttus_Config2__RegionScopeOper__c>
                    <Apttus_Config2__RegionScope__c>All</Apttus_Config2__RegionScope__c>
                    <Apttus_Config2__Sequence__c>1</Apttus_Config2__Sequence__c>
                    <Apttus_Config2__Status__c>Draft</Apttus_Config2__Status__c>
                    <Apttus_Config2__StopProcessingMoreIncentives__c>true</Apttus_Config2__StopProcessingMoreIncentives__c>
                    <Apttus_Config2__SubUseType__c>Promotion</Apttus_Config2__SubUseType__c>
                    <Apttus_Config2__UseType__c>Promotion</Apttus_Config2__UseType__c>
                    <Name>002H-Auto Single Rate Type Promotion</Name>
                </GetIncentivesForCartResponseDO:Incentives>
            </result>
        </getIncentivesForCartResponse>
    </soapenv:Body>
</soapenv:Envelope>
XML