Install & Setup
Overview
For upsell widgets to appear on the live store, merchants need to complete three main steps:
- Install GemUpsells and grant the required permissions.
- Enable the GemUpsells app embed in their Shopify theme.
- Create and publish a funnel.
Install the app
- Go to the Shopify App Store and install GemUpsells.
- Shopify displays the installation screen and requested permissions. Review and approve them.
- Open GemUpsells from Shopify admin (Apps → GemUpsells). The app uses your Shopify account for authentication, so you don't need to create a separate account.
Why does GemUpsells need these permissions?
| Permission | Purpose |
|---|---|
| Read products and collections | Select products and collections in pickers and configure display conditions. |
| Read and create discounts | Create funnel discounts and product discounts through Shopify. |
| Read orders | Display analytics and track order counts for plan usage limits. |
| Read themes | Check whether the GemUpsells app embed is enabled. |
| Write files | Upload images and icons from the editor to your store's Shopify Files. |
| Read products through the Storefront API | Display products, prices, and subscription options at Checkout, Post-purchase, and Thank you. |
GemUpsells does not request permission to edit your theme. It does not modify your theme's code.
Default setup in GemUpsells
When you open GemUpsells for the first time, the app automatically creates the following:
| Item | Initial status |
|---|---|
| Cart Drawer | Draft |
| Popup on ATC | Draft |
| Global Style | Default |
The Cart Drawer and Popup on ATC remain in Draft until you publish them. You can publish both directly from the funnel publishing popover.
Enable the app embed
The app embed acts as a switch that allows GemUpsells to run on your Shopify theme.
By default, the app embed is disabled. GemUpsells cannot enable it automatically because the app does not have permission to modify your theme. You must enable it manually once.
To enable the app embed
- Click Enable now in the Activate GemUpsells app in theme editor popup. Alternatively, use the banner on the Home page if you have dismissed the popup, or enable it directly from Shopify's Theme Editor.
- Shopify opens the Theme Editor with the GemUpsells app embed already switched on.
- Click Save in the Theme Editor to apply the changes.
Once saved, GemUpsells can run on your storefront.
Set up Checkout, Thank you, and Post-purchase
These touchpoints are part of Shopify's checkout flow, so they require additional setup in Shopify. GemUpsells cannot insert widgets into these pages automatically.
| Touchpoint | Requirement | Setup instructions |
|---|---|---|
| Checkout | The store must be on Shopify Plus. | Open the checkout editor using Set up on Checkout on the widget. Add a GemUpsells app block, enter the widget's Widget ID, and save. |
| Thank you | The store must be on Shopify Plus. | Follow the same steps as Checkout, using Set up on Thank you to open the relevant editor. |
| Post-purchase | GemUpsells must be selected as the store's post-purchase app. | In Shopify, go to Settings → Checkout → Post-purchase page, select GemUpsells, and save. |
Checkout and Thank you
Only Shopify Plus stores can add upsell app blocks to Checkout and Thank you pages.
Stores that are not on Shopify Plus cannot display GemUpsells widgets at these touchpoints, even if the funnel has been published. For non-Plus stores, the Checkout canvas displays the banner "Checkout upsells require Shopify Plus".
Keep the following in mind:
- Each widget requires its own app block with the correct Widget ID. To copy an ID, open the widget's … menu on the canvas.
- Subscription Line Item at Checkout is an exception. It does not require a separate app block or Widget ID. You only need to enable its display position below the product line item once in the checkout editor.
- GemUpsells cannot verify whether the required app blocks have been added. Publishing may succeed even if a widget is missing from the Shopify editor. In that case, the widget will not appear on the storefront.
Post-purchase
You must select GemUpsells as your store's post-purchase app to display Product Offers (PPO).
Shopify allows only one post-purchase app to run on a store at a time. Once GemUpsells is selected, its Product Offer page can appear immediately after checkout and before the Thank you page.
If GemUpsells is not configured as the post-purchase app:
- Customers will not see GemUpsells Product Offers.
- You cannot publish a funnel that contains a Post-purchase widget. The publishing popover displays the error "Post-purchase app is not set up".
- Click Setup in Shopify in the error message to open Shopify's Checkout settings.
If your store already uses another post-purchase app, selecting GemUpsells will replace it.
Important rules
- The app embed must be enabled. Without it, GemUpsells widgets will not run on your storefront, including Popup on ATC and Cart Drawer. Funnel publishing is also blocked at the Checking theme setup step.
- Each store can use a free trial only once per user, across all plans. If you have already used a trial on one plan, you cannot start another trial on a different plan.
- The order-counting cycle starts on your first subscription date and resets every 30 days.
- Upsells are paused when you reach your order limit or your free trial ends. They remain paused until your billing cycle resets or you upgrade your plan.
- Billing follows a 30-day cycle and is prorated. All billing is handled through Shopify.
Current limitations
- The GemUpsells app embed must be enabled manually in Shopify's Theme Editor.
- Reload the GemUpsells browser tab to refresh the app embed status and display the latest state.