Promotions Adjustments in Carts

In this document, you’ll learn how a promotion is applied to a cart’s line items and shipping methods using adjustment lines.

What are Adjustment Lines?#

An adjustment line indicates a change to an item or a shipping method’s amount. It’s used to apply promotions or discounts on a cart.

The LineItemAdjustment data model represents changes on a line item, and the ShippingMethodAdjustment data model represents changes on a shipping method.

The amount property of the adjustment line indicates the amount to be discounted from the original amount. Also, the ID of the applied promotion is stored in the promotion_id property of the adjustment line.

Discountable Option#

The LineItem data model has an is_discountable property that indicates whether promotions can be applied to the line item. It’s enabled by default.

When disabled, a promotion can’t be applied to a line item. In the context of the Promotion Module, the promotion isn’t applied to the line item even if it matches its rules.

Promotion Actions#

When using the Cart and Promotion modules together, such as in the Medusa application, use the computeActions method of the Promotion Module’s main service. It retrieves the actions of line items and shipping methods.

For example:

Code
Show Imports
7
8// retrieve the cart9const cart = await cartModuleService.retrieveCart("cart_123", {10  relations: [11    "items.adjustments",12    "shipping_methods.adjustments",13  ],14})15
16// retrieve line item adjustments17const lineItemAdjustments: ComputeActionItemLine[] = []18cart.items.forEach((item) => {19  const filteredAdjustments = item.adjustments?.filter(20    (adjustment) => adjustment.code !== undefined21  ) as unknown as ComputeActionAdjustmentLine[]22  if (filteredAdjustments.length) {23    lineItemAdjustments.push({24      ...item,25      adjustments: filteredAdjustments,26    })27  }28})29
30// retrieve shipping method adjustments31const shippingMethodAdjustments: ComputeActionShippingLine[] =32  []33cart.shipping_methods.forEach((shippingMethod) => {34  const filteredAdjustments =35    shippingMethod.adjustments?.filter(36      (adjustment) => adjustment.code !== undefined37    ) as unknown as ComputeActionAdjustmentLine[]38  if (filteredAdjustments.length) {39    shippingMethodAdjustments.push({40      ...shippingMethod,41      adjustments: filteredAdjustments,42    })43  }44})45
46// compute actions47const actions = await promotionModuleService.computeActions(48  ["promo_123"],49  {50    items: lineItemAdjustments,51    shipping_methods: shippingMethodAdjustments,52  }53)

The computeActions method accepts the existing adjustments of line items and shipping methods to compute the actions accurately.

Then, use the returned addItemAdjustment and addShippingMethodAdjustment actions to set the cart’s line item and the shipping method’s adjustments.

Code
Show Imports
7// ...8
9await cartModuleService.setLineItemAdjustments(10  cart.id,11  actions.filter(12    (action) => action.action === "addItemAdjustment"13  ) as AddItemAdjustmentAction[]14)15
16await cartModuleService.setShippingMethodAdjustments(17  cart.id,18  actions.filter(19    (action) =>20      action.action === "addShippingMethodAdjustment"21  ) as AddShippingMethodAdjustment[]22)