Manage upsell messages
Upsell messages let you alert shoppers to promotions and show shoppers when they are close to fulfilling a promotion’s buy or spend condition.
For example, suppose your store is running a Gift with Item Purchase promotion that offers a free team scarf with every two jerseys from the same team shop. When a shopper begins checkout with a cart that contains one jersey, the cart page could display the following message: Wait! Buy one more jersey to get a free scarf! When the shopper adds a second jersey to the cart, the free gift is added and the message could change to: Enjoy your free scarf!
This section describes upsell messages and explains how to create them in the administration interface. To learn how to customize widgets and elements so you can display the messages on your storefront, see Set up promotion upsell messages. This section includes the following topics:
- Understand upsell messages
- Understand tags
- Create upsell messages
- Localize upsell messages
- Delete upsell messages
Understand upsell messages
Each promotion can have one set of upsell messages. Each set of upsell messages can contain one each of the following three types of messages:
- Not Qualified: This is a global message that alerts shoppers to a promotion. For example, Free US Flat Rate Shipping On Orders Over $75.
- Partially Qualified: This message appears when a shopper has partially qualified for the promotion. For example, Spend Just $10 More For Free Shipping!
- Success: This message appears when the shopper has qualified for the promotion. For example, Congratulations! Your Order Ships For Free!
Important: If a promotion requires a coupon code, shoppers will not see any of its upsell messages, including the Not Qualified message, until they enter the coupon code in the shopping cart. See Add a coupon code to a promotion for more information about promotions that require coupons.
This section describes each type of upsell message you can create in the administration interface.
Not Qualified message
The Not Qualified message alerts shoppers to a promotion. You can show the message to all shoppers who can access the promotion, even if they have not yet started to qualify for it. Display a Not Qualified message where it can be easily seen by shoppers, for example, in a banner at the top of each page on your storefront.
Partially Qualified message
The Partially Qualified message appears when a shopper begins to qualify for the promotion. Partially Qualified messages are triggered by a value you specify, often called a closeness qualifier. For example, suppose a promotion offers free shipping when a shopper spends $75 anywhere in the store and you want to display the Partially Qualified message when a shopper places anything in their cart. Set this value to 1 to display the message when any item that costs $1 or more is added to the cart. To display the message only when a shopper needs to spend $25 or less to qualify for the promotion, set the value to 50.
Partially Qualified messages include variables that represent values to display in the message. When the message is displayed on the storefront, Commerce replaces the variables with the actual values that represent a shopper’s cart and its qualification for the promotion.
The following table describes each variable and lists the promotion templates for which it is available.
| Variable | Description | Promotion Templates |
|---|---|---|
|
{{AmountSpent}} {{AmountStillNeeded}} |
{{AmountSpent}} specifies the shopper’s current qualifying spend amount. {{AmountStillNeeded}} specifies the minimum spend amount to qualify for the promotion minus the shopper’s current qualifying spend amount. Note: Commerce automatically adds the appropriate currency symbol and separator to the amounts specified by these variables. |
Spend Y Get Gift with Purchase Spend Y in X Get Item Discount Spend Y in X Get Order Discount Spend Y for Order Discount Spend Y Get Shipping Discount Spend Y in X Shipping Discount |
|
{{QuantityBought}} {{QuantityStillNeeded}} |
{{QuantityBought}} specifies the number of qualifying items in the shopper’s cart. {{QuantityStillNeeded} specifies the minimum number of items to qualify for the promotion minus the number of qualifying items in the shopper’s cart. |
Buy One Get One Gift With Item Purchase Buy X Get Order Discount Buy X Get Shipping Discount |
For promotions whose Partially Qualified messages use the {{QuantityBought}} and {{QuantityStillNeeded}} variables, Commerce does not change the message text based on singular or plural quantities. For example, suppose a promotion offers 10% off with the purchase of three toys and the message displays when a shopper adds one toy to the cart. The message “Buy 2 more toys to get 10% off!” makes sense, but when the shopper adds a second toy to the cart, the message changes to “Buy 1 more toys to get 10% off!” A better message in this instance is one that accommodates one item or multiple items. For example, “Toy Sale! Buy {{QuantityStillNeeded}} more to get 10% off.”
You cannot create a Partially Qualified message for the following types of promotions, because they do not require buy or spend conditions:
- Get Item Discount
- Get Shipping Discount
- Gift with Item Purchase if the buy condition is set to Give Gift with Any Order.
Success message
The Success message lets a shopper know they have successfully qualified for the promotion. The success message is displayed when the shopper’s cart qualifies for the promotion.
Understand tags
Tags are strings that establish a relationship between upsell messages and the widgets that will display them on your storefront. You add tags to upsell messages when you create them on a promotion’s Messaging tab. Then storefront developers add the tags to widgets and that will display the messages to shoppers.
You can assign one or more tags to a single upsell message. You can create and save a message without adding tags to it, but a message with no tags cannot be displayed on your storefront.
Once you create a tag, it is available to all upsell messages in all promotions. You can assign the same tag to more than one message, including messages for different promotions. This can be useful if, you create similar promotions for different audiences or different sites. For example, you can assign the tag home to Not Qualified messages you want to display on your store's Home page to alert shoppers to promotions. Similarly, you can assign the tag cart to Partially Qualified messages so shoppers can see how close they are to qualifying when they go to check out.
If you assign the same tag to all three of a promotion’s upsell messages, the messages replace each other on the storefront wherever the tag displays them. For example, suppose you assign the tag FreeShip to all three upsell messages for a promotion that offers free shipping to any shopper who spends $150 on a single order. You configure the Partially Qualified message so that it appears when the value of a shopper’s cart is at least $10. You add the FreeShip tag to a banner on your storefront. When a shopper arrives at the site, they see the Not Qualified message (FREE U.S. Flat Rate shipping when you spend $150). in the banner. When the shopper places an item priced at $49.99 in the cart, the Not Qualified message is replaced by the Partially Qualified message (Only $50.01 away from FREE U.S. Flat Rate shipping!). When the shopper places another item, priced at $75 in the cart, the Partially Qualified message is replaced by the Success message (Your order qualifies for FREE U.S. Flat Rate shipping!). If the shopper removes one of the items from the cart, the Success message is once again replaced by the Partially Qualified message.
For more information about how Commerce determines which messages to display for a specific tag, see Set up promotion upsell messages.
Keep the following in mind when you create tags:
- Tags are case sensitive; for example, Commerce treats banner and BANNER as two different tags.
- Do not use the following characters in tags: < > { } {{ }} “
- Tags must be published before widgets can use them on your storefront. See Publish Changes for more information.
You cannot delete tags in the administration interface. You must use the Admin API messageTags endpoints to delete tags. See Set up promotion upsell messages for more information.
Create upsell messages
This section describes how to create upsell messages and tags in the administration interface. To learn how to customize widgets and elements so you can display the messages on your storefront, see Set up promotion upsell messages.
You create the messages on a promotion’s details page, with an HTML editor called CKEditor. You can write, update, and apply rich-text formatting to upsell messages.
To create upsell messages for a promotion:
- On a promotion’s details page, click Messaging.
- Enter and format the text for each message type.
- Create or select tags to add to each message.
- Click the Tag box and begin typing to display a list of existing tags. You can filter the list by typing or pasting more text in the box.
- To add a tag from the list, select it and press Enter.
- To add a new tag, continue typing the text for the tag and then press Enter.
- For Partially Qualified messages, enter an amount that will trigger display of the message.
- Click Create to save the message.
- Publish your changes.
If you edit a promotion, check its upsell messages to see if they need to be updated. Changing a promotion’s condition or offer without changing its upsell messages can cause unexpected results. For example, suppose a promotion offers free shipping when a shopper spends $100 and its Partially Qualified message is configured to appear when the shopper has spent $60. If you change the promotion’s condition to offer free shipping when the shopper spends $50, the unchanged Partially Qualified message might never appear, and when it does, it will present incorrect information.
Localize upsell messages
You can translate the text of Not Qualified, Partially Qualified, and Success messages the same way you translate other text that appears on your storefront. (See Translate store text for more information.) You cannot translate tags or the variables you use with Partially Qualified messages.
Commerce does not convert minimum spend amounts in promotions and upsell messages across different currencies your store supports. If your store supports multiple currencies, create a separate version of each minimum-spend promotion for each currency. See Understand currency-specific promotions for more information.
Delete upsell messages
You can delete one or more upsell messages from a promotion. Deleting a promotion also deletes its upsell messages. Deleting upsell messages does not delete any tags assigned to them. You must use the Admin API to delete tags. See Set up promotion upsell messages. for more information about deleting tags.
To delete an upsell message from a promotion:
- On a promotion’s details page, click Messaging.
- Click the Delete icon for the message you want to delete.
- Confirm that you want to delete the message.
- Publish your changes.