Extension Point: Promotions Calculator · Extension Point Framework

Basics

Parameter	Value
Extension Point Key	`PROMOTIONS_CALCULATOR`
Extension Point Name	Promotions Calculator
Extension Interface	PromotionsCalculator
Supports Multiple Extensions?	No
Selector Type	None
Available Since	1.4.0

note

This extension point only supports a single extension, so if multiple are defined, the highest priority extension will be invoked.

Use Cases

Extensions implementing this Extension Point are responsible for evaluating promotions for product SKUs and shopping carts. They are also responsible for tracking of coupon codes.

There is an embedded extension named ElasticPathPromotionsCalculator with priority 1000 that uses the promotions configuration from the Elastic Path database for promotion evaluation. It also leverages the JBoss Drools engine that is built into the Self-Managed Commerce platform.

note

This Extension Point supports extensions that may not use promotion rules and coupons that are configured within the Commerce Manager.

Methods

`evaluate(XPFCatalogPromotionsCalculatorInputContext context)`

The evaluate(XPFCatalogPromotionsCalculatorInputContext context) method is invoked whenever Cortex needs to evaluate catalog promotions for a product SKU. The following information is contained within the context object:

productSku: The product SKU being evaluated.
store: The current store.
currency: The session currency.
customerTags: The tags that represent the shopper selling context.

The extension is responsible for returning a XPFPromotionsCalculatorOutputContext object that contains a list of XPFPromotionAction objects that represent the actions that should be executed on the product SKU to determine the promoted price.

The XPFPromotionAction#type value must map to a value in the DiscountImplementationType enum, which determines which discount implementation should be used. The XPFPromotionAction#parameters map is passed to the discount class as a constructor parameter when the class is instantiated.

`evaluate(XPFCartPromotionsCalculatorInputContext context)`

The evaluate(XPFCartPromotionsCalculatorInputContext context) method is invoked whenever Cortex needs to evaluate shopping cart promotions for a shopping cart. The following information is contained within the context object:

cart: The shopping cart being evaluated.
store: The current store.
currency: The session currency.
customerTags: The tags that represent the shopper selling context.
evaluationStage: The type of rules to evaluate; will contain one of the following values: DefaultGroup, SubtotalDependent, CartLineItemDependent. In Drools this is known as an agenda group.

Each time that shopping cart promotions need to be evaluated by Cortex, this method will be invoked three times, with a different value for the evaluationStage parameter:

CartLineItemDependent: This should return actions related to shopping cart line item promotion rules.
DefaultGroup: This should return actions related to shopping cart promotion rules. Discounts applied by the previous evaluations can affect which conditions are satisfied for these promotions.
SubtotalDependent: This should return actions related to cart subtotal promotion rules. Discounts applied by the previous evaluations can affect which conditions are satisfied for these promotions.

`retrievePromotionRules`

The retrievePromotionRules method is invoked whenever Cortex needs to retrieve promotion rules by GUID. It is used so that Cortex can return the correct list of applied rules for each associated resource.

`retrievePromotionCarrots`

The retrievePromotionCarrots method is invoked by Cortex to identify the promotion carrots for a specific product SKU and shopper.

`retrieveCouponsByGuids`

The retrieveCouponsByGuids method is invoked by Cortex to retrieve coupon details by coupon GUIDs.

`retrieveCouponsByCodes`

The retrieveCouponsByGuids method is invoked by Cortex to retrieve coupon details by coupon code. Note that some coupon codes can actually return multiple coupon records, with different activation and limit configurations.

`retrieveCouponCodesByCustomerAndStore`

The retrieveCouponCodesByCustomerAndStore method is invoked by Cortex to retrieve a list of coupon codes that should be automatically applied to a newly created shoppingcart for the specified customer email address and store. This usually happens when a coupon is specified as being private use for a specific customer.

`validateCouponRuleAndUsage`

The validateCouponRuleAndUsage method is invoked by Cortex to validate that the specified coupon codes are valid (still usable). This is invoked when a shopper adds a coupon to cart. Any validation errors should be returned in the result map, where the coupon code is the key and the validation results are included in the value. Validity checks include ensuring that the coupon is not suspended and that it has at least one use remaining.

