HQ Super Admins only (Product Owner)

👉 Store admins configure promotions only. See the procedure Set Up a Promotion for Approaching Promotion Suggestions.

Approaching promotions tell a shopper which promotions they are close to qualifying for, and how much is still missing. The site preferences control, for each site:

• Whether the feature is active
• How suggestions are delivered to the storefront
• Whether product promotions are included
• How many suggestions are returned
• The default upsell window
• Whether coupon promotions are shown

Upsell Window
A next-tier suggestion appears only when the missing amount is inside the upsell window. The window is a percentage of the next tier threshold:

• If the promotion sets its own window (apUpsellThreshold, above 0), that value is used.
• Otherwise the site default (apDefaultUpsellPercent, default 25) is used.

Example: next tier at 100€ with a 25% window. The suggestion appears once the basket is at 75€ or more, so 25€ or less is missing.

Forward-Looking Note
Site preferences are set in Business Manager. Moving them to the storefront configuration was discussed but not done.

• apEmbedInBasket: keep this off for now. On adds work to each basket call.
• apProductEvaluatorEnabled: not yet verified for production. Product promotions are not shown to shoppers yet.
• apEnabled set to off stops the feature. The storefront receives an empty list.
• apMaxResults: the storefront can ask for fewer suggestions, never more.
• Preferences are set per site. Repeat the configuration on each site.

1. Open the site preferences
Go to: Merchant Tools → Site Preferences → Custom Site Preference Groups → Approaching Promotions

• Select the site
• Keep Instance Type on the instance you are configuring

👉 A value set to None or left empty uses the Default Value shown next to it.

2. Enable the feature

• Approaching Promotions: Enabled (apEnabled): default Yes

👉 No stops the feature. The storefront receives an empty list.

3. Set basket embedding

• Approaching Promotions: Embed in Basket Response (apEmbedInBasket): keep No (default No)

👉 Yes adds the suggestions to every basket response. This saves a request in the cart but adds work to each basket call.

4. Set the product evaluator

• Approaching Promotions: Product Evaluator Enabled (apProductEvaluatorEnabled): keep No (default No)

👉 Yes adds product promotion suggestions and higher tiers for product promotions. Not yet verified for production.

5. Set the maximum number of suggestions

• Approaching Promotions: Maximum Results (apMaxResults): default 3

👉 Maximum number of suggestions per response. The list is cut to the lower of this value and the number the storefront asks for. With 1, only the closest suggestion is shown.

6. Set the default upsell window

• Approaching Promotions: Default Upsell Window (% of next tier threshold) (apDefaultUpsellPercent): default 25

👉 Window used when a promotion does not set its own.

7. Set coupon promotion visibility

• Approaching Promotions: Hide Coupon Promotions (apHideCouponPromotions): default Yes

👉 Shows coupon promotions only when the coupon is already in the basket.

8. Save

• Click Save
• To copy the values to other sites, click Apply to Other Sites, or use Edit Across Sites on a single preference

Procedure Notes

• Next-tier suggestions also require the ApproachingPromoBuildCatalog job to run. See the procedure Manage the ApproachingPromoBuildCatalog Job.
• Next-tier suggestions per promotion are enabled by store admins with Approaching Promo: Enable Upsell on the promotion.