Promotions Adjustments in Orders

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

What are Adjustment Lines?#

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

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.

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 Order and Promotion modules together, use the computeActions method of the Promotion Module’s main service. It retrieves the actions of line items and shipping methods.

Code
Show Imports
9
10// retrieve the order11const order = await orderModuleService.retrieveOrder("ord_123", {12  relations: [13    "items.item.adjustments",14    "shipping_methods.shipping_method.adjustments",15  ],16})17// retrieve the line item adjustments18const lineItemAdjustments: ComputeActionItemLine[] = []19order.items.forEach((item) => {20  const filteredAdjustments = item.adjustments?.filter(21    (adjustment) => adjustment.code !== undefined22  ) as unknown as ComputeActionAdjustmentLine[]23  if (filteredAdjustments.length) {24    lineItemAdjustments.push({25      ...item,26      ...item.detail,27      adjustments: filteredAdjustments,28    })29  }30})31
32//retrieve shipping method adjustments33const shippingMethodAdjustments: ComputeActionShippingLine[] =34  []35order.shipping_methods.forEach((shippingMethod) => {36  const filteredAdjustments =37    shippingMethod.adjustments?.filter(38      (adjustment) => adjustment.code !== undefined39    ) as unknown as ComputeActionAdjustmentLine[]40  if (filteredAdjustments.length) {41    shippingMethodAdjustments.push({42      ...shippingMethod,43      adjustments: filteredAdjustments,44    })45  }46})47
48// compute actions49const actions = await promotionModuleService.computeActions(50  ["promo_123"],51  {52    items: lineItemAdjustments,53    shipping_methods: shippingMethodAdjustments,54    // TODO infer from cart or region55    currency_code: "usd",56  }57)

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 order’s line items and the shipping method’s adjustments.

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