`createCouponsForPromotions`

The createCouponsForPromotions method is invoked by Cortex when a shopper checks out with a cart that includes a promotion that applies a private coupon to the customer. The method should automatically create the required coupons and assign them to the customer email address specified in the context.

`disableCouponAutoApply`

The disableCouponAutoApply method is invoked by Cortex when a shopper removes a coupon code from their cart that was automatically applied based on the results of the retrieveCouponCodesByCustomerAndStore call. It should ensure that future calls to retrieveCouponCodesByCustomerAndStore will not return the specified coupon codes.

Extension Sample

@Extension
@XPFAssignment(extensionPoint = XPFExtensionPointEnum.PROMOTIONS_CALCULATOR, priority = 10)
public class SMPPromotionsCalculator extends XPFExtensionPointImpl implements PromotionsCalculator {
    @Override
    public XPFPromotionCalculationOutputContext evaluate(final XPFCatalogPromotionCalculationInputContext context) {
        return deserializeResponse(sendRequest(context, getBaseUri() + "product/evaluate"),
            new TypeReference<XPFPromotionCalculationOutputContext>() { });
    }

    @Override
    public XPFPromotionCalculationOutputContext evaluate(final XPFCartPromotionCalculationInputContext context) {
        return deserializeResponse(sendRequest(context, getBaseUri() + "cart/evaluate"),
            new TypeReference<XPFPromotionCalculationOutputContext>() { });
    }

    @Override
    public Set<XPFPromotionRule> retrievePromotionRules(final XPFRuleRetrievalContext context) {
        return deserializeResponse(sendRequest(context, getBaseUri() + "rules/identify"),
            new TypeReference<Set<XPFPromotionRule>>() { });
    }

    @Override
    public Set<XPFPromotionRule> retrievePromotionCarrots(final XPFPromotionCarrotsInputContext context) {
        return deserializeResponse(sendRequest(context, getBaseUri() + "carrots/identify"),
            new TypeReference<Set<XPFPromotionRule>>() { });
    }

    @Override
    public Map<String, XPFCoupon> retrieveCouponsByGuids(final XPFPromotionCalculatorCouponGuidRetrievalContext context) {
        return deserializeResponse(sendRequest(context, getBaseUri() + "coupons/retrieveByGuids"),
            new TypeReference<Set<XPFPromotionCalculatorCouponGuidRetrievalContext>>() { });
    }

    @Override
    public Map<String, Collection<XPFCoupon>> retrieveCouponsByCodes(final XPFPromotionCalculatorCouponCodeRetrievalContext context) {
        return deserializeResponse(sendRequest(context, getBaseUri() + "coupons/retrieveByCodes"),
            new TypeReference<Set<XPFPromotionCalculatorCouponCodeRetrievalContext>>() { });
    }

    @Override
    public Set<String> retrieveCouponCodesByCustomerAndStore(final XPFPromotionCalculatorCouponStoreEmailRetrievalContext context) {
        return deserializeResponse(sendRequest(context, getBaseUri() + "coupons/retrieveByCustomerAndStore"),
            new TypeReference<Set<XPFPromotionCalculatorCouponStoreEmailRetrievalContext>>() { });
    }

    @Override
    public Map<String, XPFPromotionCouponValidationOutputContext> validateCouponRuleAndUsage(final XPFPromotionCalculatorCouponValidationContext context) {
        return deserializeResponse(sendRequest(context, getBaseUri() + "coupons/validate"),
            new TypeReference<Set<XPFPromotionCalculatorCouponValidationContext>>() { });
    }

    @Override
    public void createCouponsForPromotions(final XPFPromotionCalculatorCouponCreationContext context) {
        return deserializeResponse(sendRequest(context, getBaseUri() + "coupons/createForPromotions"),
            new TypeReference<Set<XPFPromotionCalculatorCouponCreationContext>>() { });
    }

    @Override
    public void disableCouponAutoApply(final XPFPromotionCalculatorDisableCouponContext context) {
        return deserializeResponse(sendRequest(context, getBaseUri() + "coupons/disableAutoApply"),
            new TypeReference<Set<XPFPromotionCalculatorDisableCouponContext>>() { });
    }
}