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.

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
FieldTypeDescription
CartIDIDThe id of the cart, containing products on which the promotions are applied.
Response Data Object - Apttus_CPQApi.CPQ.GetIncentivesForCartResponseDO
FieldTypeDescription
Incentives

List<Incentives>

A list of incentives available in the cart
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

After you configure your products and update your pricing, the following code allows you to fetch the promo code, which your users can apply on the products in your shopping cart. This code snippet is for the PUSH and PULL type promotions. In the PUSH type, the promo code is automatically applied and in the PULL type, the user enters the promo code for multiple products or on the entire cart before finalizing the cart. The Incentives list collects all the promo codes applicable on your shopping cart. The condition Auto Apply__c == false further filters only those promo codes which you want the user to apply manually on the products. Each incentive record captures all the details listed in the above table.

public void getIncentivesForCart()
    {
        Map<Decimal, String> incSequencePromoCodeMap = new Map<Decimal, String>(); 
        List<Decimal> seqList = new List<Decimal>();
            
        Apttus_CPQApi.CPQ.GetIncentivesForCartRequestDO request = new Apttus_CPQApi.CPQ.GetIncentivesForCartRequestDO();
        system.debug('Cart ID: ' + cartId);
        request.CartID = cartId;
        
        Apttus_CPQApi.CPQ.GetIncentivesForCartResponseDO response = Apttus_CPQApi.CPQWebservice.getIncentivesForCart(request);
        
        String couponCodes = '';
        
        if(response.Incentives.size() > 0)
        {
            for(Apttus_Config2__Incentive__c incSO : response.Incentives)
            {
                if(incSO.Apttus_Config2__AutoApply__c == false)
                    couponCodes += incSO.Apttus_Config2__IncentiveCode__c + ',';
            }
        }
    }
CODE

Integration Details

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

Response/Request XML

Example Request (click to expand)

<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 (click to expand)

<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