Promotions

Promotions are incentives offered to shoppers to promote the purchase of items in a store. A store’s marketer creates promotions and defines a set of conditions that must be met before the promotion is applied to a given shopper. Promotions may trigger discounts or may trigger other incentives such as free items. When a promotion triggers a discount, the discounts are automatically applied to the item price, cart line item price, shipping option cost, line items total, cart total, and the order total.

Promotions are linked to a number of different resources:

• Promotions - The promotions resource provides a list of all the promotions available for the store
• Items - Promotions are linked to items when a promotion exists for that item and the shopper is eligible to receive the promotion
• Carts - Promotions are linked to carts when the contents of the shopper’s cart meet the conditions of the promotion
• Cart line items - Promotions are linked to cart line items when the line item meets the conditions of the promotion
• Shipping options - Promotions are linked to shipping options on an order shipment when the option meets the conditions of the promotion
• Purchases - Promotions are linked to purchases when the purchase had promotions applied to it
• Coupons - Promotion are linked to a coupon when the coupon triggered the promotions to apply

Read Applied Item Promotions

Retrieve catalog promotions applied to an item.

Workflow

1. Start with item
2. GET the link with rel: appliedpromotions
3. GET the link with rel: element
4. Render the response

Response Fields

Type: promotions.promotion

Name	Description	Type
name	The promotion identifier.	string
display-name	The promotion’s localized name, intended for display in the client application.	string
display-description	The promotion’s localized marketing description, intended for display in the client application.	string
display-conditions	The promotion’s localized terms and conditions, intended for display in the client application.	string

Read Promotion Carrots for an Item

Retrieve a list of shopping cart promotions that are eligible for the shopper and are related to the item (product SKU).

The following eligibility rules are applied to the promotions:

• Is a shopping cart promotion.
• The Cortex currency matches the currency condition (if present).
• The promotion is not activated by private coupons.
• Satisfies all shopper conditions.

Additionally, the following rules are used to determine if the promotion is related to the item:

Condition or Action	Matching Process
[][] items of Category [] are in the shopping cart	The condition’s category matches any of the item's assigned categories.
[][] items of Product [] are in the shopping cart	The condition’s product matches the item's product.
[][] items of SKU [] are in the shopping cart	The condition’s product SKU matches the item.
[][] items of product with attribute [] having value [] are in the shopping cart	The condition's attribute and value matches one of the item's product attribute values.
[][] items of SKU with attribute [] having value [] are in the shopping cart	The condition's attribute and value matches one of the item's attribute values.
Line item product is from category []	The condition’s category matches any of the item's assigned categories.
Line item product is []	The condition’s product matches the item's product.
Line item product attribute [] has value []	The condition's attribute and value matches one of the item's product attribute values.
Line item product SKU is []	The condition’s product SKU matches the item.
Line item product SKU attribute [] has value []	The condition's attribute and value matches one of the item's attribute values.
Get [] % off [] items in category []	The action’s category matches any of the item's assigned categories.
Get $[] off [] items in category []	The action’s category matches any of the item's assigned categories.
Get [] % off [] items of product []	The action’s product matches the item's product.
Get $[] off [] items of product []	The action’s product matches the item's product.
Get [] % off [] items of SKU []	The action’s product SKU matches the item.
Get $[] off [] items of SKU []	The action’s product SKU matches the item.
Get [] % off item number [] of product []	The action’s product matches the item's product.

A promotion will be excluded from the list if a rule condition excludes the item.

Workflow

1. Start with item
2. GET the link with rel: promotioncarrots
3. Iterate across the links with rel: element
4. Render the response

Response Fields

Type: promotions.promotion

Name	Description	Type
name	The promotion identifier.	string
display-name	The promotion’s localized name, intended for display in the client application.	string
display-description	The promotion’s localized marketing description, intended for display in the client application.	string
carrot-description	The optional carrot description defined by marketing to describe when the promotion will apply and what the actions will do.	string
promotion-type	Contains either CART or CART_LINE, depending on whether the promotion defines cart-level rules or cart line-item level rules.	string
condition-operator	Contains either AND or OR, depending on the operator that is used to evaluate promotion conditions.	string
start-date	The date and time that the promotion becomes active.	date
end-date	The date and time that the promotion expires.	date
requires-coupon-code	Indicates if the promotion requires a coupon code to be activated.	boolean

Read Promotion Carrot Conditions for an Item

Retrieve a list of conditions that are configured on a shopping cart promotion.

Workflow

