Commerce Promotion API Reference
Corecommerce
Overview
Section titled “Overview”The Promotion API evaluates and applies discounts to carts and orders. IPromotionEngine runs promotion evaluation. Custom promotions extend EntryPromotion, OrderPromotion, or ShippingPromotion.
Namespace
Section titled “Namespace”Optimizely.Commerce.Marketing
Key types
Section titled “Key types”| Type | Purpose |
|---|---|
IPromotionEngine | Evaluates promotions against a cart |
PromotionData | Base class for all promotions |
EntryPromotion | Discount on specific catalog entries |
OrderPromotion | Discount on the entire order |
ShippingPromotion | Discount on shipping |
PromotionProcessorBase | Base class for custom promotion processors |
IPromotionEngine
Section titled “IPromotionEngine”Run(IOrderGroup, PromotionEngineSettings)
Section titled “Run(IOrderGroup, PromotionEngineSettings)”Evaluates all active promotions against a cart.
Parameters
| Name | Type | Description |
|---|---|---|
orderGroup | IOrderGroup | Cart to evaluate |
settings | PromotionEngineSettings | Evaluation options |
Returns: IEnumerable<RewardDescription>
PromotionEngineSettings
Section titled “PromotionEngineSettings”| Property | Type | Description |
|---|---|---|
ExclusionLevel | ExclusionLevel | None, Unit, Order, Shipping |
ApplyReward | bool | Whether to apply the discount to the cart |
RequestedStatuses | RequestFulfillmentStatus | All, Fulfilled, NotFulfilled |
Evaluate promotions on a cart
public class PromotionService
{
private readonly IPromotionEngine _promotionEngine;
public PromotionService(IPromotionEngine promotionEngine)
{
_promotionEngine = promotionEngine;
}
public IEnumerable<RewardDescription> ApplyPromotions(ICart cart)
{
var settings = new PromotionEngineSettings
{
ApplyReward = true,
ExclusionLevel = ExclusionLevel.Unit
};
return _promotionEngine.Run(cart, settings);
}
}RewardDescription properties
Section titled “RewardDescription properties”| Property | Type | Description |
|---|---|---|
Promotion | PromotionData | The promotion that generated this reward |
SavedAmount | decimal | Amount saved by this reward |
Status | FulfillmentStatus | Fulfilled, NotFulfilled, PartiallyFulfilled |
Description | string | Human-readable reward description |
RewardType | RewardType | EachAffectedEntry, WholeOrder, Shipping |
Percentage | decimal | Percentage discount (if applicable) |
Promotion types
Section titled “Promotion types”EntryPromotion
Section titled “EntryPromotion”Discounts applied to specific line items.
| Property | Type | Description |
|---|---|---|
Condition | PromotionCondition | When the promotion triggers |
DiscountTarget | CatalogItemSelection | Which entries receive the discount |
Discount | PromotionDiscount | Discount amount or percentage |
Coupon | CouponData | Optional coupon requirement |
OrderPromotion
Section titled “OrderPromotion”Discounts applied to the order total.
| Property | Type | Description |
|---|---|---|
Condition | OrderPromotionCondition | Minimum spend or item count |
Discount | OrderDiscount | Order-level discount |
ShippingPromotion
Section titled “ShippingPromotion”Discounts applied to shipping costs.
| Property | Type | Description |
|---|---|---|
Condition | PromotionCondition | Trigger condition |
ShippingMethods | IList<Guid> | Eligible shipping methods |
Discount | ShippingDiscount | Shipping discount |
Creating a custom promotion
Section titled “Creating a custom promotion”Custom percentage-off entry promotion
[ContentType(
DisplayName = "Buy X Get Y Free",
GUID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890")]
public class BuyXGetYPromotion : EntryPromotion
{
[Display(Name = "Required quantity")]
public virtual int RequiredQuantity { get; set; }
[Display(Name = "Free quantity")]
public virtual int FreeQuantity { get; set; }
}Custom promotion processor
public class BuyXGetYProcessor : EntryPromotionProcessorBase<BuyXGetYPromotion>
{
protected override RewardDescription Evaluate(
BuyXGetYPromotion promotion,
PromotionProcessorContext context)
{
var entries = context.EntryPrices;
var qualifyingEntry = entries
.FirstOrDefault(e => e.Quantity >= promotion.RequiredQuantity);
if (qualifyingEntry == null)
{
return RewardDescription.CreateNotFulfilled("Quantity not met.");
}
var discount = qualifyingEntry.Price * promotion.FreeQuantity;
return RewardDescription.CreateFulfilled(
discount,
promotion,
"Buy X Get Y applied.");
}
}CouponData properties
Section titled “CouponData properties”| Property | Type | Description |
|---|---|---|
Code | string | Single coupon code |
MaxRedemptions | int | Maximum total uses |
UsedRedemptions | int | Current redemption count |
PromotionData base properties
Section titled “PromotionData base properties”| Property | Type | Description |
|---|---|---|
Name | string | Promotion display name |
IsActive | bool | Whether the promotion is active |
ValidFrom | DateTime? | Start date |
ValidUntil | DateTime? | Expiration date |
Priority | int | Evaluation priority (lower = higher priority) |
ExclusionLevel | ExclusionLevel | Exclusivity level |
Banner | ContentReference | Promotional banner content |
Common exceptions
Section titled “Common exceptions”| Exception | Cause |
|---|---|
PromotionProcessorException | Error during promotion evaluation |
CouponAlreadyUsedException | Coupon has reached max redemptions |
InvalidPromotionException | Promotion configuration is invalid |