Guidelines for post-purchase upsell
When you design a post-purchase upsell, a great customer-facing user experience (UX) and merchant experience are important to the success of our merchants. The post-purchase upsell page should represent the merchant well and protect their brand’s trust.
To provide a great post-purchase experience and to help the merchant gain trust from customers, implement the following UX principles in your post-purchase checkout extension:
- Be transparent about all the costs involved in a purchase.
- Present clear options to accept or refuse upsell offers without pressuring customers.
- Limit the number of consecutive upsell offers displayed to customers.
- Display relevant products by tailoring upsell offers to customers’ shopping behaviors and preferences.
- Provide default copy that addresses customers directly using a voice that's appropriate for any store, regardless of brand personality.
Header and footer
The styling of the header and footer is consistent across every post-purchase page:
- Header: Confirms the payment of the initial purchase of the order. Customers can also directly access their full order confirmation (and bypass the upsell offer pages) using the View order confirmation button.
App Bridge Checkout provides many powerful UI components that a rendering extension can use to build an interface. The App Bridge Checkout UI components are rendered natively by Shopify, so you can depend on them to be performant, accessible, and functional in all of the checkout’s supported browsers.
Before you integrate your post-purchase app into checkout, familiarize yourself with the UI guidelines and best practices for the following required components:
A callout banner encourages customers to take action on a post-purchase upsell. Use the App Bridge Checkout CalloutBanner to implement this component:
Place a callout banner near the top of the page to let the customer know what the upsell offer is. Provide strong default copy in your app to encourage merchants to be explicit about the upsell offer.
Product title and price
The product must have the same title and price that it has on the merchant’s store. Keep this consistent to maintain a customer’s trust if they compare. Place the price of the product directly below the product title.
If the post-purchase product is an upsell offer at a discounted price, then do the following:
- Strike out the original price of the product.
- Display the discounted price next to the original price so that the relationship is clear.
The product image represents the product being offered to the customer in the post-purchase upsell offer. Use the App Bridge Checkout Image component to add an image:
Adding multiple images
If the upsell offer includes multiple images, then the images need to be easy to navigate and provide additional context to the customer. Images can be presented using different angles or sizes.
||Implement auto-scrolling through the images, as this might overwhelm customers.|
The post-purchase price breakdown shows the total cost of the upsell offer that the customer is accepting. The breakdown needs to be placed under the variant and quantity pickers. The breakdown also needs to dynamically update to reflect price changes if the customer adjusts the product's quantity or variants.
Structure of the price breakdown
The price breakdown needs to include the following:
Money line: An individual breakdown of costs.
- Subtotal: The total before shipping and taxes have been included.
- Shipping: The total shipping cost for the item(s).
- Taxes: The added cost of goods or services.
Money summary: The combined total of the subtotal, shipping, and taxes.
If your product description is long enough that a customer can't see the price breakdown without scrolling, then you need to include a copy of the price breakdown at the end of your product description.
Call to action buttons
A call to action button allows a customer to accept or decline an upsell offer. Use the App Bridge Checkout Button component to implement call to action buttons.
The accept button is the primary action on the post-purchase upsell page.
Use the following text for the accept button:
[Pay now • Product total price]
If the product you are offering is free, then use the following text:
[Add now • Free] or [Add now • $0]
Confirming accepted upsell offers
Use the App Bridge Checkout Banner component to display a confirmation message when a customer accepts an upsell offer. For example: [Your order has been updated].
Customers might not expect the accept button to generate a payment immediately because the convention is for "buy now" actions to trigger an additional confirmation step. To clarify that there is no additional confirmation step, do the following:
- Add a summary modal to confirm whether the customer wants to proceed.
- Add additional help text directly under the accept button informing the customer that they'll be charged immediately.
The decline button needs to be placed under the accept button and should be less visually prominent than the accept button. However, despite being less visually prominent, the decline button should still be easy to see so that the merchant can easily decline the upsell offer. The decline button must contain the text [Decline upsell offer].
In addition to the required components, you can add the following optional components to the post-purchase page:
The product description provides a summary of the key features of the product being displayed in the product image (or images).
All upsell offers should have a product description that accurately summarizes the product features. Encourage merchants using your app to keep the product description as short as possible.
Lengthy product descriptions
- A summary description that reveals all other components without scrolling
- A longer, more detailed description below the other components
If the product has several variants (for example, size or color), then the page needs to include a variant picker under the product description. Use the App Bridge Checkout Select component to implement a variant picker.
Label the picker with the name of the variant and the variant values. For example, Size: S, M, L, XL. If your product has several sizes, then consider linking to a size chart.
The quantity picker should be placed below the product description to allow customers to adjust the quantity of a product.
The quantity picker needs to be a number stepper that's set to 1 as a default. Use the label [Quantity].
Post-purchase app selector
Merchants need to enable their post-purchase app in the Shopify admin checkout settings. If there are multiple post-purchase apps installed, then they can also use the checkout settings to select which post-purchase app they want to enable on the post-purchase page.
We recommend that you let merchants know that they might need to manually select your app to be active in the checkout settings. You could explain this in installation instructions or in your help pages.
Your can check whether or not it is currently selected, using the following GraphQL Query:
Suggested merchant-facing content for your app:
You could use the following copy as the basis for a merchant-facing message about multiple post-purchase extensions:
"If you already have a post-purchase app installed, you must manually select to make [app-name] active. You can do this in the Shopify admin checkout settings. This option only shows if you already have a post-purchase app installed."
Limitations and considerations
The following limitations and considerations for post-purchase checkout extensions apply:
- Performance: To guarantee a good experience for both merchants and customers, we strongly recommend that you prioritize performance when building your extensions. You can depend on App Bridge Checkout UI components to be performant, accessible, and functional in all of the checkout's supported browsers. Keep the following guidelines in mind when building your app:
- Network calls must complete in two seconds or less.
- Network calls that occur before an interface presents to the customer must happen in the ShouldRender handler.
- Render must not require a network call before an interface presents to the customer. Ensure the extension caches required data beforehand using the storage API from ShouldRender.
- Alternative payment methods: The post-purchase page won't be surfaced in the following scenarios:
- The customer chooses to check out with an installment service or a wallet service (such as Klarna, Affirm, AfterPay, Apple Pay, Amazon Pay, or Google Pay).
- The initial purchase was made with a gift card or any payment method other than a credit card.
- Subscriptions: We don't currently support subscription products in post-purchase upsells.
- Purchase events: Third-party analytic services that use the Shopify Pixel API (such as Google Analytics, Facebook, Pinterest and Snap) report only the purchase event and value for the initial purchase.
- Analytics: Third-party analytics services that use the
ScriptTagREST Admin API or GraphQL Admin API resource, or Additional Scripts have incomplete conversion data, because they're only triggered on the thank you page.
- Duties and support for multiple currencies: Post-purchase upsell offers won’t be surfaced on orders with duties and multiple currencies.
- Order creation delays: In scenarios such as flash sales where the Shopify Platform is under extreme load, our system might optimize to capture orders but briefly delay the order creation step for a fast and seamless buyer experience. In these scenarios, post-purchase pages won't be surfaced, even if the request for the post-purchase page was properly made.
- Multiple apps: Merchants with multiple apps that have the post-purchase checkout extension need to select which app appears on the post-purchase page. You can use a banner during app onboarding to let merchants know that they can select your app as the default post-purchase app in the Shopify admin checkout settings.
- Fulfillment holds: Shopify places a hold on fulfillment for all orders undergoing a post purchase cross-sell flow. Holds are released either when the customer visits the thank you page, or after a set amount of time, if the customer doesn't complete the post-purchase flow. If the customer doesn't complete the flow (for example, the customer closes the browser before actioning the post-purchase upsell offer), then the fulfillment hold is lifted one hour after submission of the initial checkout. Fulfillment holds are only supported using the FulfillmentOrder resource.
- Interaction with the thank you page. The post-purchase page shouldn't be used as a replacement for the thank you page. For more information, refer to the customer flow.
- Tracking and status functionality. You can't add any order tracking or status functionality on the post-purchase page.
- API versioning. The post-purchase checkout extension APIs aren't versioned and don't follow the Shopify API versioning quarterly release schedule.