1. Start with item
2. GET the link with rel: promotioncarrots
3. Iterate across the links with rel: element
4. GET the link with rel: conditions
5. Iterate across the links with rel: element
6. Render the response

Response Fields

Type: promotions.promotion-element

Name	Description	Type
element-type	The type of condition that will be evaluated by the promotion. Corresponds to the @DiscriminatorValue on a class implementing the RuleCondition interface.	string
exclusions	An array of strings representing values that should be excluded by the promotion. How this is evaluated depends on the condition type.	array
parameters	A map of key/value pairs representing parameters that are used for condition evaluation. The supported parameter keys and how they are used depends on the condition type.	object

Read Promotion Carrot Actions for an Item

Retrieve a list of actions that are configured on a shopping cart promotion.

Workflow

1. Start with item
2. GET the link with rel: promotioncarrots
3. Iterate across the links with rel: element
4. GET the link with rel: actions
5. Iterate across the links with rel: element
6. Render the response

Response Fields

Type: promotions.promotion-element

Name	Description	Type
element-type	The type of action that will be evaluated by the promotion. Corresponds to the @DiscriminatorValue on a class implementing the RuleAction interface.	string
exclusions	An array of strings representing values that should be excluded by the promotion. How this is evaluated depends on the action type.	array
parameters	A map of key/value pairs representing parameters that are used for action evaluation. The supported parameter keys and how they are used depends on the action type.	object

Read Applied Cart Promotions

Retrieve promotions applied to a cart.

Workflow

1. Start with cart
2. GET the link with rel: appliedpromotions
3. GET the link with rel: element
4. Render the response

Response Fields

Type: promotions.promotion

Name	Description	Type
name	The promotion identifier.	string
display-name	The promotion’s localized name, intended for display in the client application.	string
display-description	The promotion’s localized marketing description, intended for display in the client application.	string
display-conditions	The promotion’s localized terms and conditions, intended for display in the client application.	string

Read Applied Cart Line Item Promotions

Retrieve the promotions applied to a cart line item.

Workflow

1. Start with line-item
2. GET the link with rel: appliedpromotions
3. GET the link with rel: element
4. Render the response

Response Fields

Type: promotions.promotion

Name	Description	Type
name	The promotion identifier.	string
display-name	The promotion’s localized name, intended for display in the client application.	string
display-description	The promotion’s localized marketing description, intended for display in the client application.	string
display-conditions	The promotion’s localized terms and conditions, intended for display in the client application.	string

Read Applied Shipping Option Promotions

Retrieve promotions applied to a shipping option.

Workflow

1. Start with shipping-option
2. GET the link with rel: appliedpromotions
3. GET the link with rel: element
4. Render the response

Response Fields

Type: promotions.promotion

Name	Description	Type
name	The promotion identifier.	string
display-name	The promotion’s localized name, intended for display in the client application.	string
display-description	The promotion’s localized marketing description, intended for display in the client application.	string
display-conditions	The promotion’s localized terms and conditions, intended for display in the client application.	string

Read Promotions Triggered By Order Coupon

Retrieve a promotion triggered by a coupon on an order.

Workflow

1. Start with order-coupon
2. GET the link with rel: promotion
3. Render the response

Response Fields

Type: promotions.promotion

Name	Description	Type
name	The promotion identifier.	string
display-name	The promotion’s localized name, intended for display in the client application.	string
display-description	The promotion’s localized marketing description, intended for display in the client application.	string
display-conditions	The promotion’s localized terms and conditions, intended for display in the client application.	string

Read Applied Purchase Promotions

Retrieve promotions applied to a purchase.

Workflow

1. Start with purchase
2. GET the link with rel: appliedpromotions
3. GET the link with rel: element
4. Render the response

Response Fields

Type: promotions.promotion

Name	Description	Type
name	The promotion identifier.	string
display-name	The promotion’s localized name, intended for display in the client application.	string
display-description	The promotion’s localized marketing description, intended for display in the client application.	string
display-conditions	The promotion’s localized terms and conditions, intended for display in the client application.	string

Read Promotions Triggered By Purchase Coupon

Retrieve a promotion triggered by a coupon on a purchase.

Workflow

1. Start with purchase-coupon
2. GET the link with rel: promotion
3. Render the response

Response Fields

Type: promotions.promotion

Name	Description	Type
name	The promotion identifier.	string
display-name	The promotion’s localized name, intended for display in the client application.	string
display-description	The promotion’s localized marketing description, intended for display in the client application.	string
display-conditions	The promotion’s localized terms and conditions, intended for display in the client application.	string