The eCommerce Orders API supports two coupon scopes that affect how discounts appear in order line items and pricing: item-level (SPECIFIC_ITEMS) and order-level (GLOBAL). Each scope determines how the discount is calculated, how it affects item prices and the subtotal, and how it's represented in the appliedDiscounts structure.
Item-level coupons use the SPECIFIC_ITEMS scope. They apply a discount to specific line items in an order.
discountType in each appliedDiscounts entry is set to SPECIFIC_ITEMS. The discount reduces the line item price directly.Order-level coupons use the GLOBAL scope. They apply a discount to the entire order after the subtotal is calculated.
appliedDiscounts with discountType set to GLOBAL.Shipping coupons aren't affected by this change.
SPECIFIC_ITEMS) or the entire order (GLOBAL).appliedDiscounts: The property on order line items and the order object that contains discount details.SPECIFIC_ITEMS scope that reduces individual line item prices.GLOBAL scope that reduces the order total after the subtotal is calculated.In the legacy behavior, all coupons applied as order-level discounts regardless of their configured scope. If you have an existing integration that depends on this behavior, use this section to update your implementation.
Warning: If you don't update your integration, you'll see incorrect subtotals, mismatched totals, and duplicated or missing discount amounts.
The following table summarizes the differences between the legacy behavior and the updated behavior:
| Feature | Legacy behavior | Updated behavior |
|---|---|---|
| Scope logic | All coupons apply as order-level (GLOBAL). | Distinct logic for SPECIFIC_ITEMS vs. GLOBAL. |
| Item prices | Coupons don't affect line item prices. | SPECIFIC_ITEMS coupons reduce targeted line item prices. |
| Subtotal | Reflects pre-discount prices only. | SPECIFIC_ITEMS coupons lower the subtotal directly. |
| Data model | SPECIFIC_ITEMS scope applies GLOBAL logic. | API behavior matches the configured scope. |
If your integration consumes order data, you can no longer assume all coupons behave the same way.
You need to make the following updates:
discountType field in each appliedDiscounts entry to determine if a coupon is SPECIFIC_ITEMS or GLOBAL.SPECIFIC_ITEMS coupons lower the line item price and subtotal, while GLOBAL coupons don't.The following examples show stripped-down API response payloads focusing on the affected pricing and discount fields. Note that totalPrice includes additional charges such as tax and shipping that aren't shown in these examples.
SPECIFIC_ITEMS) couponIn this example, a $5 discount is applied to the second line item.
Legacy behavior:
Updated behavior:
lineItems[1].price and lineItemPrice: The $5 discount is applied directly to the base price, dropping from $15.00 to $10.00.lineItems[1].totalDiscount: Cleared to $0.00.priceSummary.subtotal: Drops from $30.00 to $25.00 to reflect the reduced base prices.priceSummary.discount: Cleared to $0.00 since the discount is handled at the item level.GLOBAL) couponIn this example, a $10 global discount is applied to the entire order.
Legacy behavior:
Updated behavior:
appliedDiscounts[].discountType: Changed from multiple SPECIFIC_ITEMS entries to a single GLOBAL entry. The coupon.amount reflects the total $10.00 discount instead of the split amounts.appliedDiscounts[].lineItemDiscounts: The proportional split ($6.67 and $3.33) is grouped into a single array under the global discount entry.price, lineItemPrice, totalDiscount, and priceSummary fields remain the same as the legacy behavior.