Retrieving Incentives on the Cart

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.

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

Parameters
Name	Type	Description
request	Apttus_CPQApi.CPQ.GetIncentivesForCartRequestDO	The request data object.

Request Data Object - Apttus_CPQApi.CPQ.GetIncentivesForCartRequestDO
BundleLineItemId	Id	The Id of the bundle on which promotions are to be applied.
CartID	ID	The Id of the cart, containing products on which the promotions are to be applied.
InclCoupons	Boolean	Indicates whether the coupons are included in the response.

Response Data Object - Apttus_CPQApi.CPQ.GetIncentivesForCartResponseDO
Field	Type	Description
AppliedIncentives	List <AppliedIncentives>	A list of incentives applied on the given bundle line item.
IncentiveCoupons	List <IncentiveCoupons>	A list of coupons available on the bundle line item.
IncentiveItems	List <IncentiveItems>	A list of incentives by line item.
Incentives	List<Incentives>	A list of incentives available for the line item.
getAppliedIncentivesByItem()	Map	A list of incentives applied on a line item.
getCouponsByIncentive()	Map	A list of coupons in an incentive.
getIncentivesByItem()	Map	A list of incentives available for a line item.

Data Object - Apttus_Config2__Incentive__c
Field	Type	Description
AccountScopeOper	Picklist	Consists of options such as Include and Exclude. These allow you to define a promotion by choosing to include or exclude an account.
AccountScope	Look up	Enables 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.
AccountTypeScopeOper	Picklist	Consists of options such as Include and Exclude. These allow you to define a promotion by choosing to include or exclude an account type.
AccountTypeScope	Look up	Enables 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.
Active	Boolean	Can 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.
Active	Boolean	Can 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.
AutoApply	Boolean	Can 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.
CountryScopeOper	Picklist	Consists 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.
CountryScope	Look up	Enables 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.
EffectiveDate	Date	Start Date from which the promotion is applicable.
ExpirationDate	Date	Date on which the promotion expires. It can be blank. It needs to be greater than the Start Date.
IncentiveCode	String	This 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.
IncentiveNumber	Auto Number	System 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.
Name	String	User-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.
PriceListScopeOper	Picklist	Based on the selected Price List, you can control whether to include or exclude that particular price list and its products.
PriceListScope	Look up	Consists of the price list for which you have defined promotions.
ProductFamilyScope	Look up	Consists of a product family for which you have defined promotions.
ProductFamilyScopeOper	Picklist	Based on the selected Product Family, you can control whether to include or exclude that particular product family.
ProductScopeOper	Picklist	Based on the selected Product, you can control whether to include or exclude that product.
ProductScope	Look up	Consists of the products for which you have defined promotions.
RegionScopeOper	Picklist	Consists 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.
RegionScope	Look up	Enables 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.
UseType	Picklist	This picklist indicates whether the incentive is of type Promotion or Rebate. In our case, select Promotion.
Sequence	Number	Defines the sequence in which incentives are applied, when there are more than one incentives.
Status	Picklist	Specifies 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.
StopProcessingMoreIncentives	Boolean	Indicates 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