Promotion Actions

In this document, you’ll learn about promotion actions and how they’re computed using the computeActions method.

computeActions Method#

The Promotion Module's main service has a computeActions method that returns an array of actions to perform on a cart when one or more promotions are applied.

Actions inform you what adjustment must be made to a cart item or shipping method. Each action is an object having the action property indicating the type of action.

How Promotions Stack#

When you pass more than one promotion to computeActions, Medusa applies them one after another and returns the combined actions.

Medusa applies the promotions in the following order:

1. buyget promotions, then standard promotions.
2. Within each type, Medusa sorts promotions by their application method's value in descending order.

Medusa computes each promotion against the remaining amount of a line item or shipping method: its original amount minus the amount that promotions earlier in the same computation already discounted. Medusa never discounts an item below 0.

This affects how percentages are calculated. A percentage promotion applies its percentage to the remaining amount, not the original amount. For example, if a $30 discount already applied to a $200 item, a following 10% promotion discounts 10% of the remaining $170, which is $17.

Order-Level Promotions#

Medusa always distributes a promotion whose application method's target_type is order across the cart's applicable items, whether its value is a percentage or a fixed amount. Medusa distributes the discount proportionally based on each item's remaining amount.

For example, consider a cart with two items:

• Item A: $250
• Item B: $150

If you apply a $100 fixed discount on the order, Medusa distributes it proportionally across the two items based on their share of the $400 total:

• Item A: $100 x (250 / 400) = $62.5
• Item B: $100 x (150 / 400) = $37.5

If another order-level promotion applies afterward, Medusa recalculates each item's share using its remaining amount ($187.5 and $112.5).

Action Types#

addItemAdjustment Action#

The addItemAdjustment action indicates that an adjustment must be made to an item. For example, removing $5 off its amount.

This action has the following format:

Code
1export interface AddItemAdjustmentAction {2  action: "addItemAdjustment"3  item_id: string4  amount: number5  code: string6  description?: string7  is_tax_inclusive?: boolean8}

This action means that a new record should be created of the LineItemAdjustment data model in the Cart Module, or OrderLineItemAdjustment data model in the Order Module.

removeItemAdjustment Action#

The removeItemAdjustment action indicates that an adjustment must be removed from a line item. For example, remove the $5 discount.

The computeActions method accepts any previous item adjustments in the items property of the second parameter.

This action has the following format:

Code
1export interface RemoveItemAdjustmentAction {2  action: "removeItemAdjustment"3  adjustment_id: string4  description?: string5  code: string6}

This action means that a new record should be removed of the LineItemAdjustment (or OrderLineItemAdjustment) with the specified ID in the adjustment_id property.

addShippingMethodAdjustment Action#

The addShippingMethodAdjustment action indicates that an adjustment must be made on a shipping method. For example, make the shipping method free.

This action has the following format:

Code
1export interface AddShippingMethodAdjustment {2  action: "addShippingMethodAdjustment"3  shipping_method_id: string4  amount: number5  code: string6  description?: string7}

This action means that a new record should be created of the ShippingMethodAdjustment data model in the Cart Module, or OrderShippingMethodAdjustment data model in the Order Module.

removeShippingMethodAdjustment Action#

The removeShippingMethodAdjustment action indicates that an adjustment must be removed from a shipping method. For example, remove the free shipping discount.

The computeActions method accepts any previous shipping method adjustments in the shipping_methods property of the second parameter.

This action has the following format:

Code
1export interface RemoveShippingMethodAdjustment {2  action: "removeShippingMethodAdjustment"3  adjustment_id: string4  code: string5}

When the Medusa application receives this action type, it removes the ShippingMethodAdjustment (or OrderShippingMethodAdjustment) with the specified ID in the adjustment_id property.

campaignBudgetExceeded Action#

When the campaignBudgetExceeded action is returned, the promotions within a campaign can no longer be used as the campaign budget has been exceeded.

This action has the following format:

Code
1export interface CampaignBudgetExceededAction {2  action: "campaignBudgetExceeded"3  code: string4}