# Post-purchase best practices
Source: https://docs.aftersell.com/aftersell/best_practices

A complete strategy guide for building, optimizing, and scaling your post-purchase upsell funnels in Aftersell

# Post-purchase best practices

This guide covers everything you need to build a high-performing post-purchase upsell strategy in Aftersell - from funnel architecture and product selection to discount strategy, copy and design, industry-specific playbooks, and testing.

Whether you are setting up your first funnel or optimizing an existing setup, these best practices are based on patterns from top-performing Aftersell merchants.

<Tip>
  Want real-world examples from top brands? [Download our Upsell Playbook](https://www.aftersell.com/upsell-playbook) for proven strategies and case studies you can apply to your store today.
</Tip>

<Note>
  Looking for checkout widget best practices? See [Checkout Best Practices](/aftersell/checkout_best_practices).
</Note>

***

## Funnel architecture

Your funnel architecture determines which customers see which offers, and in what order. Getting this right is the single biggest lever for post-purchase revenue.

### How the post-purchase funnel flow works

Before building funnels, make sure you understand how the offer flow works. For a full walkthrough, see [Post-purchase Overview](/aftersell/post_purchase_overview).

In short: after checkout, Upsell #1 is shown. If the customer accepts, Upsell #2 is shown as a follow-up. If the customer declines, a Downsell is shown instead. After all offers are completed, the customer lands on the Thank You Page.

<Warning>
  Shopify limits customers to a maximum of 3 accepted post-purchase offers per order. Only one product can be selected per upsell step. Plan your funnel depth with these limits in mind.
</Warning>

### Start with your hero products

Build dedicated funnels for your 3 to 6 highest-volume products first. These are the items that generate 60 to 80% of your store's revenue, and targeting them ensures your highest-traffic orders always see a relevant, optimized upsell.

Traits of a hero product:

* High sales volume and strong contribution to profitability
* Market leadership in their category
* Broad customer appeal and positive reviews
* Receives dedicated marketing efforts and promotion

### Set up a catch-all funnel

A catch-all funnel ensures that every order - even those that do not match your hero product funnels - still sees an upsell offer. This is one of the most commonly missed steps, and skipping it means leaving revenue on the table.

How to set it up:

1. Set the trigger to "Show for All Customers"
2. Assign it the **lowest priority** so it only fires when no other funnel matches
3. Include Thank You Page upsells in this funnel for full post-purchase coverage

You can adjust funnel priority by clicking the **Manage Priority** button at the top right of the funnel table.

### Use Smart Funnel as your first layer

[Smart Funnel](/aftersell/smart_funnel) uses Rokt's AI and machine learning models to automatically select the most relevant upsell offer for each customer. It evaluates at Priority 0 (before all manual funnels), making it a powerful first layer in your strategy.

We recommend enabling Smart Funnel alongside your manual funnels. It handles the dynamic targeting automatically while your manual funnels cover specific use cases, Thank You Page offers, and edge cases Smart Funnel does not reach.

<Note>
  Smart Funnel currently only supports English. If your store serves customers in other languages, use manual funnels for those audiences until multilingual support is available.
</Note>

### Add follow-up offers to your funnel

Do not stop at the first offer. A well-structured funnel includes offers on both the accept and decline paths:

* **Upsell #1** - Your primary offer (highest-margin or most complementary product)
* **Upsell #2** (accept path) - Shown when Upsell #1 is accepted. Use this for an additional complementary product or a related add-on
* **Downsell #1** (decline path) - Shown when Upsell #1 is declined. Use this for a lower-price alternative or a smaller version of the original offer
* **Thank You Page offers** - Product recommendations and upsells on the order confirmation page, shown to every customer regardless of what happened on the post-purchase page

This means every customer sees at least two offers (one on the accept or decline path, plus the Thank You Page), and customers who engage see even more.

<Tip>
  Use AI-powered product recommendation widgets on the Thank You Page to keep engagement high. These widgets automatically surface relevant products based on what the customer purchased, without any manual configuration required.
</Tip>

### Manage funnel priority intentionally

When multiple funnels match the same order, Aftersell uses the priority order to determine which one fires. Review your priority list regularly:

* Hero product funnels should have higher priority than your catch-all
* Smart Funnel always evaluates at Priority 0 (highest)
* Seasonal or promotional funnels should be temporarily elevated during campaigns

***

## Product selection

Choosing the right products to upsell has a direct impact on conversion rate. The goal is relevance - customers are far more likely to accept an offer that feels like a natural extension of what they just bought.

### Complementary products outperform same-product offers

Upselling a complementary product (for example, sandals with a dress, a phone case with a phone, a serum with a moisturizer) consistently outperforms offering the same product the customer just purchased. The exception is consumable or replenishable products where buying a second unit makes sense.

### Strategic product placement across the funnel

Since the funnel flow is based on accept and decline actions, think strategically about what goes where:

* **Upsell #1:** Your strongest, most complementary offer with the highest expected conversion rate
* **Upsell #2 (accept path):** The customer just said yes - they are engaged. Show a second complementary item or a related add-on. This is a warm audience
* **Downsell #1 (decline path):** The customer said no to the first offer. Show a lower-price alternative, a smaller size, or a different product category. Reduce the commitment level to recover the conversion

### AI recommendations vs. manual selection

Aftersell supports both AI-powered and manually selected product offers:

* **AI recommendations (automatic upsells)** use Shopify's Recommendation API to suggest complementary products based on the customer's order. The recommendations consider factors like purchase correlation, order frequency, and product affinity. For stores with very few orders or recently added products, Shopify may not have enough data to generate recommendations - in that case, you can manually add related products in the Shopify Search & Discovery app. You can exclude products from automatic upsells by selecting collections under **Settings > Automatic upsells > Excluded products** - products in the selected collections are not used.
* **Manual selection** gives you full control over exactly which products appear. This is best for curated campaigns, seasonal promotions, or when you know your catalog deeply.

<Tip>
  When using automatic upsells (AI recommendations), you can enable a setting to skip the offer if the product already exists in the original order. In Smart Funnel, this is the "Skip Products in Original Order" toggle. In regular funnels, this is in the Product Details widget settings. We recommend keeping this enabled to avoid offering the customer a product they just purchased. This setting does not apply to the Most Expensive or Least Expensive in Cart product types, which are designed to re-offer items from the original order.
</Tip>

We recommend A/B testing AI vs. manual to see which performs better for your store. Many merchants find that AI outperforms manual selection for high-traffic, diverse catalogs, while manual selection wins for stores with a smaller, curated product line.

### Quantity defaults

For lower-cost or consumable products, test offering a default quantity of 2 instead of 1. If the x2 offer is accepted more often, it means increased revenue with no extra effort. This works especially well for supplements, food items, skincare, and other replenishable goods.

***

## Discount strategy

Discounts are one of the strongest levers for post-purchase conversion, but the approach matters more than the amount.

### Always offer a discount on post-purchase upsells

Post-purchase offers convert significantly better with a discount than without one. The customer has already committed to a purchase and is in a buying mindset - a discount at this moment feels like a reward, not a sales tactic.

<Note>
  For best performance, set a non-zero Max Discount for Smart Funnel. Smart Funnel templates do not dynamically adjust based on the discount field value, so a non-zero Max Discount tends to convert best.
</Note>

### Use compare-at pricing

Enable compare-at pricing to visually emphasize the value of your upsell offer. Displaying a higher "compare at" price alongside a lower discounted price makes the deal feel more compelling, even with a smaller actual discount.

Example:

* Regular price: \$20
* Compare at price: \$25
* Customer sees: ~~\$25~~ \$20

<Warning>
  The visible discount percentage may differ from what you set in upsell settings when "Use Compare at Price" is enabled, since the compare-at price can inflate the perceived discount. Always double-check how it renders on the page by placing a test order.
</Warning>

### Round your discount percentages

Always round to the nearest 5th - for example, offer 25% or 30% instead of 27%. Round numbers look more intentional and can boost conversion rates.

### Finding the right discount level

A/B test different discount levels to find the sweet spot for your store. The goal is to determine how low you can set the discount without hurting your conversion rate. Common starting points by category:

* **Fashion and apparel:** 10-20% off
* **Supplements and health:** 15-25% off
* **Beauty and skincare:** 10-20% off
* **Food and beverage:** 15-25% off
* **Electronics and accessories:** 5-15% off
* **Home goods:** 10-20% off

These are starting ranges for testing - your optimal discount depends on your margins, product pricing, and customer behavior.

### Discount strategy across the funnel

Consider varying your discount by funnel position:

* **Upsell #1:** Your standard discount (for example, 15% off)
* **Upsell #2 (accept path):** Can be the same or slightly lower - the customer is already engaged and buying
* **Downsell #1 (decline path):** Consider a slightly higher discount to recover the customer who just said no. A bigger discount on a lower-price item can be very effective here

### When to use percentage vs. fixed dollar discounts

* **Percentage discounts** work better for higher-priced items where the dollar savings feel significant (for example, "20% off" on a \$100 item = \$20 saved)
* **Fixed dollar discounts** work better for lower-priced items where a percentage feels small (for example, "\$5 off" feels better than "10% off" on a \$50 item)

A/B test both formats to see which resonates with your customers.

***

## Copy and design

First impressions are crucial on post-purchase pages. Customers make snap judgments, so your value proposition needs to be impossible to miss.

### Emphasize key points with bold text and color

Draw attention to the most persuasive elements of your upsell page. Phrases worth highlighting:

* The discount percentage or dollar amount
* "LIMITED TIME" or urgency language
* Countdown timers
* Free shipping mentions

### Write clear, benefit-focused headlines

Your headline should tell the customer exactly what they are getting and why it matters. Lead with the benefit, not the product name.

* Good: "Complete your look - 20% off matching accessories"
* Avoid: "You might also like these products"

### Configure your accept and decline buttons intentionally

The [Buttons widget](/aftersell/post_purchase_widgets) gives you control over how the accept and decline buttons behave and appear. However, Shopify requires that the accept and decline button text follows strict guidelines - the button wording cannot be customized, only translated into a selected language.

What you can configure:

* **Accept button text** - Choose between "Pay Now" (displays "Pay now - Product total price") or "Accept Offer" (displays "Accept offer - Product total price")
* **Button language** - Select from all supported Shopify Checkout locales to automatically translate both accept and decline button text into the customer's language
* **Button layout** - Choose accept above decline, decline above accept, or side by side
* **Decline button style** - Secondary or link format
* **Button alignment and width** - Adjust positioning to match your offer design
* **Supporting text** - Add optional text above or below the buttons with styling controls and dynamic variable support

<Warning>
  The accept and decline button text cannot be freely written or customized beyond the two options listed above. This is a Shopify platform restriction, not an Aftersell limitation. The decline button text is automatically set and can only be translated, not edited.
</Warning>

### "Require Confirmation Click to Accept"

"Require Confirmation Click to Accept" is available in the Buttons widget for individual offers. This setting adds a second confirmation step before an upsell is accepted. It is worth being aware of if you are using the Most Expensive or Least Expensive in Cart product types, which re-offer items from the customer's original order. If you find that customers are reaching out about unintended purchases on these offer types, this setting can help. It is not needed for all offers, as the additional step may reduce conversion rates.
[Learn more →](/aftersell/post_purchase_widgets)

### Long-form vs. short-form offer pages

* **Short-form pages** offer concise information, faster load times, and a streamlined experience. They work well for lower-priced, impulse-friendly products.
* **Long-form pages** provide detailed product descriptions, features, benefits, and additional images. They work better for higher-ticket products where customers need more information before committing.

We generally recommend starting with short-form and testing long-form for higher-ticket items.

### Multi-step offers within a single page

If you want to show multiple products on a single upsell page (for example, three accessories on Upsell #1), you can use [multi-step offers](/aftersell/how_to_create_a_multi_step_post_purchase_upsell). Multi-step splits a single page into sequential steps where each step shows a different product. If the customer declines a step, they see the next step on the same page. If they accept, they move to the next page in the funnel (for example, from Upsell #1 to Upsell #2).

Multi-step is only available for multi-product upsells and supports up to 12 products per page. We recommend keeping the number of steps minimal for a smooth customer experience.

***

## Thank You Page strategy

Not every order qualifies for Post-purchase upsells due to [Shopify's post-purchase restrictions](/aftersell/why_isnt_my_1_click_offer_displaying). Thank You Page upsells act as a fallback, ensuring those customers still see an offer. Unlike Post-purchase offers, Thank You Page offers work with all payment methods.

### Include Thank You Page offers in every funnel

Set up Thank You Page upsells in every funnel, including your catch-all. Each funnel's Thank You Page widgets must be configured individually - there is no way to standardize them across multiple funnels. This means if you have 5 funnels, you need to configure the TYP section in each one.

Step by step:

1. Open your funnel in the Aftersell admin
2. Scroll to the **Thank You Page** section
3. Click **Add Widget** and select **Product Recommendation**
4. Choose your product selection method, configure your discount, and save
5. Repeat for each funnel, including your catch-all

### Choose the right product selection method

Thank You Page product recommendation widgets support three selection methods. Choose the one that fits your store:

* **Automatic Upsells** - Lets Aftersell recommend products based on the customer's cart contents. This is the easiest option and tends to convert well because the recommendations are personalized to what the customer just bought. Start here if you are unsure which products to show.
* **Specific Products** - Manually select up to 10 products to display. Use this when you want full control, such as promoting a specific product, clearing overstock, or running a seasonal campaign.
* **Collections** - Display products from a specific Shopify collection. Use this when you want variety within a curated set (for example, showing items from the same collection the customer purchased from).

<Tip>
  Enable **Hide product if purchased** to avoid showing items the customer already bought, and **Hide out-of-stock variants** to only display available products. Both settings are in the product recommendation widget configuration.
</Tip>

### Apply a discount to your TYP offers

You can apply a percentage or fixed dollar discount directly within the TYP widget. We recommend always including a discount on Thank You Page upsells to give customers a reason to act. Use compare-at price display to visually show the savings.

### Set the right order handling method

When a customer accepts a Thank You Page upsell, you choose how the order is processed:

* **Modify original order** - Adds the upsell product to the existing order. Free shipping is automatically applied. Use this for a seamless experience where everything ships together.
* **Create new draft order** - Creates a separate order for the upsell. Use this if your fulfillment workflow requires separate orders, if you want to offer free shipping only on the upsell, or if your upsells overlap with products in the original order.

If your top-sellers are also your main upsell candidates, prefer **Create new draft order** - "Modify original order" silently hides upsells whose variant is already in the customer's order. Bundle products are also not supported with "Modify original order" - Shopify's order-edit API rejects them, so bundle upsells are either hidden or fulfilled as a separate draft order depending on your fallback behavior. See [Order Handling](/aftersell/thank_you_page_extensions_overview#order-handling) for the full trade-off breakdown.

### Use banner text to frame the offer

Add a short banner headline above your product recommendations to give customers context. Framing like "Complete the look," "Pairs well with your order," or "Customers who bought this also loved" performs better than showing products with no context.

### Add the app block in Shopify

After configuring your Thank You Page widgets in Aftersell, you must add the Aftersell TY widget app block to **both** the Thank You page **and** the Order Status page in your Shopify Editor, then enable it and save. Skipping this step will cause your Thank You Page widgets to not display for customers.

<Warning>
  This is one of the most common reasons Thank You Page widgets do not appear. If your TYP offers are not showing, check the Shopify Editor first before troubleshooting anything else.
</Warning>

***

## Upsell strategies by industry

Different product categories have different upsell dynamics. For detailed playbooks tailored to your vertical - including recommended products, discount ranges, funnel triggers, and testing priorities for fashion, supplements, food and beverage, beauty, electronics, home goods, and automotive - see [Post-Purchase Strategies by Industry](/aftersell/post_purchase_strategies_by_industry).

***

## Testing

A/B testing and multivariate testing are the most effective ways to improve funnel performance over time. See the full [Post-Purchase A/B Testing](/aftersell/post_purchase_a_b_testing) and [Post-Purchase Multivariate Testing](/aftersell/multivariate_testing) guides for detailed setup instructions.

### Key tests to prioritize

These are the highest-impact tests based on patterns from top-performing merchants:

1. **AI (dynamic) vs. specific product (static) upsells** - Determines whether automated product matching outperforms your manual curation
2. **Default quantity 1 vs. 2** - Especially impactful for consumables and lower-cost products
3. **Long-form vs. short-form offer pages** - Tests whether customers need more information or prefer a streamlined experience
4. **Same product vs. complementary product** - Tests repurchase vs. cross-sell
5. **Single product vs. multi-product** - Tests simplicity vs. choice
6. **Varying discount percentages** - Finds the minimum discount needed to maintain conversion rate

<Note>
  A/B testing for post-purchase uses Layout A through Layout E (up to 5 layouts). You cannot A/B test one funnel against another funnel - testing happens within a single funnel across layouts. A/B testing is only available for Post-purchase upsells and is not available for Thank You Page offers. For checkout widget testing, see [Checkout A/B Testing](/aftersell/checkout_a_b_testing).
</Note>

### Data guidelines

Before making changes to a funnel, ensure it has run for a minimum of 2 to 4 weeks or collected at least 100 to 200 impressions per layout. Changes made too early are based on insufficient data and can lead to misleading conclusions.

Regularly analyze performance data to refine offers, placements, and product selections. An iterative approach helps identify high-conversion strategies while ensuring all changes are based on reliable data.

Use the **Revenue per visit** metric as your primary performance indicator over time, as it accounts for unique visits rather than raw impressions.

***

## Common mistakes

Avoid these pitfalls when setting up and optimizing your post-purchase funnels:

❌ **No catch-all funnel** - some orders will never see an upsell because they do not match any funnel triggers. Set up a catch-all funnel with the "Show for All Customers" trigger at the lowest priority so every order sees an offer.
[Fix it →](/aftersell/quickstart_guide_to_aftersell)

❌ **No Thank You Page upsells** - orders that are ineligible for Post-purchase offers (due to Shopify payment method restrictions) go unconverted. Add Thank You Page upsells to every funnel, including your catch-all. Make sure to add the Aftersell TY widget app block to both the Thank You page and Order Status page in your Shopify Editor.
[Fix it →](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell)

❌ **No downsell configured** - if a customer declines Upsell #1 and there is no downsell on the decline path, you have missed a second chance to convert. Always configure a downsell with a lower-price alternative for the decline path. You can add a downsell in the funnel editor when building your post-purchase funnel.
[Fix it →](/aftersell/post_purchase_overview)

❌ **Irrelevant upsell offers** - generic offers that do not relate to what the customer bought reduce conversions and erode trust. Use collection-based triggers and complementary product selection to match offers to what the customer purchased.
[Fix it →](/aftersell/how_to_configure_post_purchase_triggers)

❌ **Underutilizing AI tools** - missing out on dynamic personalization that often outperforms manual selection, especially for stores with large or diverse catalogs. Enable Smart Funnel and test AI recommendations in your manual funnels.
[Fix it →](/aftersell/smart_funnel)

❌ **Making changes too early** - optimizing before collecting enough data leads to decisions based on noise rather than signal. Wait for at least 2 to 4 weeks or 100 to 200 impressions per layout before drawing conclusions.
[Fix it →](/aftersell/analytics_in_aftersell)

❌ **Not testing** - running the same offer indefinitely without testing leaves performance gains on the table. Run at least one A/B test per quarter on your highest-traffic funnels.
[Fix it →](/aftersell/post_purchase_a_b_testing)

***

## Need help?

If you have questions about setting up or optimizing your post-purchase upsell strategy, chat with our support team using the live chat at the bottom right of the app.


# Add-to-cart interception
Source: https://docs.aftersell.com/aftersell/cart/add-to-cart-interception

Why Aftersell takes over add-to-cart, how to tell whether a form is intercepted, and every way to opt a form out.

When a shopper clicks **Add to cart**, Aftersell usually handles the add itself instead of letting the theme do it. This page explains why, what it means for scripts you've added, and how to turn it off for one form or for all of them.

Most stores never need to change any of this. Read on if a script of yours stopped firing on add-to-cart, or if an add-to-cart button behaves oddly.

## What interception does

Aftersell listens for the add-to-cart submit before the theme does. When it recognizes one, it:

1. Stops the event, so nothing else on the page handles that click.
2. Sends the add to Shopify itself.
3. Opens the Aftersell Cart drawer.

Step 1 is the important one, and it's the reason this page exists.

## Why it exists

Without it, both carts respond to the same click. The theme adds the item and opens its own drawer, Aftersell adds it and opens ours, and the shopper sees two carts, often with the item added twice.

Stopping the event is the simplest way to guarantee one add and one cart.

## What it costs

Stopping the event stops it for **everyone**, not just the theme. Any other code listening to that same add-to-cart stops running: your analytics, a tracking pixel, a subscription or bundle app, a script you added yourself.

It fails quietly. Nothing appears in the browser console, and the add itself still works, so the usual symptom is a number that's wrong rather than something visibly broken:

* `add_to_cart` events missing from GA4, Meta, or TikTok
* A subscription or bundle app that works on the product page but not through the cart
* Your own `addEventListener` on the form never firing

If any of that sounds familiar, this page is the cause and the fix is below.

## When Aftersell doesn't intercept

Interception isn't always on. Aftersell leaves add-to-cart alone when:

* **It recognizes your theme's cart.** On themes Aftersell knows how to work with, it makes the theme's own cart inert instead of blocking the event, then lets the theme perform the add normally. Your scripts run as they always did. See [Which themes](#which-themes-aftersell-recognizes) below.
* **The form doesn't add a line item.** A form with no variant `id` and no `items[]` is left alone.
* **You've opted out** using one of the methods below.

When Aftersell doesn't perform the add, it still watches for the cart request and opens the drawer when it sees one. See [Before you choose: what changes](#before-you-choose-what-changes).

## Which themes Aftersell recognizes

| Theme                                          |                                                                                             |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Dawn** and the rest of Shopify's free family | Craft, Colorblock, Crave, Origin, Publisher, Refresh, Ride, Sense, Spotlight, Studio, Taste |
| **Horizon**                                    | Shopify's current default theme                                                             |
| **Impulse**                                    |                                                                                             |

Aftersell matches on **how a theme is built**, not on its name, so a custom theme forked from any of these is normally recognized too, including private builds Aftersell has never seen.

<Note>
  The reverse also happens: a heavily customized build can drift far enough from its parent that Aftersell no longer recognizes it, even though the theme is still called "Dawn". Being on this list makes recognition likely, not certain.
</Note>

## Your options

Choose the narrowest one that solves your problem. Each row gives up more than the one above it.

| Option                                                               | Scope                     | Aftersell still opens the drawer |
| -------------------------------------------------------------------- | ------------------------- | -------------------------------- |
| [`registerSkipAddToCartRule`](#per-form-a-rule-in-code)              | The forms your rule picks | Yes, from the cart request       |
| [`aftersell-cart-skip-atc`](#per-form-a-class-in-your-theme)         | One form or button        | Yes, from the cart request       |
| [`skip_add_to_cart_interceptor`](#whole-store-turn-interception-off) | Every form on the store   | Yes, from the cart request       |

### Before you choose: what changes

Opting out hands the add back to your theme, which raises two questions worth answering before you pick a row: whether your cart still opens, and whether the theme's cart turns up next to it.

#### Will your cart still open?

Usually yes, with no work on your part. Whoever performs the add, Aftersell watches for the request going to Shopify and opens the drawer when it sees one, following your normal **Open cart when an item is added** setting. You don't have to call anything yourself.

Three situations break that, and all three have a fix:

**The add goes somewhere other than Shopify's cart endpoints.** Aftersell watches `/cart/add`, `/cart/change`, `/cart/update` and `/cart/clear` on your own domain. An app that adds through its own endpoint and syncs the cart afterwards isn't visible to this. Open the cart yourself once that app's add finishes:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.actions.refresh().then(() => {
  window.aftersell.cart.actions.open();
});
```

**More than about three seconds pass between the click and the request.** Aftersell treats an add that closely follows a real click or keypress as shopper-driven. Beyond that window it's considered a background add, which doesn't open the drawer unless you opt in:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.configure({ open_on_background_add: true });
```

**Your cart setting says not to.** If **Open cart when an item is added** is off, or you've set `open_on_add_to_cart: 'never'`, nothing opens the drawer. That's working as configured.

#### Will the theme's cart open too?

This is the risk the opt-outs carry, and the answer depends on your theme.

Making the theme's cart inert is **separate from interception** and happens at page load either way, so none of the opt-outs here switch it back on. On a theme from the [recognized list](#which-themes-aftersell-recognizes), the theme's own cart stays quiet and the shopper sees one cart, yours.

On a theme Aftersell doesn't recognize, there's nothing holding the theme's cart back. Opting out means the theme handles the add exactly as it always did, including opening its own drawer or redirecting to `/cart`, while Aftersell opens its drawer from the request it saw. That's two carts, and it's the reason interception exists in the first place.

If that happens, you have three choices: leave interception on for that form, use a narrower opt-out that doesn't cover the forms causing it, or stop the theme's own cart yourself in your theme code.

<Tip>
  Turn an opt-out on in a test or unpublished theme first. If the theme's own cart appears where it didn't before, your theme isn't one Aftersell recognizes, and you'll want to keep interception on for those forms.
</Tip>

<Note>
  This applies to add-to-cart only. Making the **cart icon** bypass Aftersell with the `aftersell-cart-wont-open-cart` class is different: a cart-icon click sends no request, so there's nothing for Aftersell to watch, and the drawer will not open. See below.
</Note>

### Per form: a rule in code

The preferred option. Register a rule that returns `true` for the forms you want left alone:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerSkipAddToCartRule((form) =>
  form.hasAttribute('data-skip-aftersell')
);
```

Put it in **Cart settings → Custom script → Initialization**. Rules are additive: yours runs alongside any others, and any rule returning `true` skips that form. Full details in [Hooks](/aftersell/cart/sdk-hooks#registerskipaddtocartrule).

### Per form: a class in your theme

If you'd rather not write a rule, add the `aftersell-cart-skip-atc` class in your theme:

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<form action="/cart/add" method="post" class="aftersell-cart-skip-atc">
```

<Note>
  For a form submit, the class must be on the **form element itself**. A parent `div` won't work. For a button that adds to the cart without a form submit, the class can be on the button or any element around it.
</Note>

### Whole store: turn interception off

The blunt option. Add-to-cart behaves exactly as your theme originally did, on every form:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.configure({ skip_add_to_cart_interceptor: true });
```

<Warning>
  This one is read **once, when the cart loads**. It only works from your cart's **Initialization** script. Setting it later, inside `ready()` or from an event handler, does nothing and fails silently.
</Warning>

Reach for this only when the per-form options don't fit, for example when the forms you need to exempt are created by another app and you can't identify them reliably.

## The cart icon is separate

The cart icon in your header is handled by its own interceptor, with its own opt-out. Turning off add-to-cart interception does not change what the cart icon does, and the reverse is also true.

Clicking the cart icon opens the Aftersell drawer instead of going to `/cart`. To leave one icon or button alone, add the `aftersell-cart-wont-open-cart` class to it, or to any element around it:

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<a href="/cart" class="aftersell-cart-wont-open-cart">Cart</a>
```

That control then does whatever your theme makes it do, usually going to the cart page. Aftersell is out of the picture entirely, so **the drawer will not open**. Unlike add-to-cart there's no request to watch for, so if you want your cart to open from that control you have to say so:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
document.querySelector('#my-cart-link').addEventListener('click', (event) => {
  event.preventDefault();
  window.aftersell.cart.actions.open();
});
```

The same silencing problem applies here: because Aftersell stops the click, your analytics and pixels don't see cart-icon clicks either. If that's all you need to fix, keep the drawer and stop the silencing:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.configure({ skip_open_cart_interceptor: true });
```

Your listeners run, the drawer still opens, and the click still doesn't navigate to `/cart`. Full details in [Configure](/aftersell/cart/sdk-configure#skip_open_cart_interceptor).

<Note>
  To change *which* elements open the cart rather than turning them off, use **Cart settings → Advanced → Cart icon selector** instead of editing your theme.
</Note>

## Where to go next

* **[Configure](/aftersell/cart/sdk-configure)**: every SDK option, including the ones referenced here.
* **[Hooks](/aftersell/cart/sdk-hooks)**: per-form and per-line control.
* **[Open the drawer from a page builder](/aftersell/cart/sdk-use-case-page-builder)**: for Replo, PageFly, GemPages, and custom buttons that add to the cart their own way.


# Cart analytics
Source: https://docs.aftersell.com/aftersell/cart/analytics

Read per-cart performance for your Aftersell Cart — revenue, impressions, conversion, and top products.

The **Analytics** page reports how your published carts are performing. This page covers the **cart** view — for per-variant test metrics, see [Test analytics](/aftersell/cart/test-analytics).

## Per-cart metrics

Each cart's performance is shown over a date range you choose, with a change badge comparing it to the previous equal-length period:

| Metric                      | What it means                                                                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Revenue**                 | Revenue generated by the cart, shown as a stacked-area chart with a combined total. Add-ons and Upsells are displayed as separate stacked bands. |
| **Cart impressions**        | Unique times shoppers saw the cart.                                                                                                              |
| **Checkouts completed**     | Orders completed from the cart.                                                                                                                  |
| **Conversion rate**         | Completed checkouts over impressions.                                                                                                            |
| **Subscription upgrades**   | The **count** of subscription upgrades (not a revenue figure).                                                                                   |
| **Top performing products** | The best-selling upsell and add-on products, with quantity and revenue.                                                                          |

An **overall** view also offers a **Compare** toggle to overlay the previous period.

## How the data is collected

Analytics are built from your orders. When an order completes, Aftersell attributes it back to the cart and records impressions, conversions, and revenue, which roll up into the reports.

Conversion rate is a straight per-day ratio: completed checkouts over cart impressions for each day in the range.

## Exporting

The **Revenue**, **Conversion rate**, and **Subscription upgrades** charts each have an **Export to CSV** button that downloads the displayed series (including the comparison series if Compare is on). The KPI cards and Top products don't currently export.

## A note on revenue coverage

The revenue figures count **upsell** and **add-on** revenue only — every revenue query on this page filters to those two categories. Subscription upgrades are reported separately, as a conversion count rather than a revenue figure, because the value recurs.

This is a subset of everything your cart earns, not a full partition of it, so these figures won't reconcile against a store-wide revenue total.


# Banner block
Source: https://docs.aftersell.com/aftersell/cart/banner-block

The Aftersell Cart Banner block: a message banner shown inside the drawer, with an optional countdown timer.

> The **Banner** block is a message strip shown inside the cart, useful for promotions, shipping messages, or urgency prompts such as a free-shipping notice, a sale announcement, or a "cart reserved" prompt. It can include a live countdown timer.

<Frame>
  <img alt="Banner block in the Aftersell cart drawer showing a reservation countdown message" />
</Frame>

## Behavior

* **The countdown only runs when all three conditions are met:** the timer is enabled, the text contains the `{{timer}}` token, and the duration is greater than zero. Otherwise the banner shows as static text.
* The timer counts down in `MM:SS` and is remembered for the shopper's tab (it survives navigation within your store during the session), so it doesn't restart on every page.
* **When the timer reaches `00:00`, the entire banner disappears**, so shoppers never see a zeroed-out clock.
* In the editor preview the timer loops and the banner never hides, so you can keep styling it.

## Settings

| Setting                   | What it controls                                                                                                                         | Default                                        |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| **Text**                  | The rich-text message. Include the `{{timer}}` token to show a countdown.                                                                | `Your cart is reserved for {{timer}} minutes!` |
| **Countdown timer**       | Turns the countdown on or off.                                                                                                           | On                                             |
| **Minutes** / **Seconds** | How long the countdown runs. Two number fields, shown once **Countdown timer** is on and displayed as `MM:SS` where `{{timer}}` appears. | 10 minutes                                     |

The text is translatable.

## Placement and limits

* **Region:** any (top, body, or bottom).
* **Maximum:** 3 per cart state — the filled cart and the empty cart each get their own allowance.
* **State:** both filled and empty cart.
* Added to new carts by default. Not locked, so you can remove or hide it.

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

| Prop                          | Type      | What it's for                                                                                                                 |
| ----------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `text`                        | `string`  | The banner message as sanitized HTML, with the `{{timer}}` token **already replaced** by the live countdown.                  |
| `shouldUseTimer`              | `boolean` | `true` when the countdown is running for this banner.                                                                         |
| `isTimerExpiredAndShouldHide` | `boolean` | `true` once the countdown has reached zero.                                                                                   |
| `isLoading`                   | `boolean` | Always `false` here: the block renders its built-in skeleton during load and only calls your template once the cart is ready. |

There's no separate `timer` prop. The countdown is interpolated into `text` for you, so rendering `text` is enough.

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomTemplate(props) {
  // The built-in banner removes itself at 00:00; a custom template must do the same.
  if (props.shouldUseTimer && props.isTimerExpiredAndShouldHide) return null;

  return (
    <div className="cart-external-banner" style={{ padding: '10px', textAlign: 'center' }}>
      <span dangerouslySetInnerHTML={{ __html: props.text }} />
    </div>
  );
}
```

<Warning>
  That early return matters. Without it your banner keeps rendering after the timer expires, and because the token is already substituted, shoppers see a frozen `00:00`.
</Warning>

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

### Text

The **Text** section in Design lets you control the typography of the banner message. Bold and text color are set in the Rich Text Editor above (in the Settings tab), not here.

| Setting            | What it controls                 | Default             |
| ------------------ | -------------------------------- | ------------------- |
| **Font**           | Font family for the banner text. | Inherits from theme |
| **Size**           | Font size.                       | `14px`              |
| **Line height**    | Line height multiplier.          | `1.4`               |
| **Letter spacing** | Tracking between characters.     | Normal              |

### Style

| Setting              | What it controls                                                    | Default     |
| -------------------- | ------------------------------------------------------------------- | ----------- |
| **Background color** | The banner's background fill.                                       | `#000000`   |
| **Text color**       | Fallback text color (overridden by the Rich Text Editor).           | `#ffffff`   |
| **Border**           | Whether the banner has a border — **None** (0px) or **Show** (1px). | None        |
| **Border color**     | Color of the border when **Show** is selected.                      | Transparent |

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# How do blocks work?
Source: https://docs.aftersell.com/aftersell/cart/blocks-overview

Understand Aftersell Cart blocks: sections and sub-blocks, filled vs empty, limits, locked blocks, conditions, and per-block settings.

Your cart's layout is a stack of **blocks**: configurable pieces you add, reorder, style, and customize in the cart editor. Which blocks you include, and in what order, is the cart shoppers see.

For how blocks sit inside **states** and **sections**, see [How do carts work?](/aftersell/cart/how-carts-work).

## Blocks and sub-blocks

There are two kinds of block:

* **Blocks** sit directly in the cart, in one of three sections: **Header**, **Body**, or **Footer**. Each section offers a different set of blocks.
* **Sub-blocks** nest inside another block. Today only [**Cart items**](/aftersell/cart/cart-items-block) hosts sub-blocks: the **Product** row (the line-item row itself), [**Subscription upgrade**](/aftersell/cart/subscription-upgrade-block), and [**Custom code**](/aftersell/cart/custom-code-blocks).

## Adding, reordering, and removing blocks

* **Add** a block with the **Add block** picker. A block is greyed out if it can't go where you're adding it, or if you've reached its limit (the picker shows a `count/max` badge).
* **Reorder** by dragging a block within its section.
* **Remove** with the trash icon, except locked blocks (below).
* **Show/hide** most blocks with the eye toggle, which hides a block from shoppers without deleting it. A few structural blocks can't be hidden: **Cart items**, **Checkout button**, and the **Product** row.

## Locked blocks

Some blocks can be reordered but not deleted, so core cart behavior (for example, checking out) can't be removed by accident:

* **Cart items**
* **Checkout button**

## Default blocks

New carts start with a working default layout:

* **Filled cart:** Header, Banner, Cart items, Summary, Checkout button
* **Empty cart:** Header, Empty cart block

<Info>
  The **empty cart state** is the whole empty layout. The **Empty cart block** is one block inside it. See [How do carts work?](/aftersell/cart/how-carts-work) for the difference.
</Info>

## How many of each block you can add

Limits are counted **per cart state**, not per cart. The filled cart and the empty cart each get their own allowance, so a cart can hold three Banners in its filled layout and three more in its empty layout.

Most blocks are limited to one per state. The exceptions:

| Block          | Maximum per cart state |
| -------------- | ---------------------- |
| Banner         | 3                      |
| Image          | 3                      |
| Product add-on | 3                      |
| Summary        | 2                      |
| Custom code    | Unlimited              |

## Content, Design, and Code

Each block is configured through up to three surfaces in the editor:

* **Content**: the block's settings (text, product choices, thresholds, and so on). The **Custom code** block is the one exception: it has no Content panel because the block *is* the code.
* **Design**: per-block styling that layers on top of your global [**Design settings**](/aftersell/cart/design-settings). Every block has one except **Custom code**, which has no settings panel at all.
* **Code**: override the block's built-in rendering with a [**custom template**](/aftersell/cart/custom-templates). Most blocks support this; a couple don't.

## Show or hide by market, country, or currency

Some blocks can show different settings, or hide entirely, based on who the buyer is. That is separate from the sidebar **eye toggle**, which turns a block on or off for everyone.

|                  | **Eye toggle**                                | **Conditions**                                          |
| ---------------- | --------------------------------------------- | ------------------------------------------------------- |
| **What it does** | Hide or show the whole block for all shoppers | Pick which settings variant a shopper sees (or nothing) |
| **Based on**     | Your choice in the editor                     | Shopify market, customer country, or customer currency  |
| **Where**        | Sidebar eye icon on most blocks               | Settings panel for blocks that support conditions       |

**Supported condition types today:** Shopify market, customer country, and customer currency (each with **In** or **Not in**). Cart total and cart contents are **not** condition types. Use [Rewards](/aftersell/cart/rewards-block) tier thresholds for spend/quantity progress, or the [Cart SDK](/aftersell/cart/sdk-overview) when you need a rule the editor can't express.

Conditions are an ordered list: the **first matching** condition wins. Put specific rules above an **All buyers** catch-all. If nothing matches, the block renders nothing for that shopper.

**In the editor today**, the full Conditions UI ships on the [**Rewards**](/aftersell/cart/rewards-block#per-market-rewards) block: different tier sets per market, country, or currency. Other blocks either use a single “all buyers” configuration or don't participate in this system yet.

Editor preview does **not** evaluate the live buyer. Select a condition in the panel to preview that variant.

## All blocks

**Structure**

* [Header](/aftersell/cart/header-block): title, item count, logo, and close control, pinned to the top.
* [Cart items](/aftersell/cart/cart-items-block): the items customers add to cart; repeats per line.
* [Subscription upgrade](/aftersell/cart/subscription-upgrade-block): sub-block that offers to convert a line to a subscription.
* [Summary](/aftersell/cart/summary-block): totals, savings, and applied discounts.
* [Checkout button](/aftersell/cart/checkout-button-block): the primary call-to-action to checkout.
* [Empty cart](/aftersell/cart/empty-cart-block): the content shown when the cart is empty.
* [Express payments](/aftersell/cart/express-payments-block): accelerated checkout buttons (Shop Pay, PayPal, and so on) inside the cart.

**Merchandising**

* [Upsells](/aftersell/cart/upsells-block): strategy-picked product recommendations.
* [Product add-on](/aftersell/cart/product-add-on-block): a single specific product offered as an add-on.
* [Rewards](/aftersell/cart/rewards-block): tiered rewards such as free shipping or gifts.
* [Shipping protection](/aftersell/cart/shipping-protection-block): an opt-in shipping-protection add-on.

**Shopper input**

* [Discount code](/aftersell/cart/discount-code-block): a field to apply a discount code.
* [Notes](/aftersell/cart/notes-block): an order-notes field.

**Content**

* [Banner](/aftersell/cart/banner-block): a message banner, with an optional countdown timer.
* [Image](/aftersell/cart/image-block): a single image or a hosted preset such as payment icons.
* [Custom code](/aftersell/cart/custom-code-blocks): custom HTML or React anywhere in the cart.

**Extending**

* [Custom templates](/aftersell/cart/custom-templates): override how any block renders from its Code tab.

## Blocks available in each section

Each section has a different set of blocks available. That keeps the layout focused and reduces clutter.

| Section    | Blocks available                                                                                                                                    |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Header** | Header, Banner, Rewards, Image, Custom code                                                                                                         |
| **Body**   | Banner, Notes, Discount code, Cart items, Empty cart, Custom code, Rewards, Product add-on, Shipping protection, Image, Upsells                     |
| **Footer** | Banner, Notes, Discount code, Custom code, Rewards, Product add-on, Shipping protection, Express payments, Image, Upsells, Summary, Checkout button |

Some of those blocks are state-specific (for example Empty cart only in the empty state). See [How do carts work?](/aftersell/cart/how-carts-work).

## Block validation errors

If a block's settings contain an invalid value, a small red dot appears next to that block's name in the sidebar. The dot stays until you fix the problem. It isn't a dismissible notification.

While any block has an error, **saving is blocked**. The **Save** button stays clickable, but selecting it shows an error toast (*"Fix the errors in your cart blocks before saving"*) and jumps to the first block with a problem, opening its settings so you can correct the highlighted field. **Publish** additionally requires no unsaved changes, so it stays unavailable until a clean save succeeds.

Once the invalid field is corrected the dot disappears on its own, and saving proceeds normally.

<Note>
  Hidden blocks are still validated. A block you've hidden can hold an invalid setting, show an error dot, and block saving exactly like a visible one, so if saving is blocked and every visible block looks fine, check your hidden blocks.
</Note>


# Cart items block
Source: https://docs.aftersell.com/aftersell/cart/cart-items-block

The Cart items block: the line-item list, the Product row, and the host for nested sub-blocks.

> The **Cart items** block is the list of line items in the cart, rendering each product the shopper has added with its image, title, variant, price, quantity stepper, and remove control. It's a required block, and it's the container that hosts the cart's sub-blocks (the **Product** row, [**Subscription upgrade**](/aftersell/cart/subscription-upgrade-block), and [**Custom code**](/aftersell/cart/custom-code-blocks)), providing the structure that per-line sub-blocks attach to.

<Frame>
  <img alt="Cart items block showing line items with product image, title, variant, price, quantity stepper, and remove control" />
</Frame>

## The Product row

Inside Cart items sits the **Product** sub-block: the actual line-item row. It's locked and added automatically, so every Cart items block always has exactly one Product row that you can't remove; you reposition other sub-blocks around it. Its settings control how each line's pricing is displayed:

| Setting                                    | What it controls                                                                                                                                                                                                                                                                                                            | Default                                         |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| **Strike-through price**                   | Which price is shown struck through: **Compare-at or pre-discount, whichever is higher**, **Compare-at price**, **Pre-discount price**, or **No strike-through**.                                                                                                                                                           | Compare-at or pre-discount, whichever is higher |
| **Strike-through price for subscriptions** | The same choice for subscription lines, with two differences: an extra **Subscription compare-at price** option, and **Compare-at price** renamed **Product compare-at, then subscription compare-at**.                                                                                                                     | Compare-at or pre-discount, whichever is higher |
| **Savings label**                          | Whether savings show as an **Amount**, a **Percentage**, or are **Hidden**.                                                                                                                                                                                                                                                 | Amount                                          |
| **Bundle price**                           | How the displayed price is calculated for bundle lines. **Automatic** shows the total of all items in the bundle (or the main item's price when the other items are free). **Main item price only** shows only the main (anchor) item's price. This is a display label only — Shopify's cart total is always authoritative. | Automatic                                       |
| **Savings text**                           | The savings label. Supports the `{{value}}` token.                                                                                                                                                                                                                                                                          | `Save {{value}}`                                |

The row itself renders the product image (linking to the product page when available), title, variant, price and any struck compare-at price, a quantity stepper, and a remove button. Bundle lines show a disclosure list of their components.

### Text styling

The Product row includes a **Text** section in its Design settings. Use it to control the typography of individual text elements in each line item. Select a text element from the picker to adjust its settings:

| Setting            | What it controls                                                                                                                                          |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Text color**     | Color of the selected text element.                                                                                                                       |
| **Font**           | **Theme font** (inherits your theme's font) or **Custom font** (enter the name of a font your theme already loads). Available for **Product title** only. |
| **Size**           | Font size in pixels.                                                                                                                                      |
| **Weight**         | Font weight: Light, Regular, Medium, Semibold, or Bold.                                                                                                   |
| **Line height**    | Line height as a multiplier of the font size (for example, `1.4`).                                                                                        |
| **Letter spacing** | Letter spacing in pixels. Negative values tighten the text.                                                                                               |

The text elements you can style are grouped by category:

**Product**

* **Product title** — the product name on each line. Also supports a custom font family.
* **Variant** — the variant label (for example, *Size: Medium*).
* **Subscription plan** — the read-only plan label shown on subscription lines.

**Pricing**

* **Price** — the line's current price.
* **Compare-at price** — the struck-through original price.
* **Savings** — the savings label (for example, *Save \$5.00*). Size and line height only — bold and color are set in the Rich Text Editor above.

**Bundle**

* **Bundle toggle** — the disclosure header that expands a bundle's component list.
* **Bundle item title** — the title of each component inside a bundle.
* **Bundle item variant** — the variant label for each bundle component.

Leaving any field blank keeps the element's default value.

<Tip>
  Clicking a text element directly in the cart preview highlights it and opens its controls in the panel automatically.
</Tip>

### Discount tags design

The Product row includes a **Discount tags** section in its Design settings. Use it to style the discount tag pills that appear on each line item:

| Setting              | What it controls                          | Default   |
| -------------------- | ----------------------------------------- | --------- |
| **Background color** | Fill color of the discount tag pill.      | `#F1F1F1` |
| **Text color**       | Text color inside the discount tag pill.  | `#585858` |
| **Border radius**    | Corner rounding of the discount tag pill. | `6px`     |

These settings apply only to line-item discount tags in the Cart items block. Discount code tags in the [Summary block](/aftersell/cart/summary-block) are styled separately.

## Sub-blocks and how they position

Cart items is the only block that hosts sub-blocks. **Sub-blocks render once per line, inside every product row**, positioned relative to the pinned Product row:

* Sub-blocks ordered **before** the Product row appear **above** the product content in each line.
* Sub-blocks ordered **after** the Product row appear **below** the product content in each line.

So a [Subscription upgrade](/aftersell/cart/subscription-upgrade-block) placed after the Product row shows beneath each eligible line, not once at the bottom of the whole list.

## Behavior

* When the cart has no items, the drawer switches to the empty state and this block isn't shown.
* **One cart change runs at a time.** While a quantity update or removal is in flight, the row's controls are disabled to keep the cart consistent, then re-enabled once the change settles.
* Lowering a line's quantity below 1 removes it. A quantity the store rejects (for example, beyond available stock) re-syncs to the last valid value.
* **Bundles change as a unit.** Adjusting the quantity on a bundle's anchor line scales the whole bundle in one operation — if a child is included at 3 per anchor, taking the anchor from 1 to 2 takes that child to 6. Removing the anchor removes every member of the bundle at once.
* **Some bundles can't be re-quantified.** If any of a bundle's children is included at a fractional rate (1.5 per anchor, say), the quantity stepper on that bundle is locked: the +/− buttons and the quantity field are both disabled, and typed quantities aren't accepted. The bundle can still be removed.
* **Subscription lines show their plan.** When a line has a selling plan and the [Subscription upgrade](/aftersell/cart/subscription-upgrade-block) sub-block is turned off or not added, the Product row shows a read-only plan label beneath the variant — for example, *Delivers every month (save 30%)*. When that sub-block is enabled it presents the plan in its own picker, so the read-only label is suppressed rather than duplicated.

## Placement and limits

* **Region:** body.
* **Maximum:** 1 per cart state.
* **State:** filled cart only.
* **Locked and added by default.** Cart items can't be removed or hidden, only repositioned.

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

The **Cart items** container has no custom template. The **Product** row inside it does, and it's the richest surface in the cart: your template renders once per line.

### Line content

| Prop               | Type                        | What it's for                                                                                                                                                                                                  |
| ------------------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`            | `string`                    | Product title, as plain text.                                                                                                                                                                                  |
| `variantTitle`     | `string \| null`            | Variant label. `null` for single-variant products and native bundles.                                                                                                                                          |
| `url`              | `string \| null`            | Product page URL. `null` when the line shouldn't link out.                                                                                                                                                     |
| `imageUrl`         | `string \| null`            | Line image. `null` when the product has none.                                                                                                                                                                  |
| `quantity`         | `number`                    | Current quantity on the line.                                                                                                                                                                                  |
| `price`            | `string`                    | Line price, **already formatted**.                                                                                                                                                                             |
| `compareAtPrice`   | `string \| null`            | The struck-through "was" price, already formatted. `null` when there's nothing to strike.                                                                                                                      |
| `savingsHtml`      | `string \| null`            | Savings label as sanitized HTML. `null` when hidden or there's no saving.                                                                                                                                      |
| `discountTags`     | `string[]`                  | Titles of discounts on this line, e.g. `['Spring Sale']`. `[]` when none.                                                                                                                                      |
| `sellingPlanLabel` | `string \| null`            | Read-only subscription plan name. `null` when it's a one-time line, or when the [Subscription upgrade](/aftersell/cart/subscription-upgrade-block#custom-template) sub-block is rendering the plan UI instead. |
| `bundle`           | `object \| null`            | [Bundle](/aftersell/cart/sdk-cart-object#bundles) view model on an anchor line. `null` otherwise.                                                                                                              |
| `productId`        | `number`                    | Shopify product ID.                                                                                                                                                                                            |
| `variantId`        | `number`                    | Shopify variant ID.                                                                                                                                                                                            |
| `line`             | `AftersellCartLine`         | The full [cart line](/aftersell/cart/sdk-cart-object#cart-lines), for anything the props above don't cover.                                                                                                    |
| `formatMoney`      | `(cents: number) => string` | Formats a minor-unit amount. Use it for prices you read off `line`.                                                                                                                                            |

<Warning>
  **`price` and `compareAtPrice` are formatted strings; everything on `line` is in cents.** Don't do arithmetic on `price`. Compute from `line.finalLinePrice` and friends, then run the result through `formatMoney`.
</Warning>

### Quantity and removal

| Prop                | Type                                             | What it's for                                                                                                                                                                                                                |
| ------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `increment`         | `() => void`                                     | Adds one to the line.                                                                                                                                                                                                        |
| `decrement`         | `() => void`                                     | Removes one from the line.                                                                                                                                                                                                   |
| `remove`            | `() => void`                                     | Removes the line entirely.                                                                                                                                                                                                   |
| `quantityInput`     | `string`                                         | Current value for a controlled quantity `<input>`. A string, so mid-typing states survive.                                                                                                                                   |
| `onQuantityInput`   | `(event: Event) => void`                         | `onInput` handler for that field.                                                                                                                                                                                            |
| `commitQuantity`    | `() => void`                                     | Applies the typed quantity. Wire to `onBlur`.                                                                                                                                                                                |
| `onQuantityKeyDown` | `(event: KeyboardEvent) => void`                 | `onKeyDown` handler, so Enter commits.                                                                                                                                                                                       |
| `busy`              | `boolean`                                        | `true` while any cart mutation is in flight. Disable your controls on this.                                                                                                                                                  |
| `pending`           | `'increment' \| 'decrement' \| 'remove' \| null` | Which action is currently in flight, for a targeted spinner.                                                                                                                                                                 |
| `stepperLocked`     | `boolean`                                        | `true` when quantity can't be changed, because the line is a bundle anchor with a child included at a fractional per-anchor rate. Hide or disable the stepper — the built-in handlers already reject changes while it's set. |

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomTemplate(props) {
  return (
    <div className="cart-external-cart-items__row" style={{ display: 'flex', gap: '12px', opacity: props.busy ? 0.6 : 1 }}>
      {props.imageUrl && <img src={props.imageUrl} alt="" width={64} height={64} />}

      <div style={{ flex: 1 }}>
        {props.url ? <a href={props.url}>{props.title}</a> : <span>{props.title}</span>}
        {props.variantTitle && <div style={{ opacity: 0.6 }}>{props.variantTitle}</div>}
        {props.sellingPlanLabel && <div style={{ opacity: 0.6 }}>{props.sellingPlanLabel}</div>}

        {props.discountTags.map((tag) => (
          <span key={tag} style={{ fontSize: '11px', border: '1px solid', borderRadius: '4px', padding: '1px 5px' }}>
            {tag}
          </span>
        ))}

        {!props.stepperLocked && (
          <div style={{ display: 'flex', alignItems: 'center', gap: '6px', marginTop: '6px' }}>
            <button type="button" onClick={props.decrement} disabled={props.busy}>&minus;</button>
            <input
              value={props.quantityInput}
              onInput={props.onQuantityInput}
              onBlur={props.commitQuantity}
              onKeyDown={props.onQuantityKeyDown}
              size={2}
            />
            <button type="button" onClick={props.increment} disabled={props.busy}>+</button>
            <button type="button" onClick={props.remove} disabled={props.busy}>
              {props.pending === 'remove' ? 'Removing…' : 'Remove'}
            </button>
          </div>
        )}
      </div>

      <div style={{ textAlign: 'right' }}>
        <div>{props.price}</div>
        {props.compareAtPrice && <s style={{ opacity: 0.5 }}>{props.compareAtPrice}</s>}
        {props.savingsHtml && <div dangerouslySetInnerHTML={{ __html: props.savingsHtml }} />}
      </div>
    </div>
  );
}
```

### Rendering a bundle

On a bundle's anchor line, `bundle.children` holds its contents. Children never appear as their own rows, so if you don't render them the shopper won't see what's in the bundle:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomTemplate(props) {
  return (
    <div>
      <div>{props.title} {props.price}</div>

      {props.bundle && (
        <ul style={{ margin: '4px 0 0 12px', fontSize: '12px', opacity: 0.7 }}>
          {props.bundle.children.map((child, i) => (
            <li key={child.key ?? i}>{child.quantity} × {child.title}</li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

A child's `key` is `null` for a Shopify native bundle component, so fall back to the index as above.

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Cart settings
Source: https://docs.aftersell.com/aftersell/cart/cart-settings

Behavior settings for the Aftersell Cart — when the drawer opens and the theme selectors that keep your storefront in sync.

Beyond [styling](/aftersell/cart/design-settings), the cart has a few **behavior** settings that control how it interacts with your storefront — when the drawer opens, and which theme elements Aftersell keeps in sync with the cart.

## Where to find these

In the cart editor, open **Cart settings**. The options below are grouped under **Behavior** and **Custom selector**.

## Open the cart when an item is added

**Open cart when an item is added** controls whether the drawer pops open automatically each time a shopper adds a product. It's on by default. Turn it off if you'd rather the cart stay closed until the shopper opens it themselves.

## Theme selectors

Aftersell hooks into your storefront through CSS selectors — for example, to know which element opens the cart, or which cart-icon count to keep in sync. Built-in detection covers the most popular Shopify themes (Dawn, Sense, Crave, Debut, Impulse, Horizon, and many others), so **most stores never need to touch these**. Adjust a selector only if something isn't wiring up correctly on your theme.

### Selector modes

Each selector offers the same three modes:

| Mode                 | What it does                                                                                                                                                         |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Default**          | Uses Aftersell's built-in detection for supported themes.                                                                                                            |
| **Default + custom** | Keeps the built-in detection and adds your own selector on top — use this when the default mostly works but misses an element (for example, a separate mobile icon). |
| **Custom only**      | Ignores the built-in detection and uses only your selector — use this when the default targets the wrong element or conflicts with your theme.                       |

The selector input is enabled only for the **Default + custom** and **Custom only** modes.

### The three selectors

| Selector                 | What it targets                                                                                          | Example                     |
| ------------------------ | -------------------------------------------------------------------------------------------------------- | --------------------------- |
| **Open cart selector**   | The element(s) that should open the cart drawer.                                                         | `.header__cart-toggle`      |
| **Add to cart selector** | The add-to-cart button(s) Aftersell should hook into.                                                    | `.product-form__add-button` |
| **Cart count selector**  | The element on your theme's cart icon that displays the item count, so it stays in sync with the drawer. | `.header__cart-count span`  |

### How to find a selector

1. Open your storefront in a browser (Chrome recommended).
2. Right-click the element you want to target — your cart icon, the count number, or the add-to-cart button — and choose **Inspect**.
3. In the panel that opens, find the element that represents it (the count is often a `span` inside the cart icon).
4. Note its class (starts with `.`) or ID (starts with `#`) — for example `.header__cart-count span` or `#CartCount`.
5. Back in **Cart settings**, set the selector to **Default + custom** or **Custom only** and paste it in.
6. Save, then test on both desktop and mobile.

<Tip>
  Start with **Default** — it works for most themes with no setup. Reach for **Default + custom** when only one of several icons updates (say, desktop works but mobile doesn't), and **Custom only** when the default is targeting the wrong element. If you're unsure which selector to use, your theme developer can point it out — you don't need to write any code, just copy and paste.
</Tip>


# Checkout button block
Source: https://docs.aftersell.com/aftersell/cart/checkout-button-block

The Aftersell Cart Checkout button block: the required footer CTA that sends shoppers to checkout.

> The **Checkout button** block is the primary call-to-action in the cart footer that takes shoppers to checkout, giving them a clear, prominent path from the cart to checkout. It's a required block.

## Behavior

* The button resolves a **localized, market-correct checkout URL**, so shoppers land in the right market's checkout. If that can't be resolved, it falls back to the standard `/checkout` link.
* With **Go to cart page instead of checkout** enabled, the button links to `/cart` instead.
* Clicking navigates via JavaScript so a theme's own cart handling can't intercept it, while still respecting new-tab intents (Cmd/Ctrl-click, middle-click).
* The click emits the SDK [`checkout` event](/aftersell/cart/sdk-events), which you can subscribe to.

## Settings

| Setting                                 | What it controls                                                     | Default                      |
| --------------------------------------- | -------------------------------------------------------------------- | ---------------------------- |
| **Button label**                        | Plain-text label entered in a text area. Supports `{{total_price}}`. | `Checkout • {{total_price}}` |
| **Go to cart page instead of checkout** | Sends shoppers to your `/cart` page instead of straight to checkout. | Off                          |

## Placement and limits

* **Region:** bottom.
* **Maximum:** 1 per cart state.
* **State:** filled cart only.
* **Locked and added by default.** The Checkout button can't be removed or hidden, only repositioned within the footer.

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

| Prop        | Type                  | What it's for                                                                                                                 |
| ----------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `label`     | `string`              | The button label as sanitized HTML, with `{{total_price}}` resolved.                                                          |
| `href`      | `string \| undefined` | The checkout URL. `undefined` in the editor preview, where there's nothing to navigate to.                                    |
| `isLoading` | `boolean`             | Always `false` here: the block renders its built-in skeleton during load and only calls your template once the cart is ready. |

<Warning>
  **A custom checkout button loses checkout tracking.** The built-in button attaches a click handler that emits the SDK [`checkout` event](/aftersell/cart/sdk-events#checkout) and records the conversion for [cart analytics](/aftersell/cart/analytics). That handler is not passed to custom templates, so navigating via `href` alone skips both.

  If you need the event, emit it yourself from an `onClick` before navigation. Attribution reporting still can't be recovered this way, so prefer restyling the built-in button with [design settings](/aftersell/cart/design-settings) or [custom CSS](/aftersell/cart/custom-css) unless you truly need different markup.
</Warning>

Render `href` as-is rather than defaulting it. An `<a>` with no `href` is inert, which is the correct behavior in the editor.

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Creating carts
Source: https://docs.aftersell.com/aftersell/cart/creating-carts

Create a new Aftersell Cart, name it, save it as a draft, and publish it to your storefront.

A **cart** in Aftersell is a configurable cart-drawer experience made up of [blocks](/aftersell/cart/blocks-overview). This page walks through creating your first cart and getting it live.

## Create a cart

From the **Carts** page, click **Create cart**. Aftersell creates a new cart — named *Untitled cart 1*, *Untitled cart 2*, and so on, so each new one gets a distinct name — pre-seeded with a working default layout, and opens it in the cart editor.

The default cart contains **Header → Banner → Cart items → Summary → Checkout button** for the filled state, and **Header → Empty cart** for the empty state (the empty state's Header is titled *Cart*). From there you [add, remove, and reorder blocks](/aftersell/cart/blocks-overview) to build the cart you want.

<Note>
  New carts always start from this blank default layout. To start from an existing cart instead, use the **Duplicate** action on a cart in the Carts list.
</Note>

## Name the cart

Rename the cart inline from the editor's left sidebar — click the name and type. The name **saves immediately** on its own (it doesn't wait for the Save button). Blank or whitespace-only names are rejected and revert to the previous name.

## Draft and publish

* Every new cart is a **draft**. Drafts aren't shown to shoppers — you can build and preview them freely. Use **Save** in the editor to persist your edits.
* **Publish** makes the cart live. Because only one cart can be live at a time, **publishing a cart moves your current live cart back to draft** (see [Having multiple carts](/aftersell/cart/having-multiple-carts)).
* **Unpublish** sets a live cart back to draft. With no live cart, the Aftersell Cart is disabled for shoppers until you publish another.

## Grant required permissions

Before you can publish or serve a cart, Aftersell Cart needs a set of additional permissions from your Shopify store. If these haven't been granted yet, a banner appears at the top of the **Carts** page:

> **Finish enabling your cart** — AfterSell Cart needs a few additional permissions to publish and serve carts on your storefront. Enable them to get started.

Click **Update App** in the banner to open the permissions dialog and approve the request. The banner disappears automatically once all permissions are granted.

<Tip>
  If you arrive at the Carts page through an onboarding link, the permissions dialog may open automatically so you can approve in one step.
</Tip>

## Turn on the app embed

For a published cart to actually render on your storefront, the **Aftersell Cart app embed must be enabled** in your theme. If it's off, the cart won't show even when published, and the Carts page flags the cart with an "App embed off" badge. The in-app setup guide walks you through the three steps: enable the app embed, create a cart, and publish it.

## Next steps

* [Preview your cart](/aftersell/cart/previewing-carts) before publishing.
* [Customize the look](/aftersell/cart/design-settings) with design settings.
* [Add blocks](/aftersell/cart/blocks-overview) for upsells, rewards, and more.


# Custom code blocks
Source: https://docs.aftersell.com/aftersell/cart/custom-code-blocks

The Aftersell Cart Custom code block: add your own HTML or React anywhere in the drawer, including inside Cart items.

> The **Custom code** block adds your own HTML or React to the cart. Put it in any section of the drawer, or nest it inside [**Cart items**](/aftersell/cart/cart-items-block) as a sub-block so it repeats for each line. Unlike other blocks, it has no Content settings and no Design section: the block *is* the code, so you work entirely in its **Code** tab.

<Frame>
  <img alt="Animated preview of adding and turning on a Custom code block in the Aftersell Cart editor" title="Animated preview of adding and turning on a Custom code block in the Aftersell Cart editor" />
</Frame>

## Add and turn on a Custom code block

1. Add a **Custom code** block to any section, or as a sub-block under **Cart items**.
2. Select it and open the **Code** tab.
3. Choose **HTML** or **React component**. New blocks default to HTML.
4. Write your code.
5. If you chose React, click <span><svg><path /></svg>Compile</span>.
6. Turn on **"Use custom template"**. For this block, that switch means “show my custom code”, and it defaults off, so nothing renders until you enable it.
7. Keep the sidebar eye toggle on so the block stays visible to shoppers.

Both the eye toggle and **"Use custom template"** must be on for the block to appear.

## Behavior

* The block renders nothing until the cart has loaded.
* It also renders nothing when the sidebar eye is off, **"Use custom template"** is off, the code is empty, or React fails to compile or render. Because a failure is silent, check your block in [preview](/aftersell/cart/previewing-carts) before publishing.

## HTML mode

HTML mode substitutes a small set of tokens into your markup. It’s for static or token-driven content, not for running logic.

* **Inline `<script>` tags do not run**, and HTML mode has **no access to the SDK or `window`.**
* For logic, use [**React mode**](#react-mode) or [Custom scripts](/aftersell/cart/custom-scripts) with the [Cart SDK](/aftersell/cart/sdk-overview).

### Tokens

Token values are **formatted strings** (shop money format, a percentage with `%`, or a quantity), ready to drop into markup:

| Token                    | What it shows                                                        |
| ------------------------ | -------------------------------------------------------------------- |
| `{{pre_cart_total}}`     | Cart total before discounts.                                         |
| `{{post_cart_total}}`    | Cart total after discounts.                                          |
| `{{savings_amount}}`     | Amount saved (pre-discount total minus post-discount total).         |
| `{{savings_percentage}}` | Savings as a percentage, including the `%` sign (for example `15%`). |
| `{{cart_quantity}}`      | Number of visible items in the cart.                                 |

### Example

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<div class="cart-external-custom-code_html">
  You saved {{savings_amount}} ({{savings_percentage}})
</div>
```

## React mode

React mode compiles a component and passes it as cart data plus an `add-to-cart` action.

* The editor locks the wrapper to `function CustomCode(props: CustomCodeProps) { … }`, and you edit only the body between those lines.
* You must click <span><svg><path /></svg>Compile</span> then turn on **"Use custom template"**, before the block shows.
* Your component can use `useState`, `useEffect`, `useMemo`, `useRef`, and `useCallback`.
* Unlike HTML mode, React runs in the page context, so it can call `window` and the [Cart SDK](/aftersell/cart/sdk-overview) when those are available.
* If your component throws errors at runtime, the block renders nothing and the rest of the cart keeps working.

### Props

Totals and savings amounts are integers in the currency’s [minor unit](/aftersell/cart/sdk-actions#formatmoneycents) (cents for USD), so `$12.50` is `1250`, not `12.50`. They’re not formatted money strings like the HTML tokens.

| Prop                                            | Type                        | Description                                                                                                                |
| ----------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `cart`                                          | `AftersellCart`             | The current cart. See the [cart object reference](/aftersell/cart/sdk-cart-object).                                        |
| `line`                                          | `AftersellCartLine \| null` | Set only when the block is a Cart items sub-block (one render per line); `null` in a section.                              |
| `preCartTotal`                                  | `number`                    | The cart total **before discounts** (Shopify's `original_total_price`), in the currency's minor unit (e.g. cents).         |
| `postCartTotal`                                 | `number`                    | The cart total **after discounts**, in the currency's minor unit.                                                          |
| `savings`                                       | `{ amount, percentage }`    | Savings amount and percentage.                                                                                             |
| `addProduct(variantId, quantity?, properties?)` | `function`                  | Adds a product to the cart, stamped with this block's attribution so [analytics](/aftersell/cart/analytics) can credit it. |

### The cart and line shapes

`cart` and `line` are the same objects the SDK exposes everywhere else, so they're documented once in the **[cart object reference](/aftersell/cart/sdk-cart-object)**: every field on the cart, on a line, and on a bundle.

The ones you'll reach for most: `cart.items`, `cart.itemCount`, `cart.totalPrice`, `line.title`, `line.quantity`, `line.finalLinePrice`.

Three things specific to this block:

* **`line` is only set on a Cart items sub-block**, where your component renders once per line. Placed as a section, `line` is `null` and you read `cart.items` instead.
* **Bundle children aren't in `cart.items`.** When lines are [grouped into a bundle](/aftersell/cart/sdk-use-case-bundles), only the anchor line appears; its children live on `line.bundle.children`.
* **Lines hidden by a [line transform](/aftersell/cart/sdk-hooks#registerlinetransform) aren't there either**, though they still count toward `cart.totalPrice`.

### Examples

Show the item count:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomCode(props) {
  return (
    <div className="cart-external-custom-code_jsx">
      {props.cart.itemCount} items
    </div>
  );
}
```

As a Cart items sub-block, use `props.line` for per-product content. The block renders once per line, tagged with that line's product and variant:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomCode(props) {
  if (!props.line) return null;
  return (
    <div className="cart-external-custom-code_jsx">
      {props.line.productTitle}
      {props.line.variantTitle ? ` · ${props.line.variantTitle}` : ''}
    </div>
  );
}
```

### Reading enrichment metadata

Each item in `cart.items` carries a `metadata` field: an empty object `{}` until a [cart enricher](/aftersell/cart/sdk-hooks#registercartenricher) populates it. Once populated, it is keyed by the enricher's `id` and contains the Storefront data for that line's product or variant:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomCode(props) {
  return (
    <ul>
      {(props.cart.items ?? []).map((item) => {
        const note = item.metadata?.shipping?.shippingNote;
        return (
          <li key={item.key}>
            {item.title}
            {note ? ` · ${note.value}` : ''}
          </li>
        );
      })}
    </ul>
  );
}
```

`metadata` is always present and defaults to an empty object `{}` until the enricher's async fetch completes (the "not yet enriched" test is `Object.keys(item.metadata).length === 0`). Use optional chaining (`item.metadata?.enricherId`) when reading a specific enricher's key, since that key is absent until enrichment lands.

### Reading discount codes and line discounts

`cart.discountCodes` lists the discount codes applied to the cart, and each line's `discountAllocations` lists the discounts applied to that specific line:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomCode(props) {
  const codes = props.cart.discountCodes;
  return (
    <div>
      {codes.length > 0 && (
        <p>Active discounts: {codes.join(', ')}</p>
      )}
      <ul>
        {(props.cart.items ?? []).map((item) => {
          return (
            <li key={item.key}>
              {item.title}
              {item.discountAllocations.map(
                (discount) => ` · ${discount.title} (-${(discount.amount / 100).toFixed(2)})`
              )}
            </li>
          );
        })}
      </ul>
    </div>
  );
}
```

## Placement and limits

* **Region:** any (top, body, or bottom). Also available as a Cart items sub-block.
* **Maximum:** unlimited.
* **State:** filled and empty cart (as a section block). As a Cart items sub-block, it only renders when the cart has lines, one instance per line.
* Not locked, so you can remove or hide it.
* There is no per-block Design section. Style through your own markup, [**Custom CSS**](/aftersell/cart/custom-css), and your global [**Design settings**](/aftersell/cart/design-settings).

## When to use custom code block vs. custom template vs. custom script

|                                                         | What it does                                                                          | When to use it                                                        | Example                                                                                                                                                                   |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Custom code block**                                   | Adds a *new* block of your own HTML or React.                                         | Something the built-in blocks don’t cover.                            | An estimated-total line that adds your flat shipping rate to the cart total, or a delivery-cutoff countdown above the checkout button.                                    |
| **[Custom template](/aftersell/cart/custom-templates)** | Replaces the rendering of an *existing* block with your JSX, using that block’s data. | The built-in block is almost right, but you need different markup.    | Rebuild the [Product row](/aftersell/cart/cart-items-block#custom-template) so the variant name, savings, and quantity picker sit on one line.                            |
| **[Custom script](/aftersell/cart/custom-scripts)**     | Runs JavaScript against the cart via the [Cart SDK](/aftersell/cart/sdk-overview).    | Cart-wide logic, events, and configuration rather than drawer markup. | Spend \$75, get a free tote: [add the gift](/aftersell/cart/sdk-use-case-free-gift) once the cart crosses the threshold, and take it back out if the shopper drops below. |


# Custom CSS
Source: https://docs.aftersell.com/aftersell/cart/custom-css

Add custom CSS to fine-tune your Aftersell Cart beyond the built-in design settings.

When the built-in [design settings](/aftersell/cart/design-settings) don't go far enough, add your own **custom CSS** to style the cart.

## Where to add it

In the cart editor, open **Cart settings → Custom CSS**. Your CSS **applies to the whole cart** and is loaded **after** the cart's base styles, so your rules take precedence.

## Target public classes only

Style the cart using its **public `cart-external-*` classes**. The editor autocompletes these and warns you off the rest:

* **`cart-external-*`**: the public, supported target. Use these. They carry no styling of their own, so they exist purely for your CSS to hook onto.
* **`cart-internal-*`**: the cart's own plumbing, where all of its built-in styling lives. The editor flags selectors against them as errors. They aren't churned casually, since every existing cart depends on them, but they're the cart's to change rather than a contract with you. Restyle through the `cart-external-*` twin instead.
* Other `cart-*` classes the editor doesn't recognize are flagged as warnings.

<Note>
  You'll see `cart-internal-*` classes in the markup, including in every block's default [custom template](/aftersell/cart/custom-templates). That's expected: they're what gives a block its built-in look. The rule here is about **selectors you write** in this panel, not classnames the cart renders.

  If you're writing a custom template that changes a block's DOM structure, see [Styling a custom template](/aftersell/cart/custom-templates#styling-a-custom-template) for which classnames to keep and which to drop.
</Note>

## Shadow DOM: the cart is self-contained

On the storefront, the entire cart renders inside its own **shadow DOM**. This means:

* Your theme's CSS can't leak into the cart, and the cart's CSS can't leak out, so your custom CSS is automatically scoped to the cart and won't clash with the rest of your site.
* Your selectors should reference elements and classes **inside the cart**. Selectors aimed at page elements outside the cart won't reach in.

The same boundary applies to JavaScript: `document.querySelector` can't see into the drawer either. A script reaching for a cart element has to go through [`shadowRoot`](/aftersell/cart/sdk-overview#shadowroot), and it targets these same `cart-external-*` classes.

## When to use design settings instead

For colors, radii, spacing, and width, the built-in [design settings](/aftersell/cart/design-settings) are simpler and safer, so reach for custom CSS only for what they don't cover.

## Where to go next

* **[Design settings](/aftersell/cart/design-settings)**: the built-in styling controls, and the first thing to try.
* **[Custom templates](/aftersell/cart/custom-templates)**: replace a block's markup entirely when CSS alone can't get there.
* **[Cart SDK](/aftersell/cart/sdk-overview)**: for behavior rather than appearance.


# Custom scripts
Source: https://docs.aftersell.com/aftersell/cart/custom-scripts

Run custom JavaScript in the Aftersell Cart with the Initialization and On cart update script slots.

Custom scripts let you run your own JavaScript against the cart using the [Cart SDK](/aftersell/cart/sdk-overview). Add them in the cart editor under **Cart settings → Custom script**, where a dropdown switches between two slots: **Initialization** and **On cart update**.

Write plain JavaScript in these editors, with no `<script>` tags. **On cart update** has a **Reset to default** action that restores its starter template; **Initialization** does not, so keep your own copy before you clear it.

<Note>
  A lot of what merchants used to script is now a built-in setting. Check [Before you write a script](/aftersell/cart/sdk-use-cases#before-you-write-a-script) first: a setting keeps working through cart redesigns, and your script might not.
</Note>

## Which slot to use

|                | Initialization                                                                                                                                                      | On cart update                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Runs**       | Once, when the cart loads.                                                                                                                                          | On every cart change after the first load.                              |
| **You write**  | The whole script.                                                                                                                                                   | Only the handler body. The `cart_updated` wrapper is locked.            |
| **Use it for** | Registering behavior once: [`configure`](/aftersell/cart/sdk-configure), [`events.on`](/aftersell/cart/sdk-events), [`hooks.register*`](/aftersell/cart/sdk-hooks). | Rules that have to be re-evaluated against the cart's current contents. |
| **Example**    | Hide free gift lines with a line transform.                                                                                                                         | Keep a free gift in sync with a spend threshold.                        |

## Initialization

The **Initialization** script runs **once when the cart loads**. It's your entry point for setting things up: configuring cart behavior, subscribing to events, and registering hooks. The [SDK](/aftersell/cart/sdk-overview) is available as `window.aftersell.cart`.

Setup calls you make here ([`configure(...)`](/aftersell/cart/sdk-configure), [`events.on(...)`](/aftersell/cart/sdk-events), [`hooks.*`](/aftersell/cart/sdk-hooks)) are safe to call at the top of the script even before the cart has fully booted; they're buffered and applied once it does. Actions that read or change the cart (like [`addItem`](/aftersell/cart/sdk-actions#additemvariantid-quantity) or [`getCart`](/aftersell/cart/sdk-actions#getcart)) should run inside [`ready()`](/aftersell/cart/sdk-overview#ready) or an event handler.

The slot starts out with three **commented-out** examples — opening the drawer on every add, reacting to `cart_loaded`, and hiding free gift lines — so an untouched Initialization script does nothing. Uncomment one to try it, or replace them.

The natural shape for this slot is a **one-time registration with no events involved**: register the behavior once and let the cart apply it from then on. Hiding free gift lines from the drawer, without changing the total, is the shipped example of that:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerLineTransform((line) => {
  if (line.finalLinePrice === 0) line.setHidden(true);
});
```

[`registerLineTransform`](/aftersell/cart/sdk-hooks#registerlinetransform) runs for every line as it renders, and `setHidden` is display-only, so the line stays in the cart and still counts toward the total, it just doesn't show in the drawer. See [Hide and relabel cart lines](/aftersell/cart/sdk-use-case-hide-lines) for more of what a transform can do.

Actions that read the cart go inside `ready()`:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log('Cart loaded with', state.itemCount, 'items');
});
```

Reaching into the cart's DOM needs the same wait, and it needs [`shadowRoot`](/aftersell/cart/sdk-overview#shadowroot): the cart renders inside a shadow root, so `document.querySelector` can't see anything in the drawer.

<Tip>
  Branching on market, country, or currency **before** the cart loads? Read [`context`](/aftersell/cart/sdk-overview#context) instead. It's available synchronously, with no `ready()` needed, so you can skip registering handlers entirely for shoppers a rule doesn't apply to.
</Tip>

## On cart update

The **On cart update** script runs every time the cart changes. It's a locked wrapper around a `cart_updated` subscription, so you edit only the body, and your code receives the updated `cart`.

This slot is for rules that have to be **re-evaluated on every cart change**. A free gift threshold is the classic case (spend \$75, get a free tote) because the answer depends on the current contents and nothing else can tell you when they change:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('cart_updated', (cart) => {
  const GIFT_VARIANT_ID = 1234567890;
  const THRESHOLD = 7500;   // $75.00, in cents

  let giftLine = null;
  let subtotal = 0;
  (cart.items ?? []).forEach((line) => {
    if (line.variantId === GIFT_VARIANT_ID) giftLine = line;
    else subtotal += line.finalLinePrice;   // the gift itself never counts toward the threshold
  });

  const shouldHaveGift = subtotal >= THRESHOLD;
  const hasGift = Boolean(giftLine);

  // Bail when the cart already matches. This is the part that matters: adding or
  // removing an item fires cart_updated again, so without this check the handler
  // re-enters itself forever.
  if (shouldHaveGift === hasGift) return;

  if (shouldHaveGift) window.aftersell.cart.actions.addItem(GIFT_VARIANT_ID, 1);
  else window.aftersell.cart.actions.removeItem(giftLine.key);
});
```

### Keeping the cart in a desired state

The `if (shouldHaveGift === hasGift) return;` line is what makes this safe, and it generalizes to every script that keeps the cart in a desired state. This slot both reacts to cart changes and causes them, so every `addItem` or `removeItem` re-enters it. Describe the state you want, compare it to the state you have, and return early when they already agree, so the handler converges after one pass instead of looping. See [the two rules](/aftersell/cart/sdk-events#the-two-rules) for the unguarded version to avoid and why the payload is read-only.

On a slower store it's also worth keeping a module-level in-flight flag, so two rapid changes can't both start an add before the first one lands.

<Note>
  `cart_updated` fires only on changes **after** the first load ([event timing](/aftersell/cart/sdk-events#cart_updated)), so a script in this slot won't reconcile a cart that already qualifies when the page loads. For a version that handles both, subscribe to `cart_loaded` and `cart_updated` with the same function from the **Initialization** slot. See [Auto-add a free gift at a threshold](/aftersell/cart/sdk-use-case-free-gift).
</Note>

## When a script breaks

Each slot runs in its own sandbox, so a broken **Initialization** script can't stop **On cart update** from running, and neither can break the cart itself.

Within a slot, though, execution **stops at the first error**. Everything below that line is skipped, which means any `configure`, `events.on`, or `hooks.register*` further down is never registered. That's the usual explanation for "my handler never fires" when the code looks right.

The cart names the failing line in the browser console, and each slot runs under its own filename (`aftersell-cart-init.js` and `aftersell-cart-cart-update.js`), so you can open either from the DevTools Sources panel and set breakpoints. See [Debugging](/aftersell/cart/sdk-overview#debugging) for the exact messages, and for the debug channel that catches hook failures kept off the console.

Because `cart_loaded` [replays to late subscribers](/aftersell/cart/sdk-events#cart_loaded), registration order never matters. The safest structure is to register everything first and do the risky work inside handlers, where a throw is isolated to that handler.

## Where to go next

* **[Cart SDK](/aftersell/cart/sdk-overview)**: custom scripts are how you run SDK code. See the [configure](/aftersell/cart/sdk-configure), [events](/aftersell/cart/sdk-events), [actions](/aftersell/cart/sdk-actions), and [hooks](/aftersell/cart/sdk-hooks) references for the full surface, the [cart object](/aftersell/cart/sdk-cart-object) for the shape of what handlers receive, and the [use cases](/aftersell/cart/sdk-use-cases) for ready-made snippets.
* **[Custom code blocks](/aftersell/cart/custom-code-blocks)**: for adding markup to the cart. Note the Custom code block's HTML mode does **not** run JavaScript; use custom scripts (or the block's React mode) for logic.


# Custom templates
Source: https://docs.aftersell.com/aftersell/cart/custom-templates

Override how any Aftersell Cart block renders with your own JSX: what a template replaces, what's in scope, how to style it, and where to find each block's props.

A **custom template** lets you override how an individual block renders. Instead of the block's built-in UI, the cart renders your own JSX, using the same data the block would normally use. It's a cross-cutting capability rather than a block of its own: most blocks expose it from their **Code** tab.

This page covers what applies to **every** block. For the props a specific block hands you, jump to [the block's own reference](#props-for-each-block).

## Custom template vs. Custom code block

These sound similar but do different things:

* A **custom template** *replaces the rendering of an existing block* with your own markup, and hands you that block's own data (the Header's title and item count, the Summary's totals, and so on). It doesn't add anything new; it restyles one block.
* The **[Custom code](/aftersell/cart/custom-code-blocks)** block *adds a new block* of arbitrary HTML or React anywhere in the cart.

Reach for a custom template when the built-in block is almost right but you need a different layout or markup. Reach for a Custom code block when you want to add something the built-in blocks don't cover.

## Using a custom template

1. Select a block in the editor and open its **Code** tab.
2. Edit the default template. Custom templates are **JSX only** (the HTML-or-JSX choice is exclusive to the Custom code block).
3. Click **Compile**. Compiling strips the types and transpiles the JSX, so it catches **syntax** errors. Type errors don't stop a compile — the editor flags those inline as you type, with the same IntelliSense that autocompletes the block's props.
4. Turn the template on to make the cart use it instead of the built-in rendering.
5. **Reset to default** restores the block's original template at any time.

## Writing a template with AI

The Code tab includes a **Copy AI prompt** button (✦ wand icon). Clicking it copies a self-contained brief to your clipboard that you can paste directly into an AI chat session (Claude, ChatGPT, or similar).

The prompt includes everything the AI needs to write a valid template for that specific block:

* The compile rules (single expression, no `export default`, no imports)
* The exact props the block receives, matching what the editor's IntelliSense shows
* The locked function signature the editor enforces
* Block-specific rules (money formats, which handlers to wire, accessibility requirements)
* A fill-in section where you paste your current template and describe the change you want

After copying, open an AI session, paste the prompt, fill in the two blanks at the bottom (your current template and the change you want), and send. The AI returns a complete template you can paste back into the editor and compile.

<Tip>
  Paste your existing template into the fill-in section rather than leaving it blank. The AI uses it as the starting point, so any customization you've already made carries forward rather than being replaced by the default.
</Tip>

<Note>
  The prompt is specific to each block. The **Copy AI prompt** button only appears on blocks that support custom templates.
</Note>

<Tip>
  The default template you start from is a **working copy of the block's built-in markup**, so you always have a correct, rendering reference to modify rather than a blank page. Reach for **Reset to default** whenever you want that reference back.

  It isn't always a byte-for-byte match. The Header's default template also renders `logoUrl`, which the built-in markup has no placement for, so turning that template on is how an uploaded header image first appears.
</Tip>

## What your template replaces

A template replaces the block's rendering **entirely**. There's no wrapper left around your JSX, which has consequences worth knowing before you start deleting things:

| You lose                            | What that means                                                                                                                                                                   |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The block's wrapper element         | Nothing wraps your markup. Any padding, alignment, or layout the block provided is now yours to supply.                                                                           |
| **The block's Design tab settings** | Design settings are applied as inline styles on the built-in wrapper, and that wrapper is gone. Colors, spacing, and radii set in the Design tab **stop applying** to this block. |
| Built-in accessibility affordances  | `aria-label`s, focus handling, and semantic elements only exist if your JSX includes them.                                                                                        |

<Warning>
  **The Design tab is the one people are caught by.** While a custom template is active, the Design tab's fields are disabled and a warning icon appears next to the "Design" heading. Hover over the icon to see why. Style the block from your template instead, either [inline or with your own CSS](#styling-a-custom-template). The fields re-enable as soon as you turn the custom template off.
</Warning>

What you keep: the block's position in the cart, its visibility toggle, its settings (which still feed the props you receive), the cart's [Custom CSS](/aftersell/cart/custom-css) panel, and **the built-in loading skeleton**.

That last one surprises people. The block checks whether the cart is still loading *before* it reaches your template, so the built-in skeleton renders during load and your template only runs once the cart is ready. You don't have to build a loading state.

## What's available inside a template

Your template is a single function component. It compiles from **TSX**, so type annotations are allowed and stripped at compile time. That's why the default templates are written with them:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function Header(props: HeaderProps) {
  return <div>{/* … */}</div>;
}
```

**The signature line and the closing brace are locked** — the editor won't let you edit either, and hovering shows "Locked — this line can't be edited." You write the body between them. **Reset to default** is the one thing that can replace them.

What else matters:

* **You get five hooks:** `useState`, `useEffect`, `useMemo`, `useRef`, and `useCallback`. Plus `Fragment`, for `<>…</>`.
* **There are no imports.** You can't `import` anything, and there's no `React` object in scope, so no `React.useReducer`, no `React.Children`. If a hook isn't in the list above, it isn't available.
* **Props are read-only.** Mutating a prop won't do anything useful. To change the cart, use the handler props the block gives you (`onClose`, `increment`, `selectPlan`, and so on) rather than writing to props directly.
* **`window` is reachable**, so a template can call the [Cart SDK](/aftersell/cart/sdk-overview) via `window.aftersell.cart` when it needs something the block's props don't cover.

## Conventions across every block

Three rules hold everywhere, and knowing them removes most of the guesswork:

* **`*Html` props are pre-sanitized rich text.** Render them with `dangerouslySetInnerHTML`. They've already been through the cart's sanitizer, and merchant tokens like `{{total_price}}` are already resolved.
* **Prices that arrive as `string` are already formatted** in the shop's money format. Prices as `number` are in cents. A block gives you one or the other, and each block's table says which.
* **`isLoading` is always `false` inside a template.** The block renders its built-in skeleton and only calls your template once the cart has loaded, so the prop is passed for completeness rather than for you to branch on.

<Note>
  A few blocks return nothing at all in certain states, so your template is never called with empty data. The Rewards template never sees an empty `milestones`, and the Subscription upgrade template never sees a null `view`. Each block's reference notes where this applies, so you can skip the empty-state branch.
</Note>

## Styling a custom template

The default template you start from carries the block's classnames. How you style your edits depends on how far you move from that starting point.

### The two class families

Every element in a default template carries a paired classname, and they do very different jobs:

| Family            | What it does                                                                                                        | Write CSS against it?                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `cart-internal-*` | **Carries the block's built-in styling.** Every rule in the cart's stylesheet targets this family.                  | No. It's the cart's own plumbing, and the Custom CSS editor flags selectors against it. |
| `cart-external-*` | **A hook with no styling of its own.** Nothing in the cart's stylesheet targets it; it exists for your CSS to grab. | Yes. This is the supported way to restyle a block.                                      |

So `cart-internal-header__title` is what makes the title *look* like the built-in title, and `cart-external-header__title` is the handle you're meant to grab when you want to change how it looks.

### Small changes: keep both classnames

If you're reordering elements, relabelling, or adding something inside the existing structure, leave the classnames alone. You keep the built-in look for free, and you restyle through [Custom CSS](/aftersell/cart/custom-css) targeting the `cart-external-*` hooks.

### Restructuring: drop both classnames

Once you're changing the DOM structure rather than tweaking it, take **both** families off your markup and use [your own classnames](#option-1-your-own-classnames-plus-custom-css) instead. There's a separate reason for each.

**Drop `cart-internal-*` because the built-in CSS was written for the built-in DOM.** Keep those classes on restructured markup and you inherit layout rules that assume elements you no longer have: flex containers expecting different children, spacing between elements that moved, positioning relative to something you removed. This usually surfaces as your own CSS "not working" when the built-in rules are the ones winning.

<Warning>
  **Drop `cart-external-*` because it's a shared name, not yours.** Those classnames mean something specific on the built-in markup, and your Custom CSS is written once for the whole cart. If a restructured template reuses them, any rule you write targets both your structure and the built-in one.

  That goes wrong the moment you turn the custom template off: the block reverts to its built-in markup, and your CSS is still pointing at it, now styling a DOM it was never written for. Your own prefix keeps the two cleanly separated, so toggling a template off is a clean revert.
</Warning>

Two ways to style what you've built:

#### Option 1: your own classnames plus Custom CSS

Best for anything you'll maintain or reuse. Give your classes a prefix nobody else will collide with, usually your store or brand name:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function Header(props) {
  return (
    <div className="northwind-custom-header">
      <div className="northwind-custom-header__title" dangerouslySetInnerHTML={{ __html: props.title }} />
      <button type="button" className="northwind-custom-header__close" onClick={props.onClose}>
        &times;
      </button>
    </div>
  );
}
```

Then in the cart editor, select **Cart settings** in the left panel and open the **Custom CSS** tab on the right:

```css theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.northwind-custom-header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 16px;
}

.northwind-custom-header__title {
  font-size: 18px;
  font-weight: 600;
}

.northwind-custom-header__close:hover {
  opacity: 0.6;
}
```

A prefix matters more than it looks. Without one, a class like `.header` or `.title` risks colliding with the cart's own classes, another app's template, or a future block.

#### Option 2: inline styles

No CSS panel round-trip, and everything lives in one place:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
```

Good for layout scaffolding and one-offs. Its limits are the usual ones: no `:hover` or other pseudo-classes, no media queries, and no reuse across blocks. Reach for Option 1 once you want any of those.

### Picking an approach

| Situation                                  | Do this                                                                          |
| ------------------------------------------ | -------------------------------------------------------------------------------- |
| Same structure, different wording or order | Keep both classnames, restyle via Custom CSS on `cart-external-*`                |
| New structure, styling you'll maintain     | Your own prefixed classes, both cart families dropped                            |
| New structure, a few quick layout rules    | Inline styles, both cart families dropped                                        |
| Lots of custom code across several blocks  | Your own prefixed classes everywhere, so any template can be toggled off cleanly |

<Note>
  The cart renders in a shadow root, so your theme's stylesheet can't reach inside it. Styles for a custom template have to come from the cart's own **Custom CSS** panel or from inline styles, not from your theme. See [Custom CSS](/aftersell/cart/custom-css).
</Note>

## When a template fails

A broken template never breaks the cart. The block renders **nothing** and everything around it keeps working, which is safe but easy to miss: a blank space where your block should be is the symptom.

| Failure                 | When you'll see it           | Where it reports                                                                                                        |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Type error              | As you type                  | An inline squiggle in the editor. It does **not** block compiling — the compiler strips types rather than checking them |
| Syntax error            | When you click **Compile**   | The editor, before it can reach your storefront                                                                         |
| A crash while rendering | On the storefront, once live | `console.error('[aftersell-cart] module crashed: …')`                                                                   |

Because the block silently disappears rather than erroring visibly, always check a template in [preview](/aftersell/cart/previewing-carts) before publishing. If a block has gone missing, open the browser console first.

Two things worth guarding for, since both crash a template that assumes otherwise:

* **Nullable props.** Many props are `null` in normal conditions (`logoUrl` with no logo, `imageUrl` with no image, `variantTitle` on a single-variant product). Check before you use them.
* **Arrays that can be empty.** `discountTags` and `discountCodes` are `[]` far more often than not.

## Limitations

* **Custom templates are display overrides.** To run logic against the cart (subscribe to events, add items, react to changes), use [Custom scripts](/aftersell/cart/custom-scripts) and the [Cart SDK](/aftersell/cart/sdk-overview).
* **Almost every block supports one.** The exceptions are the **[Express payments](/aftersell/cart/express-payments-block)** block, which hosts Shopify's own payment buttons, and the **[Cart items](/aftersell/cart/cart-items-block)** container itself, though the **Product** row inside it does support a custom template.
* **A template can't change what a block fundamentally does.** It changes how the block's data is presented, not the data or the behavior behind it.

## Props for each block

Every block passes its own data. The full prop table, with types and a worked example, lives on that block's page:

| Block                                                                              | Props it receives                                                                                                                  |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [Header](/aftersell/cart/header-block#custom-template)                             | `title`, `logoUrl`, `leftSection`, `rightSection`, `itemCount`, `onClose`, `isLoading`                                             |
| [Banner](/aftersell/cart/banner-block#custom-template)                             | `text`, `shouldUseTimer`, `isTimerExpiredAndShouldHide`, `isLoading`                                                               |
| [Rewards](/aftersell/cart/rewards-block#custom-template)                           | `milestones`, `rewardsMessageHtml`, `showIcons`, `isLoading`                                                                       |
| [Cart items · Product](/aftersell/cart/cart-items-block#custom-template)           | 25 props: per-line content, identifiers, and quantity controls                                                                     |
| [Subscription upgrade](/aftersell/cart/subscription-upgrade-block#custom-template) | `view`, `selectPlan`, `onChange`, `oneTimeValue`, and more                                                                         |
| [Summary](/aftersell/cart/summary-block#custom-template)                           | `leftHtml`, `rightHtml`, `discountCodes`, `totalPrice`, `savings`, and more                                                        |
| [Checkout button](/aftersell/cart/checkout-button-block#custom-template)           | `label`, `href`, `isLoading`                                                                                                       |
| [Discount code](/aftersell/cart/discount-code-block#custom-template)               | `discountCodeInput`, `placeholder`, `buttonText`, `isValidating`, `isInvalid`, `setDiscountCodeInput`, `handleSubmit`, `isLoading` |
| [Empty cart](/aftersell/cart/empty-cart-block#custom-template)                     | `text`, `cta`, `href`                                                                                                              |
| [Image](/aftersell/cart/image-block#custom-template)                               | `imageUrl`, `altText`, `maxHeight`, `fullWidth`                                                                                    |
| [Notes](/aftersell/cart/notes-block#custom-template)                               | `titleHtml`, `placeholder`, `noteInput`, `status`, `isExpanded`, `onNoteChange`, `onNoteBlur`, `onToggle`, and more                |
| [Product add-on](/aftersell/cart/product-add-on-block#custom-template)             | `addonTitleHtml`, `descriptionHtml`, `priceHtml`, `imageUrl`, `format`, `isEnabled`, `handleAdd`, `handleToggle`, and more         |
| [Shipping protection](/aftersell/cart/shipping-protection-block#custom-template)   | `titleHtml`, `descriptionHtml`, `priceHtml`, `imageUrl`, `format`, `isEnabled`, `handleAdd`, `handleToggle`, and more              |
| [Upsells](/aftersell/cart/upsells-block#custom-template)                           | `title`, `addButtonText`, `layout`, `upsells`, `selectVariant`, `handleAdd`, and the carousel controls                             |

The [Custom code](/aftersell/cart/custom-code-blocks) block is the one surface that **adds** markup rather than replacing a block's rendering, so its props are different: the whole cart, plus an add-to-cart action. See [Custom code blocks → Props](/aftersell/cart/custom-code-blocks#props).


# Design settings
Source: https://docs.aftersell.com/aftersell/cart/design-settings

Global and per-block design settings for the Aftersell Cart: colors, buttons, layout, and how block overrides layer on top.

Aftersell Cart design works at two levels: **global** settings that style the whole cart, and **per-block** overrides that fine-tune an individual block.

## Global design settings

Open **Cart settings** from the editor sidebar to reach the cart's global design. Settings are grouped into Design, Buttons, and Layout.

### Design

| Setting                  | What it controls                                                | Default   |
| ------------------------ | --------------------------------------------------------------- | --------- |
| **Background color**     | The cart's background.                                          | `#ffffff` |
| **Text color**           | Primary text.                                                   | `#000000` |
| **Secondary text color** | Muted / secondary text.                                         | `#a8a8a8` |
| **Accent color**         | Badges, dividers, and strikethrough prices.                     | `#f2f2f2` |
| **Border radius**        | Corner rounding for containers, cards, images, and text inputs. | `8px`     |

### Buttons

| Setting              | What it controls                                               | Default   |
| -------------------- | -------------------------------------------------------------- | --------- |
| **Background color** | Button fill.                                                   | `#000000` |
| **Text color**       | Button label.                                                  | `#ffffff` |
| **Border color**     | Button border.                                                 | `#000000` |
| **Border radius**    | Corner rounding for buttons, dropdowns, and quantity controls. | `8px`     |

### Layout

| Setting                | What it controls                               | Default |
| ---------------------- | ---------------------------------------------- | ------- |
| **Horizontal padding** | Left/right padding inside the cart.            | `24px`  |
| **Desktop width**      | The drawer's width on desktop (minimum 320px). | `440px` |

## Per-block design overrides

Every block except [**Custom code**](/aftersell/cart/custom-code-blocks) has its own per-block design overrides at the bottom of its settings panel — headed **Design** on every block but **Express payments**, whose overrides sit in unlabelled Style and Spacing sections. (Custom code has no settings panel at all — the block *is* the code, so it shows only a Code tab.) They control things like style, spacing and other block-specific design settings. These **per block design settings**, when blank, will fall back to the global setting for that property.

Many blocks also include a **Text** section within their Design panel, where you can set typography for specific text elements in that block — font family, size, line height, and letter spacing. Blocks with multiple text elements (such as Notes and Empty cart) show a **Text element** picker so you can style each one independently.

<Frame>
  <img alt="Animated preview of the per-block Design settings panel in the cart editor" title="Animated preview of the per-block Design settings panel in the cart editor" />
</Frame>

## Fonts and drawer position

* **Fonts:** the cart inherits your **theme's font** by default. You can set a custom font family for select text elements (such as the product title and upsells heading) from the **Text** section in each block's Design settings — see [Cart items block](/aftersell/cart/cart-items-block) and [Upsells block](/aftersell/cart/upsells-block) for details.
* **Drawer position:** the drawer's **width** is adjustable (Desktop width, above); there's no left/right position setting.

## Behavior settings

Beyond styling, **Cart settings** also holds behavior options — opening the drawer on add to cart, and the theme selectors that keep your storefront in sync. See [Cart settings](/aftersell/cart/cart-settings).

## When to use custom CSS instead

The built-in settings cover the common cases. For anything beyond them — targeting a specific element, custom spacing, responsive tweaks — use [Custom CSS](/aftersell/cart/custom-css).


# Discount code block
Source: https://docs.aftersell.com/aftersell/cart/discount-code-block

The Aftersell Cart Discount code block — let shoppers enter and apply a discount code before checkout.

> The **Discount code** block is an input where shoppers can enter and apply a promo code in the cart, so they see the discount reflected before committing to checkout.

<Frame>
  <img alt="Discount code block with input field and Apply button in the cart drawer" />
</Frame>

## Behavior

* On apply, the code is trimmed, upper-cased, and submitted to Shopify. Because Shopify accepts the request whether or not the code is valid, the block then re-checks the cart to confirm the code actually applied.
  * **Valid** → the field clears and the discount applies.
  * **Invalid** → the block shows "Invalid discount code."
* How a code stacks with other discounts (automatic discounts, other codes) is handled entirely by Shopify — the block just applies the code.
* Applied codes are shown in the [**Summary**](/aftersell/cart/summary-block) block, not here.

## Settings

| Setting         | What it controls                            | Default         |
| --------------- | ------------------------------------------- | --------------- |
| **Placeholder** | The input's placeholder text. Translatable. | `Discount code` |
| **Button text** | The apply button label. Translatable.       | `Apply`         |

## Placement and limits

* **Region:** body or bottom.
* **Maximum:** 1 per cart state — the filled cart and the empty cart each get their own allowance.
* **State:** both filled and empty.
* Not added by default. Not locked — you can remove or hide it.

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

| Prop                   | Type                      | What it's for                                                                        |
| ---------------------- | ------------------------- | ------------------------------------------------------------------------------------ |
| `discountCodeInput`    | `string`                  | Current value of the input.                                                          |
| `placeholder`          | `string`                  | Placeholder shown in the empty input.                                                |
| `buttonText`           | `string`                  | Label for the apply button.                                                          |
| `isValidating`         | `boolean`                 | `true` while a submitted code is being checked. Disable your submit control on this. |
| `isInvalid`            | `boolean`                 | `true` when the last submitted code was rejected.                                    |
| `setDiscountCodeInput` | `(value: string) => void` | Updates the input value.                                                             |
| `handleSubmit`         | `(event: Event) => void`  | Submits the current code.                                                            |
| `isLoading`            | `boolean`                 | `true` while the cart is still doing its first fetch.                                |

<Warning>
  Wire both `setDiscountCodeInput` and `handleSubmit`. Without the first, the field can't be typed into; without the second, a code is never applied.
</Warning>

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Empty cart block
Source: https://docs.aftersell.com/aftersell/cart/empty-cart-block

The Empty cart block — the content shown when a shopper has no items.

> The **Empty cart** block is the content shown when the cart has no items, typically a message and a continue-shopping button, so an empty drawer is still useful and on-brand. It only appears in the cart's **empty state**; other blocks (such as Header) can sit alongside it in that same state.

<Frame>
  <img alt="Empty cart block showing an empty-state message and a continue shopping call-to-action" />
</Frame>

## Behavior

* The block appears only when the cart is empty. As soon as a shopper adds an item, the cart switches to its filled state and this block is replaced by your filled-cart layout.
* In the editor, the CTA link is inert so clicking it doesn't navigate you away while designing.

## Settings

| Setting              | What it controls                                                                                                                                           | Default               |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| **Empty cart text**  | The empty-state message. Rich text.                                                                                                                        | `Your cart is empty.` |
| **Button text**      | The button label. Supports inline HTML formatting.                                                                                                         | `Continue shopping`   |
| **Button link**      | Where the button links.                                                                                                                                    | `/collections/all`    |
| **Background color** | Background colour for the block. Blank leaves it transparent, so the cart's own background shows through.                                                  | `transparent`         |
| **Alignment**        | How the block's text and button are aligned — **Left** or **Center**.                                                                                      | Center                |
| **Fit to height**    | Whether the block fills the cart body's remaining height and centres vertically, or sits at content height — **Fill remaining height** or **Fit content**. | Fill remaining height |

## Placement and limits

* **Region:** body.
* **Maximum:** 1 per cart state.
* **State:** empty cart only. This block does not appear in the filled state. New carts also include a Header in the empty state by default; see [How do carts work?](/aftersell/cart/how-carts-work).
* Added to new carts by default. Not locked — you can remove or hide it.

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

| Prop      | Type     | What it's for                                                                    |
| --------- | -------- | -------------------------------------------------------------------------------- |
| `text`    | `string` | The empty-cart message as sanitized HTML.                                        |
| `cta`     | `string` | Call-to-action button label, as plain text.                                      |
| `ctaHtml` | `string` | Call-to-action button label as sanitized HTML — what the default markup renders. |
| `href`    | `string` | Where the call-to-action points.                                                 |

<Note>
  This block only renders when the cart is empty, so there's no cart object in the props. Render `href` as a real `<a>` rather than a scripted navigation, and `text` with `dangerouslySetInnerHTML`, since it's already sanitized HTML.
</Note>

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

### Text

The **Text** section in Design lets you control the typography of two elements. Use the **Text element** picker to switch between them.

**Message** — the empty-state message text. Bold and text color are set in the Rich Text Editor above (in the Settings tab), not here.

| Setting            | What it controls             | Default             |
| ------------------ | ---------------------------- | ------------------- |
| **Font**           | Font family for the message. | Inherits from theme |
| **Size**           | Font size.                   | `18px`              |
| **Line height**    | Line height multiplier.      | `1.3`               |
| **Letter spacing** | Tracking between characters. | Normal              |

**Button label** — the text on the continue-shopping button. Text color is set in the Button section of Design.

| Setting            | What it controls                                         | Default        |
| ------------------ | -------------------------------------------------------- | -------------- |
| **Size**           | Font size.                                               | `15px`         |
| **Weight**         | Font weight — Light, Regular, Medium, Semibold, or Bold. | Semibold (600) |
| **Line height**    | Line height multiplier.                                  | `1.47`         |
| **Letter spacing** | Tracking between characters.                             | Normal         |

### Button

The **Button** section lets you style the CTA button independently from the global button design. Use the **Default / Hover** toggle to switch between the two states.

| Setting              | State   | What it controls                                                                        |
| -------------------- | ------- | --------------------------------------------------------------------------------------- |
| **Background color** | Default | Button fill in its resting state. Falls back to the global button background color.     |
| **Text color**       | Default | Button label color in its resting state. Falls back to the global button text color.    |
| **Background color** | Hover   | Button fill when a customer hovers over it. Falls back to the default background color. |
| **Text color**       | Hover   | Button label color on hover. Falls back to the default text color.                      |
| **Border color**     | —       | Button border color (both states). Falls back to the global button border color.        |
| **Border radius**    | —       | Corner rounding for the button. Falls back to the global button border radius.          |

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Express payments block
Source: https://docs.aftersell.com/aftersell/cart/express-payments-block

The Aftersell Cart Express payments block: surface Shop Pay, PayPal, and other accelerated checkout buttons inside the drawer.

> The **Express payments** block shows accelerated checkout buttons (such as Shop Pay, PayPal, Google Pay, or Apple Pay) inside the cart, giving shoppers the express payment options your store already offers so they can skip straight to a one-tap checkout.

## Behavior

* The block **doesn't render its own buttons.** It surfaces Shopify's own accelerated-checkout buttons inside the drawer, so which methods appear is determined entirely by your store's payment setup.
* **If your store has no accelerated payment methods enabled, nothing renders.** Enable express methods (Shop Pay, PayPal, and so on) in your Shopify settings.
* **Your theme usually needs a one-time code change too.** The block *clones* Shopify's accelerated-checkout buttons out of your storefront page, so those buttons have to be rendered there in the first place.
* In the editor, the block shows a placeholder in place of the live buttons.

### Adding the theme snippet

The block's settings panel has a **Show recommended guide to edit your theme code** section with the exact snippet and a **Copy code** button. In short:

1. Open your theme's code editor, then `layout/theme.liquid`.
2. Find the `<body>` line and add a new line below it.
3. Paste the snippet the panel gives you. It renders Shopify's accelerated-checkout buttons in a hidden container, so the cart has something to clone.
4. Save.

## Settings

| Setting                       | What it controls                                                                                     | Default  |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- | -------- |
| **Default button height**     | The button height on desktop, in pixels.                                                             | `42`     |
| **Mobile button height**      | The button height on mobile, in pixels.                                                              | `42`     |
| **Checkout button alignment** | `left`, `center`, `right`, or `space-between`. Applies only when the buttons fit on one row.         | `center` |
| **Row gap**                   | Vertical spacing between rows, in pixels. Applies only when the buttons wrap onto more than one row. | `8`      |

## Placement and limits

* **Region:** bottom.
* **Maximum:** 1 per cart state.
* **State:** filled cart only.
* Not added by default. Not locked — you can remove or hide it.

## Custom template

The Express payments block does **not** support a custom template, because it hosts Shopify's own payment buttons. Style it with the block's Design settings instead.

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Managing multiple carts
Source: https://docs.aftersell.com/aftersell/cart/having-multiple-carts

Save and manage more than one Aftersell Cart, and understand how only one goes live at a time alongside A/B tests.

You can save as many carts as you like, but **only one cart is live at a time.** This page explains how multiple carts work together.

## One live cart

The Carts page splits your carts into **Live carts** and **Draft carts**. There is always at most one live cart, and every shopper sees that same cart.

* **Publishing** a draft makes it live and **moves the previously live cart back to draft** — so publishing is also how you switch which cart is live.
* There is **no per-shopper targeting** that picks between whole carts. You don't route some shoppers to Cart A and others to Cart B outside of a test (below).

## Why keep multiple carts

Even with one live cart, saving several is useful for:

* **Preparing variants** — build a seasonal or campaign cart as a draft and publish it when you're ready.
* **A/B testing** — compare two carts against real traffic (below).
* **Keeping a known-good version** to fall back to.

To start a new cart from an existing one, use the **Duplicate** action in the Carts list.

## Running two carts at once: A/B tests

The way to serve two carts to real traffic at the same time is a [**cart test**](/aftersell/cart/tests-overview). A test pits your live cart against one challenger draft and splits traffic between them by a weight you set. Shoppers are stickily bucketed, so a returning shopper keeps seeing the same variant for the duration of the test. When you end the test, you pick the winner and it becomes the live cart.

Only one test can run per store at a time.

## Conditions target blocks, not carts

Aftersell does have **conditions** based on Shopify market, customer country, and customer currency — but these vary the content *inside a single cart* (most notably the [Rewards](/aftersell/cart/rewards-block) block's tiers), not which cart a shopper sees. Use conditions to localize a block; use publishing or a test to choose between whole carts.


# Header block
Source: https://docs.aftersell.com/aftersell/cart/header-block

The Aftersell Cart Header block: the title, item count, logo, and close control pinned to the top of the drawer.

> The **Header** block is the pinned top area of the cart drawer, giving the drawer a clear title and an obvious way to close it. You control its layout by assigning **Title**, **Logo**, and **Close button** to the left and right sections. Because the Header is pinned to the top, it stays visible while the rest of the cart scrolls.

<Frame>
  <img alt="Header block with cart title, item count, and close control at the top of the drawer" />
</Frame>

## Behavior

* The Header is pinned to the top of the drawer and doesn't scroll with the cart body.
* The close control is always available and dismisses the drawer.

## Settings

| Setting   | What it controls                                                                                                                                                                                             | Default                      |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
| **Left**  | Which elements render in the left section (`Title`, `Logo`, `Close button`) and in what order.                                                                                                               | `Title`                      |
| **Right** | Which elements render in the right section (`Title`, `Logo`, `Close button`) and in what order.                                                                                                              | `Close button`               |
| **Title** | Rich-text heading for the cart. Supports the `{{cart_item_count}}` and `{{total_price}}` tokens.                                                                                                             | `Cart • {{cart_item_count}}` |
| **Image** | An image exposed to a custom template as `props.logoUrl`. This field only appears while a custom template is active, and the built-in header never renders it. Supported formats: WebP, JPEG, PNG, GIF, SVG. | None                         |

The title is translatable. If your title resolves to empty (for example, an unset translation), the cart falls back to showing **Cart** so the header is never blank.
Elements appear in the order you select them, left to right, and each element can be assigned to only one section at a time.

## Placement and limits

* **Region:** top only.
* **Maximum:** 1 per cart state.
* **State:** filled and empty cart (each state has its own Header instance).
* Added to new carts by default in both states. Not locked, so you can remove or hide it with the eye toggle.

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

<Note>
  `logoUrl` is the one prop that has no built-in equivalent: the Header's uploaded image is **only ever rendered by a custom template**. If a merchant set a logo and it isn't showing, this is why.
</Note>

| Prop           | Type                                      | What it's for                                                                                                                 |
| -------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `title`        | `string`                                  | The header title as sanitized HTML, with `{{cart_item_count}}` and `{{total_price}}` already resolved.                        |
| `logoUrl`      | `string \| null`                          | The uploaded header image. `null` when the merchant hasn't set one.                                                           |
| `leftSection`  | `('title' \| 'logo' \| 'close_button')[]` | Items selected for the left section, in render order.                                                                         |
| `rightSection` | `('title' \| 'logo' \| 'close_button')[]` | Items selected for the right section, in render order.                                                                        |
| `itemCount`    | `number`                                  | Items in the cart, as the shopper sees it.                                                                                    |
| `onClose`      | `() => void`                              | Closes the drawer. Wire it to your close control.                                                                             |
| `isLoading`    | `boolean`                                 | Always `false` here: the block renders its built-in skeleton during load and only calls your template once the cart is ready. |

<Warning>
  If you don't wire `onClose` to something, shoppers can still close the drawer by clicking the overlay or pressing Escape, but your header will have no close button. Always include one.
</Warning>

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

### Text

The **Text** section in Design lets you control the typography of the cart title. Bold and text color are set in the Rich Text Editor above (in the Settings tab), not here.

| Setting            | What it controls             | Default             |
| ------------------ | ---------------------------- | ------------------- |
| **Font**           | Font family for the title.   | Inherits from theme |
| **Size**           | Font size.                   | `18px`              |
| **Line height**    | Line height multiplier.      | `1.3`               |
| **Letter spacing** | Tracking between characters. | Normal              |

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# How do carts work?
Source: https://docs.aftersell.com/aftersell/cart/how-carts-work

How an Aftersell Cart is structured: filled and empty states, Header/Body/Footer sections, and how blocks fit into each.

A **cart** in Aftersell is a configurable cart-drawer experience. You design it in two **states**, lay it out across three **sections**, and fill those sections with **blocks**.

## Cart states

Every cart has two independent layouts. You switch between them in the editor:

* **Filled cart**: what shoppers see when the cart has items.
* **Empty cart**: what shoppers see when the cart has no items.

Some blocks only belong in one state:

* The [**Empty cart**](/aftersell/cart/empty-cart-block) block appears only in the **empty** state.
* [**Cart items**](/aftersell/cart/cart-items-block), [**Checkout button**](/aftersell/cart/checkout-button-block), [**Notes**](/aftersell/cart/notes-block), [**Express payments**](/aftersell/cart/express-payments-block), and [**Shipping protection**](/aftersell/cart/shipping-protection-block) appear only in the **filled** state.

Other blocks (Header, Banner, Rewards, Image, Custom code, and more) can live in either state. New carts start with **Header + Empty cart** in the empty state, and **Header → Banner → Cart items → Summary → Checkout button** in the filled state.

<Info>
  The **empty cart state** is the whole empty layout. The **Empty cart block** is one block inside that layout, usually the message and continue-shopping button. They sound alike, but the state can hold more than that one block.
</Info>

## Sections

Each state is divided into three sections: **Header**, **Body**, and **Footer**. Sections control where a block sits and how it scrolls:

* **Header**: pinned to the top of the drawer; stays visible as the body scrolls.
* **Body**: the scrollable middle. Blocks here move with the content. Locked block: **Cart items**.
* **Footer**: pinned to the bottom of the drawer. Locked block: **Checkout button**.

When you add or move a block, its section decides its scrolling behavior. Not every block is available in every section. See [How do blocks work?](/aftersell/cart/blocks-overview#blocks-available-in-each-section).

## Blocks

A **block** is a configurable piece of the drawer (the product list, an upsell offer, a checkout button, and so on). You stack them in a section, reorder them, and style them. For how adding, limits, sub-blocks, and conditions work, see [How do blocks work?](/aftersell/cart/blocks-overview).

## Next steps

* [Create a cart](/aftersell/cart/creating-carts)
* [Preview a cart](/aftersell/cart/previewing-carts)
* [Manage multiple carts](/aftersell/cart/having-multiple-carts)


# Image block
Source: https://docs.aftersell.com/aftersell/cart/image-block

The Aftersell Cart Image block — display an image or a hosted preset such as payment icons inside the drawer.

> The **Image** block displays a single image inside the cart drawer (a trust badge, a promotional graphic, or a hosted preset such as a strip of payment icons) to add visual reassurance or promotion to the cart, either by uploading your own image or by dropping in a ready-made preset.

<Frame>
  <img alt="Image block rendering a hosted image or preset asset inside the cart drawer" />
</Frame>

## Behavior

* If no image and no preset are set, the block renders **nothing** on the live cart. In the editor it shows an "Add an image" placeholder so the block stays selectable.

## Settings

| Setting        | What it controls                                                                               | Default |
| -------------- | ---------------------------------------------------------------------------------------------- | ------- |
| **Image**      | The image to display (upload).                                                                 | None    |
| **Alt text**   | Accessible description of the image. Translatable.                                             | None    |
| **Max height** | Caps the image height in pixels. The image shrinks to fit and is never cropped.                | None    |
| **Full width** | Stretches the image edge to edge across the cart.                                              | Off     |
| **Preset**     | A hosted image set that overrides your upload. Currently the only preset is **payment icons**. | None    |

When you select a preset, it takes the place of any uploaded image, and the preset's own alt text is used if you leave the Alt text field blank.

## Placement and limits

* **Region:** any (top, body, or bottom).
* **Maximum:** 3 per cart state — the filled cart and the empty cart each get their own allowance.
* **State:** both filled and empty cart.
* Not added by default. Not locked — you can remove or hide it.

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

| Prop        | Type                | What it's for                                                                  |
| ----------- | ------------------- | ------------------------------------------------------------------------------ |
| `imageUrl`  | `string`            | The uploaded file or selected preset. Empty when none is set.                  |
| `altText`   | `string`            | Alt text for the image.                                                        |
| `maxHeight` | `number` (optional) | Max height in pixels. Taller images shrink to fit, preserving aspect ratio.    |
| `fullWidth` | `boolean`           | Edge-to-edge: the image spans the full cart width, with no horizontal padding. |

<Note>
  `altText` may be empty. Render `alt=""` rather than omitting the attribute, so the image is treated as decorative. `maxHeight` and `fullWidth` are values for you to apply in your own styles; the template doesn't apply them for you.
</Note>

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Notes block
Source: https://docs.aftersell.com/aftersell/cart/notes-block

The Aftersell Cart Notes block: a collapsible order-notes field that saves shopper instructions to the cart and order.

> The **Notes** block is a collapsible field where shoppers can add order notes or special instructions (gift messages, delivery instructions, and so on) without leaving the cart. The note is saved to the cart and carried through to the order.

<Frame>
  <img alt="Notes block showing a collapsible order-notes field where shoppers can add special instructions" />
</Frame>

## Behavior

* The field is a **collapsible disclosure**, collapsed by default. Collapsing is visual only — a saved note still applies. When collapsed with a note saved, a check mark shows so the shopper knows their note is stored.
* The note **saves when the shopper clicks away** (on blur), with saving / saved / error status feedback.
* If the cart note changes elsewhere — the `/cart` page or another tab — the field syncs to it, unless the shopper has already started typing, so their in-progress note is never overwritten.

## Settings

| Setting         | What it controls                            | Default                               |
| --------------- | ------------------------------------------- | ------------------------------------- |
| **Title**       | The field's label. Rich text, translatable. | `Order notes`                         |
| **Placeholder** | The input's placeholder text. Translatable. | `Special instructions for your order` |

## Placement and limits

* **Region:** body or bottom.
* **Maximum:** 1 per cart state.
* **State:** filled cart only.
* Not added by default. Not locked — you can remove or hide it.

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

| Prop            | Type                                       | What it's for                                                                                           |
| --------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `titleHtml`     | `string`                                   | Sanitized rich-text title HTML. Empty when the merchant left the title blank.                           |
| `titleText`     | `string`                                   | Plain-text title. Use it for the textarea's `aria-label`, and as the heading when there's no rich text. |
| `hasTitle`      | `boolean`                                  | Whether either title form is present. Gates the heading and the toggle's `aria-label`.                  |
| `placeholder`   | `string`                                   | Placeholder shown in the empty note field.                                                              |
| `noteInput`     | `string`                                   | Current note text.                                                                                      |
| `status`        | `'idle' \| 'saving' \| 'saved' \| 'error'` | Save lifecycle. Drives the spoken status live region.                                                   |
| `statusLabel`   | `string`                                   | Resolved live-region announcement for `status`. Empty when idle.                                        |
| `displayStatus` | `'idle' \| 'saving' \| 'saved' \| 'error'` | Status for the icon. Like `status`, except a collapsed note with text reads as `saved`.                 |
| `isExpanded`    | `boolean`                                  | Whether the note field is expanded. Collapsing is visual only; the note always persists.                |
| `onNoteChange`  | `(value: string) => void`                  | Updates the note text. Call with the new value, for example from the textarea's `onInput`.              |
| `onNoteBlur`    | `(event: unknown) => void`                 | Saves the note. Attach directly to the textarea's `onBlur`; it reads the value off the event.           |
| `onToggle`      | `() => void`                               | Toggles the expand and collapse state.                                                                  |

<Warning>
  **The note saves on `onNoteBlur`, not on every keystroke.** Wire both `onNoteChange` and `onNoteBlur`, or notes silently never persist. Keep the status text in a live region so screen readers announce saving and saved.
</Warning>

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

### Text

The **Text** section in Design lets you control the typography of two elements. Use the **Text element** picker to switch between them.

**Title** — the section heading above the note field. Bold is set in the Rich Text Editor above (in the Settings tab). Text color is set in the Toggle section of Design.

| Setting            | What it controls             | Default |
| ------------------ | ---------------------------- | ------- |
| **Size**           | Font size.                   | `14px`  |
| **Line height**    | Line height multiplier.      | `1.4`   |
| **Letter spacing** | Tracking between characters. | Normal  |

**Note field** — the text inside the textarea where shoppers type their note.

| Setting            | What it controls                                         | Default                       |
| ------------------ | -------------------------------------------------------- | ----------------------------- |
| **Text color**     | Color of the note text.                                  | Inherits from cart text color |
| **Size**           | Font size.                                               | `14px`                        |
| **Weight**         | Font weight — Light, Regular, Medium, Semibold, or Bold. | Regular (400)                 |
| **Line height**    | Line height multiplier.                                  | `1.5`                         |
| **Letter spacing** | Tracking between characters.                             | Normal                        |

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Aftersell Cart Overview
Source: https://docs.aftersell.com/aftersell/cart/overview

What the Aftersell Cart is, who it's for, and how to get started building a custom drawer experience.

The **Aftersell Cart** is a fully customizable cart-drawer experience for your Shopify store. It replaces the default cart with a slide-out drawer you build block by block, adding upsells, rewards, and add-ons, styling it to match your brand, A/B testing variations, and extending it with a JavaScript SDK.

## What it is

When a shopper adds a product, the Aftersell Cart opens as a drawer over your storefront. You design that drawer in the cart editor from a set of [blocks](/aftersell/cart/blocks-overview) (the product list, a checkout button, upsells, rewards, banners, and more) and style it with global and per-block [design settings](/aftersell/cart/design-settings).

## Requirements

* A Shopify store with the Aftersell app installed.
* The **Aftersell Cart app embed** enabled in your theme, so a published cart renders on your storefront.

## Key concepts

* **Carts**: a cart is one complete drawer experience. See [how carts work](/aftersell/cart/how-carts-work), and only [one is live at a time](/aftersell/cart/having-multiple-carts).
* **Blocks**: the building pieces of a cart. See [how blocks work](/aftersell/cart/blocks-overview).
* **Design settings**: global and per-block [styling](/aftersell/cart/design-settings), plus [custom CSS](/aftersell/cart/custom-css).
* **Tests**: [A/B test](/aftersell/cart/tests-overview) one cart against another and read the [analytics](/aftersell/cart/test-analytics).
* **SDK**: extend the cart with [JavaScript](/aftersell/cart/sdk-overview).

## Getting started

1. [Create a cart](/aftersell/cart/creating-carts). It starts from a working default layout.
2. [Add and arrange blocks](/aftersell/cart/blocks-overview) to build the experience you want.
3. [Customize the look](/aftersell/cart/design-settings) with design settings and, if needed, custom CSS.
4. [Preview](/aftersell/cart/previewing-carts) it, then publish.
5. Optionally, [test](/aftersell/cart/tests-overview) variations and [extend with the SDK](/aftersell/cart/sdk-overview).

## How these docs are organized

* [**Managing carts**](/aftersell/cart/how-carts-work): how carts are structured, then create, preview, and run one or more carts.
* [**Customizing your cart**](/aftersell/cart/design-settings): design settings, behavior settings, custom CSS, and custom scripts.
* [**Cart blocks**](/aftersell/cart/blocks-overview): how blocks work, a page for every block, plus custom templates and custom code.
* [**Cart tests**](/aftersell/cart/tests-overview): set up A/B tests and read their results.
* [**Analytics**](/aftersell/cart/analytics): how a published cart is performing — revenue, conversion, impressions, and top products.
* [**Cart SDK**](/aftersell/cart/sdk-overview): events, actions, hooks, and use cases for extending the cart with code.


# Previewing carts
Source: https://docs.aftersell.com/aftersell/cart/previewing-carts

Preview your Aftersell Cart before publishing — in the editor canvas and on your live storefront theme.

You can preview a cart two ways: live in the editor as you build it, and on your storefront theme before it goes public.

## The editor canvas

The center of the cart editor is a live preview that renders the real cart. It shows **both cart states side by side** — a **Filled cart** card and an **Empty cart** card — so you can see both as you work.

* **Choose which state you're editing** with the **Filled / Empty** toggle in the sidebar, or by clicking the **title above** a card. Clicking *inside* a card doesn't switch state — it selects the block under your cursor. The active card is outlined, and the block you're editing gets its own highlight.
* **Zoom** with the zoom pill on the canvas itself (25%–200%): `+` and `−` step by 10%, and clicking the percentage resets to 75%. Ctrl/Cmd + scroll zooms around your cursor, plain scroll and dragging pan.
* The preview reflects your [design settings](/aftersell/cart/design-settings) and [custom CSS](/aftersell/cart/custom-css) live as you change them.

## Preview on your storefront

Use **Preview** on a cart to see it on a real theme in a new tab, without making it public:

* **Live carts** open your storefront directly — the live cart is already what shoppers see.
* **Draft carts** open a **theme preview**. You pick which theme to preview on (your main theme is the default), and Aftersell stages the draft cart on that theme just for your preview session, without touching your live cart. The app embed must be enabled on the theme you choose.

<Note>
  Draft previews may not fully reflect live cart behavior — treat them as a close approximation, and do a final check after publishing.
</Note>

Save your changes before previewing — the editor prompts you to save so the preview reflects your latest work.

## Empty vs. filled states

Both states are always available in the editor canvas (the two cards), so you can design and check the empty cart and the filled cart independently. On the storefront, shoppers see whichever state matches their cart.

## Sample data scenarios

The [Cart items block](/aftersell/cart/cart-items-block) settings panel has a **Preview** section with a **Sample data** picker, letting you switch the editor preview between line-item scenarios so you can check how each one looks without building a matching cart:

| Scenario              | What it shows                                                              |
| --------------------- | -------------------------------------------------------------------------- |
| **Standard product**  | A single product with a discount applied.                                  |
| **Long product name** | A product with a very long title, for checking text wrapping and overflow. |
| **Bundle**            | A bundle anchor line with its child items.                                 |
| **Subscription**      | A subscription line with its selling plan label.                           |
| **All item types**    | The long product name, subscription and bundle lines together in one cart. |

Your choice affects the editor preview only. It's never saved to the cart, and it resets when you reload the editor.


# Product add-on block
Source: https://docs.aftersell.com/aftersell/cart/product-add-on-block

The Aftersell Cart Product add-on block: offer one specific product as a quick add inside the drawer.

> The **Product add-on** block offers a single, specific product you choose as an add-on inside the cart, promoting one known product (a warranty, a sample, a best-seller) as a quick add directly in the cart.

<Info>
  Unlike [**Upsells**](/aftersell/cart/upsells-block), which surfaces products chosen by a strategy, the Product add-on always shows the exact product you pick.
</Info>

<Frame>
  <img alt="Product add-on block offering an additional product for the shopper to include with their cart" />
</Frame>

## Behavior

* **If no live variant resolves** — the product is unset, archived, or out of stock — the block renders **nothing** rather than a dead button.
* The control reflects whether *this block's own* add-on line is in the cart, so switching it off removes the line it added (and won't affect the same product added elsewhere).
* A compare-at price strikes through when there's a genuine markdown; the "% off" label is hidden if the discount rounds below 1%.
* The add-on image falls back to the product's featured image when the chosen variant has none.

## Settings

| Setting          | What it controls                                                                                     | Default                               |
| ---------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------- |
| **Display type** | How the add control appears: **Toggle** or **Checkbox**.                                             | Toggle                                |
| **Product**      | The product variant to offer — one picker covers both. Image and price come from the chosen variant. | None                                  |
| **Title**        | Rich-text heading.                                                                                   | `<strong>{{product_title}}</strong>`  |
| **Price label**  | The price line.                                                                                      | `{{price}}`                           |
| **Description**  | Supporting copy.                                                                                     | `Add {{product_title}} to your order` |

**Title**, **Price label**, and **Description** all support the same four tokens: `{{product_title}}`, `{{price}}`, `{{compare_at_price}}`, and `{{savings}}`.

## Placement and limits

* **Region:** body or bottom.
* **Maximum:** 3 per cart state — the filled cart and the empty cart each get their own allowance.
* **State:** both filled and empty cart.
* Not added by default. Not locked — you can remove or hide it.

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

### Content

| Prop                      | Type             | What it's for                                                                                               |
| ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `addonTitle`              | `string`         | Plain-text title. Use it for the alt text and `aria-label`, and as the fallback when there's no rich title. |
| `addonTitleHtml`          | `string`         | Sanitized rich-text title HTML. Empty when none.                                                            |
| `descriptionHtml`         | `string`         | Sanitized rich-text description HTML. Empty when none.                                                      |
| `formattedPrice`          | `string`         | Currency-formatted price label. Empty when not shown.                                                       |
| `formattedCompareAtPrice` | `string`         | Formatted variant compare-at (MSRP). Empty when there's no real saving.                                     |
| `savings`                 | `string`         | Whole-percent saving label, for example `25%`. Empty when there's no saving.                                |
| `priceHtml`               | `string \| null` | Sanitized rich-text price HTML from the dedicated price field. `null` when empty.                           |
| `ctaText`                 | `string`         | Button label, for the `button` format.                                                                      |
| `imageUrl`                | `string`         | Product image. Empty when none.                                                                             |
| `productUrl`              | `string`         | Product page URL. Empty when none, in which case don't link the image or title.                             |

### State and actions

| Prop           | Type                                 | What it's for                                                                                        |
| -------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `variantId`    | `number \| null`                     | Resolved variant. `null` when there's no live variant, because the product is unset or out of stock. |
| `format`       | `'button' \| 'checkbox' \| 'toggle'` | How the buyer adds the add-on. Branch your markup on this.                                           |
| `isEnabled`    | `boolean`                            | Whether the add-on is currently in the cart.                                                         |
| `isAdding`     | `boolean`                            | `true` while the add or remove is in flight. Disable your control on this.                           |
| `handleAdd`    | `() => void`                         | Adds the add-on. For the `button` format.                                                            |
| `handleToggle` | `() => void`                         | Toggles the add-on in and out of the cart. For `checkbox` and `toggle`.                              |
| `isLoading`    | `boolean`                            | `true` while the cart is still doing its first fetch.                                                |

<Warning>
  `format` decides which handler applies: `handleAdd` for `button`, `handleToggle` for `checkbox` and `toggle`. A `null` `variantId` means there's nothing to add, so gate your control on it rather than calling a handler that can't succeed.
</Warning>

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

### Text

The **Text** section in Design lets you control the typography of three elements. Use the **Text element** picker to switch between them.

**Title** — the product name. Also supports a custom font family. Bold and text color are set in the Rich Text Editor above (in the Settings tab), not here.

| Setting            | What it controls             | Default             |
| ------------------ | ---------------------------- | ------------------- |
| **Font**           | Font family for the title.   | Inherits from theme |
| **Size**           | Font size.                   | `15px`              |
| **Line height**    | Line height multiplier.      | `1.33`              |
| **Letter spacing** | Tracking between characters. | Normal              |

**Price** — the price line. Bold and text color are set in the Rich Text Editor above.

| Setting            | What it controls             | Default |
| ------------------ | ---------------------------- | ------- |
| **Size**           | Font size.                   | `15px`  |
| **Line height**    | Line height multiplier.      | `1.33`  |
| **Letter spacing** | Tracking between characters. | Normal  |

**Description** — the supporting copy. Bold and text color are set in the Rich Text Editor above.

| Setting            | What it controls             | Default |
| ------------------ | ---------------------------- | ------- |
| **Size**           | Font size.                   | `14px`  |
| **Line height**    | Line height multiplier.      | `1.29`  |
| **Letter spacing** | Tracking between characters. | Normal  |

<Tip>
  Clicking a text element directly in the cart preview highlights it and opens its controls in the panel automatically.
</Tip>

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Rewards block
Source: https://docs.aftersell.com/aftersell/cart/rewards-block

The Aftersell Cart Rewards block: tiered free shipping, discounts, and free gifts, including different tiers by market, country, or currency.

> The **Rewards** block shows a progress bar toward reward tiers (free shipping, an order discount, or a free gift) that shoppers unlock by adding more to their cart, motivating larger carts by showing shoppers how close they are to the next reward and granting qualifying rewards automatically. Tiers can vary by market, country, and currency.

<Frame>
  <img alt="Rewards block showing a progress bar toward tiered rewards such as free shipping and a free gift" />
</Frame>

## Tier threshold validation

Each condition's tier list holds up to **4** tiers — a Rewards block with several market, country or currency conditions stores up to 4 per condition, and because the first matching condition is the one shown, any single shopper sees at most 4. Each tier's threshold must be strictly greater than the tier above it — thresholds must be in ascending order. If a tier's threshold is equal to or lower than the previous tier's threshold, an inline error appears on that tier's threshold field and the **Save** button is blocked until the issue is resolved. The affected tier automatically expands so the error is visible.

For example, if Tier 1 is set to \$100, Tier 2 must be set to \$101 or higher.

## Behavior

* Progress **excludes** reward-gift lines, product add-on lines, shipping-protection lines, and gift cards from the total, so those items don't inflate the shopper toward a reward.
* The message shows the remaining amount or count to the next tier, or the completed message once all tiers are met.
* **Free gifts are granted automatically.** When a shopper reaches a gift tier, the gift is added to the cart; if they drop below it, the gift is removed. With stackable rewards off, only the top achieved tier's gift is granted.
* **Add back removed free gifts** controls what happens when a shopper manually removes an auto-granted gift. When enabled (the default), the gift is automatically re-added on the next cart update. When disabled, the removal is respected and the gift stays out of the cart for the rest of that session, so shoppers aren't fighting the cart to decline a gift.

## Settings

| Setting                                    | What it controls                                                                                                              | Default                 |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **Rewards calculation**                    | Whether progress is measured by **Cart total (\$)** or **Cart quantity (#)**.                                                 | Cart total (\$)         |
| **Stack rewards across tiers**             | On: apply every reward the buyer unlocks, up to the highest tier reached. Off: apply only the highest unlocked tier's reward. | On                      |
| **Add back removed free gifts**            | Re-add an earned free gift after the buyer removes it.                                                                        | On                      |
| **Show tier icons**                        | Whether tier icons appear on the bar.                                                                                         | On                      |
| **Show tier labels**                       | Whether the label text appears on each tier marker on the bar.                                                                | Off                     |
| **Text after completing full rewards bar** | Rich text shown once all tiers are met.                                                                                       | `All rewards unlocked!` |
| **Tiers**                                  | The reward tiers (below). Up to **4** per condition; the panel shows a `n/4` counter and disables **Add tier** at the cap.    | None                    |

Each **tier** expands to:

| Tier setting                               | What it controls                                                                                                                                        | Default                                      |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| **Reward type**                            | **Free shipping**, **Order discount**, or **Free gift**. Changing it resets that tier's title and progress bar label to the new type's default wording. | Free shipping                                |
| **Threshold (\$)** / **Threshold (items)** | The cart total or item count that unlocks the tier. The label follows **Rewards calculation**. Minimum `1`.                                             | `50`                                         |
| **Discount value type**                    | Order discounts only: **Percentage (%)** or **Fixed amount (\$)**.                                                                                      | Percentage (%)                               |
| **Percentage off** / **Amount off**        | Order discounts only: the discount amount. Percentages are capped at 100.                                                                               | `10`                                         |
| **Title before achieving tier**            | Rich-text message shown while the shopper is still short of the tier. Supports the `{{amount}}` token.                                                  | `You're {{amount}} away from free shipping!` |
| **Progress bar label**                     | The label shown on the tier marker.                                                                                                                     | `Free shipping`                              |
| **Gift products**                          | Free gifts only: the product(s)/variant(s) granted, up to **3** per tier.                                                                               | None                                         |

## Placement and limits

* **Region:** any (top, body, or bottom).
* **Maximum:** 1 per cart state — the filled cart and the empty cart each get their own.
* **State:** both filled and empty cart.
* Not added by default. Not locked, so you can remove or hide it.

## Per-market rewards

Rewards is the block with the full **Conditions** UI today: define multiple sets of tiers, each targeting a **Shopify market**, **customer country**, or **customer currency** (**In** or **Not in**). The first matching condition is shown to the shopper. If none match, the block renders nothing for them.

Each condition is a card in the settings panel (**When** + condition). Below it, a **Display** section holds the tiers for that condition. Keep specific rules above an **All buyers** catch-all. Order is priority, not a combination of every match.

You can't delete the last condition (at least one is always required). Editor preview doesn't evaluate the live buyer; select a condition in the panel to preview that variant.

For how conditions relate to the eye toggle and other blocks, see [Show or hide by market, country, or currency](/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency).

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

| Prop                 | Type          | What it's for                                                                                                                 |
| -------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `milestones`         | `Milestone[]` | The reward tiers, in order. See below.                                                                                        |
| `rewardsMessageHtml` | `string`      | The progress or completion message as sanitized HTML.                                                                         |
| `showIcons`          | `boolean`     | Whether the merchant enabled tier icons.                                                                                      |
| `showTierLabels`     | `boolean`     | Whether the merchant enabled tier bar labels.                                                                                 |
| `isLoading`          | `boolean`     | Always `false` here: the block renders its built-in skeleton during load and only calls your template once the cart is ready. |

Each `Milestone`:

| Field             | Type                   | What it's for                                                                                           |
| ----------------- | ---------------------- | ------------------------------------------------------------------------------------------------------- |
| `id`              | `string`               | Stable key for the tier. Use it as your React `key`.                                                    |
| `label`           | `string`               | The tier's label, as plain text.                                                                        |
| `icon`            | `ReactElement \| null` | Pre-rendered icon element. `null` when the tier has none. Render it directly: `{m.icon}`.               |
| `isCompleted`     | `boolean`              | Whether the cart has reached this tier.                                                                 |
| `positionPercent` | `number`               | How full **this tier's own segment** of the bar is, `0` to `100` — not a position along one shared bar. |

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function Rewards(props) {
  return (
    <div>
      <div dangerouslySetInnerHTML={{ __html: props.rewardsMessageHtml }} />

      {props.milestones.map((milestone) => (
        // Each tier gets its own track; positionPercent (0-100) fills that track.
        <div key={milestone.id}>
          <div style={{ background: '#E9E9E9', height: 5 }}>
            <div style={{ width: `${milestone.positionPercent}%`, background: '#000', height: 5 }} />
          </div>
          {props.showIcons && milestone.icon ? milestone.icon : null}
          {props.showTierLabels && milestone.label !== '' ? milestone.label : null}
        </div>
      ))}
    </div>
  );
}
```

`m.icon` is a **pre-rendered element**, not a URL or an icon name, so render it directly rather than trying to build an image element from it.

<Note>
  `milestones` is never empty inside a custom template. When there are no tiers to show, the block renders nothing and your template isn't called at all, so you don't need an empty-state branch.
</Note>

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

### Text

The **Text** section in Design lets you control the typography of the rewards text elements. Use the **Text element** picker to switch between them.

**Message** — the progress or completion message. Also supports a custom font family. Bold and text color are set in the Rich Text Editor above (in the Settings tab), not here.

| Setting            | What it controls             | Default             |
| ------------------ | ---------------------------- | ------------------- |
| **Font**           | Font family for the message. | Inherits from theme |
| **Size**           | Font size.                   | `14px`              |
| **Line height**    | Line height multiplier.      | `1.43`              |
| **Letter spacing** | Tracking between characters. | Normal              |

**Tier label** — the label shown on each tier marker. Only available when **Show tier labels** is enabled.

| Setting            | What it controls                                         | Default              |
| ------------------ | -------------------------------------------------------- | -------------------- |
| **Text color**     | Color of the tier label.                                 | Secondary text color |
| **Size**           | Font size.                                               | `13px`               |
| **Weight**         | Font weight — Light, Regular, Medium, Semibold, or Bold. | Regular (400)        |
| **Line height**    | Line height multiplier.                                  | `1.2`                |
| **Letter spacing** | Tracking between characters.                             | Normal               |

<Tip>
  Clicking a text element directly in the cart preview highlights it and opens its controls in the panel automatically.
</Tip>

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Actions
Source: https://docs.aftersell.com/aftersell/cart/sdk-actions

Every Aftersell Cart SDK action for reading and changing the cart: open, close, add, remove, update quantity, swap a variant, read state, and format money.

Actions **read and change the cart**. They live under `window.aftersell.cart.actions`.

<Note>
  Actions run **after the cart is ready**, inside `ready()` or an [event](/aftersell/cart/sdk-events) handler.
</Note>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log(state.itemCount, 'items');
});
```

<Note>
  **Before the cart loads, actions are stubs.** Each one logs a console warning naming the action, for example `cart.actions.addItem() called before the cart loaded`, and does nothing. The async actions still resolve a Promise, so a `.then()` chain runs normally rather than throwing; `getCart()` returns `null` and `formatMoney()` returns an empty string.

  Nothing breaks if you call one too early, but nothing happens either. Watch the console for that warning when an action appears to do nothing.
</Note>

## Every action

| Action                                                   | Signature                            | Returns                 | What it does                     |
| -------------------------------------------------------- | ------------------------------------ | ----------------------- | -------------------------------- |
| [`open`](#open-and-close)                                | `open()`                             | None                    | Opens the drawer.                |
| [`close`](#open-and-close)                               | `close()`                            | None                    | Closes the drawer.               |
| [`getCart`](#getcart)                                    | `getCart()`                          | `AftersellCart \| null` | Reads the current cart.          |
| [`formatMoney`](#formatmoneycents)                       | `formatMoney(cents)`                 | `string`                | Formats an amount for display.   |
| [`addItem`](#additemvariantid-quantity)                  | `addItem(variantId, quantity?)`      | `Promise`               | Adds a variant.                  |
| [`removeItem`](#removeitemkey)                           | `removeItem(key)`                    | `Promise`               | Removes a line.                  |
| [`updateItemQuantity`](#updateitemquantitykey-quantity)  | `updateItemQuantity(key, quantity)`  | `Promise`               | Sets a line's quantity.          |
| [`replaceLineVariant`](#replacelinevariantkey-variantid) | `replaceLineVariant(key, variantId)` | `Promise`               | Swaps a line's variant.          |
| [`refresh`](#refresh)                                    | `refresh()`                          | `Promise`               | Refetches the cart from Shopify. |
| [`visualRefresh`](#visualrefresh)                        | `visualRefresh()`                    | None                    | Repaints without refetching.     |

<Warning>
  Calling an action from a `cart_updated` handler can loop. Read [the two rules](/aftersell/cart/sdk-events#the-two-rules) first.
</Warning>

***

## Drawer

### open and close

Open or close the cart drawer. Both are synchronous and take no arguments.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Open the drawer from your own cart link.
document.querySelector('#my-cart-link').addEventListener('click', (event) => {
  event.preventDefault();
  window.aftersell.cart.actions.open();
});
```

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Close it after the shopper does something in a custom block.
window.aftersell.cart.actions.close();
```

***

## Reading

### getCart()

Returns the current [cart object](/aftersell/cart/sdk-cart-object), or `null` before it has loaded. The result is a **copy**, so mutating it won't change the real cart.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  if (!state) return; // the initial load failed

  console.log(state.itemCount, 'items,', state.items.length, 'lines');
  console.log('Total:', window.aftersell.cart.actions.formatMoney(state.totalPrice));
});
```

Because it's a snapshot, don't hold on to the result; read it again each time you need current data. In an event handler you already have the fresh cart as the payload, so `getCart()` is redundant there.

### formatMoney(cents)

Formats a minor-unit amount using your store's money format. Every price in the SDK is in cents, so this is how you turn one into something you can display.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.actions.formatMoney(5779);  // "$57.79"
window.aftersell.cart.actions.formatMoney(0);     // "$0.00"
```

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Show the cart total in your own header element.
window.aftersell.cart.events.on('cart_updated', (state) => {
  document.querySelector('#header-total').textContent =
    window.aftersell.cart.actions.formatMoney(state.totalPrice);
});
```

Override the format with [`configure({ money_format })`](/aftersell/cart/sdk-configure#money_format).

***

## Changing the cart

<Note>
  The item actions identify a line by its Shopify **`key`**, not by variant ID, because a cart can hold the same variant on several lines with different properties. Read it from `getCart().items[n].key`.
</Note>

### addItem(variantId, quantity?)

Adds a variant to the cart. `quantity` defaults to `1`. Resolves once the cart has settled.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Add one, then show the shopper.
window.aftersell.cart.actions.addItem(41720671830082).then(() => {
  window.aftersell.cart.actions.open();
});
```

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Add a specific quantity.
window.aftersell.cart.actions.addItem(41720671830082, 3);
```

Adding a variant already in the cart increases that line's quantity rather than creating a second line, as long as the existing line has no line item properties. A line carrying properties is a distinct line, so you get a new one.

### removeItem(key)

Removes a line entirely.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Remove any free line from the cart.
const gift = window.aftersell.cart.actions
  .getCart()
  .items.find((line) => line.finalLinePrice === 0);
if (gift) window.aftersell.cart.actions.removeItem(gift.key);
```

### updateItemQuantity(key, quantity)

Sets a line's quantity. Passing `0` removes the line.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const line = window.aftersell.cart.actions.getCart().items[0];
if (line) window.aftersell.cart.actions.updateItemQuantity(line.key, 3);
```

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Cap a line at one unit.
window.aftersell.cart.events.on('cart_updated', (state) => {
  state.items.forEach((line) => {
    if (line.variantId === LIMITED_VARIANT_ID && line.quantity > 1) {
      window.aftersell.cart.actions.updateItemQuantity(line.key, 1);
    }
  });
});
```

That second example is safe to run from `cart_updated` because the `> 1` check is false on the second pass. See [the two rules](/aftersell/cart/sdk-events#the-two-rules).

### replaceLineVariant(key, variantId)

Swaps a line's variant while keeping its quantity and properties. Useful for a size or flavor switcher inside the cart.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const line = window.aftersell.cart.actions.getCart().items[0];
window.aftersell.cart.actions.replaceLineVariant(line.key, 41720671862850);
```

<Warning>
  The line's **selling plan resets** on a swap. A subscription line becomes a one-time purchase unless you reapply a plan.
</Warning>

The swap is an add followed by a remove, not an edit in place, so the result is a **new line**: it gets a new `key` and lands at the end of the cart. Re-read `getCart()` afterwards rather than reusing the key you passed in.

***

## Refreshing

### refresh()

Refetches the cart from Shopify. Use it after something outside the SDK changed the cart and the drawer didn't notice.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// After a raw Ajax API call of your own.
fetch('/cart/add.js', { method: 'POST', /* … */ })
  .then(() => window.aftersell.cart.actions.refresh())
  .then(() => { window.aftersell.cart.actions.open(); });
```

Most of the time you don't need this, since Aftersell already listens for Shopify's standard cart events and refetches on its own. Reach for it when a custom integration bypasses those.

### visualRefresh()

Re-runs the render transforms without refetching the cart from Shopify. You rarely need it: registering (or unregistering) a [line transform](/aftersell/cart/sdk-hooks#registerlinetransform), [comparator](/aftersell/cart/sdk-hooks#registerlinecomparator), [enricher](/aftersell/cart/sdk-hooks#registercartenricher), or either [subscription hook](/aftersell/cart/sdk-hooks#registersubscriptionoptionstransform) triggers one for you. Only the two add-to-cart hooks don't, since they change nothing already on screen.

Reach for it when something a transform *depends on* changes but the cart itself hasn't:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// A currency switcher changed the format: repaint prices already on screen.
window.myTheme.onCurrencyChange((currency) => {
  window.aftersell.cart.configure({ money_format: FORMATS[currency] });
  window.aftersell.cart.actions.visualRefresh();
});
```

***

## Notes and edge cases

* **Async actions resolve when the change settles.** Awaiting one lets you sequence work after the cart has actually updated.
* **`getCart()` returns a copy.** Mutating it does nothing to the real cart.
* **There's no action for discount codes.** Applied codes are readable on the cart (`discountCodes`, `totalDiscount`) and per line (`discountAllocations`); shoppers apply them through the [Discount code](/aftersell/cart/discount-code-block) block.
* **There's no action for cart attributes or notes.** Attributes are readable on the cart object; shoppers write notes through the [Notes](/aftersell/cart/notes-block) block.
* **To hide a line rather than remove it**, use [`registerLineTransform`](/aftersell/cart/sdk-hooks#registerlinetransform). Removing changes the shopper's total; hiding doesn't.

## Where to go next

* **[Cart object](/aftersell/cart/sdk-cart-object)**: what `getCart()` hands back.
* **[Events](/aftersell/cart/sdk-events)**: when to run these actions.
* **[Hooks](/aftersell/cart/sdk-hooks)**: change how a line renders instead of changing the cart.
* **[Use cases](/aftersell/cart/sdk-use-cases)**: complete solutions to common requests.


# Cart object
Source: https://docs.aftersell.com/aftersell/cart/sdk-cart-object

The shape of the Aftersell Cart SDK cart and its lines: every field on the cart, cart lines, bundles, and selling plans.

One object shape flows through the whole SDK. It's what [`getCart()`](/aftersell/cart/sdk-actions#getcart) returns, what [`cart_loaded` and `cart_updated`](/aftersell/cart/sdk-events) hand your handler, and what a [Custom code block](/aftersell/cart/custom-code-blocks) receives.

<Note>
  **All money is in the currency's minor unit** (cents for USD), never a formatted string. `5779` is \$57.79. Use [`formatMoney`](/aftersell/cart/sdk-actions#formatmoneycents) to display it.
</Note>

## The cart

| Field                  | Type                     | Description                                                                                                                                    |
| ---------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`                | `string`                 | The Shopify cart token.                                                                                                                        |
| `items`                | `AftersellCartLine[]`    | The line items. See [cart lines](#cart-lines).                                                                                                 |
| `itemCount`            | `number`                 | Total item quantity, as the shopper sees it.                                                                                                   |
| `hasSubscriptionItems` | `boolean`                | `true` when at least one line in `items` carries a selling plan, including add-on lines that `itemCount` leaves out. `false` on an empty cart. |
| `totalPrice`           | `number`                 | Current total, in cents.                                                                                                                       |
| `originalTotalPrice`   | `number`                 | Total before discounts, in cents.                                                                                                              |
| `totalDiscount`        | `number`                 | Discount total, in cents.                                                                                                                      |
| `compareAtTotalPrice`  | `number \| null`         | Sum of each line's compare-at (MSRP) × quantity, in cents. `null` when unavailable, so fall back to `originalTotalPrice`.                      |
| `currency`             | `string`                 | Currency code.                                                                                                                                 |
| `discountCodes`        | `string[]`               | Discount codes accepted on the cart, sorted. `[]` when none.                                                                                   |
| `attributes`           | `Record<string, string>` | Cart attributes. Read-only from the SDK.                                                                                                       |

<Warning>
  **`itemCount` is not always the sum of `items`.** `items` mirrors the real Shopify cart, including add-on lines the drawer hides, such as shipping protection. `itemCount` is the shopper-facing number that matches the cart badge. For "how many things has the shopper chosen", use `itemCount`; to iterate over the lines the cart is rendering, use `items`.

  Two things are missing from `items` entirely: lines hidden with [`setHidden`](/aftersell/cart/sdk-hooks#registerlinetransform), and [bundle children](#bundles), which move onto their anchor. Both still count toward the cart totals, which come straight from Shopify.
</Warning>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('cart_updated', (state) => {
  console.log(state.itemCount, 'items');
  console.log('Total:', window.aftersell.cart.actions.formatMoney(state.totalPrice));
  console.log('Saved:', window.aftersell.cart.actions.formatMoney(state.totalDiscount));
  console.log('Codes:', state.discountCodes.join(', ') || 'none');
});
```

## Cart lines

Each entry in `items`, and the `item` on [`item_added`](/aftersell/cart/sdk-events#item_added) and [`item_removed`](/aftersell/cart/sdk-events#item_removed):

| Field                 | Type                             | Description                                                                                                                                      |
| --------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `key`                 | `string`                         | The line's Shopify key. Pass this to the item [actions](/aftersell/cart/sdk-actions).                                                            |
| `productId`           | `number`                         | Shopify product ID.                                                                                                                              |
| `variantId`           | `number`                         | Shopify variant ID.                                                                                                                              |
| `handle`              | `string`                         | Product handle.                                                                                                                                  |
| `title`               | `string`                         | Display title.                                                                                                                                   |
| `productTitle`        | `string`                         | Product title without the variant.                                                                                                               |
| `variantTitle`        | `string \| null`                 | Variant label, or `null`.                                                                                                                        |
| `variantOptions`      | `Array<{ name, value }>`         | Selected options, e.g. `[{ name: 'Size', value: 'Medium' }]`. Shopify emits `Title: Default Title` for a single-variant product.                 |
| `quantity`            | `number`                         | Quantity of this line.                                                                                                                           |
| `linePrice`           | `number`                         | Line price, in cents.                                                                                                                            |
| `finalLinePrice`      | `number`                         | Line price after discounts, in cents.                                                                                                            |
| `originalLinePrice`   | `number`                         | Line price before discounts, in cents.                                                                                                           |
| `compareAtPrice`      | `number \| null`                 | Variant compare-at (MSRP) **per unit**, in cents. `null` when none.                                                                              |
| `properties`          | `Record<string, string> \| null` | Line item properties.                                                                                                                            |
| `internalProperties`  | `Record<string, string>`         | Render-only overlay from [`registerLineTransform`](/aftersell/cart/sdk-hooks#registerlinetransform). Never persisted to Shopify. `{}` when none. |
| `discountAllocations` | `Array<{ title, amount }>`       | Discounts applied to this line. `amount` is in cents. `[]` when none.                                                                            |
| `isGiftCard`          | `boolean`                        | Whether the line is a gift card.                                                                                                                 |
| `sellingPlan`         | `{ id, name } \| null`           | The active subscription plan, or `null` for a one-time purchase.                                                                                 |
| `bundle`              | `AftersellCartBundle \| null`    | [Bundle](#bundles) view model on the anchor line; `null` on non-bundle lines and children.                                                       |
| `metadata`            | `Record<string, unknown>`        | [Enrichment](/aftersell/cart/sdk-hooks#registercartenricher) data keyed by enricher `id`. `{}` until an enricher populates it.                   |

<Warning>
  `properties` can carry shopper-supplied input, such as a product form's custom-text field. Render it as text, never as raw HTML.
</Warning>

### Identifying a line

Use `key` for anything that acts on a line, and `variantId` or `productId` for anything that identifies a *product*:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// ✅ Acting on a line: use key.
window.aftersell.cart.actions.removeItem(line.key);

// ✅ Recognising a product: use variantId.
const hasGift = state.items.some((line) => line.variantId === GIFT_VARIANT_ID);
```

The same variant can appear on several lines when the properties differ. Two engraved mugs with different engraving text are two lines sharing one `variantId`. That's why the actions take `key`.

### Prices on a line

Three prices, easy to mix up:

| Want                                | Use                           |
| ----------------------------------- | ----------------------------- |
| What the shopper pays for this line | `finalLinePrice`              |
| What it cost before cart discounts  | `originalLinePrice`           |
| The MSRP strike-through, per unit   | `compareAtPrice` × `quantity` |

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Is this line discounted?
const isDiscounted = line.finalLinePrice < line.originalLinePrice;

// Is it free? (A common way to detect a gift line.)
const isFree = line.finalLinePrice === 0;
```

## Bundles

When lines are grouped into a bundle, the **anchor** line carries a `bundle` object. The children are folded into it and no longer appear in `items` on their own. See [Group bundle lines from another app](/aftersell/cart/sdk-use-case-bundles) for how grouping is set up.

| Field          | Type                     | Description                                             |
| -------------- | ------------------------ | ------------------------------------------------------- |
| `id`           | `string`                 | Bundle identifier.                                      |
| `source`       | `'native' \| 'grouped'`  | A Shopify native bundle, or lines grouped by Aftersell. |
| `memberKeys`   | `string[]`               | The `key` of every line in the bundle.                  |
| `children`     | `AftersellBundleChild[]` | The bundle's contents.                                  |
| `displayPrice` | `number`                 | The price shown for the bundle, in cents.               |

Each child carries `key` (`null` for a native component), `title`, `variantTitle`, `quantity`, `perAnchorQty`, `imageUrl`, `finalLinePrice`, `originalLinePrice`, and `compareAtPrice`.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Skip bundle children when totalling your own line list.
const topLevel = state.items.filter((line) => !isBundleChild(line, state));
```

## Subscription plans

A line's active plan is `sellingPlan`, or `null` for a one-time purchase. For a whole-cart answer, read `hasSubscriptionItems` rather than scanning the lines yourself, since it also counts add-on lines that `items` presents but `itemCount` skips:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
if (state.hasSubscriptionItems) {
  // The cart contains at least one subscription line.
}

const subscriptions = state.items.filter((line) => line.sellingPlan);
console.log(subscriptions.length, 'subscription lines');
```

The *available* plans on a line, the ones in the picker, aren't on the cart object. Shape those with [`registerSubscriptionOptionsTransform`](/aftersell/cart/sdk-hooks#registersubscriptionoptionstransform) and [`registerDefaultSubscriptionOptionSelector`](/aftersell/cart/sdk-hooks#registerdefaultsubscriptionoptionselector).

## Where to go next

* **[Actions](/aftersell/cart/sdk-actions)**: read and change the cart.
* **[Events](/aftersell/cart/sdk-events)**: where this object comes from.
* **[Hooks](/aftersell/cart/sdk-hooks)**: add your own data to a line with an enricher.
* **[Use cases](/aftersell/cart/sdk-use-cases)**: complete solutions that read these fields.


# Configure
Source: https://docs.aftersell.com/aftersell/cart/sdk-configure

Every Aftersell Cart SDK configure option: drawer opening, add-to-cart interception, form validation, and money formatting.

`configure(config)` sets how the cart behaves. It's a **set-up call**, so it's safe at the very top of your script, before the cart has loaded.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.configure({
  open_on_add_to_cart: 'always',
  money_format: '${{amount}} USD',
});
```

You can call it more than once and values merge. A later call overrides only the keys it names, leaving the rest alone.

<Warning>
  **Passing `undefined` clears a key rather than skipping it.** `configure({ open_on_add_to_cart: undefined })` resets that option to its default, discarding whatever an earlier call set. To leave an option alone, omit the key entirely.
</Warning>

## Options

| Option                                                          | Values                             | Default        | Purpose                                                 |
| --------------------------------------------------------------- | ---------------------------------- | -------------- | ------------------------------------------------------- |
| [`open_on_add_to_cart`](#open_on_add_to_cart)                   | `'always'`, `'never'`, `'default'` | `'default'`    | Whether the drawer opens when an item is added.         |
| [`open_on_background_add`](#open_on_background_add)             | `boolean`                          | `false`        | Also open when something *else* adds to the cart.       |
| [`validate_form_on_add_to_cart`](#validate_form_on_add_to_cart) | `boolean`                          | `false`        | Block the add if the product form is invalid.           |
| [`skip_add_to_cart_interceptor`](#skip_add_to_cart_interceptor) | `boolean`                          | `false`        | Turn off Aftersell's add-to-cart interception entirely. |
| [`skip_open_cart_interceptor`](#skip_open_cart_interceptor)     | `boolean`                          | `false`        | Let a cart-icon click reach your other scripts.         |
| [`money_format`](#money_format)                                 | string                             | store's format | Override the format used by `formatMoney`.              |

***

## open\_on\_add\_to\_cart

Controls whether the drawer opens when a shopper adds a product.

| Value       | Behavior                                                                   |
| ----------- | -------------------------------------------------------------------------- |
| `'always'`  | Always open the drawer on add.                                             |
| `'never'`   | Never open it; the item is added silently.                                 |
| `'default'` | Follow the **Open cart when an item is added** setting in the cart editor. |

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Always open, regardless of the merchant's cart setting.
window.aftersell.cart.configure({ open_on_add_to_cart: 'always' });
```

A common use is to keep the drawer shut on one specific page while leaving the merchant setting alone everywhere else:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
if (window.location.pathname.startsWith('/collections/')) {
  window.aftersell.cart.configure({ open_on_add_to_cart: 'never' });
}
```

<Note>
  If you just want this on for the whole store, it's already a setting: **Cart settings → Content → Behavior → Open cart when an item is added**. Use `configure` when the answer depends on the page, the shopper, or something only your code knows.
</Note>

## open\_on\_background\_add

Set this to `true` to also open the drawer for **background** adds — ones Aftersell detected but did not handle itself.

An add counts as background when either:

* it arrived through [Shopify's standard cart events](https://shopify.dev/docs/storefronts/themes/best-practices/standard-events) (always treated as background, whatever triggered it), or
* Aftersell saw the cart request on the wire with **no** trusted click or keypress in the preceding \~3 seconds — another app or script writing to the cart, for instance.

An add Aftersell saw on the wire that *did* follow a shopper's click is not a background add: it already opens the drawer per `open_on_add_to_cart`, with no need for this option.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.configure({ open_on_background_add: true });
```

This is an **additional gate, not an override**: a background add opens the drawer only if `open_on_add_to_cart` would have allowed it too. With `open_on_add_to_cart: 'never'`, this option does nothing.

<Tip>
  Reach for this when a third-party add button adds the item correctly but leaves the drawer closed. If the item never reaches the cart at all, that's an interception problem. See [`skip_add_to_cart_interceptor`](#skip_add_to_cart_interceptor) and the [page builder use case](/aftersell/cart/sdk-use-case-page-builder).
</Tip>

## validate\_form\_on\_add\_to\_cart

Runs the browser's native form validation (`reportValidity()`) before adding, and cancels the add if the form is invalid. Use it when your product form has required fields (an engraving message, a gift note, a required checkbox) that shoppers can currently skip.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.configure({ validate_form_on_add_to_cart: true });
```

The browser shows its own validation message on the offending field. Off by default, because a theme with a stray `required` attribute somewhere in the product form would otherwise start silently blocking add-to-cart.

## skip\_add\_to\_cart\_interceptor

Turns off Aftersell's add-to-cart interception completely. For what interception does and every way to opt out of it, see [Add-to-cart interception](/aftersell/cart/add-to-cart-interception).

The theme then performs the add itself, and every script listening on that submit runs again. Aftersell still watches for the cart request on the wire, so the drawer opens as usual. You don't lose it by opting out. On themes Aftersell recognizes, the theme's own cart stays inert, so you won't get two carts. On a theme it doesn't recognize, the theme may open its own cart alongside yours; see [Will the theme's cart open too?](/aftersell/cart/add-to-cart-interception#will-the-themes-cart-open-too).

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.configure({ skip_add_to_cart_interceptor: true });
```

<Warning>
  This one is read **once, at boot**. It only works from a set-up call that runs before the cart loads: your cart's **Initialization** script. Setting it later (inside `ready()`, or from an event handler) has no effect, and fails silently.
</Warning>

This is a blunt instrument that disables interception for every form on the page. To exempt just one form, use the [`registerSkipAddToCartRule`](/aftersell/cart/sdk-hooks#registerskipaddtocartrule) hook instead:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Preferred: exempt only the forms you own.
window.aftersell.cart.hooks.registerSkipAddToCartRule((form) =>
  form.hasAttribute('data-skip-aftersell')
);
```

## skip\_open\_cart\_interceptor

Clicking the cart icon opens the Aftersell drawer. To do that reliably, Aftersell stops the click so nothing else on the page handles it, which also stops **your** scripts from seeing it. If an analytics or pixel event fires everywhere except the cart icon, this is why.

Set this to `true` to stop silencing the click:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.configure({ skip_open_cart_interceptor: true });
```

Your listeners then run, and the drawer still opens exactly as before. The click also still doesn't navigate to `/cart`.

<Warning>
  **This does less than the name suggests.** It doesn't skip the cart-icon interceptor. It only stops it silencing other listeners. Aftersell still handles the click and still opens your cart. For a control that Aftersell should ignore completely, use the `aftersell-cart-wont-open-cart` class instead; see [Add-to-cart interception](/aftersell/cart/add-to-cart-interception#the-cart-icon-is-separate).
</Warning>

Unlike [`skip_add_to_cart_interceptor`](#skip_add_to_cart_interceptor), this one is read **on every click**, so you can set it at any point and it takes effect immediately: from `ready()`, an event handler, or conditionally per page.

<Note>
  Some themes also respond to the cart-icon click themselves. Once Aftersell stops silencing it, a theme that opens its own drawer will do so alongside yours. If you see two carts after turning this on, add the `aftersell-cart-wont-open-cart` class to the theme's icon and open the cart from your own handler with [`actions.open()`](/aftersell/cart/sdk-actions#open-and-close).
</Note>

## money\_format

Overrides the [Shopify money format](https://shopify.dev/docs/api/liquid/filters/money) that [`formatMoney`](/aftersell/cart/sdk-actions#formatmoneycents) uses. Defaults to your store's own format; if that's unavailable, prices fall back to `$X.XX`.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.configure({ money_format: '${{amount}} USD' });

// Later:
window.aftersell.cart.actions.formatMoney(5779); // "$57.79 USD"
```

Because `configure` merges and `formatMoney` reads the live value, you can change the format at runtime, for example when a currency switcher fires:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.myTheme.onCurrencyChange((currency) => {
  window.aftersell.cart.configure({ money_format: FORMATS[currency] });
  window.aftersell.cart.actions.visualRefresh(); // repaint prices already on screen
});
```

<Note>
  This changes how the SDK and the cart *display* prices. It doesn't change the currency the shopper is charged; that's Shopify Markets.
</Note>

## Where to go next

* **[Actions](/aftersell/cart/sdk-actions)**: read and change the cart.
* **[Hooks](/aftersell/cart/sdk-hooks)**: per-form and per-line control, where `configure` is too broad.
* **[Use cases](/aftersell/cart/sdk-use-cases)**: complete solutions to common requests.


# Events
Source: https://docs.aftersell.com/aftersell/cart/sdk-events

Every Aftersell Cart SDK event: when each one fires, what it hands you, what to use it for, and the mistakes that cause infinite loops.

Events let you run code **when something happens** in the cart. They live under `window.aftersell.cart.events`.

Subscribing is a set-up call, so it's safe at the top of your script, with no need to wait for `ready()`.

## Available events

| Event                                         | Payload                                            | Fires when                                      |
| --------------------------------------------- | -------------------------------------------------- | ----------------------------------------------- |
| [`cart_loaded`](#cart_loaded)                 | [`AftersellCart`](/aftersell/cart/sdk-cart-object) | The cart loads, once per page.                  |
| [`cart_updated`](#cart_updated)               | [`AftersellCart`](/aftersell/cart/sdk-cart-object) | The cart contents change, after the first load. |
| [`item_added`](#item_added)                   | `{ item }`                                         | A new line appears in the cart.                 |
| [`item_removed`](#item_removed)               | `{ item }`                                         | A line disappears from the cart.                |
| [`cart_opened`](#cart_opened-and-cart_closed) | None                                               | The drawer opens.                               |
| [`cart_closed`](#cart_opened-and-cart_closed) | None                                               | The drawer closes.                              |
| [`checkout`](#checkout)                       | None                                               | The checkout button is clicked.                 |

## Subscribing

`events.on(event, handler)` registers a handler and **returns a function that unsubscribes it**:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const off = window.aftersell.cart.events.on('cart_updated', (state) => {
  console.log('Cart total is now', state.totalPrice);
});

// later, to stop listening:
off();
```

* `events.once(event, handler)`: fires once, then unsubscribes itself.
* `events.off(event, handler)`: removes a specific handler.

A handler that throws is isolated and logged to the console; the other handlers still run.

***

## The two rules

Almost every event bug traces back to one of these.

### Don't change the cart from `cart_updated` without a guard

Changing the cart inside a `cart_updated` handler fires `cart_updated` again. If that handler changes the cart again, you have an infinite loop. The shopper watches their cart thrash while the page hammers Shopify.

<Warning>
  **Never call an action unconditionally from `cart_updated` or `cart_loaded`.** Guard it with a check on the state you're about to create, so the second pass does nothing.
</Warning>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// ❌ Loops forever: every add triggers an update, which triggers another add.
window.aftersell.cart.events.on('cart_updated', (state) => {
  window.aftersell.cart.actions.addItem(GIFT_VARIANT_ID, 1);
});

// ✅ Guarded: once the gift is present, the condition is false and it stops.
window.aftersell.cart.events.on('cart_updated', (state) => {
  const hasGift = state.items.some((line) => line.variantId === GIFT_VARIANT_ID);
  if (state.totalPrice >= 5000 && !hasGift) {
    window.aftersell.cart.actions.addItem(GIFT_VARIANT_ID, 1);
  }
});
```

The cart does give you one safety net: an update that produces an **identical** cart emits nothing, so a refetch that changes nothing won't restart the cycle. That protects you from accidental no-op loops. It does **not** protect you from a handler that genuinely changes the cart each time.

### Treat the payload as read-only

Every handler for one event receives the *same* object. Mutating it changes what the handlers after yours see, including handlers belonging to other apps on the store.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// ❌ Corrupts the payload for every later handler.
window.aftersell.cart.events.on('cart_updated', (state) => {
  state.items = state.items.filter((line) => line.finalLinePrice > 0);
});

// ✅ Copy first.
window.aftersell.cart.events.on('cart_updated', (state) => {
  const paidItems = state.items.filter((line) => line.finalLinePrice > 0);
});
```

To actually change the cart, use an [action](/aftersell/cart/sdk-actions). To change how lines render, use [`registerLineTransform`](/aftersell/cart/sdk-hooks#registerlinetransform).

***

## cart\_loaded

Fires **once**, when the cart first loads on the page. The payload is the full [cart object](/aftersell/cart/sdk-cart-object).

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('cart_loaded', (state) => {
  console.log('Page loaded with', state.itemCount, 'items');
});
```

**Use it for:** anything that needs to run against the cart's starting state, such as reconciling a free gift, initializing a widget, or reporting cart contents to analytics on page load.

**`cart_loaded` is replayed to late subscribers.** If you subscribe after the cart has already loaded, your handler is called immediately with the current cart. Subscription order never matters, so you don't have to worry about whether your script beat the cart.

<Tip>
  Logic that has to be correct both on page load and on every change afterward should subscribe to **both** `cart_loaded` and `cart_updated` with the same function. That's the standard pattern for "keep X in sync with the cart".
</Tip>

## cart\_updated

Fires every time the cart contents change **after** the first load, whether from the drawer, from your own actions, from the theme, or from another app. The payload is the full [cart object](/aftersell/cart/sdk-cart-object).

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('cart_updated', (state) => {
  document.querySelector('#my-total').textContent =
    window.aftersell.cart.actions.formatMoney(state.totalPrice);
});
```

**Use it for:** keeping something outside the cart in sync, such as a custom total, a progress bar, a header badge, or an analytics event on every change.

An update that produces an identical cart emits nothing. Re-opening the drawer, switching tabs back, or a refetch that returns the same contents will not fire it.

<Warning>
  Re-read [the two rules](#the-two-rules) before calling an action in here.
</Warning>

## item\_added

Fires when a **new line** appears in the cart. The payload is `{ item }`, where `item` is the [cart line](/aftersell/cart/sdk-cart-object#cart-lines).

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('item_added', (payload) => {
  myAnalytics.track('Added to cart', {
    id: payload.item.variantId,
    title: payload.item.title,
    quantity: payload.item.quantity,
  });
});
```

**Use it for:** add-to-cart tracking in a third-party analytics tool. This is the single most common use of the SDK. See [tracking add-to-cart](/aftersell/cart/sdk-use-case-analytics).

Two things to know about how it's derived:

<Warning>
  **A quantity change is not an add.** The cart works out adds and removes by diffing *lines*, not quantities. A shopper bumping a line from 1 to 3 fires `cart_updated`, not `item_added`. If you need to catch quantity increases too, compare against the previous state in a `cart_updated` handler.
</Warning>

It also doesn't fire for items that were already in the cart when the page loaded; those arrive via `cart_loaded`. Adding several distinct products at once fires the event once per line.

## item\_removed

Fires when a line disappears from the cart. The payload is `{ item }`, the line as it was just before it went away, so you can still read its `key`, `variantId`, and `title`.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('item_removed', (payload) => {
  console.log('Removed', payload.item.title);
});
```

**Use it for:** reversing something you did on add, such as clearing a flag, re-showing an offer the shopper declined, or reporting removals to analytics.

Same caveat as `item_added`: lowering a quantity without hitting zero isn't a removal.

## cart\_opened and cart\_closed

Fire when the drawer opens and closes. No payload.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('cart_opened', () => {
  myAnalytics.track('Cart viewed');
});

window.aftersell.cart.events.on('cart_closed', () => {
  document.body.classList.remove('cart-is-open');
});
```

**Use it for:** view tracking, pausing a video or carousel behind the drawer, toggling a class on the page.

Neither fires on the initial page load, only on an actual open or close.

## checkout

Fires when the shopper clicks the checkout button, immediately before the browser navigates. No payload.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('checkout', () => {
  myAnalytics.track('Checkout started');
});
```

**Use it for:** checkout-intent tracking.

<Warning>
  **You can't cancel checkout from this handler.** The event is a notification, not a gate; navigation happens regardless of what your code does. Keep the handler fast and synchronous: an `await` or a slow network call may not finish before the page unloads. Use [`navigator.sendBeacon`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/sendBeacon) for anything you need to reliably send.
</Warning>

***

## Listening from outside the SDK

Every event is also dispatched as a DOM `CustomEvent` on `window`, so you can listen without touching `window.aftersell.cart`. That is useful from a theme file, a third-party app, or a script that loads independently of the cart.

| Bus event      | DOM event                     |
| -------------- | ----------------------------- |
| `cart_loaded`  | `aftersell:cart:cart-loaded`  |
| `cart_updated` | `aftersell:cart:cart-updated` |
| `item_added`   | `aftersell:cart:item-added`   |
| `item_removed` | `aftersell:cart:item-removed` |
| `cart_opened`  | `aftersell:cart:cart-opened`  |
| `cart_closed`  | `aftersell:cart:cart-closed`  |
| `checkout`     | `aftersell:cart:checkout`     |

Mind the naming: the bus uses `snake_case`, the DOM events use `kebab-case` behind an `aftersell:cart:` prefix.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.addEventListener('aftersell:cart:cart-updated', (event) => {
  console.log('Cart total is now', event.detail.totalPrice);
});
```

The payload arrives on `event.detail` and matches the [cart object](/aftersell/cart/sdk-cart-object). Events are dispatched on `window`, so a listener anywhere on the page receives them. The cart renders in a shadow root, but the shadow boundary is never in the event's path. Each dispatch clones the payload, so a listener mutating `event.detail` can't affect anyone else, and a listener that throws can't disrupt the SDK.

<Warning>
  **`cart-loaded` does not replay on the DOM.** The bus replays `cart_loaded` to late subscribers, but that path bypasses the DOM dispatch, so `window.addEventListener('aftersell:cart:cart-loaded')` registered after the cart has already loaded will never fire. If your script's load order isn't guaranteed, use `window.aftersell.cart.events.on('cart_loaded', …)`, which does replay, or also listen for `aftersell:cart:cart-updated`.
</Warning>

### Shopify standard cart events

Separately, the cart publishes Shopify's [standard cart events](https://shopify.dev/docs/storefronts/themes/best-practices/standard-events) on `document` whenever it changes the cart, so theme code and other apps can react to Aftersell's mutations the same way they react to the theme's:

| Event                          | Payload on the event instance                                                    |
| ------------------------------ | -------------------------------------------------------------------------------- |
| `shopify:cart:lines-update`    | `action: 'add' \| 'update' \| 'remove'`, `context: 'cart' \| 'product'`, `lines` |
| `shopify:cart:note-update`     | `context: 'cart'`, `note`                                                        |
| `shopify:cart:discount-update` | `discountCodes: [{ code }]`                                                      |

<Warning>
  **The payload is not on `event.detail`.** `detail` carries only `{ source: 'aftersell' }` — the tag the cart uses to ignore its own events instead of looping. Everything in the table above is assigned directly onto the event object, so read `event.action`, not `event.detail.action`.
</Warning>

Each event also carries a `promise` that Aftersell settles when the underlying write lands, matching Shopify's standard — await it, don't resolve it. These are dispatched on `document` and bubble, so a `window` listener receives them too.

## Where to go next

* **[Cart object](/aftersell/cart/sdk-cart-object)**: the full shape of the payloads above.
* **[Actions](/aftersell/cart/sdk-actions)**: how to change the cart from a handler.
* **[Hooks](/aftersell/cart/sdk-hooks)**: for changing how the cart renders, rather than reacting to it.
* **[Use cases](/aftersell/cart/sdk-use-cases)**: analytics tracking, free gifts, and other complete examples.


# Hooks
Source: https://docs.aftersell.com/aftersell/cart/sdk-hooks

Change how the Aftersell Cart behaves: transform lines, enrich them with Storefront data, shape subscription options, and control add-to-cart.

Where [events](/aftersell/cart/sdk-events) let you *react* to the cart and [actions](/aftersell/cart/sdk-actions) let you *change* it, **hooks** change how the cart itself behaves: how lines render, what data they carry, and what happens on add-to-cart.

Hooks live under `window.aftersell.cart.hooks`.

<Note>
  A hook changes what the shopper **sees**; an action changes what's **in their cart**. Hiding a free gift line with a transform leaves it in the cart and in the total. Removing it with [`removeItem`](/aftersell/cart/sdk-actions#removeitemkey) takes it out for real.
</Note>

<Note>
  Hooks are set-up calls, so they're safe to register at the very top of your script, with no need to wait for `ready()`. Register them in your cart's **Initialization** script (see [Custom scripts](/aftersell/cart/custom-scripts)).
</Note>

## How registration works

Every hook is a `register*` method. You call it with your function; it returns an **unregister function** you can call to remove yours.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const off = window.aftersell.cart.hooks.registerSkipAddToCartRule((form) =>
  form.hasAttribute('data-skip-aftersell')
);

// later: off();
```

Registration is **additive**, so your function runs alongside every other one. That matters because your script is rarely the only one on the page: a subscription app, a bundle app, and the theme itself may all register against the same hook. None of them can replace yours, and nothing you register can be silently dropped by whatever loads after you.

| Hook                                                                                      | What it does                                                                                                  | With several registrations                  |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| [`registerLineTransform`](#registerlinetransform)                                         | Hide or relabel individual lines.                                                                             | All run, in registration order.             |
| [`registerLineComparator`](#registerlinecomparator)                                       | Reorder the rendered lines.                                                                                   | Compose as tie-breakers.                    |
| [`registerCartEnricher`](#registercartenricher)                                           | Attach extra Storefront data to each line.                                                                    | All run; each `id` is its own namespace.    |
| [`registerSubscriptionOptionsTransform`](#registersubscriptionoptionstransform)           | Hide or rename a line's selling plans.                                                                        | All run; patches merge per plan, per field. |
| [`registerDefaultSubscriptionOptionSelector`](#registerdefaultsubscriptionoptionselector) | Choose which plan is preselected.                                                                             | First non-`null` answer wins.               |
| [`registerSkipAddToCartRule`](#registerskipaddtocartrule)                                 | Let specific forms bypass the cart. See [Add-to-cart interception](/aftersell/cart/add-to-cart-interception). | Any rule returning `true` skips.            |

A hook that throws, or that isn't a function, is skipped; the rest still run, and the cart carries on. One broken integration can't take down add-to-cart, the subscription picker, or the sort.

The flip side is that a broken hook of yours fails **silently**: nothing reaches the browser console. See [Debugging](/aftersell/cart/sdk-overview#debugging) for where those failures do surface.

***

## registerLineTransform

`registerLineTransform(fn)` runs for every cart line before it renders. Use it to hide a line or change how it reads, without touching what's actually in the shopper's cart.

The function receives a read-only line plus setters. It returns an unregister function.

| Setter                            | Effect                                                                                                                        |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `setHidden(bool)`                 | Hide the line from the drawer. It stays in the cart and in the total.                                                         |
| `setTitle(string)`                | Change the displayed title.                                                                                                   |
| `setVariantTitle(string \| null)` | Change the displayed variant label.                                                                                           |
| `setInternalProperties(obj)`      | Merge render-only properties. Never persisted to Shopify. Used to [group bundle lines](/aftersell/cart/sdk-use-case-bundles). |

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Hide free gift lines from the drawer. The cart total is unaffected.
const off = window.aftersell.cart.hooks.registerLineTransform((line) => {
  if (line.finalLinePrice === 0) {
    line.setHidden(true);
  }
  if (line.sellingPlan) {
    line.setVariantTitle(`Delivered ${line.sellingPlan.name.toLowerCase()}`);
  }
});

// later: off();
```

<Warning>
  A transform only changes what renders. It can't change price, quantity, or line identity. Use the [actions](/aftersell/cart/sdk-actions) for that.
</Warning>

**Use it for:** hiding gift-with-purchase or app-injected lines, relabelling subscription lines, tagging discounted items, hiding bundle components the shopper shouldn't manage individually.

`setInternalProperties` is the setter behind bundle grouping: stamping the canonical bundle properties onto each line is how you make a third-party app's separate cart lines render as one item. See [Group bundle lines from another app](/aftersell/cart/sdk-use-case-bundles).

## registerLineComparator

A comparator in the same shape `Array.prototype.sort` expects. It runs after hide and rename, so it sees the transformed lines.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Subscriptions first, then everything else.
window.aftersell.cart.hooks.registerLineComparator((lineA, lineB) => {
  return (lineB.sellingPlan ? 1 : 0) - (lineA.sellingPlan ? 1 : 0);
});
```

Comparators **compose as tie-breakers**: the first one to return a non-zero value decides that pair, and the rest are consulted only on ties. Return `0` for pairs you have no opinion about. That's what hands the decision to the next comparator instead of forcing an order on it.

**Use it for:** floating subscriptions or high-value items to the top, sinking free gifts and add-ons to the bottom, keeping a sponsored product first.

## registerCartEnricher

`registerCartEnricher(registration)` fetches extra product or variant data from the Shopify Storefront API and attaches it to each matching cart line at `line.metadata[id]`. Use it to surface metafields, tags, or anything else the Storefront API exposes, with no code change from Aftersell required.

| Field      | Type                              | Description                                                                                                                     |
| ---------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `id`       | `string`                          | Namespace for the result; it lands at `line.metadata[id]`. Must be unique; a second registration with the same `id` is ignored. |
| `onType`   | `'Product'` or `'ProductVariant'` | Which node the fragment targets. Also the join key (product ID vs. variant ID).                                                 |
| `fragment` | `string`                          | A GraphQL field selection (no outer braces) spliced into the Storefront query. Braces must balance.                             |

Returns an **unregister function**.

Whenever the cart loads or changes, Aftersell fetches your fragment for every product or variant on the cart and attaches the result. The fetch is non-blocking: the cart renders immediately and re-emits `cart_updated` once the data lands. A slow or failing fragment never delays or breaks the cart.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerCartEnricher({
  id: 'pricing',
  onType: 'ProductVariant',
  fragment: `
    anchorPrice: metafield(namespace: "custom", key: "anchor_price") { value }
    subscriberPrice: metafield(namespace: "custom", key: "subscriber_price") { value }
  `,
});

// Read it once the data arrives.
window.aftersell.cart.events.on('cart_updated', (state) => {
  state.items.forEach((line) => {
    const anchor = line.metadata.pricing?.anchorPrice;
    if (anchor) console.log(line.title, 'anchor price', anchor.value);
  });
});
```

Because enrichment is asynchronous, always guard the read, since `line.metadata.pricing` is `undefined` until the first fetch resolves, and `metadata` itself defaults to `{}`.

**Use it for:** pulling a metafield onto every line (a delivery estimate, an ingredient list, a "ships separately" flag, a loyalty multiplier) and rendering it through a [Custom code block](/aftersell/cart/custom-code-blocks). See [showing metafield data on cart lines](/aftersell/cart/sdk-use-case-metafields).

<Note>
  Multiple enrichers coexist happily, since each `id` is its own namespace, so their data never collides.
</Note>

<Warning>
  Enriched values are returned as-is from the Storefront API and are **not** sanitized. Render them as text, not as raw HTML.
</Warning>

## registerSubscriptionOptionsTransform

Hide or rename the selling plans offered on a line. Your function receives read-only options plus setters, and returns nothing.

| Setter            | Effect                          |
| ----------------- | ------------------------------- |
| `setHidden(bool)` | Hide the plan from the picker.  |
| `setName(string)` | Change the displayed plan name. |

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerSubscriptionOptionsTransform((options, context) => {
  // context: { productId, variantId }
  options.forEach((option) => {
    if (option.discountPercent === 0) option.setHidden(true);
    option.setName(option.name.replace('Every ', ''));
  });
});
```

**Setters, not a returned list, so that several scripts can coexist.** If this hook returned an array, a transform that only cared about one plan would naturally write `options.filter(...)` and silently delete every other app's plans on its way out. With setters you can only describe your own edits: patches merge per plan and per field, and the last writer wins a genuine conflict on the same field of the same plan. A transform that throws contributes nothing, and the others still apply.

Every transform sees the *original* options, not a half-patched view, so registration order doesn't change what you're reading.

<Note>
  Plan order stays as Shopify returned it, so a transform can't reorder. To control which plan is offered first (and which one the one-time upgrade button subscribes to), use [`registerDefaultSubscriptionOptionSelector`](#registerdefaultsubscriptionoptionselector), which promotes its pick to the front.
</Note>

You also can't *add* a plan or change a price: `discountPercent` has no setter, because a plan Shopify won't honor at checkout would just be a broken promise in the picker.

## registerDefaultSubscriptionOptionSelector

Choose which plan is preselected on a line. Return a plan `id`, or `null` to pass on it.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerDefaultSubscriptionOptionSelector((options) => {
  const best = options
    .slice()
    .sort((optionA, optionB) => optionB.discountPercent - optionA.discountPercent)[0];
  return best ? best.id : null;
});
```

The **first selector to return the id of an available plan wins**, so return `null` for the lines you don't care about rather than guessing. That hands the decision to the next selector instead of overriding it. An id that doesn't match any plan on the line is treated the same as `null` and defers too, so a stale id can't blank out the picker.

Your function receives `(options, context)`, the same `context` the options transform gets.

## registerSkipAddToCartRule

Return `true` to let a specific product form add to the cart normally, bypassing Aftersell entirely. This is useful for a form that needs its own redirect or handling.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerSkipAddToCartRule((form) =>
  form.hasAttribute('data-skip-aftersell')
);
```

**Any `true` skips**, so keep your rule narrow, matching the specific forms you own, and return `false` for everything else. Rules are evaluated in registration order and stop at the first `true`, so don't put side effects in one: whether yours runs at all depends on what registered before it.

<Tip>
  If you control the form's markup, you don't need a hook at all: add the class **`aftersell-cart-skip-atc`** to the `<form>` and Aftersell leaves it alone. Use this hook when you can't edit the markup, or when the decision depends on something only your code knows.
</Tip>

**Use it for:** a pre-order or quote form that needs its own redirect, a subscription app's custom flow, a "buy it now" button that should go straight to checkout. To turn interception off for the whole page instead, use [`skip_add_to_cart_interceptor`](/aftersell/cart/sdk-configure#skip_add_to_cart_interceptor), but prefer this hook, which is scoped to the forms you name.

## Where to go next

* **[Cart object](/aftersell/cart/sdk-cart-object)**: the shape of the line a transform receives.
* **[Events](/aftersell/cart/sdk-events)**: everything you can subscribe to.
* **[Actions](/aftersell/cart/sdk-actions)**: reading and changing the cart.
* **[Use cases](/aftersell/cart/sdk-use-cases)**: complete solutions to common requests.


# Overview
Source: https://docs.aftersell.com/aftersell/cart/sdk-overview

How the Aftersell Cart SDK works: the global entry point, the four parts of the API, when it loads, and how to run code against it safely.

The **Cart SDK** is a JavaScript API for the Aftersell Cart on your storefront. It lets you change how the cart behaves, react to what shoppers do, and read or change the cart's contents from code.

You run SDK code through [Custom scripts](/aftersell/cart/custom-scripts), or through a [Custom code block](/aftersell/cart/custom-code-blocks)'s React mode for a block that renders its own UI.

<Note>
  Plenty of what merchants ask the SDK for is already a setting. Before writing a script, check whether a [cart block](/aftersell/cart/blocks-overview), [conditions by market/country/currency](/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency), or a [cart setting](/aftersell/cart/cart-settings) already does it. Those keep working through cart redesigns, and your script may not.
</Note>

## The global entry point

Everything hangs off one global:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart
```

<Note>
  **Every snippet in these docs writes `window.aftersell.cart` out in full**, so any one of them works on its own when you paste it. Aliasing it once (`const cart = window.aftersell.cart;`) and using `cart` from then on is perfectly valid too, and safe even before the cart loads. Just remember to include that line if you shorten a snippet, since a bare `cart` on its own throws `cart is not defined`.
</Note>

Four parts do the work:

<Columns>
  <Card title="Configure" icon="sliders" href="/aftersell/cart/sdk-configure">
    Set how the cart behaves: when the drawer opens, how money is formatted, whether Aftersell intercepts add-to-cart.
  </Card>

  <Card title="Events" icon="tower-broadcast" href="/aftersell/cart/sdk-events">
    React to what happens: the cart loaded, an item was added, the drawer opened, checkout was clicked.
  </Card>

  <Card title="Actions" icon="wand-magic-sparkles" href="/aftersell/cart/sdk-actions">
    Read and change the cart: open it, add an item, update a quantity, read the current state.
  </Card>

  <Card title="Hooks" icon="plug" href="/aftersell/cart/sdk-hooks">
    Change how the cart itself works: hide or relabel lines, reorder them, attach extra data, control add-to-cart.
  </Card>
</Columns>

<Note>
  If a script of yours stopped firing on add-to-cart, start with [Add-to-cart interception](/aftersell/cart/add-to-cart-interception). It explains why Aftersell takes over the add, and every way to opt a form out.
</Note>

Plus three smaller members:

| Member       | What it's for                                                    |
| ------------ | ---------------------------------------------------------------- |
| `ready()`    | A Promise that resolves once the cart has first loaded.          |
| `context`    | Server-rendered buyer context, readable synchronously.           |
| `shadowRoot` | The cart's shadow root, for querying elements inside the drawer. |

## Events, actions, or hooks?

The three are easy to mix up, and picking the wrong one is the most common reason a script doesn't do what its author expected:

| You want to…                           | Use        | Example                                        |
| -------------------------------------- | ---------- | ---------------------------------------------- |
| Run code *when something happens*      | **Event**  | Send an analytics event when an item is added. |
| *Change what's in* the cart            | **Action** | Add a free gift once the total passes \$50.    |
| Change *how the cart works or renders* | **Hook**   | Hide free gift lines from the drawer.          |

The distinction that matters most: an **action changes the shopper's actual cart** (and their total), while a **hook only changes what renders**. Hiding a line with a hook leaves it in the cart and in the total; removing it with an action takes it out for real.

## How and when it loads

The cart loads in two stages, and the SDK is built so you don't have to think about ordering:

1. A small **stub** creates `window.aftersell.cart` immediately, so it's always there.
2. The full SDK loads shortly after and takes over, upgrading the stub in place, so a reference you captured earlier keeps working.

That gives you two categories of call:

<Columns>
  <Card title="Set-up calls: safe immediately" icon="circle-check">
    `configure(...)`, `events.on(...)`, and every `hooks.register*` call. Buffered before boot and replayed in order once the SDK loads. Put them at the top of your script.
  </Card>

  <Card title="Actions: wait for ready()" icon="clock">
    Everything under `actions.*`. Run them inside `ready()` or an event handler. Called too early they warn in the console and do nothing, safely: the async ones still resolve, so a `.then()` chain won't break.
  </Card>
</Columns>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Set-up: fine at the top level, before the cart has loaded.
window.aftersell.cart.configure({ open_on_add_to_cart: 'always' });

window.aftersell.cart.events.on('item_added', (payload) => {
  console.log('Added', payload.item.title);
});

// Actions: wait until the cart is ready.
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log(state.itemCount, 'items');
});
```

### ready()

`ready()` returns a Promise that resolves once the first cart load **settles**. It resolves on failure as well as success, so a shopper on a flaky connection never leaves your script hanging. Check `getCart()` for `null` rather than assuming a cart arrived.

Calling `ready()` after the cart has already loaded resolves immediately, so it's safe to use as a general "the cart exists now" gate anywhere in your code.

<Tip>
  You don't need `ready()` inside an event handler. By the time `cart_loaded`, `cart_updated`, or `item_added` fires, the cart is loaded and actions are safe to call.
</Tip>

## context

`window.aftersell.cart.context` holds buyer data rendered by the server, readable synchronously, with no `ready()` needed. Use it for market or country branching that has to happen before the cart loads.

| Field                     | Description                                                                  | Available before boot              |
| ------------------------- | ---------------------------------------------------------------------------- | ---------------------------------- |
| `shopify_market`          | The buyer's Shopify market.                                                  | Yes                                |
| `customer_country`        | Two-letter country code.                                                     | Yes                                |
| `customer_currency`       | Active currency code.                                                        | Yes                                |
| `money_format`            | The store's Shopify money format.                                            | Yes                                |
| `backend_url`             | Direct backend host, used as a fallback when the app proxy isn't configured. | Yes                                |
| `storefront_access_token` | Token for Storefront API calls.                                              | **No** — added when the cart boots |

<Warning>
  `storefront_access_token` is the one `context` field the server does not render into `cart.context`. It is added to `context` when the cart boots, so reading it at the top of your script gets `undefined`. Await `window.aftersell.cart.ready()` first.
</Warning>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
if (window.aftersell.cart.context.customer_country === 'CA') {
  // Canada-only behavior, decided before the cart loads.
}
```

<Note>
  To show different block settings by market, country, or currency, use [conditions in the cart editor](/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency) instead. No script required. The full Conditions UI ships on [Rewards](/aftersell/cart/rewards-block#per-market-rewards) today.
</Note>

## shadowRoot

The cart renders inside a shadow root, so `document.querySelector` **cannot see anything inside the drawer**. To reach an element in the cart, query the shadow root:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const root = window.aftersell.cart.shadowRoot;
const button = root?.querySelector('.cart-external-checkout-button');
```

Target the same **public `cart-external-*` classes** that [Custom CSS](/aftersell/cart/custom-css) uses. Those are the supported handles. The `cart-internal-*` twins are the cart's own plumbing, so query the external ones instead.

<Warning>
  Reach for the shadow root only when no block, setting, or hook does the job. A hook survives a cart redesign; a DOM query is your code's problem to maintain.
</Warning>

The shadow root is only there once the cart has booted, so read it inside `ready()` or an event handler rather than at the top of your script.

## Debugging

A broken script must never take down add-to-cart or the drawer, so the SDK contains failures rather than letting them bubble. Where a failure surfaces depends on what broke:

| What failed                                                         | Where it shows up                                   |
| ------------------------------------------------------------------- | --------------------------------------------------- |
| Your script threw at the top level                                  | `console.error`, naming the line and what never ran |
| An [event](/aftersell/cart/sdk-events) handler threw                | `console.error`; the other handlers still run       |
| A [hook](/aftersell/cart/sdk-hooks) threw                           | Silent. Goes to the debug channel below             |
| An [action](/aftersell/cart/sdk-actions) ran before the cart loaded | `console.warn`; the call does nothing               |

### When your script throws

A custom script **stops at the first error**, so every `configure`, `events.on`, and `hooks.register*` below that line never runs. The cart says so explicitly:

```
[aftersell-cart] Initialization script error on line 12 — 4 more line(s) did not run;
any configure/events/hooks below are unregistered.
```

That's the message to look for when a handler you definitely registered never fires: it was probably never reached. The line number is the top-level statement where execution stopped, not the inner function that threw, and it's omitted rather than guessed at if the browser's stack isn't usable.

Your scripts also run under their own filenames, so they appear as `aftersell-cart-init.js` and `aftersell-cart-cart-update.js` in DevTools. You can open them from the Sources panel and set breakpoints like any other file.

### The debug channel

Hook failures are deliberately kept off the console so shoppers never see them. They go here instead:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// After reproducing the problem, inspect what was swallowed:
window.aftersellCartDebugEvents.filter((entry) => entry.level === 'ERROR');

// Or watch them live:
window.addEventListener('aftersell-cart-debug', (event) => console.log(event.detail));
```

## Where to go next

<Columns>
  <Card title="Configure" icon="sliders" href="/aftersell/cart/sdk-configure">
    Every option, with an example each.
  </Card>

  <Card title="Events" icon="tower-broadcast" href="/aftersell/cart/sdk-events">
    Every event, when it fires, and what not to do in a handler.
  </Card>

  <Card title="Actions" icon="wand-magic-sparkles" href="/aftersell/cart/sdk-actions">
    Every action, with a snippet each.
  </Card>

  <Card title="Hooks" icon="plug" href="/aftersell/cart/sdk-hooks">
    Every hook, and how registrations compose.
  </Card>

  <Card title="Cart object" icon="table-list" href="/aftersell/cart/sdk-cart-object">
    The shape of the cart and its lines.
  </Card>

  <Card title="Use cases" icon="book-open" href="/aftersell/cart/sdk-use-cases">
    Complete, runnable solutions to common requests.
  </Card>
</Columns>


# Track add-to-cart in a third-party tool
Source: https://docs.aftersell.com/aftersell/cart/sdk-use-case-analytics

Send Aftersell Cart events to Klaviyo, Triple Whale, GA4, or any analytics pixel using the Cart SDK event bus.

Aftersell handles add-to-cart itself, which means analytics tools that watch Shopify's default cart requests may not see it. Subscribing to the SDK's events restores tracking, and gives you a cleaner payload than scraping the Ajax API.

This is the most common thing merchants use the SDK for.

## The pattern

Every integration is the same three lines: subscribe to an event, read the payload, forward it to your tool.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('item_added', (payload) => {
  myAnalytics.track('Added to cart', {
    variantId: payload.item.variantId,
    title: payload.item.title,
    quantity: payload.item.quantity,
    value: payload.item.finalLinePrice / 100, // SDK prices are in cents
  });
});
```

Paste it into **Cart settings → Custom script → Initialization**. Subscribing is a set-up call, so it's safe at the very top, so you don't need to wait for the cart to load.

## Klaviyo

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('item_added', (payload) => {
  const state = window.aftersell.cart.actions.getCart();
  if (!state) return;

  window._learnq ??= [];
  window._learnq.push(['track', 'Added to Cart', {
    $value: state.totalPrice / 100,
    AddedItemProductName: payload.item.productTitle,
    AddedItemProductID: payload.item.productId,
    AddedItemVariantID: payload.item.variantId,
    AddedItemQuantity: payload.item.quantity,
    AddedItemPrice: payload.item.finalLinePrice / 100,
    ItemNames: state.items.map((line) => line.productTitle),
    CheckoutURL: `${window.location.origin}/cart`,
  }]);
});
```

Make sure [Klaviyo onsite tracking](https://help.klaviyo.com/hc/en-us/articles/4425956184731) is installed first. This script only fires the event; it doesn't load Klaviyo.

## Triple Whale

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('item_added', (payload) => {
  window.TriplePixel('AddToCart', {
    item: payload.item.variantId,
    q: payload.item.quantity,
  });
});
```

## Google Analytics 4

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('item_added', (payload) => {
  const line = payload.item;
  window.gtag('event', 'add_to_cart', {
    currency: window.aftersell.cart.actions.getCart().currency,
    value: line.finalLinePrice / 100,
    items: [{
      item_id: String(line.variantId),
      item_name: line.productTitle,
      item_variant: line.variantTitle,
      price: line.finalLinePrice / line.quantity / 100,
      quantity: line.quantity,
    }],
  });
});
```

## Other events worth tracking

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Cart viewed.
window.aftersell.cart.events.on('cart_opened', () => {
  myAnalytics.track('Cart viewed');
});

// Item removed.
window.aftersell.cart.events.on('item_removed', (payload) => {
  myAnalytics.track('Removed from cart', { variantId: payload.item.variantId });
});

// Checkout intent: fires just before the browser navigates.
window.aftersell.cart.events.on('checkout', () => {
  const state = window.aftersell.cart.actions.getCart();
  navigator.sendBeacon('/my-endpoint', JSON.stringify({
    event: 'checkout_started',
    value: state ? state.totalPrice / 100 : 0,
  }));
});
```

<Warning>
  Use [`navigator.sendBeacon`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/sendBeacon) in a `checkout` handler. The page is about to unload, and a normal `fetch` may be cancelled mid-flight. You also **can't cancel checkout** from this handler; it's a notification, not a gate.
</Warning>

## Things to get right

* **Prices are in cents.** Divide by 100 for tools that expect a decimal amount. [`formatMoney`](/aftersell/cart/sdk-actions#formatmoneycents) is for display only, so don't send a formatted string to an analytics tool.
* **A quantity bump isn't `item_added`.** Going from 1 to 3 on an existing line fires `cart_updated`, not `item_added`. If your tool needs to see that, diff against the previous state in a `cart_updated` handler.
* **Don't track from `cart_updated` if you mean "added".** It fires on every change, including removals and quantity edits, so you'll over-report.
* **Check for double-counting.** If your tool already captures add-to-cart some other way, this script will report it twice. Verify in the tool's live view before going live.

## Testing it

Add a `console.log` alongside your tracking call, then open the browser console and add a product:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('item_added', (payload) => {
  console.log('[tracking] item_added', payload.item.title);
  // …your tracking call
});
```

If the log doesn't appear, the script isn't running, so check it saved to the **Initialization** slot. If the log appears but the tool shows nothing, the problem is in the tool's payload format, not the SDK.

## Where to go next

* **[Events](/aftersell/cart/sdk-events)**: every event and when it fires.
* **[Cart object](/aftersell/cart/sdk-cart-object)**: every field you can send.
* **[Cart analytics](/aftersell/cart/analytics)**: the reporting Aftersell provides out of the box.


# Common use cases
Source: https://docs.aftersell.com/aftersell/cart/sdk-use-cases

Complete, runnable Aftersell Cart SDK solutions to the things merchants ask for most: analytics tracking, free gifts, hiding lines, metafields, bundles, and page builders.

Complete solutions to the requests that come up most often. Each one is a runnable snippet with a walkthrough and notes on adapting it.

## Before you write a script

A lot of what merchants used to script is now a built-in setting. Check this first, because a setting keeps working through cart redesigns and your script might not:

| If you want to…                                         | Use this instead of code                                                                                                                                                |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open the drawer whenever an item is added               | **Cart settings → Content → Behavior → Open cart when an item is added**                                                                                                |
| Keep your theme's cart icon count in sync               | Built in. Set **cart count selector** in cart settings if your theme needs a nudge.                                                                                     |
| Show different settings by country, market, or currency | [Conditions](/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency) (full UI on [Rewards](/aftersell/cart/rewards-block#per-market-rewards) today) |
| Offer a free gift at a spend threshold                  | The [Rewards](/aftersell/cart/rewards-block) block                                                                                                                      |
| Add an upsell, add-on, or shipping protection           | The matching [cart block](/aftersell/cart/blocks-overview)                                                                                                              |
| Restyle anything                                        | [Design settings](/aftersell/cart/design-settings), then [Custom CSS](/aftersell/cart/custom-css)                                                                       |

Reach for the SDK when the logic is genuinely yours: a rule no setting expresses, an integration with another app, or data only your store has.

## How to use these

Paste a snippet into your cart's **Initialization** script. In the cart editor, go to **Cart settings → Custom script → Initialization**. Write plain JavaScript; no `<script>` tags. See [Custom scripts](/aftersell/cart/custom-scripts) for the details.

## The use cases

<Columns>
  <Card title="Track add-to-cart in a third-party tool" icon="chart-line" href="/aftersell/cart/sdk-use-case-analytics">
    Send cart events to Klaviyo, Triple Whale, GA4, or any analytics pixel.
  </Card>

  <Card title="Auto-add a free gift at a threshold" icon="gift" href="/aftersell/cart/sdk-use-case-free-gift">
    Add a gift when the total crosses a threshold, remove it when it drops back.
  </Card>

  <Card title="Hide and relabel cart lines" icon="eye-slash" href="/aftersell/cart/sdk-use-case-hide-lines">
    Hide app-injected or free lines, rename them, and control their order.
  </Card>

  <Card title="Show metafield data on cart lines" icon="tags" href="/aftersell/cart/sdk-use-case-metafields">
    Pull a delivery estimate, badge, or any metafield onto every line.
  </Card>

  <Card title="Open the drawer from a page builder" icon="wand-magic-sparkles" href="/aftersell/cart/sdk-use-case-page-builder">
    Make Replo, PageFly, GemPages, and custom buttons open the cart.
  </Card>

  <Card title="Require terms before checkout" icon="square-check" href="/aftersell/cart/sdk-use-case-terms-checkbox">
    Block checkout until the shopper accepts your terms.
  </Card>

  <Card title="Group bundle lines from another app" icon="boxes-stacked" href="/aftersell/cart/sdk-use-case-bundles">
    Make a bundle app's separate cart lines render as one item.
  </Card>
</Columns>


# Shipping protection block
Source: https://docs.aftersell.com/aftersell/cart/shipping-protection-block

The Aftersell Cart Shipping protection block: an opt-in protection add-on that records the choice on the order.

> The **Shipping protection** block offers an opt-in shipping-protection add-on that shoppers can toggle on in the cart, letting them add protection against damage, loss, or theft during shipping and recording that choice on the order for your fulfillment or claims tooling.

## Behavior

* Adding protection does two things: it adds a **real Shopify product line** for the protection product, and it sets a `_shipping_protected` cart attribute to `true`.
* **That attribute survives checkout and lands on the order** as an order note attribute (`_shipping_protected`), so your fulfillment or claims tools can tell which orders are protected.
* Shoppers can both add and remove protection with the control, whichever display type you choose.
* **If no usable protection variant exists, the block renders nothing** rather than showing a control that would error on click.

## Settings

| Setting          | What it controls                                                                                                                           | Default                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| **Title**        | Rich-text heading. Supports `{{product_title}}` and `{{price}}`.                                                                           | `<strong>{{product_title}}</strong>`                              |
| **Price label**  | The price line, displayed below the title. Supports `{{product_title}}` and `{{price}}`. Clear this field to hide the price line entirely. | `{{price}}`                                                       |
| **Description**  | Supporting copy.                                                                                                                           | `Protect your order from damage, loss, or theft during shipping.` |
| **Price**        | The protection price (numeric, sets the charged amount).                                                                                   | `2.5`                                                             |
| **Product**      | The protection product (app-provisioned).                                                                                                  | —                                                                 |
| **Display type** | How the control appears: **Toggle** or **Checkbox**.                                                                                       | Toggle                                                            |

## Placement and limits

* **Region:** body or bottom.
* **Maximum:** 1 per cart state.
* **State:** filled cart only.
* Not added by default. Not locked — you can remove or hide it.

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

| Prop              | Type                                 | What it's for                                                                                   |
| ----------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `isEnabled`       | `boolean`                            | Whether shipping protection is currently in the cart.                                           |
| `isPending`       | `boolean`                            | `true` while the add or remove is in flight. Disable your control on this.                      |
| `title`           | `string`                             | Plain-text title. The fallback when there's no rich-text title.                                 |
| `titleHtml`       | `string`                             | Sanitized rich-text title HTML. Empty when none.                                                |
| `descriptionHtml` | `string`                             | Sanitized rich-text description HTML. Empty when none.                                          |
| `priceHtml`       | `string \| null`                     | Sanitized rich-text price HTML from the dedicated price field. `null` when that field is empty. |
| `priceLabel`      | `string`                             | Formatted price label. Empty when the price isn't shown.                                        |
| `imageUrl`        | `string`                             | Protection image. Empty when none.                                                              |
| `ctaText`         | `string`                             | Button label, for the `button` format.                                                          |
| `format`          | `'button' \| 'checkbox' \| 'toggle'` | How the buyer opts in. Branch your markup on this.                                              |
| `handleAdd`       | `() => void`                         | Adds protection to the cart. For the `button` format.                                           |
| `handleToggle`    | `() => void`                         | Toggles protection in and out of the cart. For `checkbox` and `toggle`.                         |
| `isLoading`       | `boolean`                            | `true` while the cart is still doing its first fetch.                                           |

<Warning>
  `format` decides which handler applies: `handleAdd` for `button`, `handleToggle` for `checkbox` and `toggle`. Wiring the wrong one leaves the control inert for merchants who picked the other format.
</Warning>

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

### Text

The **Text** section in Design lets you control the typography of three elements. Use the **Text element** picker to switch between them.

**Title** — the protection heading. Also supports a custom font family. Bold and text color are set in the Rich Text Editor above (in the Settings tab), not here.

| Setting            | What it controls             | Default             |
| ------------------ | ---------------------------- | ------------------- |
| **Font**           | Font family for the title.   | Inherits from theme |
| **Size**           | Font size.                   | `15px`              |
| **Line height**    | Line height multiplier.      | `1.33`              |
| **Letter spacing** | Tracking between characters. | Normal              |

**Price** — the price line. Bold and text color are set in the Rich Text Editor above.

| Setting            | What it controls             | Default |
| ------------------ | ---------------------------- | ------- |
| **Size**           | Font size.                   | `15px`  |
| **Line height**    | Line height multiplier.      | `1.33`  |
| **Letter spacing** | Tracking between characters. | Normal  |

**Description** — the supporting copy. Bold and text color are set in the Rich Text Editor above.

| Setting            | What it controls             | Default |
| ------------------ | ---------------------------- | ------- |
| **Size**           | Font size.                   | `14px`  |
| **Line height**    | Line height multiplier.      | `1.29`  |
| **Letter spacing** | Tracking between characters. | Normal  |

<Tip>
  Clicking a text element directly in the cart preview highlights it and opens its controls in the panel automatically.
</Tip>

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Subscription upgrade block
Source: https://docs.aftersell.com/aftersell/cart/subscription-upgrade-block

The Aftersell Cart Subscription upgrade sub-block: convert eligible one-time lines to a subscription from the cart.

> The **Subscription upgrade** block is a sub-block that nests inside [**Cart items**](/aftersell/cart/cart-items-block). It prompts shoppers to switch an eligible one-time line item to a subscription right from the cart, turning a one-time purchase into recurring revenue at the point of decision, and lets shoppers who are already subscribed change or cancel their plan on that line.

## Behavior

* **Only appears on eligible lines.** The block reads the product's selling plans and renders nothing on a line whose product has no subscription plans.
* **Never offered on reward gifts.** Subscribing to an auto-granted free gift would strip its reward status, so the prompt is suppressed on those lines.
* On a **one-time line**, it shows the upgrade call-to-action.
* On an **already-subscribed line**, it shows a plan selector plus the "downgrade to one-time" option.

## Settings

| Setting              | What it controls                                                                                       | Default                         |
| -------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------- |
| **Button text**      | The upgrade call-to-action on a one-time line. Supports the `{{discount}}` and `{{plan name}}` tokens. | `Subscribe & Save`              |
| **Unsubscribe text** | The option that reverts a subscribed line to a one-time purchase.                                      | `Downgrade - One time purchase` |

## Placement and limits

* **Parent:** nests inside Cart items only.
* **Maximum:** 1 per cart.
* Not added by default. Not locked, so you can remove or hide it.

Because it's a sub-block, it renders per line, positioned above or below the product content depending on where you place it relative to the Product row. See [how sub-blocks position](/aftersell/cart/cart-items-block#sub-blocks-and-how-they-position).

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

This block renders one of two states, and `view.state` tells you which. `view` is never `null` inside a custom template: when a line has no plans, the block renders nothing and your template isn't called.

| Prop              | Type                               | What it's for                                                                                                                         |
| ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `view`            | `object`                           | The line's state. Either `{ state: 'upgrade', buttonText, planId }` or `{ state: 'subscribed', plans, activePlanId }`.                |
| `title`           | `string`                           | The **product's** title, not a heading for the block. The built-in template uses it only to build the plan picker's accessible label. |
| `unsubscribeText` | `string`                           | Label for the downgrade-to-one-time option.                                                                                           |
| `busy`            | `boolean`                          | `true` while a plan change is in flight.                                                                                              |
| `selectPlan`      | `(planId: number \| null) => void` | Subscribes or switches plan. Pass `null` to unsubscribe.                                                                              |
| `onChange`        | `(event: Event) => void`           | Ready-made `onChange` for a `<select>`, so you don't have to parse the value yourself.                                                |
| `oneTimeValue`    | `string`                           | The sentinel `<option>` value representing "one-time purchase".                                                                       |
| `line`            | `AftersellCartLine`                | The [cart line](/aftersell/cart/sdk-cart-object#cart-lines) this block belongs to.                                                    |
| `productId`       | `number`                           | Shopify product ID.                                                                                                                   |
| `variantId`       | `number`                           | Shopify variant ID.                                                                                                                   |

Each entry in `view.plans` is `{ id: number, name: string, discountPercent: number }`.

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomTemplate(props) {
  const { view } = props;

  if (view.state === 'upgrade') {
    return (
      <button type="button" onClick={() => props.selectPlan(view.planId)} disabled={props.busy}>
        {view.buttonText}
      </button>
    );
  }

  return (
    <div>
      <select
        aria-label={`Subscription plan — ${props.title}`}
        value={String(view.activePlanId)}
        onChange={props.onChange}
        disabled={props.busy}
      >
        {view.plans.map((plan) => (
          <option key={plan.id} value={String(plan.id)}>
            {plan.name}{plan.discountPercent > 0 ? ` (${plan.discountPercent}% off)` : ''}
          </option>
        ))}
        <option value={props.oneTimeValue}>{props.unsubscribeText}</option>
      </select>
    </div>
  );
}
```

<Note>
  Use `onChange` for a `<select>` and `selectPlan` for buttons. `onChange` already handles the `oneTimeValue` sentinel; if you wire your own handler to a `<select>`, you have to compare against `oneTimeValue` and call `selectPlan(null)` yourself.
</Note>

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Summary block
Source: https://docs.aftersell.com/aftersell/cart/summary-block

The Aftersell Cart Summary block: totals, savings, and applied discount codes.

> The **Summary** block shows the shopper what they'll pay: a total row with optional savings, plus applied discount tags. It summarizes the cart's totals and savings just above the checkout button, so shoppers see the bottom line before they commit.

<Frame>
  <img alt="Summary block displaying subtotal, savings, and applied discounts before checkout" />
</Frame>

## Behavior

* **Savings tokens collapse gracefully.** If a cell references `{{savings}}` or `{{pre_savings_price}}` but the cart has no saving, that cell falls back to just `{{total_price}}`, so shoppers never see "\$0.00 off" or a struck price equal to the total. If you combine `{{cart_item_count}}` and `{{savings}}` in the same cell, the item count is also removed in the no-savings fallback — put them in separate cells to avoid this.
* Discount tags appear only when **Show discount codes** is on *and* the cart has discounts to list. This includes both code-based and automatic discounts.

## Settings

| Setting                 | What it controls                                                                                        | Default                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------- |
| **Left text**           | The left cell of the total row. Rich text with tokens. Example: `Subtotal ({{cart_item_count}} items)`. | `Subtotal`                       |
| **Right text**          | The right cell. Rich text with tokens (total, struck pre-savings price, savings, item count).           | Total with struck savings markup |
| **Savings format**      | Show savings as a whole `percent` or an `absolute` amount.                                              | `percent`                        |
| **Show discount codes** | Whether applied discount tags appear. This includes both code-based and automatic discounts.            | On                               |

The text cells support the `{{cart_item_count}}`, `{{total_price}}`, `{{pre_savings_price}}`, and `{{savings}}` tokens.

## Placement and limits

* **Region:** bottom.
* **Maximum:** 2 per cart state — the filled cart and the empty cart each get their own allowance.
* **State:** both filled and empty cart.
* Added to new carts by default. Not locked, so you can remove or hide it.

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

| Prop                | Type       | What it's for                                                                                                                 |
| ------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `leftHtml`          | `string`   | The left cell as sanitized HTML, with tokens resolved.                                                                        |
| `rightHtml`         | `string`   | The right cell as sanitized HTML, with tokens resolved.                                                                       |
| `discountCodes`     | `string[]` | Discount titles applied to the cart (code-based and automatic). `[]` when none.                                               |
| `showDiscountCodes` | `boolean`  | Whether the merchant wants discount tags listed **and** the cart has discounts to list.                                       |
| `hasSavings`        | `boolean`  | `true` when the cart has a saving. Use it to hide your own savings row.                                                       |
| `totalPrice`        | `string`   | Cart total, already formatted.                                                                                                |
| `preSavingsPrice`   | `string`   | Total before savings, already formatted.                                                                                      |
| `savings`           | `string`   | Amount saved. Already formatted, **or a percentage** like `15%`, depending on the merchant's savings-format setting.          |
| `itemCount`         | `number`   | Total units in the cart — visible line quantities summed, excluding the shipping-protection line.                             |
| `isLoading`         | `boolean`  | Always `false` here: the block renders its built-in skeleton during load and only calls your template once the cart is ready. |

<Warning>
  Because `savings` can be either money or a percentage, don't build your own sentence around it that assumes one. `{props.savings}` on its own is safe; `You saved ${props.savings}` is not.
</Warning>

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Test analytics
Source: https://docs.aftersell.com/aftersell/cart/test-analytics

Compare A/B test variants for your Aftersell Cart — per-variant conversion, revenue, and impressions.

The Analytics page's **test** view compares the variants of a running or completed [cart test](/aftersell/cart/tests-overview) side by side. For per-cart performance — revenue, impressions, conversion, and top products — see [Cart analytics](/aftersell/cart/analytics).

## Per-variant metrics

For a running or completed test, each variant shows:

| Metric              | What it means                                                                                                                                                                                                                                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Traffic %**       | The share of traffic allocated to the variant.                                                                                                                                                                                                           |
| **Conversion rate** | Checkouts divided by impressions.                                                                                                                                                                                                                        |
| **Added revenue**   | Revenue attributed to the variant, across upsell, add-on, and subscription revenue.                                                                                                                                                                      |
| **Impressions**     | How many times the variant was shown.                                                                                                                                                                                                                    |
| **Blocks enabled**  | A count of the revenue categories that actually **earned** in the period — Upsells, Add-ons, Subscriptions. Hover it to see which. A block the variant runs but that made no sales isn't counted, so this is not a list of the blocks the cart contains. |

There's no automatically declared winner — the variants sit side by side and you [choose the winner](/aftersell/cart/tests-overview#ending-a-test-and-choosing-a-winner) when you end the test. The significance bar on a live test shows whether you've collected enough traffic to decide.

## Notes

* **Revenue coverage.** Added revenue counts upsell, add-on, and subscription revenue. It's a subset of everything the cart earns rather than a full partition, so it won't reconcile against a store-wide total. The **Revenue** figure on the end-test screen is broader — every conversion attributed to the cart — so the two won't match for the same test. See [Cart analytics](/aftersell/cart/analytics#a-note-on-revenue-coverage).
* **Data and freshness.** Test figures are totals across the test's run window, not a daily series, so they only ever grow while the test is live. Nothing on this page is marked provisional. See [How the data is collected](/aftersell/cart/analytics#how-the-data-is-collected).
* **Export.** The per-variant test cards don't currently export to CSV.


# How do tests work?
Source: https://docs.aftersell.com/aftersell/cart/tests-overview

Create and run Aftersell Cart A/B tests, read the significance indicator, and learn what can and can't be tested.

A **cart test** is an A/B test between two whole carts. You test your live cart against one challenger, split traffic between them, and pick the winner when you're done.

## What you're testing

The unit of a test is a **complete cart** — an entire experience, not a single block or setting. You compare two of your saved carts wholesale. Any draft cart can be the challenger.

## Creating a test

From the **Carts** page, choose **Create test**. You'll need a live cart and at least two carts total. Then:

1. Your **live cart is the control** automatically — you can't change it.
2. Pick **one challenger** from your other carts.
3. Set the **traffic allocation** — the split between the two, defaulting to 50/50. Each side is between 1% and 99%, and the two must add up to 100%.
4. Give the test a **name** (required).
5. **Publish & start test.**

Only **one test can run per store at a time.**

## While a test runs

* Shoppers are **stickily bucketed** into one variant, so a returning shopper keeps seeing the same cart for the length of the test.
* **Publishing and unpublishing are locked**, and the **variant carts are read-only** in the editor — end the test to make changes.

## The significance indicator

While a test runs, Aftersell shows a **significance progress bar**: the impressions collected so far against a target sample size. The target is a **total across the test**, sized so the *smallest* variant still gathers about 3,500 impressions — roughly **7,000 in total** for a 50/50 split, and proportionally more for an uneven one (an 80/20 split needs about 17,600). As the test runs, impressions accumulate and the bar fills toward that target.

The bar appears only while a test is live. Once you end the test the bar disappears; the banner keeps showing the test's start and end dates, and you read the outcome from the per-variant results.

<Note>
  The bar is a **readiness indicator** — it tells you whether you've gathered enough traffic to make a confident call. It is **not** a statistical p-value, and Aftersell does **not** auto-declare a winner. Let the test gather enough data, then compare the variants and choose.
</Note>

## Ending a test and choosing a winner

When you end a test, you see each variant's **Revenue**, **conversion rate (CCR)**, and **impressions** side by side, and you **pick the winner yourself**. The winner is published live and the other cart returns to draft.

<Note>
  **The end-test Revenue figure is broader than the one on the Test analytics page.** Here it's every conversion attributed to the cart. On [Test analytics](/aftersell/cart/test-analytics) the Added revenue metric is narrowed to upsell, add-on and subscription revenue. Expect the two numbers to differ for the same test, and compare variants within one surface rather than across them.
</Note>

## What can and can't be tested

* **Can:** any two whole cart configurations. Swap layouts, blocks, copy, design — build a challenger cart however you like and test it against the live one.
* **A caveat on metrics:** the Added revenue metric on Test analytics covers upsell, add-on, and subscription revenue — a subset of everything a cart earns rather than a full partition. Treat it as a like-for-like read between the two variants rather than as each variant's total contribution. The end-test screen uses the broader figure described above.

See [Test analytics](/aftersell/cart/test-analytics) for how to read the results.


# Upsells block
Source: https://docs.aftersell.com/aftersell/cart/upsells-block

The Aftersell Cart Upsells block — strategy-picked product offers shown in the drawer.

> The **Upsells** block shows product offers in the cart drawer, chosen by a **Strategy** you select. When a shopper opens the cart, the block surfaces the products your Strategy returns based on the current cart contents and any targeting rules you've configured.<br /><br />Grow average order value by surfacing relevant product offers at the moment shoppers open their cart, using a Strategy that picks what to show based on cart contents and your targeting rules.

<Info>
  Unlike the [**Product add-on**](/aftersell/cart/product-add-on-block) block, which always shows one product you pick, Upsells is driven by a Strategy that decides what to show.
</Info>

<Frame>
  <img alt="Upsells block showing strategy-picked product recommendations in the cart drawer" />
</Frame>

## Behavior

* Products are fetched live based on the shopper's current cart, so the offers reflect what's actually in the cart.
* **The whole section hides when no products resolve** — no Strategy attached, the Strategy returns nothing, or none of the returned products are purchasable. Shoppers never see an empty Upsells section.
* If a returned offer carries a discount, the shopper sees an honest strikethrough and a discount badge, and the discount is applied at checkout.

## Settings

| Setting                   | What it controls                                                                                                                                                                 | Default                                 |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| **Title**                 | Rich-text heading above the offers. Supports bold, italic, alignment, and color.                                                                                                 | `You may also like`                     |
| **Add button text**       | The label on each product's add button.                                                                                                                                          | `Add`                                   |
| **Strategy**              | The Strategy that chooses which products to show.                                                                                                                                | A Shopify AI strategy, assigned for you |
| **Layout**                | **Carousel** or **List**.                                                                                                                                                        | Carousel                                |
| **Maximum products**      | How many products to show at most. Accepts `1`–`12`.                                                                                                                             | `4`                                     |
| **Show compare-at price** | Whether to show a struck compare-at price.                                                                                                                                       | On                                      |
| **Show product reviews**  | Whether to show star ratings and review counts on each upsell card. Ratings are sourced from your review app's product metafields and only appear when valid review data exists. | Off                                     |

### Supported review apps

The following metafield-based review apps are supported: Shopify Product Reviews, Junip, Okendo, Growave, Fera, Stamped, Loox, REVIEWS.io, Automizely Reviews, Judge.me, Ali Reviews, Trustoo, Rivo, Rivyo, and Vitals. Yotpo is not supported because it uses a separate API rather than product metafields.

## Design

The Upsells block has per-block design overrides in its **Design** panel. These override the cart's global design settings for this block only. Leaving a value blank inherits the global setting.

### Text styling

The Upsells block includes a **Text** section in its Design settings. Use it to control the typography of individual text elements on each upsell card. Select a text element from the picker to adjust its settings:

| Setting            | What it controls                                                                                                                                    |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Text color**     | Color of the selected text element.                                                                                                                 |
| **Font**           | **Theme font** (inherits your theme's font) or **Custom font** (enter the name of a font your theme already loads). Available for **Heading** only. |
| **Size**           | Font size in pixels.                                                                                                                                |
| **Weight**         | Font weight: Light, Regular, Medium, Semibold, or Bold.                                                                                             |
| **Line height**    | Line height as a multiplier of the font size (for example, `1.4`).                                                                                  |
| **Letter spacing** | Letter spacing in pixels. Negative values tighten the text.                                                                                         |

The text elements you can style are grouped by category:

**Heading**

* **Heading** — the section heading above the upsell cards (for example, *You may also like*). Also supports a custom font family. Bold and color are set in the Rich Text Editor above.

**Product**

* **Product title** — the product name on each upsell card.
* **Review count** — the review count shown when **Show product reviews** is enabled.

**Pricing**

* **Price** — the current price on each card.
* **Compare-at price** — the struck-through original price.
* **Discount** — the discount label (for example, *20% off*).

Leaving any field blank keeps the element's default value.

<Tip>
  Clicking a text element directly in the cart preview highlights it and opens its controls in the panel automatically.
</Tip>

### Tile colors

| Setting                   | What it controls                                 | Default     |
| ------------------------- | ------------------------------------------------ | ----------- |
| **Tile background color** | The background fill of each upsell product card. | Transparent |
| **Tile border color**     | The border color of each upsell product card.    | `#F6F6F7`   |

### Reviews

When **Show product reviews** is enabled, you can customize the star colors from the **Reviews** section of the Design panel.

| Setting              | What it controls                   | Default   |
| -------------------- | ---------------------------------- | --------- |
| **Star color**       | The filled portion of each star.   | `#FDCC0D` |
| **Empty star color** | The unfilled portion of each star. | `#D1D5DB` |

## Placement and limits

* **Region:** body or bottom.
* **Maximum:** 1 per cart state — the filled cart and the empty cart each get their own.
* **State:** both filled and empty cart.
* Not added by default. Not locked — you can remove or hide it.

## Selecting a strategy

An Upsells block doesn't arrive empty: if no Strategy is set, Aftersell resolves your store's Shopify AI strategy — creating it if you don't have one yet — and fills it in, so the block works straight away. Open the **Strategy** picker to change it. The picker has two groups:

**Quick start**

* **Create strategy from selected products** — pick specific products directly and a Strategy is created for you automatically.
* **Create strategy from scratch** — opens the Strategy editor so you can build rules without leaving the cart editor.

**Strategies**

* **Shopify AI recommendations** — creates a Strategy backed by Shopify's own recommendations, named **Shopify AI recommended products** wherever it appears afterwards. This entry disappears once you have one, since a store only ever needs a single Shopify AI strategy.
* Your existing Strategies, listed by name. Type in the search field to filter them.

Once a Strategy is selected, its name appears on the strategy row inside the block.

## Managing a selected strategy

After a Strategy is attached, a **•••** (ellipsis) button appears on the strategy row. Click it to open the actions menu:

* **Edit strategy** — opens the Strategy editor in a new tab, so your cart editor session and any unsaved changes stay intact. This option isn't available for the Shopify AI-recommended strategy, which is managed automatically and has no editable rules.
* **Remove from upsell** — detaches the Strategy from this block. The Strategy itself isn't deleted; it stays available in your Strategies list.

Editing a Strategy in a new tab doesn't affect the cart editor session — you can return to the cart editor tab and continue configuring without losing your work.

## Custom template

Supports a [custom template](/aftersell/cart/custom-templates) from its Code tab, which replaces this block's built-in markup with your JSX. These are the props it receives.

### Block content

| Prop            | Type                   | What it's for                                                             |
| --------------- | ---------------------- | ------------------------------------------------------------------------- |
| `title`         | `string`               | Section heading.                                                          |
| `addButtonText` | `string`               | Add-to-cart button label.                                                 |
| `layout`        | `'carousel' \| 'list'` | Horizontal scroll, or wrap. Branch your markup on this.                   |
| `upsells`       | `UpsellCard[]`         | The display-ready products. See [the card shape](#the-upsell-card) below. |
| `isLoading`     | `boolean`              | `true` while upsell products are still being fetched.                     |

### Adding to cart

| Prop              | Type                                             | What it's for                                                                            |
| ----------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `selectVariant`   | `(productId: string, variantId: number) => void` | Selects a variant for a product.                                                         |
| `handleAdd`       | `(productId: string) => void`                    | Adds that product's selected variant to the cart.                                        |
| `addingProductId` | `string \| null`                                 | The product currently being added, so you can disable just its button. `null` when idle. |

### Carousel controls

Only relevant when `layout` is `'carousel'`.

| Prop           | Type                                  | What it's for                                                                    |
| -------------- | ------------------------------------- | -------------------------------------------------------------------------------- |
| `trackRef`     | `{ current: HTMLDivElement \| null }` | Attach to your scroller with `ref={props.trackRef}` so the arrows can scroll it. |
| `atStart`      | `boolean`                             | `true` when the track is at its start edge. Disable the left arrow.              |
| `atEnd`        | `boolean`                             | `true` when the track is at its end edge. Disable the right arrow.               |
| `scrollByCard` | `(direction: 1 \| -1) => void`        | Scrolls the track one card left (`-1`) or right (`1`).                           |

### The upsell card

Each entry in `upsells`:

| Field                     | Type                      | What it's for                                                                                                                                                                                                                                                                                                                 |
| ------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `productId`               | `string`                  | Product GID. Use it as the React key and as the add-to-cart target.                                                                                                                                                                                                                                                           |
| `title`                   | `string`                  | Product title.                                                                                                                                                                                                                                                                                                                |
| `description`             | `string`                  | Plain-text description. `''` when the product has none.                                                                                                                                                                                                                                                                       |
| `url`                     | `string \| null`          | Product page URL. `null` when unavailable.                                                                                                                                                                                                                                                                                    |
| `imageUrl`                | `string \| null`          | Featured image. `null` when the product has none.                                                                                                                                                                                                                                                                             |
| `selectedVariantImageUrl` | `string \| null`          | The selected variant's own image. `null` when the variant has none — fall back to `imageUrl`.                                                                                                                                                                                                                                 |
| `variantTitle`            | `string \| null`          | The selected variant's option values (e.g. `Medium / Blue`), already resolved. `null` when the variant has no real title — blank or Shopify's `Default Title` placeholder. A product with one named variant still returns that name, so guard with `{upsell.variantTitle && …}` rather than keying off `hasMultipleVariants`. |
| `priceLabel`              | `string`                  | Price to show, already formatted. The sale price when discounted, otherwise the variant price.                                                                                                                                                                                                                                |
| `compareAtLabel`          | `string \| null`          | Struck-through original, already formatted. `null` when there's nothing to strike.                                                                                                                                                                                                                                            |
| `discountLabel`           | `string \| null`          | Inline discount label such as `(20% off)`. `null` when not discounted.                                                                                                                                                                                                                                                        |
| `review`                  | `object \| null`          | `{ rating, count, stars }`, where `stars` is 5 pre-rendered image URLs with fractional fill baked in. Render each as an image element. `null` when reviews are off or the product has none.                                                                                                                                   |
| `options`                 | `Array<{ name, values }>` | Option groups, for building pickers or swatches.                                                                                                                                                                                                                                                                              |
| `variants`                | `array`                   | The variant combinations. See below.                                                                                                                                                                                                                                                                                          |
| `selectedVariantId`       | `number`                  | The currently selected variant. Pass it to `selectVariant`.                                                                                                                                                                                                                                                                   |
| `hasMultipleVariants`     | `boolean`                 | Whether to render a variant picker at all.                                                                                                                                                                                                                                                                                    |
| `vendor`                  | `string`                  | The product's vendor.                                                                                                                                                                                                                                                                                                         |
| `selectedVariantImageUrl` | `string \| null`          | The selected variant's own image. `null` when it has none — fall back to `imageUrl`.                                                                                                                                                                                                                                          |

Each entry in `variants` carries `id`, `title`, `price` and `compareAtPrice` (raw, unformatted, in the currency's major unit as strings), `availableForSale`, `imageUrl`, `sku`, and `selectedOptions` (`[{ name, value }]`).

<Warning>
  **Availability is per combination, not per option.** `options` gives you the groups to render, but whether a given selection is buyable lives on the matching entry in `variants`. Resolve the shopper's picked combination against `variants` and gate on that entry's `availableForSale`, rather than assuming every value in `options` is orderable.
</Warning>

<Note>
  `priceLabel` and `compareAtLabel` are already formatted for display, while `variants[].price` and `variants[].compareAtPrice` are raw strings in the currency's major unit. Don't mix the two: show the labels, and use the raw values only for comparisons.
</Note>

## Design

Style this block with its **Design** section in the settings panel. These are per-block overrides that layer on top of your global design and fall back to it when blank.

What are design settings? Learn more here: [Design settings](/aftersell/cart/design-settings).


# Changing post-purchase button colours (CTA)
Source: https://docs.aftersell.com/aftersell/changing_post_purchase_button_colours_cta

How to change the background and text colours of the post-purchase upsell call-to-action button through your Shopify checkout settings.

> This article demonstrates how to modify the background and text colours for the post-purchase call-to-action button.

The background colour of the post-purchase upsell button always matches the button colour of your Shopify Checkout page. This is enforced by Shopify to keep the checkout experience consistent for your customers.

For the full picture of how post-purchase styling works — including what else your checkout branding controls and where to edit it on your plan — see [Post-purchase branding settings](/aftersell/post_purchase_branding_settings).

# Changing the button colour

Go to your **Shopify Admin > Settings > Checkout**, then click the "**Customize**" button on your live checkout profile:

<img alt="Shopify Checkout settings with the Customize button on the live checkout profile highlighted" />

Next, navigate to the Settings tab on the left and adjust the button colour as shown in the image below.

<img alt="Checkout editor Settings panel with the Buttons colour field highlighted" />

If your store is on Shopify Plus, you can make the same change inside Aftersell instead — see [Checkout branding settings](/aftersell/checkout_branding_settings).

# Understanding the button text colour

The text on the button is automatically determined by Shopify according to the button background colour. This ensures the text stays visible and easy to read.

***

If the button in the Aftersell editor preview does not match what you set here, that is expected on non-Plus plans — [Post-purchase branding settings](/aftersell/post_purchase_branding_settings) explains why, and how to verify with a test order.

If you have any issues or further questions, please don't hesitate to reach out to our support team via the chat option in the bottom right corner of the app.


# Checkout best practices
Source: https://docs.aftersell.com/aftersell/checkout_best_practices

A complete strategy guide for configuring, optimizing, and testing your checkout widgets in Aftersell

# Checkout best practices

This guide covers how to get the most out of Aftersell's checkout widgets on Shopify Plus -- from choosing between Pages and Standalone widgets, to configuring upsells, trust badges, rewards, and testimonials, to running A/B tests and avoiding common setup mistakes.

<Note>
  Checkout widgets are only available to Shopify Plus merchants due to Shopify's Checkout Extensibility API restrictions. For post-purchase upsell best practices, see [Post-Purchase Best Practices](/aftersell/best_practices).
</Note>

***

## Choose the right widget structure

Aftersell offers two ways to add widgets to your checkout: **Pages** and **Standalone widgets**. Choosing the right structure upfront saves time and avoids conflicts later.

### When to use Pages

A [Page](/aftersell/pages-vs-standalone-widgets) is a group of widgets that share a single set of triggers. When the trigger conditions are met, all widgets in the page display together. Use Pages when you want to show a coordinated set of widgets to the same audience -- for example, an upsell, trust badges, and testimonials all appearing together for a specific customer segment.

Pages support a guided setup that recommends widgets based on a goal you select:

* **Increase AOV and conversion rate** - Upsells, Trust Badges, Testimonials
* **Build customer trust and reduce abandonment** - Trust Badges, Cart Controls, Text
* **Promote add-ons and accessories** - Checkbox Upsells, Images, Testimonials
* **Encourage customers to reach free shipping threshold** - Upsells (with Rewards), Text

<Warning>
  Your goal cannot be changed after saving. If you need a different goal, you will need to delete the page and create a new one. Widgets can be added to or removed from a page at any time.
</Warning>

### When to use Standalone widgets

[Standalone widgets](/aftersell/pages-vs-standalone-widgets) function independently, each with their own triggers and priority configured at the variant level. Use Standalone widgets when you need a single widget that runs on its own, or when you need different trigger conditions for different widgets.

Standalone widgets also support A/B testing (Pages do not support A/B testing yet), so use Standalone if testing is part of your strategy.

### Block limits

Pages allow up to 5 blocks per widget type. Standalone widgets allow a maximum of 3 blocks per widget type. Once all blocks are in use, you cannot create additional widgets of the same type until an existing block is removed.

***

## Upsell widget strategy

Checkout upsells are your primary revenue driver at this stage. The goal is to increase AOV without increasing checkout abandonment.

### Choose the right upsell mode

Aftersell offers three upsell widget modes:

* **Single Product Upsell** - Show one product with an Add to Cart button. Best for focused, high-confidence offers where you know exactly what the customer is likely to want.
* **Multi-Product Upsell** - Show multiple products in a stack or carousel layout. Customers can accept multiple offers. Best for stores with a wide catalog where you want to give customers options.
* **Checkmark Upsell** - Show a single product with a checkbox instead of an Add to Cart button. Best for low-cost add-ons like shipping protection, gift wrapping, or rush processing where the decision is simple and fast. Note: the checkbox cannot be pre-checked or auto-added to the order by default. Shopify does not allow this. The customer must actively check the box to add the product.

### Choose the right product selection method

Each upsell widget supports several product selection methods. Choose based on your catalog and strategy:

* **Specific Products** - Manually select individual products to upsell. Use when you want full control over exactly what appears, such as during a seasonal promotion or for curated pairings.
* **Collection** - Select a collection and display up to 5 random products from it. Products already in the cart are automatically excluded. Use when you want variety within a curated set without manually managing individual products.
* **AI Recommendations** - Let Aftersell automatically recommend products based on the customer's cart contents. Use when you have a large catalog and want personalized recommendations without manual curation.
* **Most Expensive Product** - Automatically upsell the most expensive product from the customer's cart. Use for cross-sell scenarios where re-offering the hero item makes sense.
* **Spend Threshold** - Recommend products that help customers reach a free shipping threshold (requires the rewards widget to be enabled). Use alongside the rewards bar to close the gap between the customer's current cart value and the free shipping goal.

### Always add a discount to your checkout upsells

We strongly recommend adding a discount to every checkout upsell widget. A discount gives customers an immediate incentive to add the product to their order and significantly increases acceptance rates. Even a small discount signals value and can be the difference between a customer engaging with the offer or ignoring it.

Discounts are configured directly within the Aftersell upsell widget and are automatically applied when the customer adds the upsell product to their order. You can either select an existing Aftersell checkout discount or create a new one (percentage or fixed dollar) right in the widget editor. See [Checkout Widget Types](/aftersell/checkout_widget_types) for full details on discount configuration.

Keep in mind:

* Shopify only allows one line-item discount per product at a time. If a product already has a discount applied, the Aftersell upsell discount will not stack on the same line item.
* For two discounts to combine, both must be explicitly set to "combinable" in Shopify Admin.
* If another app is dynamically modifying your checkout (for example, recalculating pricing), Aftersell discounts may not apply as expected.

### Enable product review stars

If you have a compatible review app installed, enable product review star ratings on your upsell widgets. Review ratings build trust and increase the likelihood a customer will accept the offer. You can set a minimum rating threshold (default 4.0) so only well-reviewed products display stars.

Supported review apps include Shopify Product Reviews, Judge.me, Okendo, Loox, Stamped, and others that store ratings in product metafields. See [Checkout Widget Types](/aftersell/checkout_widget_types) for the full list.

***

## Content widgets that increase conversion

Content widgets do not directly offer products, but they reduce checkout abandonment and build trust, which increases overall conversion.

### Trust badges

[Trust badges](/aftersell/checkout_widget_types) highlight security features, guarantees, and shipping benefits. They can be stacked vertically or displayed horizontally.

Effective trust badge content includes:

* Secure checkout / SSL encryption
* Money-back guarantee or satisfaction guarantee
* Free returns or easy exchanges
* Free or fast shipping
* Customer count or order count ("Trusted by 50,000+ customers")

Keep badges concise and use recognizable icons. Place them near the payment section where customers are most likely to hesitate.

### Testimonials

[Flex Testimonials](/aftersell/checkout_widget_types) pull real reviews from your review app (Judge.me, Klaviyo, Okendo, or Yotpo) and display them directly on checkout. Testimonials automatically fetch reviews based on products in the customer's cart, so each customer sees reviews relevant to what they are buying.

Reviews sync automatically within 24 hours of setup, then weekly. To import reviews immediately, go to Settings > Product Reviews and click Sync now.

<Tip>
  Set a minimum rating filter (for example, 4.0) and use the truncate option to keep long reviews clean. A "Read more" button appears automatically for reviews that exceed your character limit.
</Tip>

### Rewards bar

The [rewards bar](/aftersell/checkout_widget_types) shows customers how close they are to earning free shipping. This creates a natural incentive to add more products to their order.

To get the most out of the rewards bar:

1. Set a goal based on **Order Value** or **Item Count**
2. Pair it with an upsell widget using the **Spend Threshold** product type, which automatically recommends products that help customers close the gap to the free shipping threshold
3. Create the free shipping reward in Shopify by modifying your **Shipping Rules** to offer free shipping at the target order value

The rewards bar and spend threshold upsell work best as a pair - the bar creates the motivation, and the upsell provides the product to get there.

### Cart controls

[Cart controls](/aftersell/checkout_widget_types) let customers modify their cart directly on the checkout page -- changing variants, adjusting quantities, removing items, or upgrading to a subscription. This reduces friction and can prevent abandonment from customers who would otherwise leave checkout to make changes.

You can target which products display cart controls using the visibility settings: all products, only selected products, or all products except selected ones. This lets you enable subscription upgrades only on eligible products, for example, without exposing unnecessary controls on other items.

***

## Triggers

[Triggers](/aftersell/checkout_triggers) let you control which customers see which widgets. Using triggers effectively means the right customers see the right offers at the right time.

The full set of available checkout triggers:

* **Products:** Specific products, specific collections, quantity of specific product
* **Cart:** Subtotal, quantity, subscription purchase
* **Discount:** Applied discount titles, discount value
* **Customer:** Shipping country, customer language, customer tags, device type
* **Advanced:** Group of triggers (combine multiple triggers for complex logic)

### Start with a "Show to all" baseline

Before building complex trigger logic, set up your primary widgets to show to all customers. This ensures every checkout session sees your offers and gives you a baseline to measure against before you start segmenting.

### Segment with product and cart triggers

The most impactful triggers for upsells:

* **Specific products or collections** -- Show a complementary upsell when a specific product or collection is in the cart
* **Quantity of specific product** -- Show a widget only when a customer has a certain quantity of a specific product (for example, show a volume discount upsell when a customer has 2 or more of a product)
* **Cart subtotal** -- Show a rewards bar or upsell only when the cart value is within range of a threshold (for example, show the rewards bar when the subtotal is between \$40 and \$75 if free shipping starts at \$75)
* **Cart quantity** -- Show or hide widgets based on how many items are in the cart
* **Subscription purchase** -- Show or hide widgets based on whether any item in the cart is a subscription

### Use customer triggers for personalization

* **Shipping country** -- Show different content or offers based on the customer's shipping destination
* **Customer language** -- Display translated widgets to customers whose locale matches a specific language. Set the trigger to "is French" and translate all editable fields to French within the widget
* **Customer tags** -- Target customers based on Shopify customer tags. Use this for VIP customers, loyalty tiers, wholesale accounts, or any other customer segmentation you have set up in Shopify
* **Device type** -- Show or hide widgets based on whether the customer is on mobile or desktop. This is especially important for placement strategy (see the mobile checkout behavior section below)

### Combine triggers with advanced logic

Use the **Group of triggers** option to combine multiple conditions. For example, show a specific upsell only when the cart contains Product X AND the subtotal is above \$50. This prevents irrelevant offers from appearing and improves the customer experience.

***

## Placement and branding

### Place widgets thoughtfully

Where you place your widget in the checkout affects how likely customers are to see and interact with it. General guidelines:

* **Upsells** -- Place above the payment section where customers are actively reviewing their order. Avoid placing upsells inside the order summary section (see mobile note below).
* **Trust badges** -- Place near the payment section where hesitation is highest.
* **Rewards bar** -- Place near the top of the checkout so customers see the incentive early and have time to act on it.
* **Testimonials** -- Place below the upsell for social proof reinforcement, or near the payment section.

### Placing widgets inside a shipping option row

You can also place most checkout widgets — every type except Cart Controls — directly inside a shipping option row. When placed there, the widget renders inside the row for whichever shipping method the customer currently has selected — it does not appear in every row simultaneously.

This is useful for attaching an offer or message to the shipping selection step — for example, an upsell that appears alongside the customer's chosen shipping method, or trust badges that reinforce the value of a specific rate.

Keep in mind:

* The shipping section does not render for local pickup or digital-only carts, so widgets placed there will not appear for those customers.
* Because the row is narrow and indented under a radio button, test the widget's appearance on both mobile and desktop before going live.

See [Placing a widget inside a shipping option row](/aftersell/how_to_configure_checkout_widgets#placing-a-widget-inside-a-shipping-option-row) for setup steps.

### Be aware of mobile checkout behavior

On mobile, Shopify collapses the order summary section into a dropdown that is hidden by default. Any widgets placed inside the order summary area will be hidden under that dropdown and most customers will not see them. This is Shopify's default behavior and Aftersell has no control over it.

For widgets you want every customer to see (especially upsells and rewards bars), place them outside the order summary section so they are visible on both desktop and mobile without requiring the customer to expand anything.

Use the **device type** trigger to create separate widget configurations for mobile and desktop. For example, you might show a streamlined single-product upsell on mobile (where screen space is limited) and a multi-product carousel on desktop. Or you might place a widget in the order summary for desktop users (where it is always visible) and use a separate widget outside the order summary for mobile users.

<Warning>
  If your upsell widget is placed in the order summary and you are seeing low impressions on mobile, this is likely the cause. Move the widget to a section outside the order summary, or use the device type trigger to show a differently placed widget to mobile customers.
</Warning>

After placing widgets in the Shopify Checkout Editor, check the "Include app block in Shop Pay" option if you want your widgets to display in Shop Pay checkout as well. See [Shop Pay Widgets](/aftersell/show_checkout_widgets_in_shop_pay) for setup details.

### Match your checkout to your storefront

A checkout that looks visually different from your storefront can erode trust and increase abandonment. Use the [Checkout Branding Settings](/aftersell/checkout_branding_settings) to match your checkout's button colors, corner radius, and body colors to your store's design. If your store is not on Shopify Plus, make these changes in the Shopify checkout editor instead (**Settings → Checkout → Customize**). Pay particular attention to the primary button styling -- this is the most visible element in the checkout and should feel consistent with your storefront's CTA buttons.

***

## A/B testing

A/B testing is the most effective way to improve checkout widget performance. See the full [Checkout A/B Testing](/aftersell/checkout_a_b_testing) guide for setup instructions.

### Key concepts

* A/B testing is currently available for **Standalone widgets only** (Pages do not support A/B testing yet)
* Each widget supports **two versions** (Version A and Version B) with an automatic **50/50 traffic split**
* Testing compares **content within a single widget** - you cannot test across different widget types or different placements
* Use **Version A** and **Version B** terminology (not "Layout" - that is post-purchase terminology)

### Most valuable tests to run

**Upsell widget tests:**

* Specific product vs. AI recommendations vs. most expensive product
* Complementary product vs. same product
* Percentage discount vs. fixed dollar discount
* Discount vs. no discount
* Single product upsell vs. checkmark upsell
* Active offer vs. Blank (Skip) to measure whether showing the upsell helps or hurts overall checkout conversion

**Content widget tests:**

* Trust badges with vs. without specific badges
* Different testimonial selections
* Active content vs. Blank (Skip) to measure the impact of showing the widget

### Test one variable at a time

When you change multiple elements at once, you cannot tell which change drove the result. Keep tests clean:

* Good: 10% discount vs. 20% discount (one variable)
* Avoid: 10% discount + Product A vs. 20% discount + Product B (two variables)

### Use Blank (Skip) as a control

This is one of the most valuable tests you can run. A Blank version shows nothing to the customers it is assigned to, giving you a true baseline. If the Blank version results in a higher checkout completion rate, the widget may be hurting conversion and needs to be reconsidered.

### Monitor checkout abandonment alongside upsell conversion

A higher upsell acceptance rate means nothing if checkout abandonment is increasing at the same time. Track the **Checkout abandonment rate** in Analytics > Checkout tab while running A/B tests. For content widgets, per-version analytics also include a Checkout abandonment rate metric.

### Use upsell revenue per order as your primary metric

**Upsell revenue per order** (checkout upsell revenue / purchased orders) is the recommended metric for measuring checkout widget performance over time. It accounts for both upsell acceptance and overall order completion, giving you a complete picture.

***

## Common mistakes

❌ **Placement mismatch between Aftersell and Shopify** - the placement selected in the Shopify Checkout Editor must match the placement set in Aftersell (for example, Default placement, Additional placement 1, Additional placement 2). If they do not match, the widget will not appear or will display in the wrong location. This is one of the most common reasons a widget fails to display. [Fix it →](/aftersell/how_to_configure_checkout_widgets)

❌ **Widget not enabled in Aftersell** - creating and placing a widget is not enough. You must also enable the widget using the toggle in the top right corner of the widget settings in the Aftersell admin. If the toggle is off, the widget will not display regardless of placement. [Fix it →](/aftersell/how_to_configure_checkout_widgets)

❌ **Missing Shop Pay app block setting** - if you want checkout widgets to display in Shop Pay checkout, you must check the "Include app block in Shop Pay" option in the Shopify Checkout Editor for each widget. This is off by default. [Fix it →](/aftersell/show_checkout_widgets_in_shop_pay)

❌ **No "Show to all" baseline** - jumping straight into complex trigger logic without first establishing a baseline that shows widgets to all customers. Start with "Show to all" so you have performance data, then segment with triggers based on what you learn. [Fix it →](/aftersell/checkout_triggers)

❌ **Stacking discounts that do not combine** - Aftersell upsell discounts follow Shopify's standard discount rules. If a product already has a discount and neither discount is set to "combinable" in Shopify Admin, the Aftersell discount will not apply. Check your Shopify discount combination settings before assuming a discount is broken. [Fix it →](/aftersell/checkout_widget_types)

❌ **No rewards bar alongside upsells** - running upsell widgets without a rewards bar misses the opportunity to give customers a reason to add more. Pair the rewards bar with the spend threshold product type in your upsell widget so the upsell directly helps customers reach the free shipping threshold. [Fix it →](/aftersell/checkout_widget_types)

❌ **Not testing with Blank (Skip)** - most merchants test different offers against each other but never test whether showing a widget at all is helping. Use Blank (Skip) as a control to measure whether a widget is increasing or decreasing checkout completion. [Fix it →](/aftersell/checkout_a_b_testing)

❌ **Running only one A/B test version** - for a Standalone widget A/B test to work, both versions must be active at the same time. If one version is deactivated, all traffic goes to the remaining version and no comparison data is collected. [Fix it →](/aftersell/checkout_a_b_testing)

***

## Need help?

If you have questions about configuring or optimizing your checkout widgets, chat with our support team using the live chat at the bottom right of the app.


# Configuring post-purchase offer settings
Source: https://docs.aftersell.com/aftersell/configuring_post_purchase_offer_settings

Learn how to configure settings for your post-purchase offers, including custom order tags, discounts, and product options.

When creating or editing a post-purchase offer, you have several configuration options to customize how the offer appears and behaves. This guide covers the key settings available for V2 post-purchase offers.

***

### Clicking a widget in the preview to edit it

On V2 post-purchase offers, you can open a widget's settings directly from the offer preview instead of hunting for it in the sidebar list.

* **Image and video slots** — If an image or video widget has no content uploaded yet, the preview shows a placeholder prompt in its place. Click the placeholder to open that widget's settings.
* **Text and timer blocks** — Click any rendered text or timer block in the preview to jump straight to its widget settings.

Clicking a widget in the preview switches to the **Editor** tab and opens the correct settings panel automatically.

This feature is available on V2 post-purchase offers only.

***

### Searching offer settings

The post-purchase offer editor includes a **Search settings** box at the top of the left sidebar. You can use it to quickly find any setting across your offer without scrolling through each section manually.

As you type, results are grouped:

* **This offer** — shared settings within the offer's existing widgets. Selecting a result switches to the relevant widget, opens the section, and jumps directly to the field.
* **Upsell product 1**, **Upsell product 2**, … — on a multi-product offer, each product's own settings get their own group, ordered by placement.
* **Add widget** — widgets not yet added to the offer. Selecting a result adds the widget and opens its settings.
* **Funnel settings** — links to funnel-level pages such as triggers, targeting, A/B testing, translations, and analytics.

Empty groups are left out, so a search that matches nothing per-product simply shows the other three.

This feature is available on V2 post-purchase offers only.

***

### Custom order tags

You can add a custom tag to any V2 post-purchase offer to track which specific upsell a customer accepted. When a customer accepts an offer with a custom tag configured, that tag is automatically applied to their Shopify order alongside the standard "AfterSell Upsell" tag.

#### Why use custom order tags?

Custom order tags give you more granular tracking and help you:

* Identify which specific upsell offer was accepted
* Segment orders by promotion or campaign
* Filter orders in Shopify by upsell type
* Track performance of different offers within the same funnel

#### How to add a custom order tag

1. Navigate to **Post-purchase Funnels** in the Aftersell admin.
2. Select the funnel containing the offer you want to tag.
3. Click **Edit offer** on the offer you want to configure.
4. In the offer settings, find the **Order Tag** field.
5. Enter your custom tag (up to 40 characters).
6. Click **Save**.

#### Tag requirements

* Maximum 40 characters
* Can include letters, numbers, hyphens, and spaces
* Must follow Shopify's order tag requirements

#### How custom tags are applied

When a customer accepts an offer with a custom tag configured:

* The standard "AfterSell Upsell" tag is applied to the order
* Your custom tag is also applied to the order
* Both tags appear in the order details in Shopify
* You can search and filter orders by your custom tag in the Order Browser

**Tip:** Use descriptive, consistent naming for your tags. For example: "summer-promo-accepted", "bundle-upsell", "vip-offer", "clearance-upsell".

#### Per-offer configuration

Custom tags are configured per offer, not per funnel. This means:

* Different offers in the same funnel can have different custom tags
* You can track exactly which offer in a multi-offer funnel was accepted
* Each offer's tag is independent and can be changed without affecting other offers

***

### Product selection and discounts

When configuring your offer, you can:

* Select specific products or use automatic recommendations
* Apply percentage or fixed-amount discounts
* Add product badges (like "Bestseller" or "New")
* Configure subscription options if applicable

#### Setting a discount

When configuring a discount on your offer, you set two separate fields:

* **Discount type** — choose between **% Off** and **`<CURRENCY>` Off**, where `<CURRENCY>` is your store's currency code (a USD store sees **USD Off**).
* **Discount value** — enter the amount. The field shows a `%` suffix for percentage discounts, or your store's currency **code** as a prefix for fixed-amount discounts — `USD`, not `$` — so the unit is always clear.

A live preview line appears beneath the value field showing how the discount applies to a sample product price — for example, "If your product is \$50.00, customer pays \$40.00 (saves \$10.00)". If you have a specific product selected on the offer, the preview uses that product's price instead of the sample price.

Percentage discounts are capped at 100%. If you enter a value above 100%, or switch from a fixed amount to a percentage while the value exceeds 100%, the value is automatically reduced to 100%.

#### How the discount is displayed

Post-purchase offers have no separate display-format setting: the saving a shopper sees follows the **Discount type** you picked above. A percentage discount shows as a percentage, a fixed-amount discount shows as a money amount, and an offer never shows both at once.

For the display rules on other surfaces — the Thank You Page has its own format setting, and Checkout Upsells can hide the savings text entirely — see [Customizing discount displays](/aftersell/customizing_discount_displays).

#### Rounding rules for percentage discounts

When displaying a percentage discount, Aftersell rounds to the nearest whole number (standard round-half-up rounding).

For example:

* A discount of **39.56%** will display as **40%**
* A discount of **39.44%** will display as **39%**

For more details on product selection, see the [Quickstart Guide](/aftersell/quickstart_guide_to_aftersell).

***

### Offer design and messaging

Customize how your offer appears to customers:

* Add custom text and headlines
* Include countdown timers for urgency
* Configure product images and layout
* Match your brand's checkout styling

For more information on offer design, see [Post-purchase Branding Settings](/aftersell/post_purchase_branding_settings).

***

### Applying a design template to an offer

Inside the funnel editor, you can apply a pre-built design template to any individual V2 single-product offer. Templates give you a complete layout — widgets, copy structure, and a seeded discount — as a starting point you can then customize.

This is available on V2 single-product offers only. Multi-product and box offers are not supported.

#### Available templates

Six templates are available, filtered by funnel type:

| Template               | Category             | Description                                                                     |
| ---------------------- | -------------------- | ------------------------------------------------------------------------------- |
| Bulk supply            | One-time purchase    | Long-form pitch for a multi-month supply, with supporting imagery.              |
| Video sales letter     | One-time purchase    | Video above the offer, with copy blocks either side.                            |
| Image stack            | One-time purchase    | Single centered column carried by images, no body copy.                         |
| Switch to subscription | Replacement upsell   | Swaps the one-time purchase for a subscription, with an instant-refund framing. |
| Complete the bundle    | Replacement upsell   | Swaps the purchased item for the full kit, with a reason-why list.              |
| Frequency upgrade      | Subscription upgrade | Moves an existing subscriber to a longer interval at a lower unit price.        |

One-time purchase and new subscription templates are available in every funnel. Replacement upsell and subscription upgrade templates only appear inside a funnel of that type. On a subscription-upgrade funnel's first offer, the frequency upgrade template is marked as **Recommended**.

#### How to apply a template

1. Open the funnel editor and select the offer you want to redesign.
2. In the left sidebar, find the **Template** section and click **Choose a template**.
3. Browse the template picker. Use the category rail on the left to filter by offer type.
4. Click a template card to select it. A preview thumbnail shows the layout.
5. Click **Replace layout** to apply. You'll be asked to confirm, as this replaces the offer's current layout.

Your product selection is preserved when you apply a template. The template supplies the layout and copy structure; it does not change which product is offered.

#### Example vs. starter

Each template has two views:

* **Starter** — what gets applied to your offer. Images are blank (upload prompts), and text widgets contain placeholder copy with `[Edit]` markers showing where to add your own words. This is what you customize.
* **Example** — the reference layout the template was built from, shown with real images and copy so you can see how the finished offer is meant to read.

After applying a template, a **See example** button appears in the editor header. Click it to switch the preview to the example view, then click **Back to offer** to return to your editable layout.

#### Discounts

Each template seeds a starting discount onto the offer when applied:

* Bulk supply: 56% off
* Complete the bundle: 33% off
* Video sales letter: 30% off
* Frequency upgrade: 25% off
* Image stack: 25% off
* Switch to subscription: 15% off

You can change the discount at any time in the offer's product widget settings.

#### Starter copy

Placeholder copy in the starter is in English. The accept button uses a translated preset ("Add to order" or "Upgrade subscription") that renders correctly in all 32 supported languages (English plus 31 translations) — you do not need to translate it. All other text widgets contain `[Edit]` prompts you should replace with your own copy before publishing.

***

### Need help?

If you have questions about configuring your post-purchase offers or custom order tags, our support team is here to help. Reach out via chat or email us at [support@aftersell.app](mailto:support@aftersell.app).


# Customizing discount displays in Aftersell
Source: https://docs.aftersell.com/aftersell/customizing_discount_displays



Aftersell shows a saving next to a discounted product — either a monetary amount (for example "Save \$6") or a percentage (for example "Save 20%"). Which one appears, and whether you can change it, depends on the surface.

| Surface                         | How the format is chosen                                                              |
| ------------------------------- | ------------------------------------------------------------------------------------- |
| Post-purchase upsells           | Follows the offer's **Discount type**. There is no separate display setting.          |
| Thank You Page                  | A dedicated **Discount display format** setting on the product recommendation widget. |
| Checkout Upsells (Shopify Plus) | The savings text can be hidden entirely with **Hide discount amount text**.           |

***

## Post-purchase offers

Post-purchase offers have no display-format option of their own. The format follows the **Discount type** you pick when setting the discount:

| Discount type                                  | What the shopper sees                    |
| ---------------------------------------------- | ---------------------------------------- |
| **% Off**                                      | A percentage, for example "20% OFF"      |
| **`<CURRENCY>` Off** (for example **USD Off**) | A monetary amount, for example "\$6 OFF" |

The second option is labelled with your store's currency, and the value field you type into is prefixed with the same currency **code** — `USD`, not `$`.

<img alt="Aftersell offer editor widget list with the cursor hovering the Discount option" />

<Note>
  A post-purchase offer shows either a monetary saving or a percentage saving, never both at once.
</Note>

***

## Thank You Page

The product recommendation widget on the Thank You Page has its own **Discount display format** setting, independent of the discount type:

* **Amount off** — for example "US\$120 OFF"
* **Percentage off** — for example "20% OFF"

Because it is a separate setting, you can apply a percentage discount and still show it to shoppers as a monetary amount, or the other way round.

***

## Checkout Upsells

Checkout Upsells append the saving next to the product title automatically. To turn that text off, open the upsell's content settings and tick **Hide discount amount text**.

With it enabled, the "(20% OFF)" / "(\$6 OFF)" suffix disappears while **the discounted price still shows** in the widget — so the shopper still sees what they pay, just not the saving spelled out.

The setting is always available, and it hides every source of that suffix — an Aftersell discount, a compare-at price, or a subscription discount alike.

***

## Rounding Rules for Discount Percentages

When displaying a percentage discount, Aftersell rounds the saving to the nearest whole percent. Decimals below **.5** round down, and decimals of **.5** or higher round up.

For example:

* A discount of **39.4%** will display as **39%**
* A discount of **39.5%** will display as **40%**
* A discount of **39.56%** will display as **40%**

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I display both monetary and percentage discounts at the same time?">
    No. A single offer shows either a monetary saving or a percentage saving, not both. Choose the format that best fits your marketing strategy.
  </Accordion>

  <Accordion title="Can I hide the percentage label in Checkout Upsells?">
    Yes. Tick **Hide discount amount text** in the upsell's content settings. The savings suffix next to the product title is removed and the discounted price still appears.
  </Accordion>

  <Accordion title="Can I show a percentage discount as a dollar amount?">
    On the Thank You Page, yes — **Discount display format** is independent of the discount type. On post-purchase offers, no: the format follows the discount type you chose.
  </Accordion>

  <Accordion title="How are discount percentages calculated?">
    Discount percentages are calculated based on the difference between the original price and the discounted price. The rounding rules above are then applied to determine the final displayed percentage.
  </Accordion>
</AccordionGroup>

***

**Want to go further?**

* [Post-Purchase Best Practices](/aftersell/best_practices) - tips to improve conversion across all your offers
* [How to Configure Post-Purchase Offers](/aftersell/how_to_configure_post_purchase_triggers) - set up your full post-purchase funnel


# Fulfillment
Source: https://docs.aftersell.com/aftersell/fulfillment

This article outlines how order processing workflows can be managed.

**Post-purchase fulfillment holds**

When a customer completes payment during checkout, an order is generated in Shopify. If a post-purchase upsell is offered to the customer, the order will have a fulfillment status of **On Hold**.

The **On Hold** status indicates that fulfillment should be paused, as the customer may accept the upsell, which would add items to the order. This status ensures the order is not processed prematurely, allowing time for potential additions.

<img alt="Shopify order list and detail view showing an order on hold with a Release fulfillment button" />

***

**Releasing post-purchase fulfillment holds**

Once the fulfillment hold is released, the order fulfillment status will change to **Unfulfilled**:

<img alt="Shopify orders list showing an order fulfillment status changed to Unfulfilled" />

The order hold will automatically release in the following scenarios:

* If the customer clicks Accept or Decline on all post-purchase offers.
* If 60 minutes has passed since the order's creation.

**NOTE:** If the "Release fulfillment holds from 1-click offers when offer timer ends" setting is enabled in `Aftersell > Settings > Fulfillment and payment`, the release time may differ.

**DEV Note: How the "Release fulfillment holds from 1-click offers when offer timer ends" setting functions behind the scenes.**

When the above setting is enabled, and Aftersell determines that the order hold should be released, the following actions are performed:

1. Aftersell queries Shopify for the order and retrieves all associated fulfillment orders (an order may have one or more fulfillment orders).
2. Aftersell instructs Shopify to release the order hold for each individual fulfillment order.

Aftersell will add an event to the order for each fulfillment hold released, displaying the message "Aftersell Post Purchase Upsell released fulfillment for X items."

* **Note**: Aftersell does not modify the number of fulfillments.

The following table describes the timeline of when the post-purchase fulfillment hold is released for various customer scenarios:

| Scenario                                                        | Fulfillment status at creation | Hold release timeline                                                              | Transactions / payments                       | Order edited after creation? |
| :-------------------------------------------------------------- | :----------------------------- | :--------------------------------------------------------------------------------- | :-------------------------------------------- | :--------------------------- |
| Customer is not shown a post-purchase upsell                    | Unfulfilled                    | N/A                                                                                | 1                                             | No                           |
| Customer sees a post-purchase upsell and **declines**           | On Hold                        | Released as soon as the customer declines the offer                                | 1                                             | No                           |
| Customer sees a post-purchase upsell and closes the browser tab | On Hold                        | Released after a fixed delay (there is no reliable signal that the tab was closed) | 1                                             | No                           |
| Customer sees a post-purchase upsell and **accepts**            | On Hold                        | Released as soon as the customer accepts the offer                                 | 2 (or 3 if the customer accepted two upsells) | Yes                          |

<img alt="Table of fulfillment hold release timelines for different post-purchase upsell scenarios" />

***

## Order routing for upsells

When an upsell is accepted, Shopify adds the items to the order and creates a separate fulfillment for them. By default, that fulfillment is not re-routed through your store's order routing rules, which can result in the upsell being fulfilled from a different location than the original order — creating a split fulfillment.

You can enable the **Re-run order routing on Aftersell upsells** toggle in `Aftersell > Settings > Fulfillment and payment > Order routing` to have Shopify re-apply your store's [order routing rules](https://help.shopify.com/en/manual/fulfillment/setup/order-routing) to any fulfillment containing only Aftersell upsells, once its hold is released after the post-purchase or thank you page flow completes.

A common use case is to configure your order routing rules to minimize split fulfillments as the first priority, which helps reduce the number of orders where the upsell is fulfilled separately from the original order.

> **Note:** This toggle requires the **merchant-managed fulfillment orders** and **third-party fulfillment orders** Shopify permissions. If these permissions have not been granted, a banner will appear on the settings page prompting you to grant access. The toggle is disabled until both permissions are granted.

***

## **Integrating with external fulfillment services (3PL)**

Certain fulfillment services or custom workflows may not be configured to handle the

**On Hold** status for order fulfillment. If your process does not properly manage post-purchase fulfillment holds, there is a risk of partially fulfilling orders or generating unnecessary extra fulfillments for a single order.

Fulfillment workflows differ from store to store, as do the solutions for managing orders with post-purchase upsells. Every post-purchase order is created with an **On Hold** status; work through the checks below to assess whether your fulfillment service handles that correctly:

1. **Does the order appear in your fulfillment service while it is On Hold?**
   * **Yes** → go to step 2.
   * **No** → the order will not sync until the hold releases. Once the hold is released, check whether it appears. If it does, continue to step 3; if it never appears, a custom solution is required.
2. **Is the order marked On Hold in your fulfillment service?**
   * **Yes** → the service will not fulfill it until the hold is released. Continue to step 3.
   * **No** → the order may be fulfilled while still On Hold, so it could ship before any accepted upsell items are added. Continue to step 3, but watch for premature fulfillment.
3. **When the hold is released, does the order update in your fulfillment service** (accepted upsell items and quantities synced)?
4. **Are all items and details then correct in your fulfillment service?**
   * **Yes** → your process is ready for post-purchase upsells.
   * **No** → a custom solution is required.

<img alt="Decision-tree flowchart for assessing fulfillment service compatibility with post-purchase upsells" />

If your fulfillment process requires a custom solution to work with post-purchase upsells, please contact Aftersell Support for assistance.

***

## ShipStation Integration

If you're utilizing ShipStation with a direct connection to Shopify, your fulfillment process should automatically integrate with post-purchase upsells.

However, if you're using an intermediary service to connect Shopify and ShipStation (such as NetSuite), you might require a custom solution. Please refer to the next section to review the expected order format in ShipStation to ensure everything is operating correctly.

**How On Hold Orders Look in ShipStation**

Orders marked as **On Hold** in Shopify will appear in the On Hold section of ShipStation. These orders will display a quantity of **0**. The quantity shown in ShipStation represents the fulfillable amount, which is indicated as **0** while the order is **On Hold** because none of the items are ready to be fulfilled yet (since the order may still be adjusted with post-purchase upsell items).

<img alt="On Hold order in ShipStation showing a fulfillable quantity of zero" />

After the order fulfillment hold is lifted, the order will shift to the Awaiting Shipment tab in ShipStation. The quantity will be updated to accurately reflect the total quantity of the order, including any post-purchase upsell item(s).

<img alt="ShipStation order moved to Awaiting Shipment with quantity updated after the hold is released" />

These orders will indicate that the quantity has been updated by the selling channel, which is Shopify in this instance.

<img alt="ShipStation order detail showing Selling channel adjusted quantity notes on line items" />

***

## Testing Notes

If you're testing your ShipStation integration and aren't seeing orders come in immediately, you can manually refresh the orders for your store.

<img alt="Manually refreshing store orders in ShipStation using the store update button" />


# Fulfillments and payments setting
Source: https://docs.aftersell.com/aftersell/fulfillments-and-payments-setting



This guide covers every setting available in the Fulfillment and Payment section of Aftersell. These settings control how your orders are held, released, and managed after a post-purchase upsell is offered or accepted.

You can find these settings in your Aftersell admin under **Settings > Fulfillment and Payment**.

<img alt="Aftersell Settings menu with the Fulfillment and payment section highlighted" />

***

## Fulfillment Holds

An order is placed **On Hold** when a customer hasn't yet accepted or declined all of their post-purchase offers, or if they closed the browser tab before making a decision. The hold exists as a buffer between order creation and fulfillment, ensuring the order isn't processed before the customer has finished with their post-purchase offers.

The hold is released automatically in the following situations:

* The customer accepts or declines all post-purchase offers - the hold releases immediately.
* The customer's offer timers run out all the way - the hold releases immediately.
* The customer closed the tab without deciding - the hold releases automatically after **60 minutes**.

The settings below give you more control over how and when those holds are released.

### Release fulfillment holds from 1-click offers when offer timer ends

By default, if a customer closes their browser while on the post-purchase page, the order stays On Hold for **60 minutes** before automatically releasing.

When this setting is enabled, the hold release time is reduced to match the **total** duration of the funnel's offer timers — the first offer's timer plus the longest follow-up path through it (additional upsells, or the downsell). A single 10-minute upsell releases the hold after 10 minutes instead of 60; a 10-minute upsell followed by a 10-minute downsell releases it after 20.

<Note>
  This setting only affects the release timing when a customer closes the browser mid-flow. If the customer accepts or declines all offers, or their timers run out, the hold releases immediately regardless of this setting.
</Note>

**When to enable this:** Enable this if you want orders to move to fulfillment faster after a customer abandons the post-purchase page.

<img alt="Enabled setting to release fulfillment holds when the offer timer ends" />

***

### Release fulfillment holds when the 1-click offer never loaded for the customer

In rare cases, Shopify places a fulfillment hold on an order even when the post-purchase offer never appeared to the customer, for example if the customer closed their browser before the page fully loaded. This is an occasional Shopify quirk rather than a common occurrence.

When enabled, a 5-minute release window is scheduled as a safety net for these situations, automatically releasing the hold on orders where no offer was ever shown.

Only enable this if you are actively seeing orders stuck on hold that never received a post-purchase offer. It is disabled by default and is not needed for most stores.

<Note>
  This setting is only available when **Release fulfillment holds from 1-click offers when offer timer ends** is enabled. If that setting is turned off, this option will be greyed out.
</Note>

<img alt="Setting to release fulfillment holds when the offer never loaded for the customer" />

***

### Allow Aftersell to hold orders with accepted 1-click offers for fraud review

When enabled, Aftersell will place a hold on orders where Shopify has detected a fraud risk above the level you specify. This gives you time to review potentially fraudulent orders before they are fulfilled.

**Fraud Hold Release**

You can set the fraud risk threshold using the **Fraud Hold Release** dropdown. The available options are:

* **Low Risk** - Orders flagged as medium or high risk will be held for review
* **Medium Risk** - Only orders flagged as high risk will be held for review
* **High Risk** - No orders are held; this effectively disables fraud holds

Orders where Shopify's detected fraud risk is higher than your selected threshold will be put on hold by Aftersell until you review and release them manually.

<Warning>
  If you are seeing a high number of orders stuck on hold, check your fraud threshold setting. A threshold that is too sensitive may be holding legitimate orders.
</Warning>

<img alt="Fraud review hold setting with the Fraud Hold Release dropdown set to Low Risk" />

***

## Order routing

### Re-run order routing on Aftersell upsells

When an upsell is added to an order after checkout, Shopify creates a separate fulfillment for it, and that fulfillment can be assigned to a different location than the original order — a split fulfillment.

When this setting is enabled, Aftersell asks Shopify to re-apply your store's order routing rules to any fulfillment that contains only Aftersell upsells, once its hold is released. A common use is to put "minimize split fulfillments" first in your routing priority, so the upsell is more often shipped together with the rest of the order.

<Note>
  This setting needs the **merchant-managed fulfillment orders** and **third-party fulfillment orders** write scopes. Until Aftersell has them the checkbox is greyed out — you can't turn it on to trigger the request. Grant them from the additional-permissions banner on the page using its **Update App** button, and the checkbox becomes available.
</Note>

***

## Partially Paid

A partially paid order can occur in two ways depending on the upsell type:

**Post-purchase upsells**

If a customer accepts a post-purchase upsell but the payment fails, the upsell item is still added to the order. The original items are paid for but the upsell item payment was not processed, resulting in a partially paid order.

**Thank You Page upsells**

When a Thank You Page upsell is configured to use "Modify original order", the item is added to the original order as soon as it is accepted. However, the customer still needs to complete a separate checkout to pay for it. If they exit without completing payment, the order becomes partially paid since it now contains an item that has not been paid for.

The settings below control how Aftersell handles these situations automatically.

For a full explanation of partially paid orders and how to resolve them, see [Partially Paid Orders](/aftersell/partially_paid_orders).

***

### Automatically remove unpaid 1-click and thank you page upsell products from orders

When enabled, Aftersell will automatically remove unpaid upsell products from partially paid orders after a set delay if payment has not been collected. This prevents unpaid items from being accidentally fulfilled and shipped.

**Partially paid removal delay**

Controls how long Aftersell waits after a failed payment before removing the unpaid item from the order. The default is 65 minutes.

* Waiting longer gives customers more time to pay.
* Customers see a payment prompt on the order confirmation page, and Shopify emails a reminder after 2 hours.
* Thank you page upsells are only removed when the offer uses "Modify original order", not when it creates a separate draft order.

<Note>
  Thank you page upsells are only affected by this setting when the offer is configured to use "Modify original order". Offers that create a separate draft order are not affected.
</Note>

<img alt="Setting to automatically remove unpaid upsell products with a 65 minute removal delay" />

***

### Add 'AfterSell Upsell' tag when payment is confirmed

By default, the `AfterSell Upsell` tag is added to an order as soon as an upsell is accepted, regardless of whether payment succeeds.

When this setting is enabled, the tag is only added after payment for the upsell is successfully confirmed. This prevents orders from being incorrectly tagged when the upsell payment fails.

**When to enable this:** Enable this if you use the `AfterSell Upsell` tag to trigger workflows, reports, or fulfillment logic and want to ensure only successfully paid upsells are tagged.

<Note>
  The tag is written as `AfterSell Upsell`, with a capital **S**. If you are matching on it in a Shopify Flow condition or a saved order search, use that exact spelling.
</Note>

<img alt="Setting to add the Aftersell Upsell tag only after payment is confirmed" />

***

**Want to go further?**

* [Fulfillment](/aftersell/fulfillment) - understand how post-purchase fulfillment holds work and how to integrate with 3PL services
* [Partially Paid Orders](/aftersell/partially_paid_orders) - a full guide to handling partially paid orders
* [Potential Workarounds for Fulfillment Flow Issues](/aftersell/potential_workarounds_for_fulfillment_flow_issues) - solutions for fulfillment problems with external services
* [Payment Capture](/aftersell/payment_capture) - manage how and when payments are captured for post-purchase upsells


# Analytics bar
Source: https://docs.aftersell.com/aftersell/home/analytics-bar

The analytics bar on the Aftersell home page shows revenue per surface for a date range you choose, with change badges, sparklines, and expandable charts.

The **analytics bar** runs across the top of the home page and shows revenue for each surface your offers run on, over a date range you choose.

Each tile shows the revenue for that surface, a change badge comparing it to the previous period of the same length, and a sparkline of the trend.

## Choosing a date range

The selector on the left of the bar sets the range for every tile. Comparisons are always against the immediately preceding period of the same length, so a 30-day range compares against the 30 days before it.

## Surfaces

One tile appears per surface active on your store:

| Surface           | What it measures                                                             |
| ----------------- | ---------------------------------------------------------------------------- |
| **Post-purchase** | Revenue from post-purchase offers, including manual funnels and Smart Funnel |
| **Checkout**      | Revenue from widgets on your checkout page or pages                          |
| **Rokt Network**  | Revenue from Rokt Network products                                           |

Surfaces you do not have access to are not shown — the Checkout tile only appears on plans that include Checkout upsells, and the Rokt Network tile only if your store has a Rokt account.

## Change badges

| Badge         | Meaning                                                                       |
| ------------- | ----------------------------------------------------------------------------- |
| Green, upward | Revenue increased against the previous period                                 |
| Red, downward | Revenue decreased against the previous period                                 |
| `0%`          | Revenue is unchanged                                                          |
| `—`           | No comparison is possible, usually because the previous period had no revenue |

## Expanding a tile

Select a tile to expand it into charts for that surface:

* **Post-purchase** and **Checkout** expand to a Revenue chart and a Conversion rate chart.
* **Rokt Network** expands to a Revenue chart and a Revenue per transaction chart.

Each chart plots the selected range against the previous one, with the comparison period drawn as a dashed line.

If your Rokt Network tile has no interval data to chart yet, it shows a **View detailed Rokt Network analytics** button instead, which takes you to the full Rokt Network report.

## Stores with a single surface

If your store has exactly one active surface other than Rokt Network, the bar has room to break that surface out in more detail. Instead of one revenue tile, you get three:

| Tile                                              | What it shows                    |
| ------------------------------------------------- | -------------------------------- |
| **Post-purchase revenue** or **Checkout revenue** | Revenue for that surface         |
| **Impressions**                                   | Impressions for that surface     |
| **Conversion rate**                               | Conversion rate for that surface |

Each of these expands to a single chart matching its own metric, rather than the two-chart view described above.

A store whose only active surface is **Rokt Network** gets the same treatment with Rokt's own metrics: **Rokt Network revenue**, **Transactions**, and **Revenue per transaction**.

Most stores run more than one surface and will see the standard one-tile-per-surface layout.


# App block status
Source: https://docs.aftersell.com/aftersell/home/app-block-status

App block status shows which Aftersell app blocks are added to your Shopify theme and which are still missing, grouped by surface.

Most Aftersell surfaces render through an **app block** you add to your Shopify theme. If the block is missing, that surface will not show to shoppers no matter how it is configured in Aftersell.

**App block status** tells you which blocks are in place. It appears in the **Grow your store** column on every store.

## Reading the widget

A badge at the top gives your overall coverage — for example, **5/16 blocks added**. Below it, blocks are grouped by the surface they belong to, each with its own count:

| Group                    | Covers                                                         |
| ------------------------ | -------------------------------------------------------------- |
| **Post-purchase**        | The post-purchase funnels block                                |
| **Thank you page**       | Blocks on the Thank you page, including Product recommendation |
| **Order status page**    | Blocks on the Order status page                                |
| **Profile page**         | Blocks on the customer profile page                            |
| **Customer orders page** | Blocks on the customer orders page                             |
| **Rokt Thanks**          | Rokt Thanks placements                                         |
| **Checkout**             | Checkout blocks                                                |

Only the groups relevant to your store appear.

Each block within a group is marked **Added** or **Not added**. The post-purchase funnels block additionally reports **Active** or **Inactive**, since it can be present in your theme but switched off.

Groups that contain more blocks than fit show a **Show more** link to reveal the rest.

## Fixing a missing block

Each group has an action that takes you where you need to go — **Open editor** to jump into the Shopify theme editor for that surface, or **Open settings** for blocks configured inside Aftersell. The external-link icon opens the relevant page in your Shopify admin.

After adding a block in Shopify, use the refresh icon in the widget header to re-check. The status is read from your live theme, so it will not update on its own the moment you save in Shopify.

## Why the count rarely reads 16 of 16

A full count is not the goal. Most stores only run a few surfaces, so the blocks for the surfaces you do not use will correctly stay at **Not added**. Read the groups that matter to you rather than the headline number.


# Help and announcements
Source: https://docs.aftersell.com/aftersell/home/help-and-announcements

The bottom of the Stay in the loop column carries Aftersell feature announcements, occasional messages from the team, and the Help card linking to support, docs, and case studies.

The lower part of the **Stay in the loop** column carries anything Aftersell wants to tell you, plus the ways to get help.

## Feature announcements

When there is something new, an announcement card appears with a badge showing what kind of update it is:

* **Feature release** — something new you can now use
* **Feature update** — a change to something you already have

Each card explains the feature and offers an action to set it up. Dismiss it with the **X** if it is not relevant to you.

If several announcements are waiting, dismissing one moves the next into its place, so the card stays in a single slot rather than stacking up the column.

Dismissing an announcement only affects your own view — it does not change anything about your store, and it will not come back.

## Messages from the team

Occasionally Aftersell sends a direct message about your specific store, which appears in the same column above the announcements. These are not marketing — they are usually about your account or setup, so they are worth reading.

## Help

The **Help** card is always present at the bottom of the column:

| Link                | What it does                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------ |
| **Contact support** | Opens a support conversation, pre-filled so you do not have to explain where you came from |
| **Documentation**   | Opens this documentation site                                                              |
| **Case studies**    | Opens merchant case studies showing how other stores use Aftersell                         |


# Needs attention
Source: https://docs.aftersell.com/aftersell/home/needs-attention

The Needs attention panel flags problems that are costing you revenue right now, such as post-purchase offers being switched off or subscription upgrades failing.

**Needs attention** sits at the top of the **Stay in the loop** column and flags problems that need you to do something. It is the one widget worth checking every time you open Aftersell — most of what it reports is actively costing you revenue.

When there is nothing wrong you see a green tick and:

> All clear, nothing needs your attention

When there are items, the heading shows a count and each item is listed with a severity dot and an action link.

## What it flags

| Alert                                      | Severity | Action          |
| ------------------------------------------ | -------- | --------------- |
| **Post-purchase offers are turned off**    | Critical | Enable setting  |
| **App update required**                    | Critical | Update app      |
| **Shopify plan downgrade detected**        | Warning  | Go to billing   |
| **Timer removed from Thank You page**      | Warning  | Go to Funnels   |
| **Replacement upsells are paused**         | Warning  | Review failsafe |
| **Some subscription upgrades are failing** | Warning  | Review orders   |

Critical items mean a surface is not running at all. **Post-purchase offers are turned off** in particular means no post-purchase offer is being shown to any customer, so it is worth clearing immediately.

Warnings mean something is degraded rather than stopped — a safeguard has paused part of your setup, or a subset of orders is failing.

## Refreshing

Items are evaluated from your store's current state. After fixing something, use the refresh icon in the widget header to re-check rather than waiting for the page to update on its own.

## Related

* [Replacement upsells](/aftersell/replacement_upsells) — for the failsafe that pauses them
* [Subscription upgrades troubleshooting](/aftersell/subscription-upgrades-troubleshooting) — for failing upgrades
* [App block status](/aftersell/home/app-block-status) — for surfaces that are configured but not placed in your theme


# Home page overview
Source: https://docs.aftersell.com/aftersell/home/overview

The Aftersell home page: an analytics bar across the top, a Grow your store column, and a Stay in the loop column. Learn which widgets appear and when.

The home page is where you land when you open Aftersell. It gives you revenue across every surface your offers run on, the next thing worth doing, and anything that needs your attention.

## Layout

The page has three regions:

* **Analytics bar** — full width across the top, showing revenue per surface for a date range you choose.
* **Grow your store** — the left column, holding the widgets you act on.
* **Stay in the loop** — the right column, holding alerts, announcements, and help.

## What appears, and when

Not every widget shows on every store. Some depend on which Aftersell features you have, and one pair swaps depending on how far through setup you are.

| Widget                                                          | Column           | When it appears                                                 |
| --------------------------------------------------------------- | ---------------- | --------------------------------------------------------------- |
| [Analytics bar](/aftersell/home/analytics-bar)                  | Top              | Almost always. One tile per surface active on your store.       |
| [Setup guide](/aftersell/home/setup-guide)                      | Grow your store  | Until every step is complete, or you dismiss it.                |
| [Quick actions](/aftersell/home/quick-actions)                  | Grow your store  | Once the setup guide is complete or dismissed.                  |
| [Peer benchmarks (PPU)](/aftersell/home/peer-benchmarks)        | Grow your store  | Only if your plan includes post-purchase upsells.               |
| [App block status](/aftersell/home/app-block-status)            | Grow your store  | Always.                                                         |
| [Needs attention](/aftersell/home/needs-attention)              | Stay in the loop | Always. Shows an all-clear message when there is nothing to do. |
| [Feature announcements](/aftersell/home/help-and-announcements) | Stay in the loop | When there is an unread announcement.                           |
| [Help](/aftersell/home/help-and-announcements)                  | Stay in the loop | Always.                                                         |

## Setup guide and Quick actions share a slot

This is the one piece of behavior worth knowing up front, because it explains why your home page may not match a colleague's.

The **Setup guide** and **Quick actions** occupy the same position at the top of the **Grow your store** column, and **only one of them is ever shown**:

* While you still have setup steps outstanding, you see the **Setup guide**.
* Once you finish every step — or dismiss the guide — it is replaced by **Quick actions**.

So if you are looking for Quick actions and cannot find it, you most likely still have an incomplete setup step. Finish the guide, or dismiss it, and Quick actions takes its place.

## A note on empty states

A new store will see zeroes and empty states across most of the page — `$0.00` revenue tiles, no peer benchmarks, and few app blocks added. That is expected. These widgets fill in as your offers start running; none of them need to be switched on.


# Peer benchmarks (PPU)
Source: https://docs.aftersell.com/aftersell/home/peer-benchmarks

Peer benchmarks compares your post-purchase revenue per visit against stores with a similar average order value, so you can see where you stand.

**Peer benchmarks (PPU)** compares your post-purchase performance against a peer group of similar stores, so a number like revenue per visit has something to be measured against.

The widget appears in the **Grow your store** column on plans that include post-purchase upsells. If your plan does not include them, it is not shown.

## Your peer group

The sub-heading tells you which stores you are being compared against and over what period:

* **Compared to stores that share your AOV · Last 30 days**
* **Compared to stores that share your AOV and industry · Last 30 days** — shown when Aftersell can also match you on industry

Matching on industry as well as average order value makes for a tighter comparison, so the second form is the more precise of the two.

## Revenue per visit

The benchmark metric is **Revenue per visit (RPV)**:

> Revenue per visit (RPV) = total post-purchase revenue ÷ number of orders that reached the post-purchase page.

The widget shows your RPV alongside your peer group's median, and where you fall in the group's distribution.

## Before you have data

New stores, and stores that have not yet earned through post-purchase offers, see an empty state:

> Your benchmarks will appear here as your store starts earning with the app.

This is expected and needs no action. Your position is established over time as the app performs — a single day of data is not enough to place you against a peer group.

## Full report

**View full report** opens the complete post-purchase insights report, with the benchmark broken out in more detail. The button is disabled until you have benchmark data.


# Quick actions
Source: https://docs.aftersell.com/aftersell/home/quick-actions

Quick actions puts your most-used Aftersell tasks one click from the home page. Choose which actions appear and in what order.

**Quick actions** is a row of shortcut tiles at the top of the **Grow your store** column, putting your most common tasks one click away.

It appears once the [Setup guide](/aftersell/home/setup-guide) is complete or dismissed — the two share the same slot and never show at the same time. If you cannot find Quick actions, you most likely still have an outstanding setup step.

## Default actions

Three tiles are shown by default. Which three depends on what your store has access to:

| Your store        | Default actions                                                   |
| ----------------- | ----------------------------------------------------------------- |
| Checkout and Rokt | Create funnel · Create Checkout page · Manage Rokt placements     |
| Checkout only     | Create funnel · Create Checkout page · Create product page upsell |
| Rokt only         | Create funnel · Manage Rokt placements · View Rokt payouts        |
| Neither           | Create funnel · Create product page upsell · Add Strategy         |

If one of those defaults is not available to your store, it is replaced. Stores with Checkout fall back to **Create Checkout upsell** first — this is what stores on the earlier Checkout version see in place of **Create Checkout page**. Any remaining gap is filled with **Manage billing**, then **View Order browser**, so the row always starts with three tiles.

## Choosing your own actions

Select the pencil icon in the top-right corner of the widget to open the picker, then tick the actions you want and save. Your selection is saved per store.

The picker only lists actions your store can actually use, so the set you see may be shorter than the full list below.

You can select up to nine actions. If you select more, only the first nine appear on the home page.

## Available actions

| Action                         | Available when                                                 |
| ------------------------------ | -------------------------------------------------------------- |
| **Create funnel**              | Always                                                         |
| **Create Checkout page**       | You have Checkout, on the current Checkout version             |
| **Create Checkout upsell**     | You have Checkout                                              |
| **Create product page upsell** | Product page upsells are enabled                               |
| **Add Strategy**               | Strategies are enabled                                         |
| **Manage Rokt placements**     | Your store has a Rokt account                                  |
| **View Rokt payouts**          | Your store has a Rokt account                                  |
| **Customize Checkout**         | You have Checkout, on the current Checkout version             |
| **Customize branding**         | You have Checkout                                              |
| **View Order browser**         | Always                                                         |
| **Manage billing**             | Always                                                         |
| **View Earn & Save**           | Your store is eligible for [Earn & Save](/aftersell/earn-save) |

Note that **View Earn & Save** is never one of the defaults — if you want it on your home page, add it from the picker.


# Setup guide
Source: https://docs.aftersell.com/aftersell/home/setup-guide

The Setup guide on the Aftersell home page walks you through activating post-purchase upsells, your checkout page, and Rokt Thanks, and tracks your progress across each area.

The **Setup guide** sits at the top of the **Grow your store** column and walks you through activating each Aftersell surface. It tracks your progress automatically — steps complete themselves as you finish the underlying work, whether you did it from the guide or elsewhere in the app.

The guide is grouped into three areas. Each shows its own progress (for example, **2 of 3**) and expands to reveal its steps.

## Set up post-purchase upsells

| Step                                      | What it does                                                                                  |
| ----------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Enable Aftersell in Shopify settings**  | Select Aftersell as your post-purchase app in Shopify settings.                               |
| **Create and activate your first funnel** | Build a post-purchase funnel and set it live.                                                 |
| **Enable Smart Funnel**                   | Let Aftersell automatically show and optimize the best post-purchase offer for each customer. |

Once every step is done, this area is relabelled **Post-purchase upsells are live**.

The funnel step is marked complete as soon as **any** funnel is active on your store — you do not need to have walked through the guide's own flow for it to count.

## Set up checkout page

| Step                                             | What it does                                            |
| ------------------------------------------------ | ------------------------------------------------------- |
| **Create and activate your first checkout page** | Build a checkout page and set it live.                  |
| **Place app block in the Checkout editor**       | Drag the Aftersell app block into your checkout layout. |

Once complete, this area is relabelled **Checkout page is live**.

## Set up Rokt Thanks

| Step                                         | What it does                                                                  |
| -------------------------------------------- | ----------------------------------------------------------------------------- |
| **Enable Rokt Thanks**                       | Turn on Rokt Thanks for your store.                                           |
| **Place app block on your Thank you page**   | Add the Rokt Thanks app block to your Thank you page.                         |
| **Enroll in Earn & Save to lower your bill** | Shown only if your store is eligible for [Earn & Save](/aftersell/earn-save). |

Once complete, this area is relabelled **Rokt Thanks is earning**.

## Dismissing the guide

The **X** in the guide's header dismisses it, and the chevron next to it collapses it without dismissing.

Dismissal is not always permanent. If your Rokt setup is still incomplete when you dismiss, the guide is hidden for the current session only and returns the next time you open Aftersell. Once your Rokt area is complete, dismissing it sticks.

Either way, dismissing the guide brings up [Quick actions](/aftersell/home/quick-actions) in its place — the two never appear together.


# How do post-purchase upsells affect my fulfillment?
Source: https://docs.aftersell.com/aftersell/how_do_post_purchase_upsells_affect_my_fulfillment

Post-purchase upsell offers edit the original order and create a fulfillment hold of up to 60 minutes that clears when the customer responds.

Post-purchase upsell offers will edit the original order and not create a separate order. The post-purchase upsell offer will create a fulfillment hold for up to 60 minutes. The hold clears as soon as the customer accepts or declines all offers, or their offer timers run out. Closing the browser tab is the one case where it does **not** clear early — there is no signal that the customer left, so the order stays On Hold until the hold expires.

For detailed documentation on fulfillment, please [read this section on our docs here](/aftersell/fulfillment).


# How to configure fulfillment locations for post-purchase upsells
Source: https://docs.aftersell.com/aftersell/how_to_configure_fulfillment_locations_for_1_click_upsells

Adjust which location upsells are shipped from

Shopify follows a set of rules to determine which location an upsell order is shipped from.

Stores with two or more active locations should have access to [order routing](https://help.shopify.com/en/manual/fulfillment/setup/order-routing), which can be found in the Shopify admin under `Shipping & Delivery > Order Routing`. If you don't see this option, ensure you have at least two active locations. If you do, and the section is still missing, your store might be using the legacy Location Priority system, which is located under `Locations > Location Priority`.

Shopify applies these default rules, in priority order, for selecting a location for fulfillment as of the time of writing this article:

1. **Minimize split fulfillments** — keep the order in as few shipments as possible.
2. **Stay within the destination market** — prefer locations in the customer's market.
3. **Ship from the closest location** — prefer the location nearest the customer.

If desired, an additional rule can be added above these to prioritize specific locations.

<img alt="Shopify Order routing page listing the default location routing rules in priority order" />

Another rule for upsells is that they will only ship from locations designated to fulfill online orders. This setting can be adjusted for each location in the Locations tab.

***

## Customizing Inventory Locations (Advanced)

In Aftersell, you can select which inventory locations are used for post-purchase upsells.

Please note that this is an advanced setting, which requires assistance from our support team to enable.

* Once added by our support team, you can find these inventory settings by navigating to **Aftersell > Settings > Inventory.**

<img alt="Aftersell inventory location settings with online warehouses selected and a retail location excluded" />

This setting lets you specify which locations you'd like Aftersell to exclude from upselling. **By default, every location that fulfills online orders can be sold from.** Locations that are not set to fulfill online orders are always excluded from Aftersell's inventory check — they appear in a separate, greyed-out **Brick & Mortar (Excluded)** list and cannot be turned back on here.

**Important**: This setting only applies within Aftersell; however, Shopify ultimately determines the shipping location, and Aftersell cannot direct Shopify on which location to use.

For example, if you set Aftersell to exclude Warehouse A, it will only check inventory at Warehouses B and C when a customer is viewing an upsell offer. If inventory is available at either of those locations, Aftersell will present the offer. However, once the upsell is purchased, Shopify will decide on the shipping location based on the rules set in Order Routing. If location priorities are not aligned, Shopify may still ship from Warehouse A if it has stock, even though Aftersell excluded it for upsell offers.

To avoid this, ensure your Order Routing rules are properly configured to match your Aftersell inventory settings.

***

**Note:** Automatic Upsells use Shopify's Recommendation APIs, which don't allow filtering by inventory location. Aftersell checks stock by location afterward, but the initial recommendations from Shopify can't be limited to a specific location.\
You can read Shopify's documentation on this [here](https://shopify.dev/docs/storefronts/themes/product-merchandising/recommendations/related-products)

## Hiding variants that aren't published to your Online Store

**Settings → Inventory** also has an **Unpublished variants** section. Ticking **Hide unpublished variants from post-purchase offers** excludes any variant that isn't published to your Online Store sales channel — useful if you keep variants in stock for retail or wholesale but don't want them in web storefront upsells.

See [hiding unpublished variants](/aftersell/understanding_out_of_stock_variants#hiding-variants-that-arent-published-to-your-online-store) for how it behaves, including the permission it needs and its fail-open fallback.


# How to configure post-purchase triggers
Source: https://docs.aftersell.com/aftersell/how_to_configure_post_purchase_triggers

Step-by-step guide to setting up and configuring post-purchase funnel triggers in Aftersell

Triggers control when and to whom your post-purchase funnels display. This guide walks you through configuring the most common trigger types and managing funnel priority.

<Tip>
  For detailed information about what each trigger does, see the [Post-purchase Triggers reference](/aftersell/post_purchase_triggers).
</Tip>

***

## Getting started with triggers

When you create a new funnel, you'll need to configure at least one trigger to control when it displays. You can combine multiple triggers to create precise targeting rules.

### Where to find triggers

Triggers are configured inside each funnel, not from a global menu. To open them:

1. In the Aftersell admin, go to **Post-purchase Funnels**.
2. Click the funnel you want to edit (or click **Create Funnel** to start a new one).
3. In the funnel editor, open the **Triggers** section.
4. Click **Add Trigger** to add a new trigger, or click an existing trigger to edit it.
5. After making changes, click **Save Triggers**.

Each funnel has its own set of triggers — there are no shared or store-wide triggers.

### How triggers work together

Post-purchase triggers use two levels of logic: **AND between triggers** and **OR within triggers**.

**AND logic (between triggers)**

All enabled triggers must be met for the funnel to display. If you add multiple triggers, every one must return a match.

Example:

* Customer Location = US
* Order Value > \$50

The customer must be in the US **and** the order must exceed \$50.

**OR logic (within a trigger)**

Within a single trigger, only one selected option needs to match.

Example: Product Category = Shoes, Socks, or Pants. If the order contains any one of these, the trigger passes.

<Note>
  Some triggers (like Product Quantity) allow you to switch this to AND logic.
</Note>

For a detailed explanation of trigger logic, see [Understanding Conditional Logic](/aftersell/understanding_conditional_logic_for_post_purchase_triggers).

***

## Show for all customers trigger

A "Catch-All" funnel uses the **Show for All Customers** trigger. This funnel activates when an order does not meet the criteria for any other funnel. It serves as a safety net, ensuring no orders slip through without an upsell or Thank You page offer.

To use it effectively, set this funnel to the lowest priority so it only appears if no other funnel triggers.

**Example use cases:**

* You have three funnels: one for orders over \$100, one for specific products, and one with the Show for All Customers trigger. If a customer places an order that doesn't meet the first two funnels' criteria, the Show for All Customers funnel will activate as a fallback.
* You want to ensure every customer sees at least one offer. Create a funnel with the Show for All Customers trigger and set it to the lowest priority.

***

## Product-based triggers

These triggers activate based on the products, collections, or variants in a customer's cart.

<Note>
  Ensure proper configuration to prevent hidden or wholesale-only products from appearing unexpectedly in recommendations. This includes reviewing Shopify's Product Recommendation logic and restricting such products at the add-to-cart stage.
</Note>

<AccordionGroup>
  <Accordion title="Product/Collection trigger">
    Use the **Product/Collection** trigger to display your funnel when specific products or collections are purchased.

    **To configure:**

    1. In your funnel settings, click **Add Trigger**.
    2. Select **Product/Collection** from the trigger type dropdown.
    3. Choose **Contains** or **Does not contain**.
    4. Search for and select the products or collections you want to target.
    5. Click **Save**.

    **Example use cases:**

    * Show a protein powder upsell when customers purchase any product from your "Supplements" collection.
    * You have a funnel set to products X, Y, and Z. If a customer buys products A, B, and Y, this funnel will activate. If they buy A, B, and C, it will not.
  </Accordion>

  <Accordion title="Product Quantity trigger">
    Use the **Product Quantity** trigger to display an offer based on how many of a specific product are in the cart.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Product Quantity** from the trigger type dropdown.
    3. Choose **Less than**, **More than**, or **Exactly**.
    4. Enter the quantity threshold and select the product.
    5. Click **Save**.

    **Example use cases:**

    * Set to "less than 3" for Product X. If a customer buys 2 units, the funnel activates. If they buy 3 or more, it does not.
    * Set to "more than 1" for Product Y. If a customer buys 2 or more units, the funnel activates. If they buy only 1, it does not.
    * Set to "exactly 2" for Product Z. The funnel activates only when the customer buys precisely 2 units.
  </Accordion>

  <Accordion title="Product Tag trigger">
    Use the **Product Tag** trigger to display an offer when products with certain Shopify tags are included in the order.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Product Tag** from the trigger type dropdown.
    3. Choose **Include** or **Exclude**.
    4. Enter the product tag(s) you want to target.
    5. Click **Save**.

    **Example use cases:**

    * Exclude discontinued products from receiving upsell offers by setting the trigger to exclude products tagged "discontinued."
    * Show a special offer only for products tagged "summer-collection."
  </Accordion>

  <Accordion title="Product Type trigger">
    Use the **Product Type** trigger to display an offer when purchased products belong to a defined Shopify product type.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Product Type** from the trigger type dropdown.
    3. Choose **Include** or **Exclude**.
    4. Enter the product type(s) you want to target.
    5. Click **Save**.

    **Example use case:** If you set the trigger to "Shoes," any time a customer purchases a product of type Shoes, the funnel will display. If they purchase a t-shirt (type: Apparel), the funnel will not display.
  </Accordion>

  <Accordion title="Metafields trigger">
    Use the **Metafields** trigger to display funnels based on custom metafield data associated with products or variants. You can choose between product metafields or variant metafields, but only one type can be matched at a time.

    Each sub-trigger (Product or Variant) has a **Match type** dropdown:

    * **Value matches** — match a specific metafield name and value. Choose **Includes** or **Excludes**, then enter the name and value (both are case-sensitive).
    * **Has any value** — fires when the named metafield exists and has a non-empty value. Enter only the metafield name.
    * **Is empty** — fires when the named metafield is absent or empty. Enter only the metafield name.

    **To configure using Value matches:**

    1. Click **Add Trigger**.
    2. Select **Metafields** from the trigger type dropdown.
    3. Select **Value matches** from the **Match type** dropdown.
    4. Choose **Includes** or **Excludes**.
    5. Enter the metafield **name** and **value** exactly as they appear on the product page (both are case-sensitive).
    6. Click **Save**.

    **To configure using Has any value or Is empty:**

    1. Click **Add Trigger**.
    2. Select **Metafields** from the trigger type dropdown.
    3. Select **Has any value** or **Is empty** from the **Match type** dropdown.
    4. Enter the metafield name. You can use `namespace.key` (e.g. `custom.warehouse_location`), the bare key (e.g. `warehouse_location`), or the definition name (e.g. `Warehouse Location`).
    5. Click **Save**.

    **How Value matches works:**

    * **Includes** means there's an overlap between the metafields in the order and those in the trigger list. For example, if the order metafields are `["color: red", "size: m"]` and the trigger list is `["color: red", "ship: warehouse"]`, the condition is satisfied because `color: red` matches.
    * **Excludes** means there's no overlap between the metafields in the order and the trigger list. For example, if order metafields are `["color: red", "size: M"]` and the trigger list is `["color: blue", "size: L"]`, the condition is satisfied because there are no matching name:value pairs.

    **How Has any value and Is empty work:**

    These modes evaluate across all products in the order. **Has any value** fires when at least one purchased product has a non-empty value for the named metafield. **Is empty** fires when none of the purchased products have a non-empty value for it.

    <Note>
      Switching the Match type clears any entries already added to that sub-trigger, since `name: value` tags and bare-key tags mean different things per mode.
    </Note>

    This trigger is especially useful if you use metafields to store detailed product information like materials, sizing, or special attributes.
  </Accordion>

  <Accordion title="Product/Collection Exclusion trigger">
    Use the **Product/Collection Exclusion** trigger to prevent a funnel from displaying when excluded products or collections are present in the cart.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Product/Collection Exclusion** from the trigger type dropdown.
    3. Search for and select the products or collections to exclude.
    4. Click **Save**.

    **Example use case:** If a customer has purchased from a heavily discounted product or collection, you may prefer not to show further offers. You can also combine this trigger with the Product/Collection trigger to ensure only selected products activate the funnel while others are excluded.
  </Accordion>

  <Accordion title="Subscription trigger">
    Use the **Subscription** trigger to display an offer based on whether a subscription product is included in the order.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Subscription** from the trigger type dropdown.
    3. Choose **Contains** or **Does not contain** subscription products.
    4. Click **Save**.

    **Example use cases:**

    * Set to "Does not contain" subscription products to target one-time purchasers and offer them a subscription upsell.
    * Set to "Contains" subscription products to show complementary one-time products to subscribers.

    <Note>
      Shopify only supports one subscription product per order, so you cannot upsell a subscription if the original order already includes one.
    </Note>
  </Accordion>

  <Accordion title="Variant on subscription trigger">
    Use the **Variant on subscription** trigger to display a funnel when the order includes any of the selected products purchased as a subscription. Unlike the Subscription trigger, this trigger matches on a specific product being purchased on a subscription line item — a one-time purchase of the same product does not activate the funnel.

    **Managed by the subscription upgrade wizard**

    When a funnel has a subscription upgrade offer configured, this trigger is managed automatically by the wizard and kept in sync with the upgrade's source product. The trigger is read-only while the upgrade offer is present. It unlocks if the upgrade offer is removed.

    **Manual configuration (funnels without a subscription upgrade offer)**

    1. Click **Add Trigger**.
    2. Select **Variant on subscription** from the trigger type dropdown.
    3. Click **Select** to open the product picker (filtered to subscription products only).
    4. Choose the subscription product(s) you want to target.
    5. Click **Save**.

    **Example use cases:**

    * Show a subscription upgrade offer only to customers who subscribe to a specific product, without triggering for one-time purchases of the same product.
    * Target customers subscribing to any of several products by selecting multiple products in the trigger.

    <Note>
      If a funnel has a subscription upgrade offer, the Variant on subscription trigger is read-only and managed by the wizard. To edit it manually, remove the subscription upgrade offer first.
    </Note>
  </Accordion>

  <Accordion title="Variant Name trigger">
    Use the **Variant Name** trigger to display specific funnels based on the product variant selected by the customer at checkout (e.g., size, color, style).

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Variant Name** from the trigger type dropdown.
    3. Choose **Include** or **Exclude**.
    4. Enter the variant name(s) you want to target.
    5. Click **Save**.

    **Example use cases:**

    * Set to include "Large." If a customer purchases a t-shirt in size Large, the funnel activates. Size Small or Medium will not trigger it.
    * Set to include "Red" and "Blue." Either color variant will activate the funnel; Green will not.
  </Accordion>
</AccordionGroup>

***

## Cart & discount triggers

These triggers activate based on cart value, contents, or discounts applied.

<AccordionGroup>
  <Accordion title="Order Value trigger">
    Use the **Order Value** trigger to target customers based on their cart total.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Order Value** from the trigger type dropdown.
    3. Choose **Greater than** or **Less than**.
    4. Enter the dollar amount threshold.
    5. Click **Save**.

    **Example use cases:**

    * Show premium upsells to customers with orders over \$100.
    * Offer free shipping upgrades to customers with orders under \$50.
    * A funnel set to "less than \$50.00" will activate for a \$30.00 order but not a \$60.00 order.
  </Accordion>

  <Accordion title="Quantity trigger">
    Use the **Quantity** trigger to show an upsell offer based on the total item count in a customer's order. This trigger counts all items across every product in the cart, regardless of which specific products they are.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Quantity** from the trigger type dropdown.
    3. Choose **More than**, **Less than**, or **Exactly**.
    4. Enter the item count threshold.
    5. Click **Save**.

    **Example use cases:**

    * Set to "less than 3" - the upsell appears only when there are 1 or 2 total items in the cart.
    * Set to "more than 1" - the funnel triggers for orders with 2 or more total items.
    * Set to "exactly 3" - the funnel triggers only when there are exactly 3 total items in the cart.

    <Tip>
      If you need to trigger based on the quantity of a specific product rather than total cart item count, use the Product Quantity trigger instead.
    </Tip>
  </Accordion>

  <Accordion title="Discount Code trigger">
    Use the **Discount Code** trigger to include or exclude customers from seeing a funnel based on a discount code they applied. You can also exclude all orders that used any manually-entered discount code, without specifying individual codes.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Discount Code** from the trigger type dropdown.
    3. Choose one of the three options:
       * **Includes** — the funnel shows only when the order includes one of the specified codes.
       * **Excludes** — the funnel shows only when none of the specified codes were applied.
       * **Excludes any manual discount code** — the funnel shows only when no manually-entered discount code was used at checkout. Automatic and script discounts are ignored, so a site-wide automatic discount will not suppress the funnel.
    4. For **Includes** or **Excludes**, enter the discount code(s), pressing **Enter** after each one to save it. No codes are needed for **Excludes any manual discount code**.
    5. Click **Save**.

    **Example use cases:**

    * Show a funnel only to email subscribers by including their specific discount code.
    * Exclude all orders that used any manually-entered discount code to prevent upsell offers from showing to customers who already received a discount.

    <Note>
      Be sure to press **Enter** after entering a discount code to save it in the funnel.
    </Note>
  </Accordion>

  <Accordion title="Discount Percent (%) trigger">
    Use the **Discount Percent** trigger to display a funnel based on the line-item discount percentage applied to the order (this excludes shipping discounts).

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Discount Percent (%)** from the trigger type dropdown.
    3. Choose **More than**, **Less than**, or **Exactly**.
    4. Enter the discount percentage threshold.
    5. Click **Save**.

    **Example use cases:**

    * Set to "more than 20%." A customer with a 25% discount will see the funnel; one with 15% or no discount will not.
    * Set to "less than 10%." A customer with a 5% discount will see the funnel; one with 15% will not.
    * Set to "exactly 10%." The funnel only activates for orders with precisely a 10% discount applied.
  </Accordion>
</AccordionGroup>

***

## Customer attribute triggers

These triggers use customer data to control funnel visibility.

<AccordionGroup>
  <Accordion title="Customer Tag trigger">
    Use the **Customer Tag** trigger to include or exclude customers from seeing a funnel based on their associated Shopify customer tags.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Customer Tag** from the trigger type dropdown.
    3. Choose **Include** or **Exclude**.
    4. Enter the customer tag(s) you want to target.
    5. Click **Save**.

    **Example use cases:**

    * Set to include "VIP." Only customers with the VIP tag will see the funnel.
    * Set to exclude "Wholesale." Wholesale customers won't see retail upsells.
  </Accordion>

  <Accordion title="Customer Order History trigger">
    Use the **Customer Order History** trigger to create offers based on a customer's past purchases of specific products.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Customer Order History** from the trigger type dropdown.
    3. Search for and select the specific products to check for in past orders.
    4. Click **Save**.

    <Warning>
      You must select specific products or collections when using this trigger. The default match mode is **Include**, and if you leave products/collections unselected while using **Include**, the trigger can never be satisfied — this permanently blocks the funnel from firing. Always select at least one product or collection. If your goal is simply to check whether a customer has ordered before, use the Customer Order Count trigger instead.
    </Warning>

    <Note>
      This trigger reviews only past orders, not the current order. By default, it only looks back over the past 60 days of order history; checking further back requires additional permissions — reach out to support if you need a longer lookback window.
    </Note>
  </Accordion>

  <Accordion title="Customer Order Count trigger">
    Use the **Customer Order Count** trigger to display a funnel specifically for new or returning customers based on how many orders they've previously placed.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Customer Order Count** from the trigger type dropdown.
    3. Choose **Equal to**, **Greater than**, or **Less than**.
    4. Enter the order count threshold.
    5. Click **Save**.

    **Example use cases:**

    * Set to "equal to 0" to target first-time customers only.
    * Set to "greater than 3" to target loyal customers who have placed 4 or more previous orders.
    * More than 0 orders = returning customer; 0 orders = new customer.

    <Note>
      This trigger is based on past purchases, not the current order.
    </Note>
  </Accordion>

  <Accordion title="Customer Language trigger">
    Use the **Customer Language** trigger to tailor offers based on the customer's preferred language. If your store serves customers in more than one language, you can create a separate funnel for each one and display the right offer based on the language the customer checked out in.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Customer Language** from the trigger type dropdown.
    3. Select the language you want to target.
    4. Click **Save**.

       <img alt="Aftersell funnel triggers with the Customer language trigger enabled and a Select language dropdown" />

    **Setting up a multi-language funnel**

    Start by creating a funnel for your first language, then duplicate it for each additional language. Rename each funnel so it's easy to identify, update its Customer Language trigger to match, and manually translate all available text fields, including the product title, description, timer, and any custom text widgets.

    **Current limitations**

    Some elements are controlled globally through the **Translations** section in Aftersell's **Settings**, meaning they can only be set to one language at a time. Changing these will affect all funnels regardless of language.

    <img alt="Aftersell Translations page with global 1-Click upsell text fields like Free, Shipping, and Taxes" />

    The Shopify controlled header at the top of the post-purchase page will automatically display in the customer's checkout language. This includes text like "You've paid for your order." and cannot be customized through Aftersell.

    <img alt="Shopify post-purchase header reading You've paid for your order with a View order confirmation link" />
  </Accordion>

  <Accordion title="Once per Customer trigger">
    Use the **Once per Customer** trigger to ensure a funnel only shows once per customer across all of their orders.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Once per Customer** from the trigger type dropdown.
    3. Click **Save**.

    **Example use cases:**

    * A customer who sees this funnel after their first purchase will not see it again on any future purchases, even if all other trigger conditions are met.
    * Use it to show a special "welcome offer" exclusively on a customer's first purchase.
  </Accordion>
</AccordionGroup>

***

## Order details & time-based triggers

These triggers depend on checkout details, marketing data, or timing.

<AccordionGroup>
  <Accordion title="UTM Parameter trigger">
    Use **UTM Parameter** triggers to display specific funnels based on marketing campaign parameters in the URL.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **UTM Parameter** from the trigger type dropdown.
    3. Choose the UTM parameter type (source, medium, campaign, term, content, or id).
    4. Enter the exact value to match.
    5. Click **Save**.

    **Example use cases:**

    * Set to "utm\_source = facebook." Customers arriving via a Facebook link will see the funnel; others will not.
    * Set to "utm\_campaign = summer\_sale" to show campaign-specific offers to customers from that campaign.
    * Show exclusive offers to customers arriving from your email campaign by targeting `utm_source=email`.

    For advanced UTM tracking setup, see [How to use Direct-to-Checkout UTM Links](/aftersell/how_to_use_direct_to_checkout_utm_links).

    <Warning>
      UTM triggers do not fire when customers use express checkout methods (Shop Pay, Apple Pay, Google Pay, PayPal, etc.) because express checkout bypasses the standard cart flow where UTM parameters are captured. If you're using UTM triggers for campaign tracking, consider using other trigger types (product, collection, order value) as alternatives, or creating separate funnels for general traffic that don't rely on UTM parameters.
    </Warning>
  </Accordion>

  <Accordion title="Currency trigger">
    Use the **Currency** trigger to control whether customers see a funnel based on the currency they use at checkout.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Currency** from the trigger type dropdown.
    3. Choose **Include** or **Exclude**.
    4. Select the currency or currencies you want to target.
    5. Click **Save**.

    **Example use cases:**

    * Set to "USD." Customers checking out in US Dollars will see the funnel; those in EUR, GBP, or others will not.
    * Set to "CAD" and "USD." Customers in either currency will see the funnel.

    **Important notes:**

    * Thank You Page offers automatically adjust to the customer's checkout currency, making a single funnel viable across markets.
    * Post-purchase upsells do not support multi-currency. Customers will not see upsell offers unless your store currency matches their checkout currency. Use Thank You Page offers for universal visibility.
    * If your store uses **Shopify Markets**, Aftersell integrates seamlessly to display products in the correct local currency.
  </Accordion>

  <Accordion title="Device Type trigger">
    Use the **Device Type** trigger to scope a funnel to customers on a specific device — Desktop only or Mobile only.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Device Type** from the trigger type dropdown.
    3. Choose **Desktop only** or **Mobile only**.
    4. Click **Save**.

    **Example use cases:**

    * Set to **Desktop only** to show an offer that works best on larger screens, such as a detailed product comparison or multi-image layout.
    * Set to **Mobile only** to target customers browsing on their phone with a mobile-optimized offer.
    * Combine with other triggers (e.g., Order Value) to show a desktop-only offer to high-value customers.

    <Note>
      If a customer's device type cannot be detected, the trigger fails closed and the funnel will not display. This matches the behavior of other triggers when required data is unavailable.
    </Note>
  </Accordion>

  <Accordion title="Shipping Country trigger">
    Use the **Shipping Country** trigger to include or exclude customers based on their shipping destination.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Shipping Country** from the trigger type dropdown.
    3. Choose **Include** or **Exclude**.
    4. Select the countries you want to target.
    5. Click **Save**.

    **Example use cases:**

    * Exclude international shipping for products only available domestically.
    * Show region-specific products to customers in certain countries.
    * Create country-specific Thank You Page offers (since Post-purchase upsells don't display for non-default currencies).
  </Accordion>

  <Accordion title="Random Sample trigger">
    Use the **Random Sample** trigger to control funnel visibility for a random subset of customers. This is ideal for A/B testing new funnels or surprising a select group with special offers.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Random Sample** from the trigger type dropdown.
    3. Enter the percentage of customers who should see the funnel.
    4. Click **Save**.

    **Example use cases:**

    * Set to "25%." The funnel randomly activates for approximately 25% of qualifying customers.
    * For A/B testing, create two funnels each with a Random Sample trigger set to "50%." Each funnel will show to roughly half your customers.
  </Accordion>

  <Accordion title="Date/Time trigger">
    Use the **Date/Time** trigger to schedule funnel visibility based on specific dates and times, ideal for time-sensitive promotions, seasonal campaigns, or limited-time deals.

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Date/Time** from the trigger type dropdown.
    3. Use the date picker to select your start date, end date, or both.
    4. Use the timezone dropdown to select the timezone your schedule should follow (for example, "GMT-07:00 - (MST) America/Phoenix").
    5. Click **Save**.

    **Example use cases:**

    * Set to activate "between December 1 and December 25" for a holiday promotion.
    * Set to activate "after January 1, 2026" to launch a new year promotion.
    * Set a start and end date in your store's local timezone to run a weekend flash sale from Friday 12:00 AM to Sunday 11:59 PM.

    <Note>
      The timezone you select determines when the trigger starts and stops. Choose the timezone that matches your store's primary market or promotion schedule.
    </Note>
  </Accordion>

  <Accordion title="Shipping Method trigger">
    Use the **Shipping Method** trigger to control funnel visibility based on the customer's chosen shipping option at checkout (e.g., standard, expedited, international, pickup).

    **To configure:**

    1. Click **Add Trigger**.
    2. Select **Shipping Method** from the trigger type dropdown.
    3. Choose **Include** or **Exclude**.
    4. Select the shipping method(s) you want to target.
    5. Click **Save**.

    **Example use cases:**

    * Show an expedited delivery upgrade upsell only to customers who selected standard shipping.
    * Exclude "Local Pickup" customers from seeing shipping protection or delivery-related upsells.
    * Target customers who chose international shipping with a customs-friendly product bundle.

    <Note>
      Matching is case-insensitive and checks whether your Shopify shipping rate name *contains* the text you enter in the trigger — it doesn't need to be an exact, full match. For example, a trigger value of "express" will match shipping rate names like "Express Shipping" or "2-Day Express."
    </Note>
  </Accordion>
</AccordionGroup>

***

## Managing funnel priority

When you have multiple funnels, priority determines which funnel displays when multiple funnels' triggers are met.

**How funnel priority works:**

* Funnels are evaluated in priority order: Priority 1 → Priority 2 → Priority 3, etc.
* The first funnel whose triggers are all met will display.
* Lower priority funnels are only checked if higher priority funnels don't match.
* Smart Funnel (if enabled) is evaluated at Priority 0, before all manual funnels.

### Viewing funnel priority

You can see each funnel's current priority number on the left side of the funnel table in the **Post-purchase Funnels** section.

### Reordering funnels

1. Go to **Post-purchase Funnels** in the Aftersell admin.
2. Click the **Manage Priority** button at the top right of the funnel table.
3. Drag and drop funnels to reorder them.
4. Click **Save** to apply the new priority order.

<img alt="Post Purchase Funnels list showing priority numbers beside each funnel with a Manage priority button" />

**Best practices for funnel priority:**

* **Place specific funnels first** - Put funnels with narrow targeting (specific products, high-value orders) at higher priority.
* **Place broad funnels last** - Put funnels with general targeting (collections, low order values) at lower priority.
* **Set Catch-All funnel to lowest priority** - If you have a "Show for All Customers" funnel, make it the last priority so it only displays when no other funnel matches.
* **Test your priority order** - Place test orders to verify the correct funnel displays for different scenarios.

**Example priority structure:**

* Priority 1: High-value orders (\$200+) with specific product
* Priority 2: Orders containing products from premium collection
* Priority 3: Orders with any product from main category
* Priority 4: Catch-All funnel (Show for All Customers)

***

## Combining multiple triggers

You can add multiple triggers to a single funnel to create precise targeting rules. Remember: all triggers must be met for the funnel to display.

### Example: targeting high-value supplement customers

Add these triggers to the same funnel:

* **Product/Collection trigger:** Contains products from "Supplements" collection
* **Order Value trigger:** Greater than \$75
* **Customer Order Count trigger:** More than 0 orders (returning customers only)

This funnel will only display to returning customers who purchase supplements and have a cart value over \$75.

### Example: targeting customers who haven't purchased specific upgrades

This is useful when you sell products with optional upgrades and want to show different upsells depending on what the customer has and hasn't already purchased.

**Scenario:** You sell a base product with two optional upgrades - "Premium Rotor" and "Water Resistance."

**Funnel 1 - Customer bought neither upgrade (highest priority)**

* No product exclusions needed
* Set to **highest priority** so it is evaluated first
* This funnel shows both upgrades as upsell options

**Funnel 2 - Customer bought Premium Rotor but not Water Resistance**

* Add a **Product/Collection trigger** set to **Contains** "Premium Rotor"
* Add a **Product/Collection Exclusion trigger** set to exclude "Water Resistance"
* This funnel shows only the Water Resistance upsell

**Funnel 3 - Customer bought Water Resistance but not Premium Rotor**

* Add a **Product/Collection trigger** set to **Contains** "Water Resistance"
* Add a **Product/Collection Exclusion trigger** set to exclude "Premium Rotor"
* This funnel shows only the Premium Rotor upsell

<Warning>
  Funnel priority is critical here. If Funnel 1 is not set to the highest priority, Aftersell may match a single-upgrade funnel first for customers who bought neither upgrade, resulting in only one upsell being shown instead of both.
</Warning>

***

## Next steps

* Learn about all available trigger types in the [Post-purchase Triggers reference](/aftersell/post_purchase_triggers)
* Understand how triggers work together with [Understanding Conditional Logic](/aftersell/understanding_conditional_logic_for_post_purchase_triggers)
* Set up your first funnel with the [Quickstart Guide](/aftersell/quickstart_guide_to_aftersell)
* Review [Best Practices](/aftersell/best_practices) for optimizing your funnel strategy


# How to create a multi-step post-purchase upsell
Source: https://docs.aftersell.com/aftersell/how_to_create_a_multi_step_post_purchase_upsell

This article covers how to display more than two post-purchase upsell pages to customers.

Due to [Shopify post-purchase API limitations](https://shopify.dev/docs/apps/build/checkout/product-offers#limitations-and-considerations), a customer can accept up to two post-purchase upsells. Additionally, customers can only select one product per upsell step due to platform restrictions. However, with Aftersell's multi-step setting, you can display more than two upsell pages to the customer. Multi-step offers split up each page into multiple steps, allowing customers to potentially select products across different steps.

[Analytics](#analytics)

[Best practices](#best-practices)

[Design](#design)

[Steps to set up a multi-step post-purchase upsell](#steps-to-set-up-a-multi-step-post-purchase-upsell)

# Steps to set up a multi-step post-purchase upsell:

* Create a **Multi Product** upsell
* Click *Edit offer > Upsell products > Enable multi-step upsell*
* Click *Add step*

Drag and drop a product to the new step

<img alt="Aftersell Edit upsell products panel with the Enable multi-step upsell checkbox and product list" />

# Accepting or declining a step

A customer begins on the first step of a page. If they decline, they move to the next step. If they decline the final step, they are taken to the next page. If they accept a step, they are directed to the next page where they can consider additional offers. This sequential approach allows customers to potentially accept products across different upsell pages.

<img alt="Diagram of two customer flows moving through upsell steps via accept and decline paths to Upsell 2 or Downsell" />

***

# Analytics

You can use product-specific analytics to measure the performance of multi-step post-purchase upsells. These can be found under Top performing products on the Aftersell analytics page or in the Product breakdown for an A/B test.

An impression for a product in a multi-step upsell is only tracked once that product is shown. For example, if a Green Shirt is in Step 3 but the customer accepts Step 2 and never sees Step 3 then there will be no impression tracked for the Green Shirt.

The overall page (e.g., Upsell #1) will track exactly 1 impression even if there are multiple steps.

***

# Design

## How to add custom text on each step:

To show different text for each step, you can use the step text variables. These variables provide text that can be used in other widgets that will automatically update when the step changes.

1. Click *Step 1 > ... > Show text* and write "`` `{first-name}` ``, grab this deal in the next `` `{timer}` `` minutes!" in *Variable `` `{step-header-A}` ``*
2. Repeat for Step 2 and write "No worries, how about this one instead? (`` `{timer}` ``)"
3. In the Timer widget, replace the text with "`` `{step-header-A}` ``". This will automatically show the text from the current step in the timer and change when the customer goes to the next step.

## Steps with only one product each:

To create nice-looking steps with only one product each, you can enable *Edit offer > Upsell products > Layout settings > Spotlight first product*. We recommend also enabling the price breakdown, product reviews, and adding custom text for each product.

# Best practices

* Any page, including Upsell #1, Upsell #2, or Downsell, can utilize multi-step sequences. You can also combine different formats, such as having a multi-step Upsell #1 and a single-step Upsell #2. However, multi-step functionality is only available for Multi-Product upsells and is not supported for Single Product upsells.
* We recommend keeping the number of steps minimal to provide a smooth customer experience.
* While Aftersell does not limit the number of steps you can create, there is a cap of 12 products per page. This allows flexibility, such as creating a page with up to 12 steps, each featuring one product, or 4 steps with 3 products each, and so on.- Consider using sequential offer displays to guide customers through a logical progression of complementary products.
* Customize your flow design to optimize customer engagement based on your specific product relationships.

# Frequently asked questions

## Do customers need to decline one offer to see the next?

When using multi-step upsells, customers who decline an offer will automatically move to the next step in the sequence. If they accept an offer, they will move to the next upsell page in your sequence.

## Can customers select more than one product in a single step?

No, due to platform restrictions, only one product can be selected per upsell step. This is why the multi-step feature is valuable, it enables customers to potentially select multiple products through a sequential approach.


# How to use direct-to-checkout UTM links
Source: https://docs.aftersell.com/aftersell/how_to_use_direct_to_checkout_utm_links

Learn how to trigger post-purchase funnels using UTM parameters, including setup for direct-to-checkout links

Aftersell supports triggering funnels based on UTM parameters, which is an optional feature specifically intended for advanced use cases. You can configure your funnel to activate when a customer visits your site with a specific UTM query string.

This setup is optional and typically required only for advanced tracking needs, such as direct-to-checkout links or campaign-specific offers.

## How UTM triggers work

UTM triggers allow you to show specific post-purchase funnels based on UTM parameters in the URL. This is useful for:

* **Campaign-specific offers** - Show different upsells based on the marketing campaign
* **Direct-to-checkout links** - Trigger funnels when customers skip the storefront
* **Channel attribution** - Personalize offers based on traffic source (email, social media, ads)
* **A/B testing** - Test different offers for different campaign variations

## Quick start: Basic UTM trigger setup

For standard storefront visits (not direct-to-checkout), you can set up UTM triggers using the Aftersell app embed. To see how to quickly get started with UTM triggers, check out this video:

<iframe title="How to set up UTM Triggers" />

### Enable the UTM app embed

To track UTM parameters on storefront pages:

1. In your Shopify admin, go to **Online Store > Themes**
2. Click **Customize** on your active theme
3. In the theme editor, click the **App embeds** icon (puzzle piece) in the left sidebar
4. Find **Aftersell UTM Tracker** and toggle it **on**
5. Click **Save**

Once enabled, Aftersell will automatically capture UTM parameters when customers visit your storefront with UTM links.

### Configure UTM triggers in your funnel

After enabling the app embed:

1. Go to **Post-purchase Funnels** in the Aftersell admin
2. Create or edit a funnel
3. In the **Triggers** section, add a **UTM Parameter** trigger
4. Configure the UTM parameter and value you want to match
5. Save your funnel

## Supported UTM parameters

Aftersell supports the following standard UTM parameters:

* `utm_source` - Identifies the traffic source (e.g., google, newsletter, facebook)
* `utm_medium` - Identifies the marketing medium (e.g., email, cpc, social)
* `utm_campaign` - Identifies the specific campaign (e.g., spring\_sale, product\_launch)
* `utm_term` - Identifies paid search keywords (e.g., running+shoes)
* `utm_content` - Differentiates similar content or links (e.g., banner\_ad, text\_link)
* `utm_id` - Identifies the campaign ID (e.g., campaign\_123)

All six parameters are tracked and can be used to trigger funnels.

## Partial field matching

When configuring UTM triggers, Aftersell supports **partial matching** for UTM parameter values. This means:

* ✅ **Trigger value:** `spring` → **Matches:** `spring_sale`, `spring_2026`, `early_spring`
* ✅ **Trigger value:** `email` → **Matches:** `email_newsletter`, `promotional_email`
* ✅ **Trigger value:** `sale` → **Matches:** `spring_sale`, `flash_sale`, `sale_2026`

This flexibility allows you to create broader triggers that match multiple campaign variations without creating separate triggers for each one.

**Example:** If you set a trigger for `utm_campaign` contains `sale`, it will match any campaign with "sale" in the name, such as `spring_sale`, `summer_sale`, or `flash_sale_2026`.

## Direct-to-checkout UTM links

The basic setup shown in the video above does **not** support links that send customers **directly to checkout**. By default, Aftersell can only detect UTM parameters on storefront pages. This is because it relies on a theme app embed, which works only on storefront pages and not on the checkout or thank-you page.

### Enable UTM tracking on checkout pages

To track UTM parameters on the checkout page (for direct-to-checkout links), you need to **add a Shopify Pixel** to your store.

⚠️ **Important limitations:**

* This setup requires the visitor to have a **cart token** when they arrive at checkout through a UTM link. Without a cart token, the UTM data will not be captured.
* **Express checkout methods (Shop Pay, Apple Pay, Google Pay) are not supported** because they bypass the cart and do not generate a cart token. Customers using express checkout will not trigger UTM-based funnels.

### Setting up the Shopify pixel

Follow these step-by-step instructions to set up direct-to-checkout UTM tracking:

1. In your Shopify admin, go to **Settings > Customer Events**.
2. Click **Add Custom Pixel** and give it any name you like.
3. Under the **Permission** dropdown, select **Analytics**. This is the only permission required.
4. For the **Data Sale** dropdown, you can choose **Data collected does not qualify as data sale**. Aftersell keeps all collected data private and never shares it with anyone other than you.
5. In the code editor that appears, paste in the code provided below.
6. Click **Save**, then **Connect**.

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
/**  
 * IMPORTANT: This pixel can only fire on sessions where the  
 * customer has a cart object, otherwise it will be skipped.  
 * For example, clicking "Buy Now" on a product page skips the cart,  
 * going directly to checkout.  
**/  
function processData({event, cartToken}) {  
  // TODO: Edit MYSHOPIFY_DOMAIN to your domain. E.g.  
  // const MYSHOPIFY_DOMAIN = 'example-store.myshopify.com';  
  const MYSHOPIFY_DOMAIN = '';  
  
  const enableDebug = false;  
  
  // DO NOT EDIT PAST HERE  
  const SESSION_STORAGE_KEY = 'as-customer-trigger-data';  
  const HOST = 'https://start.aftersell.app';  
  
  if (!MYSHOPIFY_DOMAIN) {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because of missing Shopify domain");  
    }  
    return;  
  }  
  if (!cartToken) {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because of missing cart token");  
    }  
  }  
    
  let existingCustomerData = null;  
  try {  
      existingCustomerData = JSON.parse(  
          sessionStorage.getItem(SESSION_STORAGE_KEY) || 'null'  
      );  
  } catch (ignore) {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because malformed user data json");  
    }  
  }  
    
  const allowedUrlParams = [  
        'utm_source',  
        'utm_medium',  
        'utm_campaign',  
        'utm_term',  
        'utm_id',  
        'utm_content',  
    ];  
    
  const searchParams = new URLSearchParams(event.context.window.location.search);  
  let hasCustomerData = false;  
  const customerData = {};  
  for (const param of allowedUrlParams) {  
    const paramValue = searchParams.get(param) || existingCustomerData?.[param];  
    if (paramValue) {  
        hasCustomerData = true;  
        customerData[param] = paramValue;  
    }  
  }  
  
  if (hasCustomerData) {  
    sessionStorage.setItem(SESSION_STORAGE_KEY, JSON.stringify(customerData));  
  
    const postBody = {  
      shop: MYSHOPIFY_DOMAIN,  
      cartToken,  
      checkoutToken: event.data.checkout.token ?? undefined,  
      customerTriggerData: customerData,  
    };  
  
    if (enableDebug) {  
      console.log("UTM pixel fired with the following data:", postBody);  
    }  
      
    fetch(`\${HOST}/api/v1/storefrontSessions`, {  
        method: 'POST',  
        headers: {  
            'Content-Type': 'application/json',  
        },  
        body: JSON.stringify(postBody),  
    });  
  } else {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because there was no data to send");  
    }  
  }  
}  
  
analytics.subscribe('checkout_started', (event) => {  
   // minimum realistic time between adding item to cart and clicking checkout  
    const COOKIE_POLLING_INTERVAL_MS = 500;  
  
    let currentCookieValue = getCookieValue({ cookie: document.cookie, cookieName: 'cart' });  
    processData({event, cartToken: currentCookieValue});  
  
    setInterval(() => {  
        const newCookieValue = getCookieValue({ cookie: document.cookie, cookieName: 'cart' });  
        if (newCookieValue !== currentCookieValue) {  
            currentCookieValue = newCookieValue;  
            processData({event, cartToken: newCookieValue});  
        }  
    }, COOKIE_POLLING_INTERVAL_MS);  
});  
  
function getCookieValue({ cookie, cookieName }) {  
    const cartCookieRegex = new RegExp(`^\${cookieName}=`);  
    const cartCookie = cookie  
        .split(';')  
        .map((val) => val.trim())  
        .find((val) => cartCookieRegex.test(val));  
    if (!cartCookie) return null;  
    const cartCookieValue = cartCookie.replace(`\${cookieName}=`, '');  
    return cartCookieValue;  
}
```

**Important configuration notes:**

* **Edit `MYSHOPIFY_DOMAIN`:** You must replace the empty string with your store's myshopify.com domain (e.g., `'example-store.myshopify.com'`)
* **Enable debug mode (optional):** Set `enableDebug = true` to see console logs for troubleshooting
* **Supported parameters:** The pixel tracks all six standard UTM parameters listed in the `allowedUrlParams` array

## Testing your UTM trigger setup

After setting up UTM triggers, use this checklist to verify everything is working correctly:

### For storefront UTM tracking (app embed)

* ✅ **App embed enabled:** Verify the Aftersell UTM Tracker app embed is toggled on in your theme settings
* ✅ **Test URL:** Visit your store with a UTM parameter (e.g., `yourstore.com?utm_campaign=test`)
* ✅ **Complete purchase:** Add a product to cart and complete checkout
* ✅ **Check funnel:** Verify the correct funnel appears on the thank-you page
* ✅ **Order browser:** Check the Aftersell Order Browser to confirm the UTM trigger was detected

### For direct-to-checkout UTM tracking (Shopify pixel)

* ✅ **Pixel installed:** Verify the custom pixel is saved and connected in Settings > Customer Events
* ✅ **Domain configured:** Confirm `MYSHOPIFY_DOMAIN` is set correctly in the pixel code
* ✅ **Cart token present:** Ensure the customer has items in cart before going to checkout (required for tracking)
* ✅ **Test URL:** Use a direct-to-checkout link with UTM parameters (e.g., `yourstore.com/checkout?utm_campaign=test`)
* ✅ **Complete purchase:** Complete the checkout process
* ✅ **Check funnel:** Verify the correct funnel appears on the thank-you page
* ✅ **Order browser:** Check the Aftersell Order Browser to confirm the UTM trigger was detected
* ⚠️ **Express checkout:** Remember that Shop Pay, Apple Pay, and Google Pay will NOT work with UTM triggers

### Troubleshooting tips

If UTM triggers are not working:

1. **Enable debug mode:** Set `enableDebug = true` in the pixel code and check browser console for error messages
2. **Verify cart token:** Ensure customers have items in cart before reaching checkout (pixel requires cart token)
3. **Check trigger configuration:** Verify the UTM parameter and value in your funnel trigger match the URL parameters
4. **Test partial matching:** Remember that triggers use partial matching - `sale` will match `spring_sale`, `flash_sale`, etc.
5. **Check funnel priority:** If multiple funnels match, only the highest priority funnel will show
6. **Review Order Browser:** Use the Aftersell Order Browser to see which triggers fired for each order

## Best practices for UTM triggers

* **Use consistent naming:** Establish a naming convention for your UTM parameters (e.g., `utm_campaign=email_spring_2026`)
* **Leverage partial matching:** Use broader trigger values to match multiple campaign variations
* **Test before launching:** Always test your UTM links and triggers before sending to customers
* **Document your campaigns:** Keep a record of which UTM parameters you're using for each campaign
* **Combine with other triggers:** Use UTM triggers alongside product or order value triggers for more precise targeting
* **Monitor performance:** Regularly check the Order Browser to see which UTM campaigns are driving the most upsells


# Installing Aftersell
Source: https://docs.aftersell.com/aftersell/installing_aftersell

How to install Aftersell on your Shopify store

**This guide will walk you through the process of installing Aftersell on your Shopify store. It is a quick and easy process, and only takes 2 minutes!**

## Step 1: Shopify App Store

Navigate to the Shopify App Store. Use the search bar at the top to search for "Aftersell." Look for Aftersell in the search results and click on it.

<img alt="Shopify App Store search results with AfterSell Post Purchase Upsell highlighted" />

[Aftersell on Shopify App Store](https://apps.shopify.com/aftersell)

## Step 2: Install Aftersell

On the Aftersell app page, click the "Install" button. You will be redirected to a page where you can review the permissions the app requires.

<img alt="AfterSell app listing page with an arrow pointing to the Install button" />

## Step 3: Configure Aftersell

After successful installation, you will be redirected to the Aftersell dashboard. Follow the on-screen prompts to complete the initial setup and configure Aftersell according to your preferences.


# Post-purchase multivariate testing
Source: https://docs.aftersell.com/aftersell/multivariate_testing

Learn how to set up and analyze multivariate tests for your post-purchase offers in Aftersell

# Post-purchase multivariate testing

Multivariate testing lets you test multiple offer variables at once - like discounts, timers, shipping, and quantity - to find the best-performing combination. You define the variables and select the options you want to test, and Aftersell combines them into all possible layout combinations for testing.

It's one of the most powerful ways to optimize your post-purchase upsell strategy.

<Note>
  In multivariate testing, you define individual variables and their options, and Aftersell combines them into all possible layout combinations for testing. If you want to configure complete layouts individually and test them against each other (up to 5 layouts), use [Post-Purchase A/B Testing](/aftersell/post_purchase_a_b_testing) instead.
</Note>

<Note>
  Multivariate testing is only available for post-purchase upsells. Multivariate testing for Thank You page offers is not currently available. For checkout widget testing, see [Checkout A/B Testing](/aftersell/checkout_a_b_testing).
</Note>

***

## 1. Define your goal

Before setting up your multivariate test, take a moment to define what success looks like for your store. Setting a clear objective helps you choose the right variables to test and measure what truly matters. Some popular goals include:

* Increasing conversion rates on upsell offers
* Boosting average order value (AOV)
* Identifying the most effective product or incentive

<Tip>
  Need inspiration? Check out our [Best Practices](/aftersell/best_practices) article for ideas that drive real results.
</Tip>

## 2. Create your test pages

In addition to your variables, a multivariate test lets you add up to 5 offer pages (your base offer plus up to 4 more), each of which can have its own product, layout, or content. Variables you configure in the next step apply across all pages and override matching settings on individual pages.

## 3. Choose the variables to test

Choose from four available variables that could affect buyer behavior:

* **Discounts:** Percentage vs. fixed dollar vs. no discount
* **Timer:** Different countdown durations, e.g. 5 min vs. 15 min
* **Shipping:** Free vs. flat-rate
* **Quantity:** Different default quantities

<Tip>
  Too many variables means harder analysis. Keep it focused.
</Tip>

## 4. Create your variations

Set up options for each variable. For example:

* **Discounts:** 10%, 20%, 30%
* **Timer:** 5, 10, or 15 minutes
* **Shipping:** Free vs. flat-rate

Aftersell combines your pages and selected variable options into all possible layout combinations for testing. The total number of layouts is your number of pages multiplied by the number of options for each active variable — for example, 2 pages with a 3-option discount variable and a 2-option timer variable produce 2 × 3 × 2 = 12 layouts.

## 5. Set up your multivariate test

1. Open the **Aftersell Dashboard**
2. Go to **Post-Purchase Funnels**
3. Create a new funnel or open an existing one
4. Click **Create test** and select **Multivariate Test**
5. Add your pages and select your desired variables and options
6. Click **Start test**

Each combination is automatically labeled as **Layout A**, **Layout B**, and so on for easy reference in your analytics.

<Note>
  Be sure to press Enter after typing in each variable to save it properly.
</Note>

### How traffic is split

Traffic is automatically distributed evenly across all layouts generated by the test. There is no way to manually adjust the traffic percentage for each layout. For example, if your pages and variable combinations produce 4 layouts, each layout will receive approximately 25% of traffic.

There is no option to set custom percentages (for example, you cannot set Layout A to 80% and Layout B to 20%).

***

## 6. Review the results

Once your test has been running for a sufficient amount of time, ideally 2-4 weeks, you'll have enough data to make informed decisions. Shorter test durations may not yield statistically reliable insights, especially if traffic is low.

To view your results, go to the **Tests** tab in your Aftersell Analytics dashboard.

For a complete breakdown of all Tests tab metrics, including group-level analytics, Performance by Variable, the All Groups table, and how to select a test, see [Post-Purchase Analytics](/aftersell/analytics_in_aftersell).

<Tip>
  Your test will show the impressions needed to be statistically viable, helping you know when the data is ready to act on. Look for consistent performance across multiple metrics, not just a spike in one area.
</Tip>

## 7. Apply the winning variation

Once a winner emerges:

1. Apply that variation across your funnel
2. Monitor performance to ensure it continues delivering strong results
3. Consider testing again with a new set of variables

***

## Limitations

### Multivariate testing is within a single funnel only

Multivariate testing runs within the same funnel. You cannot run a multivariate test across multiple funnels.

### Multivariate testing is for post-purchase (one-click) upsells only

Multivariate testing is not currently available for Thank You page offers. It is only supported for post-purchase upsell funnels.

### Custom traffic percentages are not supported

Traffic is always split evenly across all layouts generated by the test. There is no option to assign custom percentages to individual layouts.

***

## Multivariate test vs. A/B test

Not sure which testing method to use?

|                          | **Multivariate Test**                                                                                                            | **A/B Test**                                                                            |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| How it works             | You define individual variables and their options, and Aftersell combines them into all possible layout combinations for testing | You manually configure each layout as a complete offer and test them against each other |
| Layouts                  | Based on your selected variable combinations (Layout A, B, C, etc.)                                                              | Up to 5 layouts (Layout A through E), each manually configured                          |
| Best for                 | Finding the best combination of individual variables (discount, timer, shipping, quantity)                                       | Comparing complete offer designs against each other                                     |
| Traffic split            | Evenly across all combinations                                                                                                   | Evenly across all layouts                                                               |
| Statistical significance | Requires more traffic due to more combinations                                                                                   | Faster to reach with fewer layouts                                                      |
| Results                  | More complex - identifies best combination of variables                                                                          | Easier to interpret - one layout wins                                                   |

**Use Multivariate Testing when:**

* You want to test multiple variables simultaneously and find the best combination
* You have high traffic levels
* You want to define variables and have Aftersell combine them into layout combinations for testing

[**Use A/B Testing when:**](/aftersell/post_purchase_a_b_testing)

* You want to compare complete offer configurations
* You have moderate traffic levels
* You want clear, straightforward results

***

## Best practices

* **Start simple:** Don't overload with too many variables
* **Be patient:** Let tests run long enough to collect data (minimum 2-4 weeks)
* **Keep testing:** Use winners to inspire your next round of tests

***

## Need help?

If you have questions about setting up or analyzing your multivariate tests, chat with our support team using the live chat at the bottom right of the app.


# Post-purchase upsells vs. thank you page upsells
Source: https://docs.aftersell.com/aftersell/one_click_upsells_vs_thank_you_page_upsells

This article outlines the key differences between post-purchase and Thank You page upsells.

Comparison:

|                                                                                   | **Post-Purchase** | **Thank You Page** |
| :-------------------------------------------------------------------------------- | :---------------: | :----------------: |
| Subject to [Shopify limitations](/aftersell/why_isnt_my_1_click_offer_displaying) |         ✅         |          ❌         |
| Adds to original order                                                            |         ✅         |    Configurable    |
| Doesn't require re-entering payment                                               |         ✅         |          ❌         |

## Here's a rundown of how these work:

To make the most of Aftersell's potential, understanding the functional and strategic differences between these upsell options is imperative.

## **Post-purchase upsells**

* Display **immediately after Checkout** but **before the Thank You Page**.
* Your customer's **payment information is already saved**, allowing them to **accept the offer with just one click**.
  * This makes it easy to convert, helping you **generate extra revenue effortlessly**.
* The upsell is **combined with the original order**, which means **no additional shipping costs** or fulfillment steps for your team.- This bundling ensures **reduced shipping costs** and facilitates easier order tracking for your team.

## Can a customer see both?

Yes. If a funnel contains both a post-purchase offer and a Thank You Page widget, a single customer who uses a supported payment method (such as credit card or Shop Pay) will see **both**: the post-purchase offer first, then the Thank You Page offer after. This is intentional—every customer is shown at least one offer, and shoppers on unsupported payment methods (such as Apple Pay, Google Pay, or other wallets) only see the Thank You Page offer because Shopify skips the post-purchase step for those payments. See [Payment methods](/aftersell/payment_methods) and [Why isn't my 1-click offer displaying?](/aftersell/why_isnt_my_1_click_offer_displaying).

There is no built-in setting to suppress the Thank You Page widget based on payment method. If you want to avoid showing two offers to supported-payment customers, configure your funnel with **only** a post-purchase offer or **only** a Thank You Page widget rather than both.

## **Thank You Page Upsells**

* Appear on the **Thank You Page**, which displays after the post-purchase page. This page may also be referred to as the **Order Status** or **Order Confirmation** page.
* Payment information is not saved at this point, since checkout has already been completed. Customers must re-enter their payment details and complete checkout again to accept the offer.

Thank You Page upsells can be configured in one of two ways:

* **Modify original order** - the upsell is combined with the initial purchase into a single order.
* **Create new draft order** - the upsell generates a second order that is distinct from the original.

When configured as a new draft order, if the customer abandons the second checkout, the upsell order remains in **Draft** status.

Additional limitations to consider:

* Shopify restricts Thank You Page upsells to **one product per upsell offer**, and all products must be visible across the entire site.
* Because the checkout phase has ended, customization options for Thank You Pages remain limited, requiring thorough planning.
* Shopify restrictions mean products used in Thank You Page upsells must always be visible sitewide.
* Aftersell provides settings to automatically hide already-purchased products to enhance customer alignment and avoid redundancy.


# Partially paid orders
Source: https://docs.aftersell.com/aftersell/partially_paid_orders

What causes partially paid orders when a post-purchase upsell payment fails, how to identify them in Shopify admin, and how to resolve them.

# What causes a Partially paid order?

In some cases, when your customer attempts to accept a post-purchase upsell they might receive a **payment declined** message. The payment could fail for a number of reasons, the most likely causes of payment failure are insufficient funds on the card or if the payment processor denies the transaction. If the payment for a post-purchase upsell item fails, Shopify will still add the upsell item to the order. This results in a **Partially paid order** where the initial items are paid for, but the payment for the upsell item was not processed.

### **🔖 If you are seeing a high number of Partially paid orders**

A high number of **Partially paid orders** indicates that there is likely an issue with the payment capture process. Do any of the following apply to you?

* Your store's **Payment capture** setting is set to **Manual**, or
* You use a fraud detection app such as **NoFraud** or **Riskified**, or
* You use a **Shopify Flow** to capture payment or send emails about high-risk orders

If any of the above points apply to you, read more about how to deal with payment capture for post-purchase upsells [here](/aftersell/payment_capture).

If none of the above points apply to you, continue reading to learn how to deal with partially paid orders.

## **What do you see in Shopify Admin for Partially paid orders?**

In your Shopify admin, a **Partially paid order** can be identified by the order payment status of **Partially paid** as shown in the image below.

<img alt="Shopify orders list showing one order marked Partially paid and another marked Paid" />

**Partially paid orders** will also show a failed payment processing attempt in the order timeline.

<img alt="Order timeline showing a failed payment attempt below the AfterSell order edit entry" />

## **What does a customer see for Partially paid orders?**

### **"Payment needed" banner on order confirmation page**

If a customer accepts a post-purchase upsell and the payment is declined, your customer will be redirected to the order confirmation page. On the order confirmation page, the customer will see a message notifying them that the product was added to the order, but payment is still required. The message will prompt the customer to pay for the outstanding amount.

<img alt="Order confirmation page with a payment needed banner and Pay now button" />

### **Invoice email after 2 hours**

If payment for the upsell item is still outstanding after 2 hours, Shopify will send an **invoice email**. If payment for the additional item has already been received, or the item has been removed from the order, this email will not be sent. For more details on resolving **Partially paid orders**, continue reading below.

<img alt="Shopify invoice email in the inbox requesting payment of the outstanding amount" />

<img alt="Shopify invoice page showing the amount due, Pay now button, and order summary" />

***

# **Resolving and fulfilling a Partially paid order**

### **🚧 A partially paid order should not be fulfilled until the issue is resolved**

You may lose money if a post-purchase upsell item is fulfilled without processing payment for the item. Please ensure that you are resolving **Partially paid order** issues using the steps below to avoid accidentally shipping unpaid items.

## **Resolving Partially paid orders**

A **Partially paid order** can be resolved in one of two ways:

1. **Collecting payment for the unpaid product.** This is the preferred case. If possible, we want the customer to pay for the additional product using a different card or payment method. This relies on the customer clicking on the message on the order status page. It is not guaranteed that the customer will go through the payment process again for the additional product. Please read the next option below to handle any orders where the customer does not pay for the additional item.
2. **Remove the unpaid item from the order.** If the customer does not choose to pay for the additional item, then we still want to be able to fulfill the original order. To ensure that the unpaid additional item doesn't get fulfilled without payment, we want to remove the item from the order. **Aftersell has a built-in setting that automates this process of removing items for you, and it is turned on by default.** To check it or change the delay:

* Navigate to **Settings > Fulfillment and Payment > Partially Paid**
* Confirm *"Automatically remove unpaid 1-click and thank you page upsell products from orders"* is on — it is enabled by default on every store, including stores that predate the setting. This automatically removes unpaid upsell items from **Partially paid orders** after the specified delay if the payment is not collected. Choose a delay from the dropdown: ASAP (under 3 minutes), 10, 15, 30, 45, or 65 minutes, 1.5, 2.5, 3, 6, 12, or 24 hours. Selecting a longer delay will give your customers a longer period to hopefully pay for the additional item. Selecting a shorter delay will allow you to fulfill orders more quickly, but may result in fewer customers paying for the additional item.

<img alt="Enabling automatic removal of unpaid upsell items in Aftersell fulfillment settings" />

## **Fulfillment considerations with Partially paid orders**

**Benefits of automating unpaid item removal** By using Aftersell's automatic removal feature for unpaid upsell items, you can:

* Avoid mistakenly shipping unpaid items, reducing potential revenue loss
* Ensure that only fully paid orders proceed to fulfillment, avoiding unnecessary delays
* Save time and manual effort involved in tracking and removing unpaid items

This automation streamlines your order management process, letting you focus more on growing your business.

We do not want to accidentally fulfill unpaid upsell items in **Partially paid orders**. Because there are many different ways to handle fulfillment, the best way to ensure that **Partially paid orders** are handled properly in fulfillment is to **test on your store**, or on a sandbox/development store.

### **Testing Partially paid orders**

To test a **Partially paid order**, we need to simulate a failed payment on the post-purchase page. To simulate a failed payment, we can take advantage of a Shopify limitation: *Shopify fails to process transactions under \$0.50 (USD or CAD)*. You can set up a test funnel on Aftersell and discount a product so that the total price (after tax and shipping) is under \$0.50 as shown in the image below. The item must be at least \$0.01, it cannot be free. Accepting a post-purchase upsell for less than \$0.50 will result in a partially paid order.

<img alt="Post-purchase upsell offer with a product discounted to ten cents for testing" />

### **Solutions to potential fulfillment problems with Partially paid orders**

If you have tested a **Partially paid order** and are having problems with fulfillment, the safest solution is to ensure that orders are not imported into your fulfillment service until the order hold has been released and the order is fully paid. For details on customizing fulfillment workflows, see the [Fulfillment article](/aftersell/fulfillment).


# Payment capture
Source: https://docs.aftersell.com/aftersell/payment_capture

How to avoid missing payments on your post-purchase upsell orders 

***

## Payment Capture

If your store is using Manual Payment Capture, you may be seeing some orders in a partially paid status. This article will show you how to resolve this issue while retaining your Manual Payment Capture settings.

***

## Why This Happens

If your store is using a fraud detection app (e.g. **NoFraud** or **Riskified**), the fraud detection app might not natively support post-purchase upsells. In these cases it will often capture payment for the order too early, before the post-purchase upsell is added. The post-purchase upsell payment will be authorized, but only the initial payment would be captured. Such an order would be shown as **Partially paid**.

Additionally, the timing of the fraud app's payment capture can interfere with Aftersell's item cleanup logic. If the fraud app captures the original payment **after** the upsell authorization fails, Aftersell may not remove the unpaid upsell item from the order as expected. This can result in customers receiving free product.

***

## How to Fix It

First, you'll need to confirm that you're currently on Manual Payment Capture. If you aren't, then unfortunately the rest of this article won't apply to you.

### Confirm Your Payment Capture Settings

Your store may have an automatic payment capture system set up, yet still have the Shopify Manual Payment Capture setting enabled. You can confirm your store's payment capture settings:

**Shopify Admin > Settings > Payments > Payment Capture Method**

<Frame>
  <img alt="Shopify Payments settings showing the payment capture method option" />
</Frame>

If you're currently on Manual Payment Capture, continue reading!

### Creating a Shopify Flow

The simplest solution to ensure that all payments for an order are captured is to use a **Shopify Flow**. Below is an image of a Shopify Flow that achieves this:

<Frame>
  <img alt="Shopify Flow with an order transaction trigger, conditions, and capture payment action" />
</Frame>

### Explaining the Flow

This flow has 3 steps:

1. **A Trigger** is put in place to ensure you only start the flow when an order transaction has been created. The first transaction for an order is created when the customer places the order. An additional transaction is created if the customer accepts the Aftersell post-purchase upsell. Our goal is to capture payment on the second transaction, so we will check some conditions in the next step.
2. **Conditions** are put in place to ensure the flow only continues in certain scenarios. We only want this flow to continue if the transaction that was created is from a post-purchase upsell. We also don't want to run this flow if payment for the original order hasn't been captured yet. This flow is only supposed to capture additional payment that was missed. If there hasn't been any payment captured yet, then we will do nothing in this flow and assume that the regular payment capturing system will capture the full amount.
3. **Capture payment** once all of your checks have passed. This will capture the payment only for the extra amount from the post-purchase upsell. Problem solved!

After implementing the flow above, if you are using external fulfillment services please ensure that the payment capture Flow doesn't have unintended effects on your fulfillment. For more details on fulfillment, please see our [Fulfillment Documentation](/aftersell/fulfillment).

***

## Post-Purchase Upsell Payment Capture Not Working

\<Note>

This section applies if you are experiencing a **recent spike** in Partially paid orders specifically on post-purchase upsells, even if you do not use a fraud detection app.

\</Note>

### What Changed

Shopify updated their built-in automation template **"Capture payment if order is not high fraud risk"** around **March 31, 2026**. This update changed how Shopify evaluates fraud risk on order edits, which broke the automatic payment capture for post-purchase upsells.

Previously, Shopify would re-run fraud analysis when an order was edited (such as when a post-purchase upsell item was added). This risk-level change would re-trigger the payment capture template flow, capturing the upsell payment. Shopify no longer re-runs fraud analysis on order edits, so the template flow does not re-trigger and the upsell payment is not captured.

This issue affects stores **with or without** a fraud detection app.

### Symptoms

You may be experiencing this issue if:

* You have noticed a sudden spike in **Partially paid** orders on post-purchase upsells
* Only orders where a customer accepted a post-purchase upsell are showing as Partially paid
* Payment for the original order is captured, but the upsell payment is **authorized and not captured**
* You did not change anything in your store settings around the time the issue started

### How to Fix It

<Tip>
  **Use the Aftersell Flow template for a one-click setup.** Aftersell publishes a pre-built Flow template called **"Capture payment when a post-purchase upsell is accepted"** in Shopify's Flow template library. You can install it directly from the Flow app without building the workflow manually. Search for it in the Flow template library under the **Orders** category.
</Tip>

If you prefer to build the flow manually, create a new **Shopify Flow** with the following configuration:

1. **Trigger:** "Aftersell Post Purchase Offer Accepted" - This fires when a customer accepts an Aftersell post-purchase upsell offer and the item is successfully added to the order.
2. **Condition:** "Order capturable is equal to True" - This ensures the flow only attempts to capture payment when the order is in a state where capture is possible.
3. **Action:** "Capture payment" - If the condition is true, the flow captures the outstanding payment for the upsell amount.

<Frame>
  <img alt="Shopify Flow with Aftersell offer accepted trigger, capturable condition, and capture payment action" />
</Frame>

\<Warning>

**Do not add a presentment money amount condition.** Some stores have experienced issues where Shopify incorrectly returns the presentment money amount as 0, even when there is an outstanding balance. Adding a condition like "presentment money amount is greater than 0" can cause the flow to skip payment capture on valid orders. This can result in customers receiving invoice emails instead of having their payment captured automatically. Keep the flow simple: trigger, capturable check, capture payment.

\</Warning>

\<Info>

Your existing Shopify automation for capturing payment on the original order can stay as-is. This new flow runs alongside it and only handles the post-purchase upsell payment.

\</Info>

### After Setting Up the Flow

* **Test the flow** on a development or sandbox store before enabling it in production.
* **Monitor your orders** for a few days after enabling the flow to confirm payments are being captured as expected and no invoice emails are being sent to customers.
* **Check your fulfillment workflow.** If you use external fulfillment services, make sure this payment capture flow does not trigger fulfillment before you are ready. For more details, see our [Fulfillment Documentation](/aftersell/fulfillment).
* **Review your order hold settings.** If you have had orders ship without completed payment, confirm your order hold settings are configured to prevent fulfillment until payment is fully captured.

***

## Summary

| Situation                                                                                                                         | Cause                                                                                                                                                              | Fix                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| Sudden spike in Partially paid orders on post-purchase upsells (with or without a fraud app)                                      | Shopify updated the "Capture payment if order is not high fraud risk" automation template around March 31, 2026, changing how fraud analysis is run on order edits | Create the "Aftersell Post Purchase Offer Accepted" Shopify Flow                                  |
| Fraud detection app (e.g. Riskified, NoFraud) captures payment too early, or customers receiving free product from failed upsells | Fraud app captures original payment before upsell is added, or interferes with item cleanup timing                                                                 | Create the "Order transaction created" Shopify Flow from the manual capture section above         |
| Customers are receiving invoice emails after accepting a post-purchase upsell                                                     | The Shopify Flow may include a presentment money condition that Shopify is returning incorrect data for                                                            | Remove the presentment money condition from the flow (keep only the "Order capturable" condition) |
| You are not on Manual Payment Capture                                                                                             | Different issue - this article does not apply                                                                                                                      | See [Partially Paid Orders](/aftersell/partially_paid_orders) for other causes                    |

***

## Frequently Asked Questions

### I don't use a fraud app. Why are my post-purchase upsell payments not being captured?

Shopify updated their built-in "Capture payment if order is not high fraud risk" automation template around March 31, 2026. Previously, Shopify would re-run fraud analysis when an order was edited (like when a post-purchase upsell was added), which re-triggered the payment capture flow. Shopify no longer does this, so the upsell payment is not captured. Creating the "Aftersell Post Purchase Offer Accepted" Shopify Flow described above will resolve this issue.

### Will the new flow capture the full order amount or just the upsell amount?

The flow only captures the outstanding upsell amount. It does not re-capture or double-capture the original order payment.

### What happens if the order is not capturable when the flow runs?

The flow checks the "Order capturable" condition first. If the order is already capturable it captures straight away.

If it is not, the Aftersell template does not give up immediately: it waits **60 seconds**, checks `Order capturable` a second time, and captures if the order has become capturable in the meantime. Only if it is still not capturable does the run end, with the message **"Order did not become capturable in time"** — no capture is attempted too early either way.

A hand-built flow with only the single condition stops at the first check instead of retrying.

### I already have a Shopify automation for capturing payment. Do I need to change it?

No. Your existing Shopify automation (such as "Capture payment if order is not high fraud risk") can stay as-is. The new Shopify Flow runs alongside it and specifically handles the post-purchase upsell payment gap.

### My customers are receiving invoice emails after accepting a post-purchase upsell. What is happening?

This can happen if the Shopify Flow includes a presentment money amount condition. Shopify sometimes returns the presentment money amount as 0 even when there is an outstanding balance. When this happens, the flow skips payment capture, and Shopify sends an invoice email to the customer instead. The fix is to remove the presentment money condition from the flow and keep only the "Order capturable" check.

### I use Riskified / NoFraud and my customers are getting free product from upsells. What is happening?

When a customer accepts a post-purchase upsell but the upsell payment authorization fails, Aftersell should remove the unpaid item from the order after a set amount of time (configured in Aftersell > Settings > Fulfillment and Payment > Partially Paid). However, if your fraud app captures the original payment at a specific point in the sequence, it can interfere with Aftersell's cleanup logic, causing the unpaid item to stay on the order and get fulfilled for free. The Shopify Flow fix above will help by ensuring payment is captured promptly. You should also review your Partially Paid auto-removal settings and your order hold settings to prevent fulfillment before payment is confirmed.

### Is Aftersell involved in payment capture?

No. Aftersell is not involved in payment authorization or capture. Aftersell tells Shopify to add the upsell product to the order via Shopify's post-purchase API. Shopify handles the rest of the payment process. The Shopify Flows described in this article are the recommended way to ensure payment is captured.

### Where can I learn more about Partially paid orders?

See our [Partially Paid Orders](/aftersell/partially_paid_orders) article for details on what causes Partially paid orders and how to resolve them.


# Payment methods
Source: https://docs.aftersell.com/aftersell/payment_methods

This article will cover the payment methods supported for post-purchase offers.

Post-purchase upsells may not display due to **limitations in Shopify's Post-Purchase Extensions API**. For more information, you can refer to [Shopify's documentation](https://shopify.dev/docs/apps/checkout/product-offers/post-purchase#limitations-and-considerations) on these limitations. While post-purchase upsells are a powerful way to increase AOV, their availability depends largely on the **payment method used at checkout** and a few other Shopify-enforced conditions.

The most common reason post-purchase upsells don't appear is the use of an **unsupported payment method**. In the funnel editor, open the **Triggers** step and hover the info icon beside the **Triggers** heading for a quick summary of which payment methods skip post-purchase offers.

***

## **Supported Payment Methods**

Post-purchase upsells will display as long as the order meets [Shopify's requirements](/aftersell/why_isnt_my_1_click_offer_displaying) and uses a supported payment method. Here's the full list of these **supported payment methods:**

* **Shopify payments** (for Credit Cards)
* **Shop Pay**
* **PayPal Express** (with Automatic Payments enabled, PayPal knows them as Reference Transactions)
  * See the [PayPal Automatic Payments article](/aftersell/paypal_automatic_payments) for more information on how to check this.
  * **NOTE:** Shopify automatically sends a request for Automatic Billing/Reference Transaction Approval on your behalf when you install Aftersell. It usually gets accepted within a few days but we recommend checking its status until approved.\
    If you've been declined, you'll need to reach out to PayPal Support directly and ask them about your Reference Transaction Application being denied.
  * There's a known PayPal limitation affecting post-purchase offers. PayPal Express only supports one upsell after checkout due to how it processes additional charges. As a result, only the first upsell or downsell will appear, and any further offers will be skipped. This is a PayPal system restriction that Shopify and Aftersell cannot override. Impressions for Upsell #2 and beyond should still appear when using other supported payment methods.

We're aware that some PayPal versions are currently not working with post-purchase offers. Our team is investigating the issue. We also recommend contacting Shopify Support for any questions related to this PayPal issue.

* **Braintree** (without CVV verification enabled)
* **Authorize.net**
  * **Note:** *Replacement* *Upsells* are an exception, and are not supported by Authorize.net. This is because the settlement process necessary to enable transaction refunds happens once a day, making the refund of an item that was just purchased infeasible.
* **Stripe**
  * **Note:** Newer versions of stripe are no longer supported by Shopify's Post-Purchase API. Ensure compatibility by using officially supported versions of Stripe or other direct credit card processors fully embedded in Shopify's checkout workflow.
  * It is also important to note that newer versions of Stripe are no longer supported by Shopify's Post-Purchase API. Merchants should ensure compatibility by using officially supported Stripe versions or other fully embedded direct credit card processors within Shopify's checkout workflow.
* **Adyen** (credit card payments processed through Shopify's checkout)
* **Pin Payments**
* Any other **direct credit card payment processor** that is embedded within Shopify's checkout.

***

## **Unsupported Payment Methods**

The following payment methods are currently **unsupported for post-purchase upsells:**

#### **Buy Now, Pay Later / Installments**

* Affirm, Afterpay (Clearpay), Klarna, Sezzle, Zip, Splitit, Laybuy, Scalapay, Shop Pay Installments, etc.

#### **Digital Wallets**

* Apple Pay, Google Pay, Amazon Pay, PayPal Wallet

#### **PayPal Billing Agreement**

* Orders paid via PayPal Billing Agreement skip post-purchase offers.

#### **Bank Transfers**

* iDEAL, Bancontact, PayPlus, etc.

#### **Regional / Alternative Payment Gateways**

* Mollie, Checkout.com, Worldpay, and similar gateways that are not embedded directly into Shopify's checkout as a supported credit card processor.
* If your store's primary gateway isn't listed in the **Supported Payment Methods** section above, assume it is **not** supported by Shopify's Post-Purchase Extensions API and use Thank You Page offers instead.

#### **Providers That Retain CVV/CVN**

* PayPal Payments Pro, Payflow Pro, and Eway. Shopify's Post-Purchase Extensions API does not support third-party payment providers that require the customer's CVN/CVV to be retained. (Braintree works only with CVV verification disabled — see the Supported Payment Methods list above.)

#### **Other**

* Gift cards — **any** gift card payment on the order disqualifies it, whether the gift card covers the whole total or only part of it
* Cash on Delivery
* Shopify store credit

These limitations apply to **all post-purchase apps**, as required by Shopify's API.

***

## Additional Shopify Requirements

Additionally, orders must meet the following conditions to support post-purchase upsells:

* The order value must be at least \$0.50
* The order must be placed on the Online Store sales channel, a supported headless/custom sales channel, or through a draft-order payment link.
* The order must be completed in the store's default currency.
* Duties and landed costs must not be included.
* The order must have a shipping destination country — Shopify needs one to render the post-purchase page.
* The order must not be for local delivery or local pickup.

***

## **What If Most Of My Orders Use Unsupported Payment Methods?**

If your customers frequently uses BNPL, wallets, or bank transfers, we recommend using **Thank You Page offers** instead.

Thank You Page upsells:

* Work with **all payment methods**
* Do not rely on Shopify's Post-Purchase API
* Appear on the Thank You / Order Status page

Here's how you can set them up:

1. **Access Your Funnel Settings**
   * Open your Aftersell account.
   * Navigate to the final step of your funnel and select `Edit Extensions Page`. This allows you to configure and add Thank You Page widgets or product recommendations.
2. **Open the Shopify Editor**
   * In the Aftersell dashboard, locate the blue banner and click `Open Shopify Editor` to add Aftersell widgets.
3. **Add Widgets to Shopify**
   * In the Shopify Editor, add the Aftersell widgets to the following locations:
     * Thank You Page
     * Order Status Page
   * Ensure that the widgets display upsell offers or product recommendations.
4. **Save and Test**
   * After completing the configuration, save changes and simulate an order using an unsupported payment method to confirm the Thank You Page upsell is displayed.

## Benefits of Thank You Page Upsells

* **Universal Compatibility:** Thank You Page upsells work with all payment methods, bypassing Shopify's API limitations.
* **Simplified Checkout Process:** Offers appear on the order status page, providing a seamless post-purchase experience without altering the payment mechanism.
* **Customizable Recommendations:** You can highlight relevant product recommendations, enhancing the likelihood of additional purchases.

***

# Troubleshooting Payment Method Issues

If your funnels or upsell offers are not triggering as expected, consider these steps:

1. **Verify Payment Method Compatibility:** Ensure the customer used a supported payment method listed above.
2. **Check Store Configuration:** Confirm conditions like default currency, sales channel, order minimum value, and absence of duties or landed costs are met.
3. **Review Documentation:** Consult our [documentation](/aftersell/why_isnt_my_1_click_offer_displaying) for updates and guidelines. Additionally, Thank You Page offers are compatible with all payment methods, making them a versatile option for orders placed with unsupported payment methods, such as Buy Now Pay Later services or digital wallets.
4. **Check Widget Placement:** Ensure the widgets are correctly placed on the Thank You Page and Order Status Page through the Shopify Editor.
5. **Activate Thank You Page Settings:** Verify that your Thank You Page setup is activated in Aftersell to avoid default redirection to the product page.


# PayPal automatic payments
Source: https://docs.aftersell.com/aftersell/paypal_automatic_payments

How PayPal Reference Transactions work and how to check your approval status for post-purchase upsells

Reference Transactions allow applications to charge customers without requiring them to re-enter their payment details, making them essential for post-purchase upsells to display to PayPal customers. When you first install Aftersell, an approval request is automatically sent to PayPal on your behalf.

**Checking your approval status**

1. Go to your Shopify admin and click **Settings** in the bottom left
2. Click **Payments** in the left column
3. Find your PayPal payment method and click **Manage** in the top right
4. Check the **Automatic Payments** line for your current status

**What does my status mean?**

**Approved:** PayPal customers will be able to see your post-purchase upsells, assuming all other Shopify requirements are met.

**Pending:** PayPal hasn't reviewed your application yet. Check back daily until the status changes.

**Declined:** PayPal has denied access to Reference Transactions for your account. This is outside of Aftersell and Shopify's control. Contact PayPal support directly and ask them why your account was not approved for reference transactions, then follow their recommendations to appeal the decision.

**My status shows "Approved" but PayPal customers still aren't seeing upsells**

Shopify can occasionally display an incorrect approval status. If eligible customers still aren't seeing upsells despite an approved status, contact PayPal support directly and ask them to confirm whether your account is approved for reference transactions. If they confirm approval, take a screenshot of that confirmation and reach out to our support team for further assistance.


# Post-purchase offer types
Source: https://docs.aftersell.com/aftersell/post-purchase-offer-types

The offer structures and product-selection methods available for Aftersell post-purchase offers, including Most Expensive and Least Expensive in Cart.

Every post-purchase offer is built from two choices: the **offer structure** (how many products the offer shows) and the **product-selection method** (how Aftersell decides which product to put in the offer). This page covers the options available for each so you can pick the right combination for your funnel.

<Note>
  Only **one product per offer** can be accepted at a time, unless you use [multi-step offers](/aftersell/how_to_create_a_multi_step_post_purchase_upsell). Post-purchase offers **add** to the customer's order; they do not replace items already purchased (except [Replacement Upsells](/aftersell/replacement_upsells)).
</Note>

***

## Offer structures

When you create an offer, you first choose how many products it presents.

* **Single Product** — Shows one product to the customer. Best for a clear, focused offer with a single accept/decline decision.
* **Multi Product** — Shows several products at once (in a stack or carousel). The customer picks one to accept.

***

## Product-selection methods

Within each structure, you choose how the product (or products) is selected. The available methods depend on whether the offer is Single or Multi Product.

| Method                                       | Available in   | What it does                                                                                                                                                               |
| -------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Specific product(s)**                      | Single & Multi | Hand-pick the exact product(s) to show. Use this to promote a hero product, bestseller, or item you want to move.                                                          |
| **Collection**                               | Multi only     | Pick a Shopify collection; Aftersell shows products from it. Items already in the order are excluded automatically.                                                        |
| **Automatic upsell (AI)**                    | Single & Multi | Uses Shopify's Recommendation API to suggest complementary products based on the customer's order.                                                                         |
| **Most Expensive / Least Expensive in Cart** | Single only    | Re-offers the highest- or lowest-priced item from the customer's original order at a discount. See [below](#most-expensive-and-least-expensive-in-cart).                   |
| **Strategy**                                 | Single & Multi | Attaches a [Strategy](/aftersell/implementing_strategies_post_purchase_upsells) to the offer for dynamic, rule-based merchandising evaluated each time the offer is shown. |

***

## Most Expensive and Least Expensive in Cart

The **Most Expensive in Cart** and **Least Expensive in Cart** methods automatically identify either the highest- or lowest-priced item in your customer's order and offer it again at a discount, right after checkout. They are a quick way to boost average order value without manually selecting products for each offer.

### How it works

When a customer completes a purchase, Aftersell scans their order and surfaces either the most or least expensive product as a post-purchase upsell at the discount you configure.

**Most Expensive in Cart**

* If the order contains one product, that product is the upsell.
* If the order contains multiple products, only the most expensive one is targeted.

**Least Expensive in Cart**

* If the order contains one product, that product is the upsell.
* If the order contains multiple products, only the least expensive one is targeted.

To further enhance this functionality, Aftersell leverages Shopify's Recommendation API, enabling more accurate, personalized suggestions based on factors such as customer behavior and product affinity.

<Warning>
  Both options work best for stores where customers are likely to want a second unit of a product, such as consumables, gifts, or everyday essentials. They are less suited to categories like clothing, where repeat purchases of the same item are uncommon. For those stores, AI-driven upsells that suggest complementary products tend to perform better.
</Warning>

### How to set it up

1. In Aftersell, create a new upsell offer.
2. Choose **Single Product** and select either **Most Expensive in Cart** or **Least Expensive in Cart**.
3. Set your desired discount percentage.
4. Save and place a test order to confirm the offer is displaying correctly.

<Note>
  The Most Expensive in Cart and Least Expensive in Cart options only appear if your offer is set to target a single product. If you do not see them, check that multiple product targeting is not enabled.
</Note>

### Running an A/B test

You can compare either option (Variant A) against AI-recommended products (Variant B). Variant A shows the most or least expensive item at your configured discount. Variant B shows up to four AI-recommended products. Traffic is split 50/50 between the two. See [Post-Purchase A/B Testing](/aftersell/post_purchase_a_b_testing) for details.

### Best practices

**Start simple.** Get the basic offer running and tested before adding downsells or additional steps to the flow. Too many offers in a row can reduce conversions.

<Tip>
  Most Expensive in Cart drives higher revenue per upsell. Least Expensive in Cart is a lower-friction option that is easier for customers to say yes to.
</Tip>

**Match the method to your catalog.** If your customers are unlikely to buy the same item twice, consider switching to AI-driven recommendations instead.

**Use A/B testing to decide.** If you are unsure which approach suits your store, run a split test and let performance data guide your decision.

### Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;No Possible Upsells&#x22; error">
    This error means Aftersell cannot find a valid product to upsell, usually because too many products or collections are excluded.

    To fix it:

    1. Open your funnel and go to the exclusions section for the upsell offer.
    2. Remove any unnecessary exclusions that may be blocking eligible products.
    3. Save and place a test order to check if the offer now appears.
  </Accordion>

  <Accordion title="&#x22;Most Expensive in Cart&#x22; or &#x22;Least Expensive in Cart&#x22; option is not selectable">
    This option only appears when the offer is set to target a single product. If you have multiple product targeting enabled, the option will be unavailable. Switch to single-product targeting to unlock it.
  </Accordion>

  <Accordion title="Hiding the original product from the upsell">
    This is not supported with either option. If you need to hide already-purchased items from the upsell offer, use a multi-product upsell instead and configure it to skip or hide specific products.
  </Accordion>
</AccordionGroup>

### Limitations

* Both options only work with single-product offer configurations.
* Aftersell cannot dynamically select the most or least expensive item when multiple product targeting is enabled.
* It is not possible to hide the originally purchased product from the upsell.
* For more flexibility, consider multi-product upsells or AI-driven recommendations.

***

## Related offer modes

These features extend or change how an offer behaves and have dedicated guides:

* **[Subscription offers](/aftersell/subscriptions_in_post_purchase_offers)** — Offer a subscription-enabled product as one-time only, subscription only, or both.
* **[Replacement Upsells](/aftersell/replacement_upsells)** — Swap a one-time product in the order for a different product or a subscription version.
* **[Subscription Upgrades](/aftersell/subscription-upgrades)** — Modify a subscription the customer already purchased in this order.

***

**Want to go further?**

* [How to configure post-purchase triggers](/aftersell/how_to_configure_post_purchase_triggers) — control when each offer shows.
* [Configuring post-purchase offer settings](/aftersell/configuring_post_purchase_offer_settings) — discounts, tags, and product options.
* [Post-purchase best practices](/aftersell/best_practices) — tips to improve conversion across all your offers.


# Post-purchase A/B testing
Source: https://docs.aftersell.com/aftersell/post_purchase_a_b_testing

Learn how to set up, manage, and analyze A/B tests for your post-purchase offers in Aftersell

# Post-purchase A/B testing

A/B testing (also known as split testing) allows you to compare up to five versions of a post-purchase offer within a single funnel to determine which performs better. Each version is called a **layout** (Layout A, Layout B, Layout C, Layout D, Layout E). Traffic is automatically split evenly across all active layouts, and performance is tracked separately so you can identify the higher-performing version.

By testing variations of your offers, you can improve conversion rates, increase revenue, and make data-driven decisions about your upsell strategy.

<Note>
  A/B testing lets you manually configure each layout as a complete offer and test them against each other. If you want to define individual variables (like discount type, timer duration, product type) and have Aftersell combine them into all possible layout combinations for testing, use [Multivariate Testing](/aftersell/multivariate_testing) instead.
</Note>

<Note>
  A/B testing is only available for post-purchase upsells. A/B testing for Thank You page offers is not currently available. For checkout widget A/B testing, see [Checkout A/B Testing](/aftersell/checkout_a_b_testing).
</Note>

***

## What you can test

You can test nearly any element of your post-purchase offer, including:

* **Products:** Different products, single product vs. multi-product offers, or AI recommendations vs. specific products
* **Discounts:** Different discount amounts or types (percentage vs. fixed dollar)
* **Copy:** Headlines, descriptions, and call-to-action text
* **Images:** Product images or lifestyle photos
* **Urgency elements:** Countdown timers with different durations
* **Quantities:** Default quantity of 1 vs. 2 (or more)
* **Offer design:** Different layouts or visual styles

<Tip>
  For best results, test one element at a time so you can clearly identify what drives performance changes. If you want to define multiple variables and have Aftersell combine them into layout combinations for testing, use [Multivariate Testing](/aftersell/multivariate_testing) instead.
</Tip>

***

## How to set up an A/B test

### Step 1: Create or open a funnel

1. Open the **Aftersell app** from your Shopify Admin
2. Navigate to **Post-purchase Funnels** in the left sidebar
3. Either create a new funnel or open an existing funnel you want to test

### Step 2: Create your test

1. In your funnel, click **Create Test**
2. Select **A/B Test** from the options

### Step 3: Set up your layouts

Configure each layout as a complete offer. You can create up to 5 layouts (Layout A through Layout E).

For each layout, you can customize:

* Product selection
* Discount amount and type
* Offer copy and messaging
* Images and visual elements
* Countdown timer settings
* Default quantity
* Any other offer settings

### Step 4: Start the test

1. Review all layouts to ensure they're configured correctly
2. Click **Start Test** to begin splitting traffic across layouts
3. Ensure your funnel is **enabled** and **published**

Your A/B test is now live.

### How traffic is split

Traffic is automatically distributed evenly across all layouts in the test. There is no way to manually adjust the traffic percentage for each layout. For example:

* If you have **2 layouts**, traffic will split **50% / 50%**
* If you have **3 layouts**, traffic will split approximately **33% / 33% / 33%**
* If you have **4 layouts**, traffic will split **25% each**
* If you have **5 layouts**, traffic will split **20% each**

All layouts within the same test receive equal traffic distribution. There is no option to set custom percentages (for example, you cannot set Layout A to 80% and Layout B to 20%).

***

## Managing your test

Once your A/B test is live, its status will show as **In progress**. From here, you can pause, edit, reset, delete, or select a winner.

### Test statuses

* **Not started**: The test has been created but is not active. Traffic is not being split. If you see 100% of traffic going to one layout, click **Start test**.
* **In progress**: Traffic is being split evenly across all layouts.
* **Paused**: Traffic splitting has stopped.
* **Finished**: The test has completed. Results are available in the Analytics > Tests tab.

Hover over the status badge to see a date tooltip. The tooltip shows:

* **Started \[date]** — for tests that are in progress, paused, or finished
* **Last reset \[date]** — for tests that are not started but have had their analytics reset
* **Created \[date]** — for tests that have not yet been started and have never been reset

### Pause the test

Click **Pause** to temporarily stop traffic splitting. When a test is paused:

* Traffic is no longer split between layouts
* Only the first layout created, Layout A, will be shown
* You cannot choose which layout displays while paused

To permanently display a different layout, you must select a winner or delete the test. When you unpause the test, traffic splitting resumes evenly.

### Edit the test

Use the three-dot menu to select **Edit test** if you need to adjust products, pricing, layout, or messaging. For accurate results, avoid making major changes while a test is running.

### Reset analytics

Select **Reset analytics** to clear current test data and restart tracking from zero. This resets only the A/B test data. Historical lifetime offer data is not deleted.

### Delete the test

Select **Delete test** to permanently remove the A/B test. If deleted:

* Traffic will no longer be split
* The offer returns to normal behavior
* Lifetime offer analytics become visible again

### Select a winner

When you are ready to end the test:

1. Click **Select winner**
2. Choose the layout to keep
3. Confirm

This ends the test and applies the selected layout as the active offer. All customers will see the chosen layout moving forward.

***

## How A/B test analytics work

Once your test is running, you can track performance in the **Analytics** section of your Aftersell dashboard under the **Tests** tab.

For a complete breakdown of all Tests tab metrics, including group-level analytics, Performance by Variable, the All Groups table, and how to select a test, see [Post-purchase Analytics](/aftersell/analytics_in_aftersell).

***

## Limitations

### A/B testing is within a single funnel only

A/B testing compares layouts within the same funnel. You cannot A/B test one funnel against another funnel.

### A/B testing is for post-purchase upsells only

A/B testing is not currently available for Thank You page offers. It is only supported for post-purchase upsell funnels.

### Custom traffic percentages are not supported

Traffic is always split evenly across all active layouts. There is no option to assign custom percentages to individual layouts.

***

## Best practices for A/B testing

### Run tests long enough

* **Minimum duration:** 2-4 weeks
* **Minimum impressions:** At least 100-200 impressions per layout (more is better)
* Shorter tests may not produce statistically reliable results, especially with low traffic.

The analytics dashboard will show you the impressions needed to be statistically viable, helping you know when the data is ready to act on.

### Test one element at a time

When you change multiple elements simultaneously, you won't know which change drove the results. Test one variable at a time for clear insights:

**Good**: Test 10% discount vs. 20% discount (one variable)

**Avoid**: Test 10% discount + Product A vs. 20% discount + Product B (two variables)

### Look for consistent performance

Don't make decisions based on a single metric. A winning layout should perform well across multiple metrics:

* Higher conversion rate
* Higher revenue per visit
* Comparable or better average upsell value

### Consider statistical significance

Before declaring a winner, ensure your results are statistically significant. Look for:

* Clear performance differences (not just 1-2% variations)
* Consistent trends over time
* Sufficient sample size (impressions)

### Apply the winning layout

Once you've identified a clear winner:

1. Stop the test
2. Apply the winning layout to your funnel
3. Monitor performance to ensure results remain consistent
4. Consider running a new test to further optimize

***

## A/B test vs. Multivariate test

Not sure which testing method to use?

|                          | **A/B Test**                                                                            | **Multivariate Test**                                                                                                            |
| ------------------------ | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| How it works             | You manually configure each layout as a complete offer and test them against each other | You define individual variables and their options, and Aftersell combines them into all possible layout combinations for testing |
| Layouts                  | Up to 5 layouts (Layout A through E), each manually configured                          | Automatically generated based on variable combinations (Layout A, B, C, etc.)                                                    |
| Best for                 | Comparing complete offer designs against each other                                     | Finding the best combination of individual variables (discount, timer, shipping, quantity)                                       |
| Traffic split            | Evenly across all layouts                                                               | Evenly across all combinations                                                                                                   |
| Statistical significance | Faster to reach with fewer layouts                                                      | Requires more traffic due to more combinations                                                                                   |
| Results                  | Easier to interpret - one layout wins                                                   | More complex - identifies best combination of variables                                                                          |

**Use A/B testing when:**

* You want to compare complete offer configurations
* You have moderate traffic levels
* You want clear, straightforward results

[**Use Multivariate Testing when:**](/aftersell/multivariate_testing)

* You want to test multiple variables simultaneously and find the best combination
* You have high traffic levels
* You want to define variables and have Aftersell combine them into layout combinations for testing

***

## Common A/B test ideas

Need inspiration? Here are proven A/B tests to try:

### Product-based tests

* **Same product vs. complementary product:** Test whether customers prefer to buy more of what they just purchased or try something new
* **Single product vs. multi-product offer:** Compare a single item offer against a multi-product offer with complementary products
* **AI-powered vs. static product:** Test dynamic AI recommendations against manually selected products

### Discount tests

* **Discount amount:** Test 10% off vs. 20% off vs. 30% off
* **Discount type:** Compare percentage discounts (20% off) vs. fixed dollar amounts (\$5 off)
* **No discount vs. discount:** Test whether a discount is necessary for your audience

### Quantity tests

* **Default quantity:** Test quantity of 1 vs. quantity of 2 (especially effective for consumables)

### Copy and messaging tests

* **Headline variations:** Test different value propositions or messaging angles
* **Urgency messaging:** Test with vs. without urgency language
* **CTA button text:** Test different call-to-action phrases

### Design tests

* **Long-form vs. short-form:** Test detailed product descriptions against concise offers
* **Image variations:** Test different product images or lifestyle photos
* **Timer duration:** Test 5-minute vs. 10-minute vs. 15-minute countdown timers

For more detailed strategies and examples, check out our [Best Practices](/aftersell/best_practices) guide.

***

## Frequently asked questions

### Do A/B tests stop running automatically after reaching statistical significance?

No. A post-purchase A/B test keeps running until you end it yourself — there is no automatic stop when a result reaches statistical significance. The analytics dashboard shows the recommended number of impressions for a statistically viable result, but reaching that number doesn't stop the test or pick a winner. Deciding when the data is conclusive, and ending the test, is up to you. When you're ready, end it with **Select winner** (or pause or delete it) — see [Managing your test](#managing-your-test).

***

## Need help?

If you have questions about setting up or analyzing your A/B tests, chat with our support team using the live chat at the bottom right of the app.


# Post-purchase branding settings
Source: https://docs.aftersell.com/aftersell/post_purchase_branding_settings

How your post-purchase page inherits Shopify checkout branding and where to edit those branding settings depending on your Shopify plan.

Your post-purchase page is styled by your **Shopify checkout branding**, the same settings that style your checkout, thank-you, and order status pages. It does not have its own separate styling.

<Note>
  If your store is not on a Shopify Plus plan, the preview in the Aftersell editor will not match your live page. Shopify does not let apps read your branding on those plans, so the preview will fall back to the default Shopify settings

  This affects the preview only; your live post-purchase page still uses your real branding. To confirm, place a test order and check the post-purchase page.

  The checkout editor does not show a post-purchase page, so there is nothing to preview there. Your branding still applies to it behind the scenes
</Note>

Where you edit that branding depends on your Shopify plan.

## If you are not on Shopify Plus (also works for Shopify plus)

Shopify only lets apps read and write checkout branding on Plus plans, so Aftersell cannot show or change your branding. Make your changes in the Shopify checkout editor instead. To open it, go to **Settings → Checkout** in your Shopify admin and click **Customize**:

<img alt="Opening the Shopify Settings Checkout page and its branding customization editor" />

The checkout editor does not show a post-purchase page, so there is nothing to preview there. Your branding still applies to it.

The **Colors → Buttons**  setting is the one merchants ask about most — it controls the "Add to order" and next-step buttons on your post-purchase page:

<img alt="Checkout editor Settings panel with the Buttons colour field highlighted" />

## If you are on Shopify Plus

Edit your branding directly in Aftersell, under **Settings → Checkout branding**. Your changes are written straight to your Shopify checkout branding, so they apply to your checkout, post-purchase, thank-you, and order status pages. Also see [Checkout Branding Settings](https://docs.aftersell.com/aftersell/checkout_branding_settings#checkout-branding-settings)

On these plans the Aftersell editor preview also shows your real branding, so you can see your styling without placing an order.

You can use the Shopify checkout editor instead if you prefer. Both write to the same settings, so you only need one.

***

Many of the fields in the Shopify checkout editor are linked to Aftersell's post-purchase page. The mapping below shows which Shopify checkout setting controls which element on the post-purchase upsell page:

| Shopify checkout setting                 | Controls on the post-purchase page       |
| :--------------------------------------- | :--------------------------------------- |
| **Logo** (image, position, size)         | The store logo at the top of the page    |
| **Main content area → Background color** | The page background                      |
| **Order summary → Background color**     | The offer summary background             |
| **Typography → Headings**                | Offer and product headings               |
| **Typography → Body**                    | Body text                                |
| **Colors → Accents**                     | Links, highlights, and checkmarks        |
| **Colors → Buttons**                     | The "Add to order" and next-step buttons |
| **Form fields**                          | The variant and quantity form fields     |

For instance, the button color in the Shopify checkout is directly reflected in the button color on the post-purchase page:

<img alt="Numbered diagram mapping Shopify checkout branding settings to post-purchase page elements" />

***


# Post-purchase overview
Source: https://docs.aftersell.com/aftersell/post_purchase_overview

This guide explains what post-purchase offers are, how they work, and how to start using them with Aftersell.

# Overview

Aftersell's Post-purchase offers help increase your average order value (AOV) by presenting relevant upsell offers after the initial purchase. These offers are shown either immediately after checkout or on the Thank You page, allowing customers to buy more.

***

## What is a post-purchase offer?

A post-purchase offer is an additional product offer shown after a customer completes their initial checkout. Offers can appear in two places:

* Right after checkout, before the order confirmation. (Post-purchase upsells)
* After the order is confirmed, as part of the order status page. (Thank you page upsells)

In both cases, offers are designed to be quick and easy to accept and this helps you generate more revenue without interrupting the customer's checkout experience.

***

## How the post-purchase page works

The post-purchase page is a Shopify-hosted page shown between checkout and the order confirmation. This is where Aftersell can display Post-purchase upsells, based on what the customer just purchased.

## Funnel flow:

1. Customer completes checkout.
2. Aftersell shows the first upsell offer.
3. Customer accepts or declines.

   * If accepted, the product is added to the original order. and you can set more "if accepted" follow ups.
   * If declined, a downsell offer can be shown.
4. Customer is taken to the Thank you page.

***

## How the thank you page works

The Thank You page is the final page of the checkout experience where customers view their order summary and tracking info. With Aftersell, you can turn this page into another opportunity to increase sales by adding:

* Product recommendations
* FAQs
* Text
* Image

Thank You Page upsells can be configured in one of two ways:

* **Modify original order** - the upsell is combined with the initial purchase into a single order.
* **Create new draft order** - the upsell generates a second order that is distinct from the original. When configured as a new draft order, if the customer abandons the second checkout, the upsell order remains in **Draft** status.

For how to configure these widgets and the full list of Thank You Page settings, see the [Thank You Page extensions overview](/aftersell/thank_you_page_extensions_overview).

If your store is still on the legacy Thank You page scripts editor, the order-handling options differ (merging must be enabled and is off by default) — see the [Thank You page scripts overview](/aftersell/thank_you_page_scripts_overview).

***

## Key benefits

* **Boost average order value.** Post-purchase and Thank You Page offers help customers add more to their purchase.
* **Acceptance on the post-purchase page.** No extra steps or friction.
* **Completely native to Shopify.** Offers match your brand and are hosted by Shopify.
* **Highly targeted.** Use conditions to control when and what offers show.
* **Visual aid features.** Implement the 'Show progress bar on funnel' to guide customers through multi-step funnels.

***

## How to create a post-purchase funnel

When you open **Post-purchase Funnels** for the first time (or when you have no funnels), you'll see a **Get started** screen with two cards:

* **Guided funnel setup** (marked *Recommended*) — walks you through setup, from triggers to offers to your thank you page.
* **Start from scratch** — a blank canvas where you set up the triggers and offers yourself.

### Starting from a template

<Note>
  The ready-made template gallery below is superseded by the guided setup above and is no longer shown on the funnels page. It is documented here for stores that still see it.
</Note>

Where the gallery does appear, it shows these ready-made funnel options:

* **Classic upsell** — A 4-step funnel: Upsell 1 (most expensive product), Upsell 2 (4 AI-recommended products), Downsell 1 (most expensive product), and Downsell 2 (AI-recommended product).
* **Bestseller bundle** — A 4-step funnel: Upsell 1 (4 AI-recommended products), Upsell 2 (most expensive product), Downsell 1 (most expensive product), and Downsell 2 (most expensive product).
* **Subscription Upgrades** — Builds a funnel that offers existing subscribers a post-purchase change to their active subscription. This template appears only when the Subscription Upgrades Beta feature is enabled on your account, and it opens its own setup wizard rather than the confirmation modal below. See [Subscription Upgrades](/aftersell/subscription-upgrades).

#### Confirmation modal for Classic upsell and Bestseller bundle

When you click **Use this template** on the Classic upsell or Bestseller bundle, a confirmation modal opens before the funnel is created. The modal lets you:

* **Preview the offer flow** — See each step in the funnel with the product type and discount that will be applied.
* **Set a max discount** — Enter a whole number from 0 to 100. How the amount is distributed depends on the template: for the Classic upsell, Upsell 1 receives half this amount (rounded up) and the remaining steps receive the full amount; for the Bestseller bundle, both Upsell 1 and Upsell 2 receive half this amount (rounded up) and the remaining steps receive the full amount. The default is 30%.
* **Choose the funnel's starting status** — Toggle the funnel active or inactive before saving. An active funnel starts showing to customers immediately after creation.

Click **Save** to create the funnel, or **Cancel** to exit without creating anything. After the funnel is created, you land directly in the funnel editor to customize triggers, offers, and design.

### Bulk actions on funnels

You can perform bulk actions on multiple funnels at once from the **Post-purchase Funnels** list using the **More actions** button (the kebab menu icon) in the filter bar.

#### Enabling or disabling multiple funnels at once

1. Select the checkboxes next to the funnels you want to update. Use the header checkbox to select all funnels on the current page.
2. Click the **More actions** button (the kebab menu icon) in the filter bar.
3. Select **Enable funnel** / **Enable N funnels** or **Disable funnel** / **Disable N funnels**. The option is greyed out if all selected funnels are already in that state, or if nothing is selected.

Only funnels that need to change are updated — funnels already in the target state are skipped. Your selection is preserved after the operation, so you can chain enable and disable actions without re-selecting.

#### Deleting multiple funnels at once

1. Select the checkboxes next to the funnels you want to delete. Use the header checkbox to select all funnels on the current page.
2. Click the **More actions** button (the kebab menu icon) in the filter bar.
3. Select **Delete funnel** (singular) or **Delete N funnels** (plural, showing the count of selected funnels). The option is disabled until at least one funnel is selected.
4. Confirm the deletion in the modal that appears.

Deleting a funnel removes it and all its associated widgets, split tests, and Thank You Page widgets. This action cannot be undone. Historical analytics data for deleted funnels is preserved — see [Analytics in Aftersell](/aftersell/analytics_in_aftersell) for details.

***

### Adding more funnels

Once you have at least one funnel, use the **Add funnel** button to create additional funnels. The button opens a dropdown where you can:

* Pick a template to start from (same options as the gallery). Selecting Classic upsell or Bestseller bundle opens the confirmation modal described above.
* Select **Create manually** to build a funnel from scratch with no presets.

### Manual setup steps

1. Go to **Post-purchase Funnels** in the Aftersell admin.
2. Click **Add funnel** and choose **Create manually**, or select a template.
3. Set [trigger conditions](/aftersell/post_purchase_triggers) to control when the funnel shows.
4. Add upsell offers.
5. Customize the offer design and messaging.
6. Enable the funnel and publish it.

You can create multiple funnels and prioritize them to control which one runs when multiple conditions match. You can also track the triggers for post-purchase upsells using Aftersell's Order Browser, which displays a "shown" status to confirm successful activation of the funnel.

***

## Summary

Post-purchase and Thank You Page offers give you two powerful ways to drive more revenue after the sale is complete. With Aftersell, you can easily create personalized upsells that feel native to your store and are proven to convert.

Need help getting started? Visit our [Post-purchase Help Center](/aftersell/best_practices) or our [Thank You Page guides](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell), or contact our support team.


# Post-purchase strategies by industry
Source: https://docs.aftersell.com/aftersell/post_purchase_strategies_by_industry

Upsell playbooks tailored to your industry with product selection, discount ranges, funnel triggers, and testing priorities to help you get the most out of your post-purchase funnels

# Post-purchase strategies by industry

Different product categories have different upsell dynamics. Use these playbooks as a starting point for your vertical, then A/B test to refine. For universal best practices that apply to all industries, see [Post-purchase Best Practices](/aftersell/best_practices).

<Tip>
  Want real-world examples from top brands? [Download our Upsell Playbook](https://www.aftersell.com/upsell-playbook) for proven strategies and case studies you can apply to your store today.
</Tip>

<Note>
  The discount ranges listed below are starting points for testing, not guarantees. Your optimal discount depends on your margins, product pricing, and customer behavior. Always A/B test to find what works for your store.
</Note>

***

## Fashion and apparel

Fashion stores convert best on complementary accessories. A customer who just bought a dress is far more likely to accept earrings, a clutch, or a scarf than another dress.

* **Upsell #1:** Complementary accessory (jewelry, bags, scarves, belts, shoes)
* **Upsell #2 (accept path):** A second complementary item from the same collection
* **Downsell (decline path):** Lower-price accessory from the same collection
* **Discount range:** 10-20% off
* **Funnel triggers:** Use [collection-based triggers](/aftersell/how_to_configure_post_purchase_triggers) so the upsell adapts to what the customer is buying
* **Thank You Page:** "Complete the Look" product recommendations using automatic upsells
* **Testing priority:** Single product vs. multi-product offers, AI vs. manual product selection

<Tip>
  For fashion stores, avoid upselling the same item the customer just purchased. A diversified approach that shows complementary products increases resonance with buyers.
</Tip>

***

## Supplements and health

Supplements are ideal for quantity-based upsells because customers use them regularly and replenishment is expected.

* **Upsell #1:** Same product at quantity 2 or 3, or a complementary supplement (for example, vitamin D with a multivitamin)
* **Upsell #2 (accept path):** A related supplement that pairs with the first (for example, fish oil after accepting a multivitamin)
* **Downsell (decline path):** Single unit of a related product at a smaller size or lower price point
* **Discount range:** 15-30% off (higher discounts work well here because margins are typically strong)
* **Funnel triggers:** Product-specific triggers for your top sellers
* **Testing priority:** Default quantity 1 vs. 2, percentage vs. fixed dollar discount
* **Subscriptions:** Supplements are one of the strongest use cases for subscription upsells. For example, a customer who makes a one-time purchase of a probiotic could be offered "Love your probiotics? Subscribe and save 20% with automatic monthly delivery." You can offer "Subscription only," or give the customer the choice between one-time and subscription with subscription preselected as the default. You can also use a [replacement upsell](/aftersell/replacement_upsells) to swap the one-time purchase for a subscription version of the same product after checkout. Note: replacement upsells are currently a beta feature. Contact support to enable this for your account. Place your subscription offer as Upsell #1 since Shopify only allows one subscription offer per funnel. See [Subscriptions in Post-purchase Offers](/aftersell/subscriptions_in_post_purchase_offers) for setup details.

***

## Food and beverage

Similar to supplements, food and beverage products lend themselves to quantity upsells and variety offers.

* **Upsell #1:** Same product at a higher quantity, or a different flavor or variety
* **Upsell #2 (accept path):** A complementary product (for example, a sauce after accepting pasta, a snack after accepting a beverage)
* **Downsell (decline path):** Sampler or trial size of a related product
* **Discount range:** 15-30% off
* **Funnel triggers:** Product or collection-based
* **Testing priority:** Same product replenishment vs. variety cross-sell
* **Subscriptions:** Recurring food and beverage purchases are a natural fit for subscription upsells. For example, a customer who places a one-time order for a bag of coffee could be offered "Never run out: subscribe and save 15% with monthly delivery." A customer who buys a variety pack of protein bars could see "Get a fresh box every 4 weeks." Offer the choice between one-time and subscription with subscription preselected, or use a [replacement upsell](/aftersell/replacement_upsells) to swap the one-time purchase for a subscription version. Note: replacement upsells are currently a beta feature. Contact support to enable this for your account. Place your subscription offer as Upsell #1 in the funnel. See [Subscriptions in Post-purchase Offers](/aftersell/subscriptions_in_post_purchase_offers) for setup details.

***

## Beauty and skincare

Beauty customers respond well to routine-building upsells. Products that pair naturally with what they just bought tend to convert well.

* **Upsell #1:** Next step in the skincare routine (for example, serum after moisturizer, SPF after cleanser)
* **Upsell #2 (accept path):** Another routine step or a tool/applicator that goes with the products
* **Downsell (decline path):** Travel size or sample of the original upsell product
* **Discount range:** 10-20% off
* **Funnel triggers:** Collection-based, or product-specific for hero SKUs
* **Thank You Page:** "Build Your Routine" product recommendations using automatic upsells
* **Testing priority:** AI recommendations vs. curated routine sets
* **Subscriptions:** Skincare routines are naturally recurring, making beauty products a strong fit for subscription upsells. For example, a customer who makes a one-time purchase of a daily moisturizer could be offered "Subscribe for 15% off and get a fresh jar delivered every 60 days." A customer who buys a retinol serum as a one-time order could see "Start your routine: subscribe and save on monthly refills." Offer subscription as the default option or use a [replacement upsell](/aftersell/replacement_upsells) to swap the one-time purchase for a subscription. Note: replacement upsells are currently a beta feature. Contact support to enable this for your account. Place your subscription offer as Upsell #1 in the funnel. See [Subscriptions in Post-purchase Offers](/aftersell/subscriptions_in_post_purchase_offers) for setup details.

***

## Electronics and accessories

Electronics upsells work best with protective accessories and add-ons that enhance the primary purchase.

* **Upsell #1:** Primary accessory (case, screen protector, charger)
* **Upsell #2 (accept path):** Secondary accessory (cable, stand, cleaning kit)
* **Downsell (decline path):** Lower-tier version of the primary accessory (for example, basic case instead of premium case)
* **Discount range:** 5-15% off (customers expect smaller discounts on tech accessories)
* **Funnel triggers:** Product-specific triggers matching accessories to each device
* **Testing priority:** Accessory type (protection vs. enhancement), single vs. multi-product

***

## Home goods

Home goods customers often buy in projects or collections. They are furnishing a room, not buying a single item.

* **Upsell #1:** Complementary item from the same collection or room category
* **Upsell #2 (accept path):** Another piece from the same collection or a functional add-on
* **Downsell (decline path):** Smaller accent piece (candle, throw pillow, organizer)
* **Discount range:** 10-20% off
* **Funnel triggers:** Collection-based triggers
* **Testing priority:** Same-collection cross-sell vs. AI recommendations

***

## Car parts and automotive

Car parts customers are often completing a specific repair or upgrade project and are open to related components.

* **Upsell #1:** Related part for the same repair (for example, brake pads with rotors, oil filter with oil)
* **Upsell #2 (accept path):** Another related component for the same project (for example, brake fluid after accepting pads and rotors)
* **Downsell (decline path):** Maintenance consumable (cleaning supplies, fluids, small hardware)
* **Discount range:** 5-15% off
* **Funnel triggers:** Product or collection-based, matching related parts to each primary product
* **Testing priority:** Related repair part vs. maintenance consumable

***

## Don't see your industry?

These playbooks cover the most common verticals, but the core principles apply to any product category:

1. **Lead with a complementary product** that feels like a natural extension of what the customer bought
2. **Always configure a downsell** on the decline path with a lower commitment offer
3. **Include Thank You Page upsells** in every funnel so no order goes without an opportunity
4. **A/B test** AI recommendations vs. manual product selection to see which performs better for your catalog
5. **Start with a discount** and test to find the minimum level that maintains your conversion rate

For more detail on each of these principles, see [Post-purchase Best Practices](/aftersell/best_practices).

***

## Need help?

If you have questions about building upsell funnels for your specific industry, chat with our support team using the live chat at the bottom right of the app.


# Post-purchase triggers
Source: https://docs.aftersell.com/aftersell/post_purchase_triggers

This article explains how post-purchase triggers function.

Triggers can be utilized to display a funnel in particular situations, and they can be combined to effectively highlight funnels for specific scenarios.

***

Show for all customers trigger

[Product-Based Triggers](#product-based-triggers)

* [Product/Collection Trigger](#productcollection)
* [Product Quantity Trigger](#product-quantity)
* [Product Tag Trigger](#product-tag)
* [Product Type Trigger](#product-type)
* [Metafields](#metafields)
* [Product/Collection Exclusion Trigger](#productcollection-exclusion)
* [Subscription Trigger](#subscription)
* [Variant on Subscription Trigger](#variant-on-subscription)
* [Variant Name Trigger](#variant-name)

[Cart & Discount Triggers](#cart-%26-discount-triggers)

* [Order Value Trigger](#order-value)
* [Quantity Trigger](#quantity)
* [Discount Code Trigger](#discount-code)
* [Discount Percent (%) Trigger](#discount-percent-%28%25%29)

[Customer Attribute Triggers](#customer-attribute-triggers)

* [Customer Tag Trigger](#customer-tag)
* [Customer Order History Trigger](#customer-order-history)
* [Customer Order Count Trigger](#customer-order-count)
* [Customer Language Trigger](#customer-language)
* [Once per Customer Trigger](#once-per-customer)

[Order Details & Time-Based Triggers](#order-details-%26-time-based-triggers)

* [UTM Parameter Trigger](#utm-parameter)
* [Currency Trigger](#currency)
* [Device Type Trigger](#device-type)
* [Shipping Country Trigger](#shipping-country)
* [Random Sample Trigger](#random-sample)
* [Date/Time Trigger](#datetime)
* [Shipping Method Trigger](#shipping-method)

***

# Show for All Customers Trigger

A "**Catch-All" funnel** uses the "Show for All Customers" trigger.

This funnel activates when an order does not meet the criteria for any other funnel.

It serves as a **safety net**, ensuring no orders slip through without an upsell or thank-you page offer. To use it effectively, set this funnel to the **lowest priority** so it only appears if no other funnel triggers.

Here are some examples:

* You have three funnels: one for orders over \$100, one for specific products, and one with the Show for All Customers trigger. If a customer places an order that doesn't meet the first two funnels' criteria, the Show for All Customers funnel will activate as a fallback.
* You want to ensure every customer sees at least one offer. Create a funnel with the Show for All Customers trigger and set it to the lowest priority. This funnel will catch any orders that don't match your other targeted funnels.

***

# Product-Based Triggers

*These triggers activate based on the products, collections, or variants in a customer's cart.*

Additionally, ensure proper configuration to prevent hidden or wholesale-only products from appearing unexpectedly in recommendations. This includes reviewing Shopify's Product Recommendation logic and restricting such products at the add-to-cart stage, mitigating unintended visibility issues.

## **Product/Collection**

The Product/Collection Trigger displays the funnel when a customer purchases a specific product or a product from a particular collection.

Here are some examples:

* You have a funnel with a Product/Collection Trigger set to products X, Y, and Z. If a customer buys products A, B, and Y, this funnel will activate, showing the upsells within that funnel to the customer.
* You have a funnel with a Product/Collection Trigger set to products X, Y, and Z. If a customer buys products A, B, and C, this funnel will not activate since none of the specified products (X, Y, or Z) were purchased.

## **Product Quantity**

The Product Quantity Trigger displays the offer based on how many of a specific product are included in the cart. Unlike the Product/Collection Trigger (which checks whether a product is present at any quantity), the Product Quantity Trigger lets you set a quantity threshold for a specific product.

**To configure a Product Quantity trigger:**

1. Check the **Product quantity** box in your trigger settings.
2. In the condition row, choose an operator from the dropdown: **More than**, **Less than**, or **Exactly**.
3. Enter the quantity threshold in the number field.
4. Use the product selector to choose which product the condition applies to.
5. Click **Save**.

**Example use cases:**

* Set to "more than" 2 of Product A (the upsell only appears when a customer has 3 or more of Product A in their cart).
* Set to "exactly" 1 of Product A (the upsell fires only for single-unit orders of that product).
* Set to "less than" 3 of Product A (the upsell appears when there are 1 or 2 of that product in the order).

**Using multiple condition rows:**

You can add multiple rows to target different products or quantity ranges within the same trigger. Each row specifies its own operator, threshold, and product. Use the **Condition Logic** toggle in the top right corner to connect rows with AND or OR logic.

For example:

* Row 1: "more than" 1 of Product A **AND** Row 2: "exactly" 1 of Product B (the upsell only appears when both conditions are met simultaneously).
* Row 1: "exactly" 2 of Product A **OR** Row 2: "more than" 3 of Product B (the upsell appears when either condition is met).

## **Product Tag**

The Product Tag Trigger displays the offer when products with certain Shopify tags are included in the order.

Here are some examples:

* You want to exclude discontinued products from receiving upsell offers. Set the Product Tag Trigger to exclude products tagged "**discontinued**." If a customer purchases a product with this tag, the funnel will not activate.
* You want to show a special offer only for products tagged "**summer-collection**." Set the Product Tag Trigger to include products with this tag. If a customer purchases any product tagged "**summer-collection**," the funnel will activate.

## **Product Type**

The Product Type Trigger displays the offer when the products belong to a defined Shopify product type.

* For example, if you set the Product Type Trigger to "Shoes," then any time a customer purchases a product that belongs to the *Shoes* product type, the funnel will display. For instance, if the customer adds a pair of running sneakers (type: Shoes) to their cart, the funnel will activate. However, if the customer adds a t-shirt (type: Apparel), the funnel will not display because the product type does not match the trigger.

## Metafields

The Metafields trigger displays funnels based on custom metafield data associated with products or variants. You can choose between product metafields or variant metafields, but only one type can be matched at a time.

Each sub-trigger (Product or Variant) has a **Match type** dropdown with three options:

* **Value matches** — the existing behaviour. Enter a metafield name and value (`name: value`), then choose **Includes** or **Excludes**. Both the name and value are case-sensitive and must match exactly as they appear on the product page.
* **Has any value** — fires when the named metafield exists and has a non-empty value. Enter only the metafield name; the value input is hidden.
* **Is empty** — fires when the named metafield is absent or has an empty value. Enter only the metafield name; the value input is hidden.

**Value matches — how Include and Exclude work:**

Include means there's an overlap between the metafields in the order and those in the trigger list.

* For example, if the order metafields are `["color: red", "size: m"]` and the trigger list is `["color: red", "ship: warehouse"]`, the condition is satisfied because `color: red` matches.

Exclude means there's no overlap between the metafields in the order and the trigger list.

* For example, if the order metafields are `["color: red", "size: M"]` and the trigger list is `["color: blue", "size: L"]`, the condition is satisfied because there are no matching name:value pairs.

**Has any value / Is empty — how matching works:**

For these modes, enter the metafield name using any of the following formats (all are equivalent):

* `namespace.key` — for example, `custom.warehouse_location`
* bare key — for example, `warehouse_location`
* definition name — for example, `Warehouse Location`

The trigger evaluates across all products in the order. **Has any value** fires when at least one purchased product has a non-empty value for the named metafield. **Is empty** fires when none of the purchased products have a non-empty value for it (the metafield is absent or empty on every product).

<Note>
  Switching the Match type clears any entries already added to that sub-trigger, since `name: value` tags and bare-key tags mean different things per mode.
</Note>

This trigger is especially useful if you are using metafields to store detailed product information (like materials, sizing, or special attributes) and want to target funnels based on that data.

## **Product/Collection Exclusion**

The Product/Collection Exclusion Trigger prevents the funnel from displaying when excluded products or collections are present in the cart.

* For example, if a customer has purchased from a heavily discounted product or collection, you may prefer not to show further offers to that customer. This trigger allows you to skip all offers if those specific products or collections are in the customer's cart.
* Additionally, you can combine this trigger with the Product/Collection Trigger to ensure that only selected products or collections activate the funnel, while any others are excluded.

## **Subscription**

The Subscription Trigger displays the offer based on whether a subscription product is included in the order.

Here are some examples:

* You have a funnel with a Subscription Trigger set to "**do not include a subscription**." If a customer purchases only one-time products, the funnel will activate, allowing you to offer them a subscription upsell.
* You have a funnel with a Subscription Trigger set to "**include a subscription**." If a customer purchases a subscription product, the funnel will activate, allowing you to show them complementary one-time products.

**Note:** Shopify only supports one subscription product per order. This means you cannot upsell a subscription if the original order already includes a subscription.

## **Variant on subscription**

The Variant on Subscription trigger displays the funnel when the order includes any of the selected products purchased as a subscription. Unlike the Subscription trigger (which checks whether any subscription is present), this trigger matches on a specific product being purchased on a subscription line item — so a one-time purchase of the same product does not activate the funnel.

This trigger is used automatically by the subscription upgrade wizard. When a funnel has a subscription upgrade offer configured, the trigger is managed by the wizard and kept in sync with the upgrade's source product. The trigger is read-only while the upgrade offer is present; it unlocks if the upgrade offer is removed.

On funnels without a subscription upgrade offer, you can configure the trigger manually. The product picker is filtered to subscription products only.

Here are some examples:

* You have a subscription upgrade funnel targeting customers who subscribe to Product A. The Variant on Subscription trigger is set to Product A. If a customer purchases Product A as a subscription, the funnel activates. If they purchase Product A as a one-time item, the funnel does not activate.
* You have multiple subscription upgrade offers in the same funnel. The trigger is set to the union of all upgrade source products, so the funnel activates when any of those products is purchased as a subscription.

## **Variant Name**

The Variant Name Trigger allows you to display specific funnels based on the product variant selected by the customer at checkout. By using this trigger, you can include or exclude customers from certain offers depending on the exact variant they choose, such as size, color, or style.

Here are some examples:

* You have a funnel with a Variant Name Trigger set to include "**Large**." If a customer purchases a t-shirt in size Large, the funnel will activate. If they purchase size Small or Medium, the funnel will not activate.
* You have a funnel with a Variant Name Trigger set to include "**Red**" and "**Blue**." If a customer purchases a product in either Red or Blue color variant, the funnel will activate. If they purchase Green, the funnel will not activate.

***

# Cart & Discount Triggers

*These triggers activate based on the cart value, contents, or discounts applied.*

## **Order Value**

The Order Value Trigger is used to display an offer if an order meets a specified dollar value requirement, which can be set as greater than or less than a chosen amount. When an order meets your set criteria, the offer will be shown to the customer.

Here are some **examples**:

1. Your funnel has an Order Value Trigger set to activate when orders total less than \$50.00. If a customer places an order totalling \$30.00 with various products, the offer will display, as the order meets the "less than \$50.00" requirement.
2. Your funnel has an Order Value Trigger set to activate when orders total less than \$50.00. If a customer places an order totalling \$60.00 with various products, the offer will not display since the order value does not meet the "less than \$50.00" requirement.

In both examples, the specific products in the order are irrelevant; the trigger is based solely on order value.

## **Quantity**

The Quantity Trigger shows an upsell offer based on the total item count in a customer's order. It looks at the overall number of items across all products in the cart, regardless of which specific products they are.

**To configure a Quantity trigger:**

1. In the **Cart & Discount Triggers** section, check the **Quantity** box.
2. In the condition row, choose an operator from the dropdown: **More than**, **Less than**, or **Exactly equals**.
3. Enter the item count in the number field.
4. Click **Save**.

**Example use cases:**

* Set to "**less than 3**" - the upsell appears only when there are 1 or 2 total items in the cart.
* Set to "**more than 1**" - the funnel triggers for orders with 2 or more total items.
* Set to "**exactly 5**" - the funnel triggers only when there are exactly 5 total items in the cart.
* Set to "**exactly 0**" or "**less than 1**" - useful for targeting new customers who have no previous items. For example, combine this with the Customer Order Count trigger to show a welcome offer to first-time buyers with a single-item cart.

💡 **Tip:** If you need to trigger based on the quantity of a specific product rather than total cart item count, use the Product Quantity trigger instead (found under Product-Based Triggers).

## **Discount Code**

The Discount Code Trigger lets you include or exclude customers from seeing a funnel based on a discount code they use. A third option, **Excludes any manual discount code**, lets you exclude all orders where a manually-entered discount code was applied — without needing to list individual codes.

Here are some examples:

* You're running two promotions: 25% off for new customers and 10% off for email subscribers. Use the Discount Code trigger set to **Includes** with the email subscription discount code to display the funnel only to email subscribers.
* You want to prevent upsell offers from showing to any customer who used a discount code at checkout. Set the trigger to **Excludes any manual discount code**. The funnel will only fire for orders with no manually-entered discount code. Automatic and script discounts (such as a site-wide automatic discount) are not counted, so they will not suppress the funnel.

**NOTE:** ***Be sure to press "enter" after entering the discount code to save it in the funnel.***

## **Discount Percent (%)**

The Discount Percent (%) Trigger displays a funnel based on the line-item discount percentage applied to the order (this excludes shipping discounts). Choose **More than**, **Less than**, or **Exactly**, then enter the percentage threshold.

Here are some examples:

* You have a funnel with a Discount Percent Trigger set to "**more than 20%**." If a customer receives a 25% discount, the funnel will activate. If they receive a 15% discount or no discount, the funnel will not activate.
* You have a funnel with a Discount Percent Trigger set to "**less than 10%**." If a customer receives a 5% discount, the funnel will activate. If they receive a 15% discount, the funnel will not activate.
* You have a funnel with a Discount Percent Trigger set to "**exactly 10%**." The funnel only activates for orders with precisely a 10% discount applied.

***

# Customer Attribute Triggers

*These triggers use customer data to control funnel visibility.*

## **Customer Tag**

The Customer Tag Trigger allows you to include or exclude customers from seeing a funnel based on their associated tags.

Here are some examples:

* You have a funnel with a Customer Tag Trigger set to include "**VIP**." If a customer has the VIP tag, the funnel will activate. If they don't have this tag, the funnel will not activate.
* You have a funnel with a Customer Tag Trigger set to exclude "**Wholesale**." If a customer has the Wholesale tag, the funnel will not activate, preventing retail upsells from showing to wholesale customers.

## **Customer Order History**

The **Customer Order History Trigger** lets you create offers based on a customer's past purchases.

**Important:** You must select specific products or collections when using this trigger. The default match mode is **Include**, and if you leave products/collections unselected while using **Include**, the trigger can never be satisfied — this permanently blocks the funnel from firing, not just leaves it inactive with no effect. Always select at least one product or collection.

If your goal is simply to check whether a customer has ordered before, use the [**Customer Order Count Trigger**](#customer-order-count) instead:

* More than 0 orders = Returning customer
* 0 orders = New customer

**NOTE:** *This trigger reviews only past orders, not the current order the customer is about to place.*

**NOTE:** *By default, this trigger only looks back over the past 60 days of order history. Checking further back requires additional permissions — reach out to support if you need a longer lookback window.*

## **Customer Order Count**

The Customer Order Count Trigger enables you to display a funnel specifically for new or returning customers.

Here are some examples:

* You have a funnel with a Customer Order Count Trigger set to "**equal to 0**." If a customer has never placed an order before (first-time customer), the funnel will activate. If they have placed any previous orders, the funnel will not activate.
* You have a funnel with a Customer Order Count Trigger set to "**greater than 3**." If a customer has placed 4 or more previous orders, the funnel will activate. If they have placed 3 or fewer orders, the funnel will not activate.

**NOTE:** *This trigger is based on past purchases, not the current order.*

## **Customer Language**

The Customer Language trigger enables you to display specific offers based on the language a customer checked out in, creating a more personalized and engaging experience.

Here are some examples:

* You have a funnel with a Customer Language trigger set to "English." If a customer checks out in English, the funnel will activate. If they check out in any other language, the funnel will not activate.
* You have a funnel with a Customer Language trigger set to "French." If a customer checks out in French, the funnel will activate. If they check out in any other language, the funnel will not activate.

<img alt="Configuring the Customer language trigger with a Select language dropdown in the funnel settings" />

**Note:** While most text within a funnel can be translated manually, some global elements such as button labels and certain words are controlled through the **Translations** section in Aftersells **Settings** and currently only support a single language across all funnels. This is an area of active development and will be improved in a future update.

<img alt="Aftersell Translations settings page with 1-Click upsell and Thank you page text fields" />

## **Once per Customer**

The Once per Customer trigger ensures a funnel only shows once per customer across all orders.

Here are some examples:

* You have a funnel with the Once per Customer trigger enabled. If a customer sees this funnel after their first purchase, they will not see it again on any future purchases, even if all other trigger conditions are met.
* You want to show a special "welcome offer" only to new customers on their first purchase. Enable the Once per Customer trigger to ensure the offer appears only once per customer, preventing it from showing on repeat purchases.

***

# Order Details & Time-Based Triggers

*These triggers depend on checkout details, marketing data, or timing.*

## **UTM Parameter**

A UTM Trigger is a marketing tool that activates specific actions based on UTM parameters in a URL. UTM parameters (Urchin Tracking Module) help track the effectiveness of online campaigns by providing details about the source, medium, and campaign name.

Here are some examples:

* You have a funnel with a UTM Parameter Trigger set to "**utm\_source = facebook**." If a customer clicks a link with `?utm_source=facebook` in the URL, the funnel will activate. If they arrive from a different source or no UTM parameter, the funnel will not activate.
* You have a funnel with a UTM Parameter Trigger set to "**utm\_campaign = summer\_sale**." If a customer clicks a link with `?utm_campaign=summer_sale` in the URL, the funnel will activate, allowing you to show campaign-specific offers.

When users click a link with UTM parameters, the trigger can identify these tags and perform actions such as:

* Displaying tailored offers or content based on specific campaigns.
* Segmenting visitors by their entry points to analyze marketing channel effectiveness.
* Creating personalized experiences with customized messages or redirects.

If you're interested in setting up Direct-to-Checkout UTM Links, please follow this [link](/aftersell/how_to_use_direct_to_checkout_utm_links).

⚠️ **Known limitation:** UTM triggers do not fire when customers use express checkout methods (Shop Pay, Apple Pay, Google Pay, PayPal, etc.) because express checkout bypasses the standard cart flow where UTM parameters are captured. If you are using UTM triggers for campaign tracking, consider using other trigger types (product, collection, order value) as alternatives, creating separate funnels for general traffic that do not rely on UTM parameters, or tracking campaign performance through other analytics tools.

## **Currency**

The Currency Trigger allows you to control whether customers see a funnel based on whether they check out in your store's default currency or in an international (non-default) currency. It does not let you target individual named currencies — instead, you choose between two options: **Default store currency only** or **International currencies only**.

Here are some examples:

* You have a funnel with a Currency Trigger set to "**Default store currency only**." If a customer checks out in your store's default currency, the funnel will activate. If they check out in any international (non-default) currency, the funnel will not activate.
* You have a funnel with a Currency Trigger set to "**International currencies only**." If a customer checks out in a currency other than your store's default, the funnel will activate. If they check out in your store's default currency, the funnel will not activate.

# General Rules for Currency Display

* Thank You Page offers and upsells adjust to the customer's currency, offering a seamless experience for shoppers in various markets. This means all prices are displayed in the same currency as the market chosen by the customer or their browsing session.

**Since Post-purchase upsells aren't shown to customers checking out in a currency other than your store's default**, everyone still sees the Thank You Page. By using the Currency Trigger, you can tailor specific Thank You Page offers for different currencies, enabling you to provide targeted product recommendations and offers that align with the customer's checkout currency. Alternatively, Thank You page offers can be used to create universal visibility for all customers, irrespective of country or currency, bypassing Shopify's post-purchase multi-currency restrictions. This approach offers a wider scope for upsell promotions.

# Shopify Markets Integration

* If your store uses Shopify Markets to display different currencies based on customer location, Aftersell integrates seamlessly to ensure products are displayed in the correct local currency.
  * Shopify Markets automates the process of showing localized currencies and pricing for upsell offers.
  * For details on setting up Shopify Markets, refer to Shopify's official documentation: [Shopify Markets Documentation](#).

# Important Considerations

* Always ensure that your store's default currency settings align with your operational requirements and customer expectations.
* For post-purchase upsell offers, check currency configurations to ensure compatibility with your target markets.

# Thank You Page Offers

* **Localized Pricing:** All Thank You Page upsells automatically adjust to the customer's currency. This ensures that a single funnel can offer localized pricing to all customers.
* **Currency Conversion:** Thank You Page upsells display in the checkout currency, even if the order currency differs from the store's default currency.

# Post-purchase upsell offers

* **Multi-Currency Limitation:** Post-purchase upsell offers do not support multi-currency. For this reason, customers will not see offers unless your store currency matches the expected currency.

## **Device Type**

The Device Type Trigger allows you to scope a funnel to customers on a specific device type — Desktop only or Mobile only. When enabled, the funnel only displays if the customer's device matches your selection.

Here are some examples:

* You have a funnel with a Device Type Trigger set to **Desktop only**. If a customer completes checkout on a desktop browser, the funnel will activate. If they check out on a mobile device, the funnel will not activate.
* You have a funnel with a Device Type Trigger set to **Mobile only**. If a customer checks out on a mobile device, the funnel will activate. If they check out on a desktop, the funnel will not activate.

**Note:** If a customer's device type cannot be detected (for example, when using a legacy storefront script), the trigger fails closed — the funnel will not display. This is the same behavior as other triggers when required data is unavailable.

## **Shipping Country**

The Shipping Country Trigger allows you to include or exclude customers from viewing a funnel based on their shipping destination country. For example, you can configure a funnel to exclude products restricted to the US when the shipping address is from outside the United States. This ensures geographical restrictions are respected, aligning the funnel offers with region-specific product availability.

As a reminder, Post-purchase upsells won't display to customers checking out in a currency different from your store's default currency; however, everyone will still see the Thank You Page. By using the Shipping Country Trigger, you can create targeted Thank You Page offers for specific countries, allowing you to provide tailored product recommendations and offers based on the customer's shipping location. This also means adjusting your shipping costs for different countries.

## **Random Sample**

The Random Sample Trigger enables you to control funnel visibility for a random subset of customers. This trigger is ideal for testing new funnels with a small percentage of your customer base or surprising a select group of customers with special offers.

Here are some examples:

* You have a funnel with a Random Sample Trigger set to "**25%**." The funnel will randomly activate for approximately 25% of customers who meet all other trigger conditions. The remaining 75% will not see the funnel.
* You want to A/B test two different upsell offers. Create two funnels, each with a Random Sample Trigger set to "**50%**." Each funnel will show to approximately half of your customers, allowing you to compare performance.

By applying the Random Sample Trigger, you can effectively test new strategies, measure impact, or add an element of exclusivity to your promotions, creating unique experiences for "**lucky**" customers who meet the criteria.

## **Date/Time**

The Date/Time Trigger allows you to schedule the visibility of a funnel based on specific dates and times. With this trigger, you can activate or deactivate offers according to a set schedule, making it ideal for time-sensitive promotions, seasonal campaigns, or exclusive, limited-time deals.

Here are some examples:

* You have a funnel with a Date/Time Trigger set to activate "**between December 1 and December 25**." The funnel will only activate for orders placed during this date range, perfect for holiday promotions.
* You have a funnel with a Date/Time Trigger set to activate "**after January 1, 2026**." The funnel will only activate for orders placed on or after this date, useful for launching new year promotions or product releases.

The Date/Time trigger includes a timezone selector dropdown, allowing you to choose the timezone your schedule should run in (for example, "GMT-07:00 - (MST) America/Phoenix"). Dates are selected using a date picker calendar, and you can set a start date, end date, or both to define the active window.

**Note:** Make sure you select the correct timezone for your store's primary audience. If your store serves customers across multiple time zones, choose the timezone most relevant to your promotion schedule.

## **Shipping Method**

The Shipping Method Trigger enables you to control funnel visibility based on the customer's chosen shipping option at checkout. This trigger allows you to include or exclude customers from specific offers depending on their selected shipping method.

Here are some examples:

* You sell a perishable product that requires overnight shipping. Set the Shipping Method Trigger to include "Overnight" or "Express" so the upsell only appears to customers who chose fast shipping and will receive their order quickly.
* You want to offer an expedited shipping upgrade. Set the trigger to include "Standard Shipping" so only customers who chose the slower option see the upsell to upgrade.
* You offer local pickup. Set the trigger to exclude "Local Pickup" so that shipping-dependent offers (like shipping protection) do not appear to customers collecting in-store.

**Note:** Matching is case-insensitive and checks whether your Shopify shipping rate name *contains* the text you enter in the trigger — it doesn't need to be an exact, full match. For example, a trigger value of "express" will match shipping rate names like "Express Shipping" or "2-Day Express."

***

# Conditional Logic

Post-purchase triggers work together using simple logic: all triggers must be met (**AND logic**), and within each trigger, only one condition needs to match (**OR logic**).

For more details on how our trigger logic is applied, check out this article:

[Understanding Conditional Logic](/aftersell/understanding_conditional_logic_for_post_purchase_triggers)

<Note>
  **Combining product conditions.** A funnel has a single Product/Collection block, and everything inside it uses OR logic — the trigger fires when **any one** of the listed products or collections is in the order. There is no AND setting between separate products or collections in that block.

  If you need the order to contain product A **and** product B, use the **Product Quantity** trigger instead. It has a **Condition Logic** setting you can set to AND, with one row per product. It is the only product-based trigger that supports AND across rows.
</Note>


# Post-purchase widgets
Source: https://docs.aftersell.com/aftersell/post_purchase_widgets

Reference for Aftersell post-purchase widgets: funnel-wide progress bar and timer, plus offer-level product, text, discount, and testimonials widgets.

***

# Funnel-wide widgets

## Progress Bar

The **Progress Bar** shows customers where they are in the post-purchase flow.

When enabled, the progress bar appears on all upsell offers within the funnel. Any changes made to the progress bar apply across the entire funnel.

<img alt="Post-purchase progress bar with Cart, Order placed, Special offer, and Done steps" />

**Configuration options**

* Toggle the progress bar on or off for the funnel
* Choose a display style:
  * **Minimal**
  * **Minimal with labels**
  * **Maximal**
* Select a **Black** or **White** appearance
* Adjust top and bottom padding to control spacing

***

# Offer-level widgets

Offer-level widgets control the content and behaviour of an individual upsell offer.

These widgets define what the customer sees on a specific upsell step, including messaging, urgency, product information, pricing details, and actions.

Each offer in a funnel can be customized independently using offer-level widgets, allowing you to tailor the experience at every step.

These widgets include:\
[Text](#text)\
[Timer](#timer)\
[Upsell Product](#upsell-product)\
[Product Selection](#product-selection)\
[Discount](#discount)\
[Badge](#badge)\
[Shipping](#shipping)\
[Image](#image)\
[Buttons](#buttons)\
[Price Breakdown](#price-breakdown)\
[Product Details](#product-details)\
[Variant & plan options](#variant--plan-options)\
[Layout](#layout)\
[Video](#video)\
[Testimonials](#testimonials)

***

## Text

The **Text** widget is used for headings and supporting copy throughout an offer.

It supports a heading and optional body text, with controls for font size, color, weight, alignment, strikethrough, and spacing.

Use the dynamic variable `{first-name}` to personalize messaging for each customer.

***

## Timer

The **Timer** widget adds urgency by displaying a live countdown.

While the timer is running, the offer remains visible. When the timer reaches zero, the upsell offer automatically disappears and the customer is moved forward in the funnel.

***

## Upsell Product

The **Upsell Product** widget is the heart of the offer. It defines which product is being shown and acts as the container for all product-related widgets below.

Everything that follows is configured within this widget.

***

## Product Selection

The Product Selection widget controls which product is shown in an upsell offer.

You can select a fixed product or dynamically determine the upsell product based on the customer's original order, allowing for both static and adaptive upsell experiences.

#### Product type options

* **Specific product**\
  Always displays the same product in the upsell.
* **Automatic upsell**\
  Dynamically selects a product using predefined upsell logic.
* **Most expensive in cart**\
  Uses the highest-priced item from the customer's original order.
* **Least expensive in cart**\
  Uses the lowest-priced item from the customer's original order.

#### Changing the product

The selected product appears at the top of the widget. To change it:

1. Click **Change product**
2. Select a product type
3. Choose or confirm the product

When browsing the **Products** tab in the picker, you can check **Active products only** to hide Draft and Archived products from the list. This filter is off by default and only applies to the Products tab — Collections are not affected.

<img alt="Aftersell offer editor showing the Edit upsell product panel beside a live offer preview" />

#### Identifying products with identical names

If your store has multiple products or variants with the same title, enable the **Show IDs** toggle in the product picker to display the numeric Shopify product ID and variant ID beneath each name. This makes it easy to confirm you are selecting the correct product.

The **Show IDs** toggle is available on the **Product** tab of the picker and is off by default. It is not available on the Collection tab.

***

## Discount

The **Discount** widget applies and displays promotional pricing.

You can choose between a percentage (%) discount or a fixed dollar (\$) discount. Custom discount text can be added if desired, and the discount can either reference the product's compare-at price or ignore it.

### Bulk discount shortcut for multi-product offers

For multi-product and collection offers, a **Discount** section appears directly in the Upsell Products widget settings — below the product selection area. This gives you a faster way to set or update discounts across multiple products without opening each product's individual settings.

The section is collapsed by default. When you expand it:

* A list of all products in the offer is shown, each with a checkbox and a badge displaying its current discount (for example, `17% off` or `$18.00 off`).
* Select the products you want to update using the checkboxes. All products are selected by default.
* A pill below the list shows how many products your changes will apply to.
* Use the discount type and value fields to set the discount. Changes apply only to the selected products — unselected products keep their existing discounts.

#### Mixed discounts across products

When selected products have different discount settings, the fields show placeholder text to indicate the variation:

* If products have different **discount types** (for example, some are % off and others are \$ off), the type selector shows **Mixed**.
* If products have different **discount values** or types, the value field shows **Multiple values** with a note that entering a new value will override each selected product's current discount.

#### Info icon on product rows

An info icon (i) appears beside a product's discount badge when that product has additional discount settings configured — such as a custom discount title, a compare-at price, or a subscription discount. Hovering over the icon shows a summary of those extras.

***

## Badge

The **Badge** widget highlights key product attributes such as popularity or urgency.

You can select a predefined badge label, choose from multiple visual styles, include an icon, and control where the badge appears in the offer or directly on the product image.

<img alt="Post-purchase offer showing a Trending badge above the product title" />

Custom badge images can be uploaded from **Advanced badge settings** (SVG or PNG, up to 10MB).

<Note>
  Badge editing is available on V2 offers only. V1 offers preserve any badges that were previously configured, but badge settings cannot be edited on V1 offers.
</Note>

### Badges section: offer badge and product image badge

The Badge widget's settings are a unified **Badges** section with two independent controls, each drawing from your saved badge library:

* **Offer badge** — placed in the offer content, not on the product image. Select any saved badge and configure:
  * **Position in offer** — Above product title, Adjacent to product price, or Below product price.
  * **Spacing from price** — the gap when the badge is adjacent to the price (0–3); shown only for the Adjacent position.
  * **Badge size** — how large the badge appears in the offer.
* **Product image badge** — overlaid on the product image. Select a saved badge and configure:
  * **Size on image** — Small (1×), **Medium (1.5×, the default)**, or Large (2×).
  * **Position on image** — the nine positions from Top left through Bottom right.
  * **Show badge on all product images** — off by default, so only the primary image is badged; enable it to badge every image in the product carousel. Applies to single- and multi-product offers.

Both badges are optional and are set independently — removing one leaves the other unaffected. On a multi-product spotlight layout, the spotlight (hero) product does not support a product image badge. For box offers, both the offer badge and the product image badge are available on each box candidate.

### Creating and managing saved badges

Saved badges are reusable across offers and are created and edited from the badge builder, reached from the Badges section. Open the section, click **Create badge** (or pick an existing badge), give it an internal name, choose a type, and save.

* **Text badge** — configure the text, a **shape** (Pill, Rectangle, Circle, Ribbon, or Starburst), an optional icon, a background color, and a text color. Preset text suggestions (for example, Bestseller, Free shipping, New, Lowest price, or Limited time offer) are available for quick setup. **Font size** sets the text size in pixels, measured against a 500 px reference image and scaled proportionally when the badge is rendered.
* **Image badge** — upload a raster image (PNG, JPEG, WebP, GIF, or AVIF). **Badge size** sets the image height in pixels; the width adjusts to preserve the aspect ratio.

## A live preview updates as you configure the badge. Editing a saved badge updates every offer that uses it once the funnel is saved, and deleting one removes it from every offer that uses it.

## Shipping

The **Shipping** widget controls how shipping costs are communicated.

You can either offer free shipping or charge for shipping by setting a specific shipping price.

***

## Image

The **Image** widget controls how product images are displayed.

It includes options to adjust the main image size, add a border, enable an image carousel, and upload a custom product image from **Advanced image settings**.

***

## Language

The **Language** section controls which language is used for all system text in the offer, including button text, subscription labels, pricing labels, and other non-editable strings.

Select a language from the **Language** dropdown to automatically translate system text for that offer. Aftersell supports 32 languages.

This setting does not affect badges or custom text fields — only system-generated text is translated.

***

## Buttons

The **Buttons widget** controls how customers accept or decline an upsell during checkout.

You can customize how the buttons behave and appear, including:

* Selecting the **default accept button text**
* Requiring a **confirmation click** before an upsell is accepted
* Changing the **decline button style** (for example, button or link)
* Adjusting **button alignment** and width
* Adding optional **supporting text** above or below the buttons, with styling controls and dynamic variable support

### Button text

You can configure the accept button text for your post-purchase offers using the **Default accept button text** dropdown. The available options depend on the offer type:

**Standard offers:**

* **Pay Now** - Displays "Pay Now • \[product total price]" (or "Add Now • Free" for free products)
* **Accept Offer** - Displays "Accept Offer" regardless of price

**Subscription Upgrade offers:**

* **Upgrade Subscription** - Displays "Upgrade Subscription" (default for new Subscription Upgrade offers)
* **Accept Offer** - Displays "Accept Offer" regardless of price
* **Pay Now** - Displays "Pay Now • \[product total price]" (or "Add Now • Free" for free products)

To translate button text, use the **Language** section above the Buttons section.

### Button layout options

You can also control the **position of the accept and decline buttons** relative to each other. The following layouts are supported:

* **Accept above decline** - Displays the accept button above the decline option
* **Decline above accept** - Displays the decline option above the accept button
* **Accept beside decline** - Displays the accept and decline buttons side by side

These layout options give you more flexibility to match your desired checkout experience and messaging hierarchy.

***

## Price Breakdown

The **Price Breakdown** widget adds clarity around pricing.

It can display shipping and tax, include extra details such as subtotal and discounts, and be aligned or positioned near the payment buttons for maximum clarity.

### Hide shipping adjustment line

When your offer is configured as a replacement upsell (using the "Replace item in original order with upsell" setting), the price breakdown includes a **Shipping adjustment** line that reflects any shipping cost difference between the original and replacement product.

You can suppress this line using the **Hide shipping adjustment line** checkbox, which appears in the Price Breakdown section only when a replacement upsell is configured. This setting is off by default, so existing offers are unaffected.

* When checked, the shipping adjustment line is hidden from the customer's price breakdown.
* When unchecked, the shipping adjustment line is shown as normal.

This setting only affects the shipping adjustment line on replacement upsell offers. The standard shipping line on non-replacement offers is not affected.

***

## Product Details

The **Product Details** widget controls how key product information is presented.

It supports product review ratings (automatically hidden if no reviews exist), an optional quantity selector, and the ability to skip the offer if the product already exists in the original order.

Product titles and prices are fully stylable and support some dynamic variables including `{product}`, `{original-price}`, `{current-price}`, `{savings}`, and `{savings-line}`.

An optional offer description can be added to reinforce value or urgency.

### Product review star colors

When **Show product reviews rating** is enabled, you can customize the colors of the star rating display:

* **Star color** — the color of filled (active) stars. Defaults to `#fdcc0d` (yellow).
* **Empty star color** — the color of unfilled (inactive) stars. Defaults to `#d1d5db` (light gray).

To change the colors, open the **Product Details** widget settings, enable **Show product reviews rating**, and use the color inputs to set your preferred hex values.

### Quantity selector presets

When the quantity selector is enabled, you can configure a **preset quantity** to control how many units are shown or allowed when the offer is displayed. The following preset options are available:

* **Fixed** — Sets a specific quantity that the customer starts with. The quantity selector is hidden and the customer cannot change the quantity.
* **Percentage of purchased quantity** — Sets the quantity as a percentage of the number of units the customer originally purchased.
* **Minimum quantity** — Sets a floor on the quantity. The customer starts at this value and can increase from there.
* **Maximum quantity** — Sets a cap on the quantity. The customer starts at 1 and cannot increase past the configured maximum (up to 20). A message is shown to the customer indicating the maximum quantity for the item.

### Description position

For single-product offers, you can control where the product description appears in relation to the CTA buttons:

* **Default (above buttons)** - The description appears above the accept and decline buttons
* **Below buttons** - The description appears below the accept and decline buttons

This setting allows you to adjust the layout to better match your messaging hierarchy and design preferences.

***

## Variant & plan options

The **Variant & Plan Options** widget controls variant visibility, selection, and subscription plan locking.

You can show or hide out-of-stock variants, hide the entire product if all variants are unavailable, and control whether variant options with a single choice are shown. **Advanced settings allow you to hide the variant selector entirely**.

Variant preselection options include Smart matching to the initial purchase, Unselected, requiring the user's selection or First available variant.

For products with multiple variant options, all options are displayed and an in-stock variant is preselected when available; out-of-stock options are shown as unavailable. For products with a single variant option, out-of-stock options are hidden.

### Subscription plan locking

When offering subscription products with multiple subscription plans, you can lock the offer to a specific plan. This prevents customers from changing the subscription plan during the post-purchase experience, ensuring they receive the exact subscription option you've configured.

**To lock a subscription plan:**

1. In the **Variant & Plan Options** section, locate the **Lock subscription plan** dropdown
2. Select a specific plan from the dropdown
3. The plan is now locked — customers will see the plan name as static text instead of a changeable dropdown

<Frame>
  <img alt="Variant and Plan Options panel with the Lock subscription plan dropdown" />
</Frame>

**When a plan is locked:**

* Customers see the plan name displayed as text
* The plan selector dropdown is hidden
* Customers cannot change the subscription plan
* If the locked plan is no longer available in Shopify, the offer gracefully falls back to showing all available plans

**Automatic reset:**

The locked plan setting automatically resets if you change the product's purchase option to one-time purchase only (removing the subscription option).

### Variant selector position

You can control where the variant selector appears in relation to the CTA buttons:

* **Above CTA buttons (default)** - The variant selector appears above the accept and decline buttons
* **Below CTA buttons** - The variant selector appears below the accept and decline buttons

When both the variant selector and product description are positioned below the CTA buttons, you can control their order:

* **Variant selector first** - The variant selector appears before the product description
* **Description first** - The product description appears before the variant selector

You can also adjust the top and bottom padding of the variant selector to fine-tune spacing and create the desired visual layout.

***

## Layout

The **Layout** widget controls the overall structure and spacing of the upsell.

You can choose between a single-column or two-column layout, adjust the maximum layout width, and fine-tune top and bottom padding to create a clean, readable experience.

***

## Video

The **Video** widget adds a clickable thumbnail to an offer that opens a hosted video player in a new tab, with a styled backdrop and a button to return to the upsell. The video plays in a new tab rather than inline, so the upsell offer stays open in the original tab.

The widget also supports a **backdrop color** to match your brand or focus attention on the player, and **layout settings** for alignment (left, center, right), and top and bottom padding.

To preview the customer experience, click the thumbnail in the **offer preview** in the editor. The hosted video player opens in a new tab exactly as it will on the storefront, so you can confirm the thumbnail, CTA, and close behaviors before publishing.

### Browser compatibility

The video widget opens the player in a new tab. On desktop this always works, so the widget always shows.

On mobile it works the other way around: Aftersell shows the widget only in browsers it recognises as able to open a new tab without pushing the customer out of checkout. That covers native mobile browsers — Safari, Chrome, Firefox and other well-known ones — along with the Facebook and Instagram in-app browsers.

**Every other mobile browser hides the widget.** That includes in-app browsers such as the Google app, TikTok and Pinterest, generic webviews, and anything Aftersell doesn't recognise. Because unrecognised browsers are hidden rather than shown, the set of environments where the widget won't appear isn't a fixed list — a browser Aftersell hasn't seen before hides it too.

Where the widget is hidden, you can upload a **Fallback image** to show in its place — a static promotional image or a branded graphic, for example. It's displayed without a link or play button. If no fallback image is set, nothing renders in place of the widget.

<Tip>
  Set a **Fallback image** on any video widget you publish. Because anything unrecognised is hidden, your traffic sources alone won't tell you whether some customers are missing the widget — and without a fallback, those customers see nothing at all.
</Tip>

### Video source

The widget plays a single video from one of two sources. Use the **Upload** / **Link** toggle in the widget settings to choose which source the player uses:

* **Upload** — drag and drop or select an MP4, WebM, or MOV file (up to 50 MB) to host it directly in your Shopify Files. After uploading, Shopify processes the file and a preview appears in the editor.
* **Link** — paste a YouTube URL, a Vimeo URL, or a direct link to a hosted video file (for example, an MP4 on your own CDN).

You can fill in both, but only the source selected in the toggle plays — the other is kept behind its tab and is **not** used as an automatic fallback. If only one source is set, that source plays regardless of the toggle.

You must set at least one source — an uploaded video or a video link — before you can save the widget.

#### Supported link formats

The link field accepts the following:

* **YouTube** — use the standard video URL (for example, `https://youtu.be/VIDEO_ID` or `https://www.youtube.com/watch?v=VIDEO_ID`). YouTube Shorts URLs (`youtube.com/shorts/...`) are not supported — open the video on YouTube and use the Share link instead.
* **Vimeo** — use the standard video URL (for example, `https://vimeo.com/VIDEO_ID`). Showcase URLs, and channel or profile pages that don't point at a specific video, are not supported — use the individual video's URL from its address bar. A channel or group URL that includes the numeric video ID does work.
* **Direct file** — a publicly accessible HTTPS URL pointing to a video file (for example, an MP4 on your CDN).

#### Link validation

The editor validates your link at two points:

* **When you leave the field** — if the URL shape is recognisably wrong (for example, a YouTube Shorts link or a Vimeo showcase URL), an inline error explains what to use instead.
* **When you save** — the editor checks with the video provider to confirm the video is embeddable. If the video is private, deleted, or has embedding turned off, the save is blocked and the reason is shown on the link field. Fix the link and save again to continue.

If the provider check is unavailable (for example, due to a network issue), the save proceeds without blocking.

#### Shopify Files permission

Uploading a video requires the `write_files` permission. If this permission has not been granted, a banner appears in the upload area with an **Update** button. Click it to grant the permission and enable uploads.

#### Upload processing

After you drop or select a file, the uploader shows **Uploading…** while the file transfers, then **Processing…** while Shopify transcodes it. A preview appears once processing is complete. You can continue editing other widget settings while the video processes.

You can't save a widget whose only source is a video that is still processing — the save is blocked until transcoding finishes, or until you add a video link to use as the source in the meantime. If you discard changes or close the editor before saving, any in-progress uploads are deleted from Shopify Files.

Video links are validated when you save the widget.

### Thumbnail and watch-video CTA

Upload the image customers will see in the offer before they open the video. A watch-video CTA is automatically placed on top of the thumbnail to draw attention to the play action. You can style the CTA label text to match your brand. Thumbnails are not auto-generated from the video — they must be uploaded.

You can also upload a separate **mobile-only thumbnail**. When set, the mobile thumbnail is shown on mobile devices and the default thumbnail is used on desktop, so you can tailor the image for each screen size.

### Fallback image

The **Fallback image** setting lets you upload an image to display when the video widget is hidden because the customer's browser can't open the player — see [Browser compatibility](#browser-compatibility). The fallback image is shown without a link or play overlay; it's a static image only.

If no fallback image is uploaded, nothing renders in place of the widget.

### Autoplay

The **Autoplay** toggle controls whether the video starts playing automatically when the hosted player opens.

When autoplay is enabled, the video starts **muted**. Most modern browsers block autoplay of videos with sound until the customer interacts with the page, so playing muted is required for autoplay to actually fire reliably. Customers can unmute the video using the player controls once it has started.

If you would rather have audio play from the first frame, leave autoplay off and rely on the customer to manually click play on the video.

### Closing the video

There are three ways for a customer to close the hosted player and return to the upsell offer:

* **Back to offer button** — a button below the player that closes the tab and returns to the upsell.
* **Double-click anywhere** — double-clicking anywhere on the backdrop closes the player.
* **Auto-close on end** — when the video finishes playing, the player closes automatically.

Because the video opens in a new tab, closing the player closes that tab — the upsell remains in the original tab.

### Language and translations

The video player page's copy — the back-to-offer button label, the desktop and mobile hints, and the title and message shown when the video is unavailable — follows the offer's **Language** setting and can be customized under **Settings > Translations**.

***

## Testimonials

The **Testimonials** widget displays real product reviews on your post-purchase offer to build trust and reinforce the customer's decision to accept an upsell.

Reviews are pulled from your connected review app. The widget appears in the offer editor picker as **"Testimonials"** with a star icon.

To use this widget, you must have a review app connected in **Settings > Product Reviews**. Supported apps include Judge.me, Klaviyo, Okendo, and Yotpo. See [Review app integrations](/aftersell/checkout_widget_types#review-app-integrations) for setup instructions.

### Selection modes

The Testimonials widget supports two modes:

* **Manual** — You select a curated pool of reviews to display. Reviews are shown in the order you saved them.
* **Dynamic** — Reviews are automatically pulled from your review app's synced cache based on the products in the upsell offer. Reviews are keyed to the offer's products, not the customer's original order.

### Configuration options

* **Review app** — Select which connected review app to pull reviews from.
* **Mode** — Choose Manual or Dynamic.
* **Minimum rating** — Set the minimum star rating for reviews to display (for example, 4 stars and above).
* **Display toggles** — Show or hide individual review elements:
  * Star rating
  * Review title
  * Reviewer name
  * Review date
  * Verified buyer badge
* **Truncate review text** — Set a maximum character length for review text. Reviews exceeding this limit are clipped with an ellipsis.
* **Max reviews to show** — Set how many reviews appear, from 1 to 3.
* **Layout** — Arrange reviews **Horizontal** (side by side) or **Vertical** (stacked).
* **Padding** — Adjust spacing around the widget.

### Dynamic mode and review syncing

In dynamic mode, Aftersell imports reviews from your review app and stores them so they can be displayed on the offer. The first import happens automatically within 24 hours of connecting your review app, and then once a week after that.

To import reviews immediately, go to **Settings > Product Reviews** and click **Sync now** for your review app.

### Verified buyer badge

When the verified buyer badge is enabled, a **"Verified buyer"** label is shown on qualifying reviews. This label is automatically translated into the language set for the offer and supports 32 languages.

***

## Adding additional widgets

Widgets can be added either **above or below the Upsell Product widget**, allowing you to control the flow of information before or after the product itself.

Additional widgets that can be added include:

* **Image** - Display a supporting image to visually reinforce the offer.
* **Text** - Add supporting text to communicate key messages.
* **Text & Image** - Combine text and visuals to highlight value or explain the offer.
* **Extra Buy Button** - Add an additional call-to-action to encourage offer acceptance. Not available on offers that show more than one product.
* **Trust Badge** - Display trust signals such as guarantees, security, or credibility indicators.
* **FAQs** - Answer common customer questions to reduce friction and increase confidence.
* **Video** - Embed a video to demonstrate the product or tell your brand's story. See [Video](#video).
* **Testimonials** - Show real product reviews from your connected review app. Available on V2 offers. See [Testimonials](#testimonials).

To add a widget:

1. Choose whether you want the widget to appear **above or below** the Upsell Product widget
2. Click **Add widget** in the selected section
3. Select and configure the widget you'd like to include

***

To learn more about what post-purchase offers are, how they work, and how to start using them with Aftersell, take a look at [this article for more information](/aftersell/post_purchase_overview).

***

The behavior and appearance of widgets are limited to the configuration options available in the editor.\
Further customizations are not supported due to Shopify limitations.

***

## Need help?

If you have questions or need assistance setting up your post-purchase offers, our support team is here to help. You can reach out anytime through the in-app chat or by contacting us via email.


# Potential workarounds for fulfillment flow issues
Source: https://docs.aftersell.com/aftersell/potential_workarounds_for_fulfillment_flow_issues

Two workarounds for post-purchase fulfillment problems: handling On hold orders natively or using manual payment capture as a fulfillment hold.

## Solutions to fulfillment problems

To solve fulfillment problems, we must prevent orders from being fulfilled until we are certain that the customer is no longer on the post-purchase page. This ensures that the order is in it’s final state and will not have extra items added.

There are two common solutions to fulfillment problems:

1. (*Preferred*) Look for a setting in the fulfillment service to handle **On hold** orders. If the fulfillment services can natively handle **On hold** orders then enabling the setting should resolve any issues. Many older systems do not have this setting though, in which case:
2. Use the payment status of the order as a makeshift fulfillment hold. Almost all fulfillment systems have an option to not fulfill orders that are not marked as **Paid**. This solution is described in detail below as it is non-intuitive and is generally more involved.

## Using payment status as a makeshift fulfillment hold

The core principle of this solution is that we only want to mark an order as **Paid** when it can be fulfilled (i.e., there is no fulfillment hold).

By default, Shopify captures payment immediately when an order is placed. This means that orders will be marked as **Paid**. To change this behaviour, you can go to ***Shopify > Settings > Payments > Payment capture method > Manage*** and change the payment capture method to “**Manually**”.

<img alt="Shopify Payment capture method dialog with the Manually option selected" />

With the payment capture set to manual, we get to control when the payment is captured and thus when the order is imported into the fulfillment service. To do this, we can set up a Shopify Flow to capture the payment when and order is no longer **On hold**. When the payment is captured, the order will be marked as **Paid** and the fulfillment system can then import the final order which would include the post-purchase upsell item.

Note that “fulfillable” is used to check whether or not an order is **On hold.** This is the easiest way to check for holds in a Flow.

<img alt="Shopify Flow workflow capturing payment when an order's Fulfillable field is true" />

The same principles apply to other fulfillment services. If you need help wiring this up for a specific one, contact support through the in-app chat.


# Progress bars & product badges
Source: https://docs.aftersell.com/aftersell/progress_bars_product_badges

This article outlines how the Progress bar & product features work.

You can find these features in the **1-click upsell editor**, in the left sidebar under the **Funnel-wide widgets** group (which holds the progress bar and the Badge widget):

<img alt="Upsell editor sidebar highlighting the Funnel-wide widgets progress bar and the new Badge widget" />

## Progress bars

The **Funnel-Level** widget allows you to add a progress bar to one upsell and have it automatically applied to all upsells within the same funnel. This ensures a consistent experience across offers while reducing manual setup for merchants.

* The widget is always available but marked as hidden for existing offers and funnels.
* It is enabled by default for newly created funnels.
* Merchants can still upload a custom progress bar using the **Image** widget if they prefer a custom design etc.

  * You currently cannot translate these widgets and therefore have to upload custom images with the personalized translations you require. Translations and more options will be available soon!

### Settings

<img alt="Edit Progress Bar Widget panel with style, appearance, and padding controls beside the offer preview" />

### Style

Minimal

<img alt="Minimal style progress bar showing cart, dollar, gift, and checkmark icons without labels" />

Minimal with labels

<img alt="Minimal with labels progress bar showing Cart, Order placed, and Done milestones" />

Maximal

<img alt="Maximal style progress bar with cart, dollar, gift, and checkmark milestone icons" />

### Appearance

Black

<img alt="Black appearance progress bar displayed above the upsell offer preview" />

White

<img alt="White appearance progress bar displayed above the upsell offer preview" />

***

## Product Badges

**Product Badges** let merchants highlight key product details directly on the offer. These badges help draw attention to important features or offers, increasing visibility and buyer confidence.

* Available as an option on each product.
* Merchants can upload their own custom badges.
* Colors, text, and icons cannot currently be edited, but customizable templates will be available soon.

### Settings

## Badge labels Options:

* **Bestseller** - Ideal for highlighting products with the highest sales or strongest performance to boost trust and social proof.
* **Trending** - Great for showcasing products that are currently gaining traction or experiencing high engagement.
* **New** - Best for drawing attention to newly launched products or offers.
* **Lowest Price** - Useful for promoting discounted or best-value items to encourage quick conversions.
* **Ships Free** - Perfect for emphasizing free shipping offers, helping reduce purchase hesitation.

## Appearance Options

Badges come in four appearance styles to match different funnel designs and brand aesthetics:

* **Vibrant** - Bright and eye-catching, ideal for drawing immediate attention to key offers.
* **Vibrant Inverse** - A variation of Vibrant with inverted colors for a bolder contrast.
* **Classic Dark** - Clean and professional, best for lighter backgrounds.
* **Classic Light** - Subtle and minimal, designed for darker backgrounds or a softer look.

## Position in Offer

Badges can be placed in different positions within the offer layout to best fit your design and draw attention where it’s most effective:

* **Above Product Title** - Great for immediate visibility before the shopper reads product details.
* **Adjacent to Product Price** - Ideal for reinforcing urgency or value near the price point.
* **Below Product Price** - Best for subtle messaging that supports the purchase decision without distraction.

***

## Why It Matters

Progress bars have consistently shown positive results in improving both revenue per visitor (RPV) and conversion rates across many merchants, including those using Smart Funnels.

Similarly, **Product Badges** have proven effective in enhancing trust and buyer awareness, leading to measurable improvements in overall funnel performance.


# Quickstart guide to Aftersell
Source: https://docs.aftersell.com/aftersell/quickstart_guide_to_aftersell

This article outlines how to activate Aftersell, set up post-purchase offers, and deliver a seamless funnel experience for your shoppers

This guide walks you through setting up Aftersell's post-purchase funnel from start to finish, from creating your trigger to customizing post-purchase offers and optimizing your thank-you page.

Aftersell seamlessly integrates into your Shopify checkout flow, allowing you to deliver targeted offers immediately after a purchase without disrupting the customer experience.

***

# Setting up your first funnel

When you open Post-purchase Funnels for the first time, you'll see a **"Start with a template"** gallery instead of a blank screen. Pick a template that fits your store and click **Use this template** — Aftersell creates the funnel and takes you straight into the editor to customize it.

Available templates:

* **Classic upsell** — Offer one more of what the customer just bought, at a discount. A simple starting point.
* **Bestseller bundle** — A full upsell flow with a follow-up multi-product offer and a downsell. Great for catalog stores.
* **Thank-you boost** — A friendly thank-you message on the order confirmation page.

If you'd prefer to start from scratch, use the **Add funnel** button (available once you have at least one funnel) and select **Create manually**. If you'd like to learn more about post-purchase funnels and how they work, check out [this article](/aftersell/post_purchase_overview).

***

# Triggers

Triggers can be utilized to display a funnel in particular situations, and they can be combined to effectively highlight funnels for specific scenarios.

### What triggers do

Triggers enable you to **control exactly when and with whom a funnel appears**. They act like filters or rules so that your funnel is shown only under specific conditions such as certain products, cart value or customer attributes

### Benefits of using triggers in funnels

* **Increase relevance and conversions** - Show personalized offers based on what the customer purchased (e.g., display a "Shoes" funnel after a shoe purchase).
* **Avoid irrelevant offers** - Exclude specific products, collections, discount codes, or regions where offers don't apply.
* **Personalize by customer type** - Target new or returning customers and tailor offers using tags or order history.
* **Run smarter campaigns** - Use random-sample triggers for testing or date/time triggers for limited-time promotions.
* **Maximize ROI** - Focus your efforts where they're most effective and maintain a smooth, trustworthy post-purchase experience.- **Refine targeting with exclusions** - Manage product/collection exclusions to ensure ineligible products never trigger upsell offers. This customization helps tailor campaigns for customer relevance and exclusivity.

### Show for all customers trigger

A **"Catch-All" funnel** uses the **Show for All Customers** trigger.

This funnel does not look for any conditions and activates **when an order doesn't meet the conditions of any other funnel**, acting as a **safety net** to ensure every customer still sees an upsell or thank-you page offer.

If you have other funnels created, **set this funnel to the lowest priority** so it only appears when no other funnel is triggered.

Want to understand each trigger in more detail? Take a look at [this article](/aftersell/post_purchase_triggers).

***

Post-purchase upsell offer

# Checkout upsells vs post-purchase upsells

Checkout upsells appear directly on the checkout page during the customer's purchase process, integrated with Shopify's checkout flow. Post-purchase upsells, on the other hand, are displayed immediately after the order is confirmed, aligning with Shopify's post-purchase ordering requirements.

Once you've selected your triggers, proceed to the next step to **create your offers**.<br />Below is a quick overview of how the offer flow works:

<img alt="Post-purchase funnel flow chart branching offers by accepted and declined upsells" />

### **Add your offer products**

Choose the type of upsell you'd like to offer. There are a few different options to choose from:

**Single Product**

* **Specific product** - Choose a specific product to display to your customers. This can be a popular item or one you'd like to promote more.
* **Automatic upsell** - Uses Shopify's AI to suggest a complementary product based on what's currently in the customer's cart.
* **Most expensive/Least expensive in cart** - Re-offers the item from the customer's original order that was either the most or least expensive. To further enhance this functionality, Aftersell leverages Shopify's Recommendation API. This enables more accurate and personalized product suggestions by considering factors such as customer behavior and product affinity. For more information, refer to Shopify's [Recommendation API Documentation](https://shopify.dev/docs/themes/product-merchandising/recommendations/related-products#recommendation-logic).

**Multi Product**

* **Specific products -** Choose multiple (up to 12) specific product to display to your customers at once
* **Collection** - Choose a specific collection for your customers to see
* **Automatic upsell** - Uses Shopify's AI to suggest multiple complementary products based on what's currently in the customer's cart. Similar to single-product upsells, multi-product suggestions utilize Shopify's advanced Recommendation API to tailor product collections dynamically based on customer behavior and preferences.

Please note that only **one product per upsell offer** can be accepted at a time, unless you're using **multi-step offers**. To learn more, check out [this article](/aftersell/how_to_create_a_multi_step_post_purchase_upsell) on multi-step upsells.

These upsell offers **add to your customer's order**, they don't replace items already in the cart.<br />To learn more about **replacement upsells**, contact our team through live support or by email at [**support@aftersell.app**](mailto:support@aftersell.app).

***

### Customize your offers

Once your offer products are chosen, you'll want to customize your offers to match your store's branding and focus on **why** the customer should add the upsell.

Each widget helps you build an offer that matches your brand and connects with your customers.

Here's a quick rundown of the widgets you can add:

* **Text** – Add headlines, short descriptions, or supporting text that explains why the offer is worth grabbing. Keep it simple and persuasive.
* **Timer** – Create urgency by showing a countdown timer (perfect for limited-time offers).
* **Upsell Product** – This is where you can choose whether your offer is to be shown as a one-time purchase, subscription or both!
* You can customize the **product selection**, apply a **discount**, or include a **badge** (like "Bestseller" or "New")

### Optional: Add a custom order tag

You can add a custom tag to track which specific offer a customer accepted. When configured, your custom tag is automatically applied to the order in Shopify alongside the standard "AfterSell Upsell" tag.

To add a custom order tag:

1. In the offer settings, find the **Order Tag** field
2. Enter your custom tag (up to 40 characters)
3. Save your changes

This helps you segment orders and track performance of specific offers. For more details, see [Configuring post-purchase offer settings](/aftersell/configuring_post_purchase_offer_settings).

Your post-purchase page is styled by your Shopify checkout branding. On Shopify Plus you can edit it in Aftersell; on other plans you edit it in the Shopify checkout editor, and the Aftersell preview will show default colours until you place a test order. See [Post-purchase branding settings](/aftersell/post_purchase_branding_settings).

Once you're happy with your offers and customizations, you're ready to move on to the final step of your funnel - The Thank You Page.

***

# Thank you page

The Thank You page is your chance to bring customers back for more! Use this space to encourage repeat purchases, share product recommendations, and strengthen brand loyalty.

To get started, click **"Edit Extensions Page"** this opens the editor where you can customize your Thank You page.

### Make the most of your thank you page

You can personalize your Thank You page using a variety of **widgets**. These let you highlight key products, answer customer questions, and add engaging content that keeps shoppers connected to your brand.

Here are a few popular ways to use them:

* **Product Recommendations** – Use specific products, automatic upsells or collections to drive repeat purchases.
* **FAQs** – Answer common questions to build trust and reduce support inquiries.
* **Text or Image Widgets** – Share thank-you messages, brand stories, or special offers like discount codes.

For a complete list of available widgets and detailed setup instructions, check out [this article](/aftersell/thank_you_page_extensions_overview).

### Important information

Once you're happy with your Thank you Page widgets, you'll need to add them to **both** the **Thank you and order status pages** in the Shopify editor. Skipping this step will cause the thank you page widgets to not display for your customers.

<img alt="Prompt to place Thank You widgets via the Open Shopify editor button" />

Add the Aftersell TY widgets in your Shopify Editor in two locations:

Thank you page

<img alt="Adding the Aftersell TY Product Recommendation block on the Shopify Thank you page" />

Order status page

<img alt="Adding the Aftersell TY Product Recommendation block on the Shopify Order status page" />

Once you've placed the app blocks on both the thank you and order status page, make sure to enable the widget and save your work.

<img alt="Clicking Enable on the inactive Product Recommendation widget in the Shopify editor" />

Now that everything has been set up, you can set the status of funnel to active

<img alt="Funnel list row with the Status toggle switched on to activate the funnel" />

**Note:** If a product recommendation on the Thank You page is accepted, it can either generate a new, separate order **or** be merged into the original order, depending on your settings. Refer to [this article](/aftersell/thank_you_page_extensions_overview) for more information.

For more information about the differences between post-purchase upsells and thank you page upsells, please refer to [this article](/aftersell/one_click_upsells_vs_thank_you_page_upsells).

***

# Smart funnel

If a manual funnel is a lot of work, you can use our Smart Funnel to automatically optimize and deliver the best post-purchase offers for you.

Smart Funnel uses Rokt's advanced AI and machine learning algorithms trained on millions of transactions to automatically show each shopper the most relevant post-purchase offer. It continuously analyzes your store's data and customer behaviour, improving in real time to deliver smarter results over time. Additionally, it seamlessly integrates Shopify's Recommendation API for generating specific product recommendations, combining Rokt's AI capabilities with Shopify's data-driven insights for optimal upsell presentation.

**Key benefits**

* **Personalized targeting:** Tailors offers to each customer using AI.
* **Optimized performance:** Adapts automatically to boost results.
* **Effortless setup:** Fully automated and easy to manage.

To get started with the smart funnel, you'll first want to click enable.

<img alt="Smart Funnel panel with the Enable button and an active status showing traffic and discount" />

From here, you can customize your Smart Funnel to fit your store's goals:

* **Traffic Allocation:** Decide how much of your traffic you want to run through the Smart Funnel instead of manual funnels.
* **Max Discount:** Set the highest discount the Smart Funnel can offer to your shoppers.
* **Default Products:** The Smart Funnel automatically uses AI-recommended upsells to help boost revenue.
* **Skip Products in Original Order:** Choose whether to exclude items your shoppers already have in their original order.
* **Highlighted Product (optional):** Feature a specific product you'd like to spotlight in the funnel.
* **Require Confirmation Click to Accept (optional):** Enable this to require customers to click the accept button twice—once to confirm their intent, and once to complete the purchase.

<img alt="Edit Smart Funnel dialog with traffic allocation, max discount, and default product fields" />

**Funnel priority**<br />Smart Funnel is set to **Priority 0**, so its offers appear before any manual funnels when eligibility criteria are met.

For more details about the Smart funnel, take a look at [this article](/aftersell/smart_funnel). For more details about customization and the AI Upsell Widget within the Smart Funnel, you may refer to the steps outlined in Shopify's Recommendation API documentation for deeper technical insights. Additionally, Shopify's Recommendation API uses algorithms designed to analyze factors such as purchase proximity, order frequency, and customer cart history. This technical backbone ensures high accuracy in product recommendations, directly driving customer satisfaction and revenue.

***

## **Need more help?**

If you have any other questions about post-purchase upsells, thank you page offers or the smart funnel, our support team is always happy to help through **live chat** or [**support@aftersell.app**](mailto:support@aftersell.app).


# Replacement upsells
Source: https://docs.aftersell.com/aftersell/replacement_upsells

How Replacement Upsells work in Aftersell and how to set them up, from variant and quantity swaps to converting a one-time purchase into a subscription.

Replacement Upsell lets you swap a one-time product in the customer's order for a different product on the post-purchase page. The replacement can be a subscription version of the same product, a different variant or quantity, or a completely different product. The customer accepts in one click, the original line item is refunded, and the replacement line item is added to the order.

<Note>
  Replacement Upsell is currently a Beta feature. To use it on your store, message support via the in-app chat and we will enable it on your account. The **Replace item in original order with upsell** toggle will not appear in the offer editor until it has been enabled.
</Note>

<Warning>
  Replacement Upsell only works when the original line item is a one-time purchase. If the customer's order already contains a subscription, the offer is silently skipped. To modify an existing subscription (change frequency, swap product, or both), use [Subscription Upgrade](/aftersell/subscription-upgrades) instead.
</Warning>

<Warning>
  When a customer accepts a Replacement Upsell, Aftersell charges the full replacement product price and refunds the original. The customer's bank statement will show two transactions, even though the net amount matches the displayed Accept Offer button. Plan your offer copy and post-purchase confirmation email so customers do not think they were double-charged.
</Warning>

## Which feature do you need?

Three subscription-adjacent post-purchase features, three different jobs. Use this flow to pick the right one.

<Info>
  **Does the customer's order already contain a subscription?**

  → **Yes** → Use [Subscription Upgrade](/aftersell/subscription-upgrades). It modifies the customer's existing subscription contract in Recharge, Skio, or Loop (change frequency, swap product, or both).

  → **No** → continue below.

  **Do you want the customer to keep what they bought AND get a recurring subscription, or replace what they bought entirely?**

  → **Keep what they bought + add a new subscription on top** → Use [Subscription Upsell](/aftersell/subscriptions_in_post_purchase_offers).

  → **Replace what they bought with something else** (subscription version, different product, different variant or quantity) → Use **Replacement Upsell** (this guide).
</Info>

## What is a Replacement Upsell?

When a customer accepts a Replacement Upsell:

1. The original one-time line item is **refunded** in Shopify.
2. The replacement line item is **added** to the same order, either as a one-time purchase or a subscription (depending on what you configured).
3. The customer pays for the replacement on the same order.
4. Their statement shows two transactions: the refund of the original, and the charge for the replacement. The displayed Accept Offer button reflects the **net difference** between the two prices.

This is implemented using Shopify's post-purchase API:

* For a one-time replacement (different variant, quantity, or product), Aftersell sends an `add_variant` changeset.
* For a subscription replacement, Aftersell sends an `add_subscription` changeset.
* The original line item is removed via Shopify's refund API.

Aftersell does not call your subscription app's API directly for subscription replacements, the subscription is created by Shopify's native Subscription API and your subscription app picks it up via its own Shopify integration.

## What Replacement Upsell can do

Replacement Upsell supports four scenarios. In each case, the **original line item must be a one-time purchase**. The replacement can be either one-time or subscription.

* **One-time to one-time, same product, different variant.** For example, swap the Twin size for the Queen size.
* **One-time to one-time, same product, different quantity.** For example, swap a single bottle for a 3-pack of the same item. Enable **Override quantity** on the replacement to set the quantity that ships.
* **One-time to one-time, completely different product.** For example, swap a starter bottle for a full-size version of a different SKU.
* **One-time to subscription.** For example, swap the one-time bottle for a monthly subscription of the same bottle, or for a subscription version of a different product. This is the most common use case.

## What Replacement Upsell cannot do

These scenarios are **blocked by Aftersell at offer-display time**. The offer will silently skip if the customer's order matches any of them.

* **Subscription to one-time.** Removing the subscription line item does not cancel the subscription contract in Recharge, Skio, or Loop. The customer would still be billed and also receive the replacement.
* **Subscription to a different subscription.** Same root cause as above, plus Shopify's "one subscription per order" rule blocks adding a new subscription to an order that already contains one.
* **Subscription to subscription variant or frequency swap.** Same root cause.

If you need to change a customer's existing subscription, use [Subscription Upgrade](/aftersell/subscription-upgrades) instead. Subscription Upgrade modifies the existing contract in Recharge, Skio, or Loop directly, without trying to remove and re-add the subscription line.

<Tip>
  Whenever a Replacement Upsell is skipped (a blocked scenario above, an unsupported payment gateway, or a discounted trigger line), Aftersell automatically tries to show the **downsell** offer in the same funnel instead. Set up a downsell as a fallback whenever you use Replacement Upsell so the shopper still sees an offer.
</Tip>

## What the customer sees

Understanding the customer's view prevents the most common support ticket: "Why was I double-charged?"

### In the post-purchase offer

The Accept Offer button shows the **net difference** between the original and the replacement. For example, if the customer bought a \$30 bottle and you offer a \$45 3-pack, the Accept button reads "Add \$15.00 to your order." If the replacement is cheaper than the original, the button reads as a credit.

The offer card shows the replacement product's image, title, and price. The offer card uses the variant-specific image when one is tagged on the variant in Shopify. If the variant has no image tagged, the offer card falls back to the parent product's first image. This means swapping between two variants of the same product may or may not change the image, depending on whether each variant has its own image set up in Shopify.

### On the Shopify order after acceptance

The order ends up showing both:

* The original line item with a **refund** applied to it.
* The new line item for the replacement, charged at full price.

The order total reflects the net result, but the customer's bank statement will show two transactions, one charge for the replacement and one refund for the original. This is how Aftersell processes Replacement Upsell acceptances at the payment level. The net amount matches the displayed Accept Offer button.

To reduce confusion:

* Include a line in the offer copy that explicitly describes the refund-and-replace mechanic. For example: "When you accept, we will refund the original item and charge for the replacement. You will see two line entries on your statement, the net is the upgrade price shown on this button."
* Enable Aftersell's automatic refund-notification email for replacement upsells, which sends the customer a confirmation explaining the refund.

### In the subscription provider portal (when replacement is a subscription)

If the replacement is a subscription, the customer will see the new subscription in your subscription provider's customer portal (Recharge, Skio, Loop, Appstle, Smartrr, Stay.ai). The portal is owned by your subscription provider, not by Aftersell. Make sure your subscription provider's welcome email is configured to send within minutes of acceptance.

## Compatible subscription platforms

When the replacement is a subscription, Replacement Upsell works with any subscription app that uses Shopify's native Subscription API. Aftersell does not call provider APIs directly for this flow, the subscription is created by Shopify and your subscription app picks it up via its own Shopify integration.

Compatible providers include Recharge, Skio, Loop, Stay.ai, Appstle, Smartrr, Bold Subscriptions (when running on Shopify's native subscriptions API), and Shopify's native selling plans.

If your replacement target has a prepaid subscription plan configured (for example, every 3 months charged upfront), confirm with your subscription provider that prepaid is supported as a replacement destination. Prepaid handling varies by provider.

## Payment method requirements

Aftersell explicitly blocks Replacement Upsell on some payment gateways because they cannot reliably support the refund-and-recharge pattern in the post-purchase window:

* **Authorize.net** (`authorize_net`). Authorize.net requires transactions to settle before refunds can be issued, and settlement has a delay, so Aftersell cannot reliably refund the original and add the replacement on the same Shopify order. If Authorize.net is your payment processor, route those customers to Thank-You-page offers instead.
* **Manual payment gateways** (`manual`). This covers cash on delivery, custom payment methods, draft-order checkouts, and any other manual payment processor that does not capture a vaulted authorization. Replacement Upsell needs an active vaulted payment to issue a follow-up charge, which manual gateways do not provide.

When the order's payment gateway is one of these, Replacement Upsell silently skips the offer. The skip reason surfaces in the Aftersell order browser as **"Payment gateway does not support replacement upsells."**

For the broader list of payment methods that affect all Aftersell post-purchase offers (not just Replacement Upsell), see [Payment Methods](/aftersell/payment_methods).

## Creating a Replacement Upsell offer

<Frame>
  <img alt="Setting up a Replacement Upsell in the offer editor" />
</Frame>

To create a Replacement Upsell:

1. In your Aftersell dashboard, go to **Post-purchase funnels**.
2. Open an existing funnel or click **Add Funnel**.
3. Add an upsell offer and configure it.

The configuration lives inside a standard post-purchase offer, with Replacement Upsell controls surfacing when you enable them.

A Replacement Upsell offer has three separate product selections, and they need to be configured consistently for the replacement to fire:

* **Funnel trigger.** Set at the funnel level. Determines which orders see the offer.
* **Upsell product.** Set in the offer's Upsell Products section. The product that gets added to the order when the customer accepts.
* **Product to replace.** Set inside the **Replace item in original order with upsell** section, by clicking the **Edit product to replace** button. The exact product and variant in the customer's cart that will be refunded and removed.

If the **Product to replace** does not match the variant the customer actually purchased, Aftersell cannot find a matching line item to remove, and the replacement silently does not fire.

### Step 1: Configure the funnel trigger

The trigger determines which orders see the offer:

* **Product trigger.** Set to the one-time product you want to replace. Without this, the offer can fire on unrelated orders.
* **Subscription trigger.** Set to **do not include a subscription**. This ensures the offer only shows to customers whose orders do not already contain a subscription (which would block the replacement).

All enabled triggers use AND logic. Every condition must be met.

### Step 2: Pick the upsell product

In the offer editor:

1. Click **Add Upsell** and search for the product the customer should receive instead.
2. If the replacement is a subscription, select **Subscription only** as the purchase option and pick the selling plan.
3. If the replacement is a one-time purchase, select **One-time purchase only**.
4. If you are doing a variant or quantity swap of the same product, pick the same product and adjust the variant or quantity controls.

### Step 3: Enable Replacement Upsell

In the offer's advanced settings, enable **Replace item in original order with upsell**. This is the toggle that turns a standard upsell into a Replacement Upsell.

<Frame>
  <img alt="Replacement Upsell settings and toggles in the offer editor" />
</Frame>

When this is enabled, you can also configure:

* **Allow replacement when target has a discount.** When off (default), Replacement Upsell will skip orders where the trigger line carries an order-level discount. When on, the replacement still fires, but the discount on the original line is refunded with the original (it does not carry to the replacement). See [Discount handling](#discount-handling).
* **Override quantity.** Set a specific quantity for the replacement line item. Useful when swapping a single unit for a multi-pack.

### Step 4: Set the product to replace

Click **Edit product to replace** and pick the exact product and variant that should be removed from the customer's order when the offer is accepted. This must match what the customer actually has in their cart.

For variant swaps of the same product (Small → Large), the **Product to replace** must point to the Small variant specifically. If you point it to Large or to any variant the customer did not buy, the offer will skip with no error.

### Step 5: Add optional discount

If the replacement is a subscription, you can apply a first-cycle discount to make the offer more attractive. The discount applies to the first billing cycle of the new subscription, future renewals charge at the regular subscription price.

For one-time replacements, the discount applies to the one-time charge on this order.

### Step 6: Customize the offer copy

Make the refund-and-replace mechanic explicit in the offer copy. Recommended elements:

* Title: clearly describes the swap (for example, "Upgrade to the 3-pack and save").
* Description: explain that the original is refunded and the replacement is charged.
* Accept button: defaults to showing the net price, customize to "Switch to subscription" or "Upgrade my order" if you want a verb-based CTA.

## Discount handling

Replacement Upsell has specific behaviour around discounts that catches partners off guard.

### Discounts on the original line do not carry to the replacement

When Aftersell refunds the original line item, any discount that was applied to it goes with it. The replacement line is charged at the full price (or at your replacement-offer discount, if you configured one), but the customer's original discount does not transfer.

If you want the customer to keep an equivalent discount, configure it on the replacement offer directly.

### Allow replacement when target has a discount

By default, Replacement Upsell **skips** the offer if the trigger line carries an order-level discount. This is a protective default to avoid refund-amount mismatches.

To allow the offer to fire even when the trigger has a discount, enable the **Allow replacement when target has a discount** toggle in the offer's advanced settings. When enabled, the refund covers the discounted price (not the full price), and the replacement is charged according to your offer configuration.

### First-cycle discount on subscription replacements

When the replacement is a subscription, the discount you configure on the offer applies to the **first billing cycle only**. Future recurring orders charge at the regular subscription price. The customer sees the recurring price under **Recurring subtotal** in the offer.

## Analytics and reporting

Refunds generated by a Replacement Upsell carry the note **"AfterSell Post-Purchase Replacement Upsell"** in Shopify, which makes replacement-related refunds easy to identify.

Aftersell analytics do **not** subtract the refunded amount from the upsell value. Replacing a \$100 product with a \$200 product is reported as a \$200 upsell, not a \$100 net.

## Worked examples

Three common Replacement Upsell scenarios, with the exact configuration and what the customer experiences.

### Scenario 1: One-time bottle to monthly subscription of the same product

**Setup.** Your customer bought a one-time bottle of supplement at \$40. You want to offer them a monthly subscription of the same bottle at \$36 per month, with a 15% first-cycle discount.

**What you set in the offer:**

* Funnel trigger: Product is the one-time bottle.
* Upsell product: the same bottle, monthly selling plan.
* Purchase option: Subscription only.
* First-cycle discount: 15%.
* Product to replace: the one-time bottle (same variant the customer purchased).

**What the customer sees in the offer:**

* Accept Offer button: "Add \$0.60 to your order" (net difference between \$40 one-time and \$30.60 first-cycle subscription after 15% off \$36).
* Recurring subtotal: \$36.00 every 30 days.

**On accept:**

* Original \$40 one-time bottle is refunded.
* A new subscription line is added at \$30.60 for the first cycle.
* A monthly subscription is created in your subscription app at \$36 base price.
* The next charge happens in 30 days at \$36.

**Customer statement:** one \$40 refund, one \$30.60 charge. Net: customer paid \$30.60 for this delivery, will pay \$36 every 30 days going forward.

### Scenario 2: Single bottle to 3-pack of the same product

**Setup.** Your customer bought one \$30 bottle. You want to offer them a 3-pack at \$75 (vs \$90 if bought individually).

**What you set in the offer:**

* Funnel trigger: Product is the single bottle.
* Upsell product: same product.
* Override quantity: 3.
* Purchase option: One-time purchase only.
* Product to replace: the single bottle (same variant).

**What the customer sees in the offer:**

* Accept Offer button: "Add \$45.00 to your order" (net difference between \$30 and \$75).

**On accept:**

* Original \$30 bottle is refunded.
* 3 bottles are added at \$75 total.
* Customer pays the net \$45 on this Shopify order.

### Scenario 3: One-time product to a different subscription product

**Setup.** Your customer bought a one-time \$25 starter kit. You want to offer them a monthly subscription to your premium product line at \$50 per month.

**What you set in the offer:**

* Funnel trigger: Product is the starter kit.
* Upsell product: the premium product.
* Purchase option: Subscription only.
* Selling plan: Monthly, \$50.
* Product to replace: the starter kit (same variant).

**What the customer sees in the offer:**

* Accept Offer button: "Add \$25.00 to your order" (net difference between \$25 and \$50).
* Recurring subtotal: \$50.00 every 30 days.

**On accept:**

* Original \$25 starter kit is refunded.
* New subscription line is added at \$50.
* Monthly subscription created in your subscription app at \$50.
* Customer pays \$25 net on this Shopify order.

## Per-variant funnels

A single Replacement Upsell offer targets one specific product and variant on each side. If your subscription plans differ per variant (different sizes, flavours, or prices), you cannot configure one offer that says "swap whichever variant the customer bought to its matching subscription variant." Each variant pairing needs its own funnel.

For example, if you sell a serum in three sizes (Small / Medium / Large) and want each one to swap to its subscription counterpart, you would build three funnels:

* Funnel 1: trigger = Small one-time, replacement = Small subscription.
* Funnel 2: trigger = Medium one-time, replacement = Medium subscription.
* Funnel 3: trigger = Large one-time, replacement = Large subscription.

Aftersell does not currently include a built-in variant pairing feature, so each variant pair needs its own funnel.

## Testing a Replacement Upsell

Before going live:

<Steps>
  <Step title="Place a real test order in Shopify">
    Place a real low-price test order with the one-time product as the trigger. Do not rely on Preview Mode for this step. Preview Mode renders the funnel visually and lets you click through Accept and Decline, but it is sandboxed: no order is created, no refund is applied, no subscription is created, no charges happen, and no emails or webhooks fire. Use Preview Mode for layout and copy review, and a real test order for end-to-end verification.
  </Step>

  <Step title="Accept the upsell on the post-purchase page">
    After checkout, the post-purchase offer will appear. Accept the Replacement Upsell to trigger the real changeset.
  </Step>

  <Step title="Check Shopify">
    In **Shopify Admin → Orders**, find the test order. You should see the original line item with a refund applied, and the replacement line item added.
  </Step>

  <Step title="Check the customer's statement">
    On a real card, verify that both transactions (the refund of the original and the charge for the replacement) post correctly. The net should match the displayed Accept Offer button.
  </Step>

  <Step title="Check your subscription provider (if replacement is a subscription)">
    Find the customer's new subscription in your provider's dashboard. Confirm the cadence, the next charge date, and the product. There is no automatic retry on Aftersell's side if enrollment fails, contact your subscription provider's support if the subscription is missing.
  </Step>
</Steps>

## Beta failsafe

While Replacement Upsell is in Beta, Aftersell tracks errors on each offer and stops showing the offer to new customers once the error count crosses a threshold. This protects you from a widespread misconfiguration silently impacting many customers.

<Frame>
  <img alt="Replacement Upsell Beta failsafe in the Order Browser" />
</Frame>

### Configuring the failsafe threshold

The failsafe threshold is configurable in **Settings → Replacement Upsells**. It counts replacement errors over a **rolling 7-day window** and pauses replacement upsells once your chosen threshold is reached within that window. You can pick from:

* **Stop on any issue in the past 7 days** (recommended — this is the default). The offer stops as soon as the first replacement fails within the rolling window.
* **Stop after 3 issues in the past 7 days**.
* **Stop after 5 issues in the past 7 days**.
* **Stop after 7 issues in the past 7 days** (most permissive).
* **Custom…** — reveals a number field where you can enter any whole number from **1 to 100**. Use this if your store processes high order volumes and the presets trip too quickly.

Pick a higher threshold if you are confident in the offer's configuration and want to absorb a few transient Shopify or subscription-provider errors without disabling the offer. Pick a lower threshold if customer-facing failures are high-cost for your store.

### What trips the failsafe

Any exception in the replacement flow counts as an error within the rolling 7-day window. The most common causes:

* Shopify rejects the changeset because the checkout has already completed.
* The replacement product was deleted or unpublished between offer setup and the customer accepting.
* The selling plan on a subscription replacement was deactivated.
* A transient Shopify API or subscription-provider outage.

### When the failsafe trips

When the error count within the rolling 7-day window reaches your threshold, the offer **stops being shown** to new customers. You'll know in two places:

* **Home page banner.** A warning banner titled **"Replacement upsells are paused"** appears on your Aftersell home page, with a **Review failsafe** button linking to **Settings → Replacement Upsells**.
* **Failsafe status card** (Settings → Replacement Upsells). A status card shows a **Failsafe tripped** (amber) or **Not tripped** (green) badge, plus your current rolling count and threshold — for example, "4 of 5 errors in the past 7 days".

Because the failsafe uses a rolling 7-day window, it **self-heals**: once the error count drops below your threshold, replacement upsells resume automatically — no action required.

### How to reset

You can reset the failsafe yourself from **Settings → Replacement Upsells**. Once you've resolved the underlying issue, click **Reset failsafe** and confirm in the modal — the rolling error count clears immediately and replacement upsells resume for new orders. (The button is disabled when your current error count is already zero.)

Only reset after fixing the root cause, otherwise the failsafe will trip again once the threshold is reached. If you're unsure what caused the errors, contact support via the in-app chat before resetting.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The Replacement Upsell offer type does not appear in my funnel editor">
    Replacement Upsell is a Beta feature that requires manual enablement by Aftersell support. Contact support via the in-app chat to request access. Once enabled, the **Replace item in original order with upsell** toggle will appear in the offer's advanced settings.
  </Accordion>

  <Accordion title="The offer is not showing on test orders">
    Three causes:

    * **Funnel trigger mismatch.** Confirm the trigger product is the same product that is in the test order's cart.
    * **Order already contains a subscription.** Replacement Upsell skips any order where the trigger line is a subscription. Use Subscription Upgrade instead in that case.
    * **Original line has a discount.** By default, Replacement Upsell skips lines with an order-level discount. Enable **Allow replacement when target has a discount** in the offer's advanced settings.
  </Accordion>

  <Accordion title="The offer shows but the replacement doesn't actually happen (or the customer received the original product)">
    A Replacement Upsell offer has three separate product selections in the editor, and they need to be configured consistently for the replacement to fire:

    1. **Funnel trigger.** Set at the funnel level. Determines which orders see the offer.
    2. **Upsell product.** Set in the offer's Upsell Products section. The product that gets added to the order when the customer accepts.
    3. **Edit product to replace.** Set inside the **Replace item in original order with upsell** section, by clicking the **Edit product to replace** button. This is the exact product and variant in the customer's cart that will be refunded and removed.

    The most common configuration mistake: the **product to replace** does not match the variant that is actually in the customer's cart. When that happens, Aftersell cannot find a matching line item to remove, and the replacement silently does not fire.

    To fix:

    * Open the Replacement Upsell offer.
    * Click **Edit product to replace** and confirm the selected product and variant **exactly match** the product+variant the customer should have purchased (per the funnel trigger).
    * If you are swapping between variants of the same product (Small → Large), the "product to replace" must point to the Small variant specifically. If you point it to Large or to any variant the customer did not buy, the offer will skip.
    * Save and test with a real low-price order that includes the exact variant you want to swap from.
  </Accordion>

  <Accordion title="My customer thinks they were double-charged">
    This is the expected behaviour. The original line is refunded and the replacement is charged, so the customer's bank statement shows two transactions even though the net amount is the displayed offer price. To reduce confusion:

    * Add a sentence to the offer copy explaining the refund-and-replace mechanic.
    * Enable Aftersell's automatic refund-notification email for replacement upsells.
    * Train your support team to explain the two-line-entry pattern when a customer reaches out.
  </Accordion>

  <Accordion title="I see &#x22;Partial refunds are not allowed until the transaction is settled&#x22;">
    Some payment gateways (including Authorize.net and others that batch-settle transactions on a delay) do not permit refunds until the original transaction has settled. Because a Replacement Upsell charges the replacement and refunds the original immediately after checkout, the refund step can fail with the error "Partial refunds are not allowed until the transaction is settled. Please try again later." Aftersell does not automatically retry the refund after settlement, so you will need to issue the refund manually from the Shopify order once the original transaction settles (typically within 24 hours, depending on your gateway's settlement schedule). To avoid this scenario, Replacement Upsell is skipped entirely for known unsupported gateways. If you keep seeing it on a supported gateway, contact support so we can investigate.
  </Accordion>

  <Accordion title="The original order's discount disappeared after the replacement">
    When Aftersell refunds the original line item, any discount applied to it goes with the refund. The replacement line is charged separately. If you want the customer to retain the discount, configure it on the replacement offer directly using the offer's discount field.
  </Accordion>

  <Accordion title="Can Replacement Upsell swap a subscription for another subscription?">
    No. If the original line item in the order is already a subscription, Replacement Upsell will not fire. This is because removing the subscription line item does not cancel the subscription contract in your subscription app, the customer would still be billed and also receive the replacement. To modify an existing subscription (change frequency, swap product, or both), use [Subscription Upgrade](/aftersell/subscription-upgrades) instead.
  </Accordion>

  <Accordion title="My Replacement Upsell offer suddenly stopped firing">
    Replacement Upsell tracks errors per offer over a rolling 7-day window and stops showing the offer once the error count crosses your configured threshold in **Settings → Replacement Upsells** (default: stop on any issue in the past 7 days). When the failsafe trips, a **"Replacement upsells are paused"** banner appears on your Aftersell home page with a **Review failsafe** link to **Settings → Replacement Upsells**, where a status card shows your current error count and whether the failsafe is tripped.

    If errors are no longer occurring, the offer resumes automatically once the rolling 7-day count drops below the threshold. To resume immediately after fixing the issue, click **Reset failsafe** on that settings page. If you're unsure of the root cause, contact support via the in-app chat.
  </Accordion>

  <Accordion title="The replacement product image is wrong or generic">
    The offer card uses the variant-specific image when one is tagged on the variant in Shopify. If the variant has no image tagged, the offer card falls back to the parent product's first image. If you are swapping between variants of the same product and the image is not changing, confirm that each variant has its own image set up in Shopify.
  </Accordion>

  <Accordion title="I want to configure Replacement Upsell across many product variants">
    Build one funnel per variant. Each funnel has a product+variant trigger and a corresponding replacement product+variant. Aftersell does not currently include a built-in variant pairing feature.
  </Accordion>

  <Accordion title="The customer accepted but the new subscription is not in my subscription app">
    Same failure mode as Subscription Upsell: most often a selling plan was deactivated between the offer rendering and the customer accepting. Shopify accepts the changeset but no subscription is enrolled downstream. Confirm the selling plan is still active in Shopify and assigned to the replacement product. Check your subscription app's order import or webhook logs for the affected order. If the subscription is missing, your subscription app's support team can usually manually enroll the customer.
  </Accordion>

  <Accordion title="I want to cancel the new subscription after the customer accepted">
    Aftersell does not manage subscription cancellation. Cancellation of future cycles happens in your subscription provider's customer portal or by the customer themselves. The Shopify refund mechanism for the first cycle works the same as any other line item.
  </Accordion>

  <Accordion title="My Authorize.net customers never see the Replacement Upsell offer">
    This is expected. Authorize.net is explicitly blocked from Replacement Upsell in Aftersell's code because it requires transactions to settle before refunds can be issued, and settlement has a delay that breaks the refund-and-recharge pattern Replacement Upsell relies on. Run Thank-You-page offers for Authorize.net customers as an alternative. You can confirm this is the cause by opening the order in the Aftersell order browser, the skip reason will read "Payment gateway does not support replacement upsells."
  </Accordion>

  <Accordion title="My cash-on-delivery or draft-order customers don't see the offer">
    Manual payment gateways (cash on delivery, custom payment methods, draft-order checkouts) are explicitly blocked from Replacement Upsell because they do not vault a card for follow-up charges. The order browser will show "Payment gateway does not support replacement upsells" as the skip reason. For broader payment-method limitations on post-purchase offers, see [Payment Methods](/aftersell/payment_methods).
  </Accordion>
</AccordionGroup>


# Smart funnel
Source: https://docs.aftersell.com/aftersell/smart_funnel

Set up Aftersell Smart Funnel to let Rokt AI automatically pick the best post-purchase offer for each shopper and run it alongside manual funnels.

This article outlines how Smart Funnel uses AI to deliver the most relevant post-purchase offers.

## Overview

Smart Funnel automatically selects and displays the most compelling post-purchase offer for each shopper. Powered by Rokt's industry-leading AI and machine learning models, trained on millions of transactions across diverse verticals, it continuously analyzes your store's performance data and customer behavior. The model updates in real time, so the longer it runs, the better it gets at matching the right offer to the right customer.

### Benefits of Smart Funnel:

* **Precision targeting:** Uses AI to tailor offers for individual customers.
* **Performance optimization:** Can outperform standard manual funnels.
* **Ease of use:** Fully automated for seamless operation.

Smart Funnel is evaluated at **Priority 0**.

This means that if a shopper meets the eligibility criteria, the Smart Funnel offer will be shown before any manual funnels.

***

## Key Settings

### Steps to Set Up Smart Funnel:

1. **Enable the Smart Funnel:** Access Aftersell's funnel settings and activate the Smart Funnel option. Follow the on-screen prompts to begin setup.
2. **Adjust Allocation:** If you would like the Smart Funnel to handle all eligible customers, set its allocation to 100%.
3. **Define Offer Parameters:** Choose the maximum discount amount you are comfortable offering.
4. **Select Industry:** Pick the industry that best matches your business, for example Apparel and Fashion.
5. **Optional Highlight Product:** Leave this blank unless you have a single, high-performing product you would like to promote.
6. **Require Confirmation Click (Optional):** Enable this setting if you want customers to confirm their acceptance twice, once to indicate intent and once to complete the purchase. This reduces accidental purchases.
7. **Save and Test:** Complete the setup and test the Smart Funnel to ensure it aligns with your upsell strategy.

<img alt="Table describing Smart Funnel settings including traffic allocation, max discount, and industry selection" />

## Important Notes

### AI Recommended Products

Smart Funnel pulls product recommendations from your selected Product Recommendation Tool, configured under Settings → Automatic Upsells. You can exclude specific SKUs there as well.

If your highlighted product goes out of stock, or if the selected layout calls for multiple items, the AI automatically substitutes the next best products.

***

### Highlighted Product (Optional)

You can optionally pin a specific item as the hero offer when using single product or hero product layouts. This is useful for promoting overstock inventory or proven best sellers while still benefiting from Smart Funnel optimization.

***

## Thank You Page (TYP) Behaviour

Smart Funnel governs post-purchase upsells only and does not natively support Thank You Page, or TYP, upsells.

Because of this limitation, when TYP widgets are eligible to display, the system automatically references the first applicable manual funnel that contains TYP upsells. Only the TYP widgets from that funnel will be displayed, even though the post-purchase offers from that funnel are not shown earlier in the customer journey.

If a shopper sees a Smart Funnel post-purchase offer, manual funnel post-purchase offers are suppressed due to priority rules. However, TYP widgets may still appear based on manual funnel eligibility.

***

## English Only Display

Smart Funnel content is currently available in English only.

To ensure a seamless experience, delivery is automatically restricted to shoppers who check out with an English locale (the check is on the customer's checkout locale, not your store's default language). If a significant portion of your audience speaks other languages, continue using manual funnels with locale-based triggers to serve those shoppers effectively.

Support for additional languages is on our roadmap.

***

### **Discount Requirements**

For best performance, we recommend setting a non-zero Max Discount, since the templates do not dynamically adjust based on the discount field value. A 0% Max Discount is allowed, but for 0% discount offers a manual funnel is generally a better fit. This may be improved in the future.

***

## Previewing how Smart Funnel works

The Smart Funnel banner on the Funnels page includes a **?** (question mark) button. Clicking it opens an interactive sample preview that shows you how a Smart Funnel flows in practice.

The preview uses a representative funnel shape drawn from the current active cross-store experiment, with products resolved against your own catalog. You can click **Accept** or **No thanks** on each offer card to walk through the branching logic — accepting advances to the next upsell, declining softens the offer to a downsell — the same logic your live funnel uses.

> ℹ️ The products, prices, and discounts shown in the preview are placeholders. After checkout, the AI builds a personalized funnel for each shopper based on their profile and purchase history.

***

## Troubleshooting low or zero visits

If your Smart Funnel is active and has allocated traffic but is getting very few or no post-purchase visits, an **info icon** (!) appears on the Smart Funnel banner. Clicking it scrolls to and expands the eligibility details panel at the bottom of the Funnels page.

<Note>
  Eligibility insights are not available on every store yet. If you don't see the info icon, contact support and we can look into low or zero visits with you.
</Note>

> ℹ️ The eligibility insights icon only appears when viewing a date range of 30 days or longer. Short or custom date ranges don't provide enough data to diagnose a problem.

The icon appears when:

* Your Smart Funnel is active with traffic allocated, **and**
* Post-purchase visits are **0** (any traffic allocation), **or**
* Post-purchase visits are **fewer than 10** with **50% or more** of traffic allocated to the Smart Funnel

When you open the eligibility details panel, it lists the most likely causes:

**Shopify eligibility limits (not fixable)**
Some orders can't show one-click post-purchase offers — for example, orders paid with Apple Pay or Google Pay. This is a Shopify platform restriction. The panel links to Shopify's limitations documentation.

**Excluded collections (fixable)**
If you've excluded collections from product recommendations in Settings → Automatic upsells, and every AI-recommended product falls within those excluded collections, Smart Funnel skips the offer entirely. The panel shows how many collections you've excluded and links directly to your exclusion settings.

**"Skip products in original order" combined with exclusions (fixable)**
If you have both "Skip products in original order" enabled and excluded collections configured, Smart Funnel may skip offers when every recommended product is filtered out by one or both rules. The panel links to your Smart Funnel settings so you can adjust these options.

***

## Best Practices for Using Smart Funnel

To maximize effectiveness:

* Combine Smart Funnel with manual funnels to support features like Thank You Page widgets.
* Verify Shopify's eligibility rules for post-purchase upsells to understand targeting limitations.
* Use customization options to align offers with your business goals.

***

## Frequently Asked Questions

**Can I run Smart Funnel alongside existing funnels?**\
Yes. Aftersell allows you to operate both Smart and manual funnels simultaneously. Each has a predefined priority, and the system determines which funnel to display based on eligibility.

**How does automation improve upselling?**\
Smart Funnel uses machine learning to analyze customer behavior and store data, ensuring the most relevant offers are displayed automatically. This reduces manual effort and increases conversion potential.

**Why doesn't the Smart Funnel appear for every customer?**\
This is due to Shopify platform restrictions. Smart Funnel relies on Shopify's post-purchase upsell feature, which is not available for all orders.

**Will using Smart Funnel remove Thank You Page upsells?**\
Smart Funnel does not support TYP upsells directly. TYP widgets can still appear through eligible manual funnels. However, Smart Funnel post-purchase offers will take priority over manual funnel post-purchase offers.

**Can I A/B test the Smart Funnel?**\
Smart Funnel does not use the Layout A–E [post-purchase A/B testing](/aftersell/post_purchase_a_b_testing) or [multivariate testing](/aftersell/multivariate_testing) tools, both of which are built for manual funnels. To compare Smart Funnel against a manual funnel, run both at the same time and split traffic between them using each funnel's allocation setting. Aftersell tracks performance separately for each funnel, so you can compare results in your analytics.

***

## Need Help?

If you have questions about setting up Smart Funnel or understanding your results, contact our Customer Support team through the app for assistance.


# Subscription upgrades
Source: https://docs.aftersell.com/aftersell/subscription-upgrades



Subscription Upgrades lets you offer existing subscribers a post-purchase change to their active subscription right after checkout. You can change the delivery frequency, swap to a different subscription product, do both, or [add another item to their subscription](/aftersell/subscription-upgrades-add-item). The change is applied directly in Recharge, Skio, or Loop, so no refund or new charge is issued for the subscription itself.

## Which feature do you need?

Aftersell has three post-purchase features that work with subscriptions. They sound similar but behave very differently. Use this decision flow before setting anything up.

<Info>
  **Think of it like this:**

  1. **Subscription Upgrade** modifies an existing subscription in some way — its frequency, its product, or by adding an item to it.
  2. **Subscription Upsell** is additive only: it creates a brand-new subscription. With a subscription provider connected, it works even on orders that already contain a subscription, so you no longer need to worry about the Shopify limitation.

  Aftersell handles each scenario with a dedicated feature so you do not have to think about the platform rules directly:

  * **To change a subscription the customer already has**, use Subscription Upgrade. It modifies the customer's existing subscription directly in Recharge, Skio, or Loop. A small non-subscription placeholder product is added to the Shopify order to satisfy Shopify's rules, while the real upgrade happens in your subscription platform.
  * **To add a brand-new subscription**, use **Subscription Upsell**. The original item stays in the order as is, and the customer ends up with a new recurring subscription alongside it. This works whether or not the order already contains a subscription — see [upselling existing subscribers](/aftersell/subscription-upsell-existing-subscribers).
  * **To swap a one-time product for another**, use **Replacement Upsell**. The replacement can be a subscription version of the same product, a different product entirely, or a different variant or quantity of the same product.
</Info>

<Note>
  **The "one subscription per order" limitation no longer blocks subscription upsells.** Shopify does not let a post-purchase upsell add a subscription to an order that already contains one. When you connect Recharge, Skio, or Loop, Aftersell creates the new subscription in your provider instead of through Shopify, so subscription offers reach existing subscribers too. See [upselling existing subscribers](/aftersell/subscription-upsell-existing-subscribers).
</Note>

Use the three questions below to find the right feature for your scenario. Work through them in order and stop at the first **Yes**, that is the feature you should use.

**Q1: Do you want to change a subscription the customer already has?**

* **Yes**, use [Subscription Upgrade](#how-subscription-upgrades-work). This is the feature this guide covers. Subscription Upgrade modifies the customer's existing subscription in Recharge, Skio, or Loop, right after they complete checkout. You can change the delivery or billing frequency, swap to a different subscription product, do both at once, or [add another item to the subscription](/aftersell/subscription-upgrades-add-item). The customer's existing subscription is updated in place. No refund or new charge is issued for the subscription itself. A small placeholder line item (the "offer product") is added to the Shopify order as a record of the accepted upgrade.
* **No**, go to Q2.

**Q2: Do you want to add a brand-new recurring subscription to their order, on top of what they already bought?**

* **Yes**, use [Subscription Upsell](/aftersell/subscriptions_in_post_purchase_offers). Subscription Upsell adds a new subscription to the order. Whatever they already bought stays in the order, and a recurring subscription is added alongside it. On an order with no subscription, this uses Shopify's Subscription API. On an order that **already contains a subscription**, Aftersell creates the new subscription in your connected provider instead — see [upselling existing subscribers](/aftersell/subscription-upsell-existing-subscribers). Either way the customer ends up with a second, independent subscription.
* **No**, go to Q3.

**Q3: The customer bought a one-time product. Do you want to replace it with a different product, either a subscription version of the same product or an entirely different product?**

* **Yes**, use [Replacement Upsell](/aftersell/replacement_upsells). Replacement Upsell removes the original one-time product from the order and adds the replacement in its place. Shopify refunds the original line item and charges for the replacement. The replacement can be a subscription version of the same product (for example, the customer bought a one-time bottle and you want them on a monthly subscription instead), or a completely different product, one-time or subscription.

### At a glance

| If you want to                                                                                             | Use this feature                                                                      | What the customer sees on their order                                                                            |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Modify a subscription they already have <br />(change frequency, swap to a different subscription product) | Subscription Upgrade (this guide)                                                     | A small placeholder line item (the "offer product"). The subscription itself changes in Recharge, Skio, or Loop. |
| Add another item to a subscription they already have                                                       | [Add an item to a subscription](/aftersell/subscription-upgrades-add-item)            | The added item, charged on this order. It then ships and bills with their subscription.                          |
| Add a new subscription on top of what they bought                                                          | [Subscription Upsell](/aftersell/subscriptions_in_post_purchase_offers)               | A new subscription line item, alongside what they already bought.                                                |
| Add a new subscription when the order **already has** a subscription                                       | [Upselling existing subscribers](/aftersell/subscription-upsell-existing-subscribers) | The new item charged at its first-cycle price. A second subscription is created in your provider.                |
| Replace a one-time product with a subscription or a different product                                      | [Replacement Upsell](/aftersell/replacement_upsells)                                  | A refund line for the original product, and a new charge for the replacement product.                            |

## How Subscription Upgrades work

Here is the customer's experience end-to-end, and what happens behind the scenes.

The customer journey is four short steps:

1. **Buys subscription.** The customer completes checkout on a product that has a subscription selling plan.
2. **Sees upgrade offer.** On the post-purchase page, they see the Subscription Upgrade offer you configured.
3. **Post-purchase accept.** They accept without re-entering payment or shipping details.
4. **Plan updates.** Their existing subscription is modified in Recharge, Skio, or Loop. A small placeholder line item (the "offer product") is added to the Shopify order as a record of the acceptance.

The two systems are connected to one customer action but execute independently:

* **In Shopify**, the offer product is added to the order as a placeholder line item. It is required because Shopify's post-purchase API cannot add a second subscription to an order that already contains one.
* **In Recharge, Skio, or Loop**, the customer's existing subscription is updated, and no refund is issued for the original subscription. In most cases it is edited in place and keeps its ID. Two shapes work differently:

  * **Converting to a prepaid plan** on Recharge or Skio. The provider cannot switch an active subscription onto a prepaid plan, so Aftersell creates the subscription on the new plan and then cancels the original.
  * **Upgrading one line of a multi-line subscription** on Skio or Loop. The provider cannot re-time a single line, so that line is created as its own new subscription and removed from the original — Skio sets its quantity to `0`, Loop removes the line outright.

  In both cases the upgraded item ends up under a **different subscription ID**, which matters if you have integrations keyed on it. See [Fulfillment & 3PL mapping](/aftersell/subscription-upgrades-fulfillment).

The new plan's pricing applies on the **next recurring cycle in your subscription platform**, not on the Shopify order the customer just completed.

If the provider call fails after the offer product was added to the order, Aftersell retries it in a background workflow. The workflow classifies the failure first, so what happens next depends on the cause and the upgrade type:

* **Transient causes and provider rate limits** are replayed. The workflow checks the provider's current state before re-running, so a slow-but-successful upgrade isn't applied twice.
* **Causes a replay can't fix** are routed to manual reconciliation instead.
* **Where a refund is safe** — no provider mutation succeeded, and the charged line was a placeholder rather than a product the shopper keeps — the charge is refunded automatically. Net-new subscriptions and box upgrades are never refunded this way, because the shopper receives real products in both cases.

If the outcome is manual reconciliation, contact support and see [Troubleshooting](/aftersell/subscription-upgrades-troubleshooting).

## What the customer sees

The Subscription Upgrade flow touches two systems, and the customer sees different things in each. Understanding this prevents support tickets about "double charges" or "missing items".

### On the Shopify order

When the customer accepts an upgrade, Aftersell does **not** remove the original subscription line item from their order. Removing it would require a refund, which causes more customer confusion ("I got double charged, what's going on?") than it solves.

Instead, the order ends up with:

* The **original subscription line item**, as the customer purchased it.
* The **offer product**, as a separate placeholder line item that represents the upgrade.

For this reason, naming the offer product clearly is critical. The customer should be able to look at their order summary and immediately understand what the second line item represents.

**Good names:**

* Upgrade to Quarterly
* Quarterly plan upgrade
* Switch to monthly delivery

**Avoid generic names** like Subscription Upgrade if you offer multiple upgrade tiers. The customer will not know which one they accepted.

In Shopify Admin, also add a short description to the offer product that explains it represents the subscription upgrade and that no additional charges occur from this line.

### In the subscription provider portal

In Recharge, Skio, or Loop's customer portal, the customer sees their updated subscription. When the change takes effect depends on whether the immediate upgrade option was used:

* **By default (next billing cycle)**, the change applies at the customer's next billing cycle. The current cycle is unchanged, and the new plan takes effect from the next renewal onward.
* **With immediate upgrade (beta, on request)**, the new billing interval starts immediately instead of waiting for the next renewal. The customer's existing subscription is still updated in place; it is not deleted and recreated.

## Works with Recharge, Skio, and Loop

Subscription Upgrades is currently only compatible with **Recharge**, **Skio**, and **Loop**. The upgrade is applied inside whichever of these platforms powers your subscriptions, so connecting one is a required setup step.

For what an integration is, which platforms are supported, and provider-specific token setup, see [Integrations](/aftersell/subscription-upgrades-integrations).

If you use a subscription app other than these three, you cannot use Subscription Upgrades at this time, but you can still use [Subscription Upsell](/aftersell/subscriptions_in_post_purchase_offers) and [Replacement Upsell](/aftersell/replacement_upsells).

## Next steps

<CardGroup>
  <Card title="Setup & configuration" icon="sliders" href="/aftersell/subscription-upgrades-setup">
    Connect your provider and build the upgrade offer with the setup wizard.
  </Card>

  <Card title="Add an item to a subscription" icon="plus" href="/aftersell/subscription-upgrades-add-item">
    Grow a subscription by adding a new product to it, instead of changing it.
  </Card>

  <Card title="Testing" icon="vial" href="/aftersell/subscription-upgrades-testing">
    Place a test order and verify the upgrade in Shopify and your provider.
  </Card>

  <Card title="Limitations & important notes" icon="triangle-exclamation" href="/aftersell/subscription-upgrades-limitations">
    Constraints and behaviours to know before you launch.
  </Card>

  <Card title="Fulfillment & 3PL mapping" icon="truck" href="/aftersell/subscription-upgrades-fulfillment">
    Make sure your 3PL ships the right product after an upgrade.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/aftersell/subscription-upgrades-troubleshooting">
    Fixes for the most common upgrade issues.
  </Card>

  <Card title="Integrations" icon="plug" href="/aftersell/subscription-upgrades-integrations">
    Recharge, Skio, and Loop setup guides.
  </Card>
</CardGroup>


# Adding an item to an existing subscription
Source: https://docs.aftersell.com/aftersell/subscription-upgrades-add-item



**Add another subscribable item to subscription** is a Subscription Upgrade type that adds a brand-new product to a customer's existing subscription, instead of changing the frequency or swapping the product they already subscribe to. The item joins their subscription and recurs on the same cadence from then on.

Use it when you want to grow the value of a subscription rather than change it. For example, a customer subscribed to monthly coffee beans accepts an offer to add a bag of filters to that same monthly delivery.

New to Subscription Upgrades? Start with the [Overview](/aftersell/subscription-upgrades). For the full wizard walkthrough, see [Setup & configuration](/aftersell/subscription-upgrades-setup).

## How it differs from the other upgrade types

The other three upgrade types modify what the customer already subscribes to. Add-item leaves the existing subscription intact and adds to it.

| Upgrade type                                      | What happens to the existing subscription                                                |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Change delivery or billing frequency              | Same product, new cadence.                                                               |
| Replace with a different product                  | The subscribed product is swapped for another.                                           |
| Both – change frequency and replace product       | Both of the above.                                                                       |
| **Add another subscribable item to subscription** | **Nothing is changed or removed. A new item is added alongside what they already have.** |

## What the customer experiences

1. **Buys a subscription.** The customer completes checkout on a product with a subscription selling plan.
2. **Sees the offer.** On the post-purchase page they see the item you configured, at the price you set.
3. **Accepts.** The displayed price is charged on that Shopify order, with no re-entry of payment or shipping details.
4. **The item joins their subscription.** In Recharge, Skio, or Loop, the item is added to their subscription and bills with it on every following cycle.

The cadence is always inherited from the customer's existing subscription. You do not set a frequency for the added item, and you cannot set one — the whole point of add-item is that the new product ships and bills together with what the customer already receives.

## Setting it up

Add-item is configured in **Step 3: Subscription upgrade** of the Subscription Upgrade wizard.

1. In your Aftersell dashboard, go to **Post-purchase funnels**.
2. Click **Add Funnel** and select the **Subscription Upgrade** template.
3. Complete Step 1 (connect your provider) and Step 2 (pick the trigger product) as normal.
4. In Step 3, set **Subscription upgrade type** to **Add another subscribable item to subscription**.
5. Under **Item to add to the subscription**, click **Choose item to add** and pick the product (and variant, if it has variants).
6. Complete Step 4 (offer product) and click **Create offer**.

<Note>
  The item you pick here must have an **active selling plan**. Only products with active selling plans appear in the picker, because the added line has to be a recurring line in your subscription platform. This is a different field from the Step 4 offer product, which is the visual placeholder the customer sees in the offer card.
</Note>

Aftersell validates the configuration against your provider when you save, using the same checks that run when a funnel is activated. If your provider cannot run the offer as configured, the wizard tells you before you save rather than letting it fail after a customer has been charged.

<Warning>
  If you switch your connected provider to one that does not support add-item, a saved add-item offer resets to **Change delivery or billing frequency** and the added item is cleared. Re-check the offer's configuration after changing providers.
</Warning>

## Provider behaviour

All three supported providers can add an item to a subscription, but they realize it differently, and the difference is visible to the customer. The wizard shows the relevant description for your connected provider when you select the add-item type.

### Skio and Loop

The item is added as a **recurring line on the existing subscription**. No second subscription is created, and no other line on the subscription is modified.

* The displayed price is charged on the current Shopify order.
* The item is then added to the subscription and billed with it **from the next order onward**.

### Recharge

Recharge has no add-a-line API. Aftersell instead creates a **second subscription** for the added item that inherits the cadence of the customer's existing subscription, anchored to that subscription's **existing next charge date** — so the two bill together rather than the new one charging straight away.

* The item is added and charged now, so it ships in the next delivery.
* It then recurs on the same cadence as the original subscription.

<Note>
  On Recharge, the customer will see **two subscriptions** in their Recharge portal: their original one, and one for the added item on a matching cadence. They are billed on the same cadence but are separate subscription records, so the customer can manage or cancel the added item independently.
</Note>

### At a glance

|                                      | Skio                                        | Loop                                    | Recharge                                                                             |
| ------------------------------------ | ------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
| How the item is added                | Recurring line on the existing subscription | Recurring line on the existing contract | Second subscription inheriting the cadence                                           |
| Subscriptions in the customer portal | One                                         | One                                     | Two                                                                                  |
| First recurring charge               | Next order                                  | Next order                              | Next order — the sibling is anchored to the existing subscription's next charge date |
| Prepaid subscriptions                | Not supported                               | Not supported                           | Supported                                                                            |

## Limitations

* **No discounts.** Add-item offers do not support a first-order or recurring discount. Selecting the add-item type hides the recurring-discount section in Step 3; the **First-order discount** field in Step 4 still appears, but whatever you type there is saved as `0`. Set the price you want on the Step 4 offer product instead.
* **Prepaid subscriptions are not supported on Skio or Loop, but only Skio is checked when you save.** Skio rejects adding a recurring line to a prepaid subscription, so Aftersell validates the trigger product's selling plans at save time: it blocks the offer when every plan on the variant is prepaid, and warns when only some are. Loop gets no equivalent check — a Loop add-item offer on a prepaid trigger saves cleanly and then fails when a prepaid subscriber accepts it, so verify the trigger yourself on Loop.
* **The added item must have an active selling plan.** On Loop in particular, the variant must have a selling plan or the provider rejects the add.
* **Failed add-item calls are retried.** Add-item is part of the automatic retry workflow like the other upgrade types. Re-issuing it can't stack quantity, because each provider's execute step carries a dedupe guard that recognises an item already added. A failure with a cause that a replay can't fix — rather than a transient one — is routed to manual reconciliation instead of being retried forever.
* **Adding an item the customer already subscribes to behaves differently by provider.** On Skio and Loop, the existing line's quantity is incremented. On Recharge there is no add-line API, so the item becomes its own sibling subscription — leaving the customer subscribed to it twice, on two separate subscriptions. Choose an item your trigger-product subscribers are unlikely to already have, especially on Recharge.
* **One subscription change per post-purchase flow.** As with the other upgrade types, only the first accepted subscription offer in a funnel goes through.

## Related

* [Setup & configuration](/aftersell/subscription-upgrades-setup)
* [Limitations & important notes](/aftersell/subscription-upgrades-limitations)
* [Fulfillment & 3PL mapping](/aftersell/subscription-upgrades-fulfillment)
* [Troubleshooting](/aftersell/subscription-upgrades-troubleshooting)


# Subscription upgrades fulfillment & 3PL mapping
Source: https://docs.aftersell.com/aftersell/subscription-upgrades-fulfillment



The offer product on the Shopify order is a placeholder, not a real product to ship. Your fulfillment provider (3PL) needs to know what to actually send the customer when an upgrade is accepted.

## Mapping the placeholder to a real product

Aftersell does not handle the fulfillment side of subscription upgrades. You need to sync with your 3PL provider to confirm the right mapping is in place on their end. In most cases this means:

* Mapping the offer product (the placeholder) to the upgraded product the customer should receive.
* Confirming the upgrade flows through correctly when the subscription is updated in Recharge, Skio, or Loop.

## If your 3PL integrates with your subscription platform

If your 3PL integrates directly with your subscription platform (Recharge, Skio, or Loop), the behaviour may vary depending on the upgrade configuration:

* **For most upgrades**, the customer's existing subscription is updated in place and keeps the same subscription ID, so direct integrations pick up the change correctly.
* **For prepaid conversions**, Recharge and Skio cancel the original subscription and create a new one to apply the prepaid plan.
* **For a single line of a multi-line subscription**, Skio and Loop cannot re-time one line in place. They create a new subscription holding that line and retire it from the original — Skio sets the old line's quantity to `0`, Loop removes it. If it was the original's last active line, Loop cancels the original outright.

In both of these cases the upgraded item ends up under a **different subscription ID**, so integrations that rely on stable subscription IDs may need to re-sync after that type of upgrade.

This is why it is best to always run a [test order](/aftersell/subscription-upgrades-testing), confirm everything is working as expected, and check in with your 3PL provider for any setup or mapping questions.


# Subscription upgrades integrations
Source: https://docs.aftersell.com/aftersell/subscription-upgrades-integrations



A Subscription Upgrade never changes a subscription inside Aftersell alone. The actual change — a new frequency, a swapped product, or a recurring discount — is applied inside the subscription platform that powers your store's subscriptions. The connection between Aftersell and that platform is the **integration**.

## Why an integration is required

When a customer accepts an upgrade, two things happen in parallel:

* **In Shopify**, Aftersell adds the offer product (a placeholder line item) to the order.
* **In your subscription platform**, Aftersell calls the provider's API to modify the customer's existing subscription.

That second step only works if Aftersell is connected to your provider with a valid API token that holds the right permissions. This is why [Step 1 of the setup wizard](/aftersell/subscription-upgrades-setup#step-1-connect-provider) asks you to pick a provider and paste an API token before you can build the offer. Without a working integration, the offer product would be added to the order but no subscription would change.

## Supported platforms

Subscription Upgrades is currently compatible with three platforms. Each has its own token scopes, capabilities, and quirks, so follow the dedicated guide for the platform you use.

<CardGroup>
  <Card title="Recharge" icon="rotate" href="/aftersell/subscription-upgrades-recharge">
    All upgrade types. Prepaid and postpaid. Near real-time sync.
  </Card>

  <Card title="Skio" icon="rotate" href="/aftersell/subscription-upgrades-skio">
    All upgrade types. Prepaid and postpaid. Near real-time sync.
  </Card>

  <Card title="Loop" icon="rotate" href="/aftersell/subscription-upgrades-loop">
    All upgrade types. Postpaid only.
  </Card>
</CardGroup>

## If you use a different subscription app

If you use a subscription app other than Recharge, Skio, or Loop, you cannot use Subscription Upgrades at this time. That means you cannot offer an upsell that modifies a customer's existing subscription, whether that is changing the delivery or billing frequency, swapping to a different subscription product, or both.

You can, however, still use other post-purchase offer types:

* [Subscription Upsell](/aftersell/subscriptions_in_post_purchase_offers), to add a new subscription line item to a one-time order.
* [Replacement Upsell](/aftersell/replacement_upsells), to swap a one-time product in the order for another product. This covers one-time to one-time (including the same product in a different quantity or variant) and one-time to subscription (the customer's order becomes a subscription order instead of a one-time order). Replacement Upsell cannot operate on a subscription line item in the order. If the original purchase was a subscription, use Subscription Upgrade instead.

## Related

* [Overview](/aftersell/subscription-upgrades) — how Subscription Upgrades work end to end.
* [Setup & configuration](/aftersell/subscription-upgrades-setup) — connect your provider and build the offer.


# Subscription upgrades limitations & important notes
Source: https://docs.aftersell.com/aftersell/subscription-upgrades-limitations

Constraints before launching a Subscription Upgrade funnel: one change per flow, prepaid conversion behavior, recurring discounts, and add-item limits.

Review these constraints and behaviours before you launch a Subscription Upgrade funnel. They explain the edges of what the feature can and cannot do, and prevent the most common surprises.

## Important notes

* **One subscription upgrade offer per funnel.** Each funnel supports at most one subscription upgrade offer. The **Subscription upgrade** option in the add-offer menu shows a used count and is disabled once the limit is reached. To add a different upgrade, remove the existing one first. This limit exists because two upgrade offers would compete for the same subscription line.
* **One subscription change per post-purchase flow.** Only one subscription offer can be accepted per post-purchase page. If your funnel has multiple subscription-related steps, only the first accepted offer goes through. The funnel editor warns when it detects this conflict.
* **Subscriptions only.** This feature only fires when the customer's order contains the subscription version of the eligible product. It will not fire for one-time purchases of the same product.
* **Frequency on replacements.** When using **Replace with a different product**, the new item inherits the original subscription's frequency unless you also pick **Both – change frequency and replace product**.
* **Multi-product upsells.** Subscription upgrade settings are configured per product. If you are offering multiple products in one upsell, configure each individually.
* **Recurring discount applies to every future renewal.** Unlike a one-time discount, this stays in effect on every renewal of the upgraded subscription.
* **Prepaid conversion with partial credit is not supported.** If a customer already paid for part of a prepaid cycle, Aftersell cannot pro-rate the remaining shipments, and the original subscription is **never refunded**. On Recharge, converting a subscription to a prepaid plan cancels the original and recreates it on the new plan; if the upgrade is set to start immediately, Aftersell also creates a single-charge \$0 bridge subscription to cover the deliveries the customer has already paid for, so nothing is dropped between the old cycle and the new plan's first charge. A replacement that does not move the customer onto a prepaid plan is applied to the existing subscription in place.

## Add-item upgrades

The **Add another subscribable item to subscription** type has its own constraints:

* **No discounts.** Add-item offers do not support a first-order or recurring discount. The recurring-discount section is hidden on this type; the **First-order discount** field in Step 4 still appears but is always saved as `0`. Set the price you want on the Step 4 offer product instead.
* **Not supported on prepaid Skio or Loop subscriptions, and only Skio is validated.** Skio rejects adding a recurring line to a prepaid subscription; Aftersell blocks the offer at save time when every selling plan on the trigger variant is prepaid, and warns when only some are. The Loop integration does not handle prepaid either, but it is not covered by that save-time check — the offer saves and fails on accept instead.
* **Failed calls are retried.** Add-item is part of the automatic retry workflow; a per-provider dedupe guard keeps a replay from adding the item twice. Contact support only if the failure is reported as needing manual reconciliation.
* **Adding an item the customer already subscribes to increases that line's quantity** instead of creating a second line.
* **Recharge creates a second subscription** rather than adding a line, because it has no add-a-line API. The customer sees two subscriptions on a matching cadence in their portal.

For the full behaviour, see [Adding an item to an existing subscription](/aftersell/subscription-upgrades-add-item).

## Subscription upsells on subscription orders

Shopify does not allow a post-purchase upsell to add a subscription to an order that already contains one. With Recharge, Skio, or Loop connected, Aftersell creates the new subscription in your provider instead, so subscription offers still reach existing subscribers. Notes and constraints:

* **A provider connection is required.** Without one, subscription offers on subscription orders are dropped (subscription-only products) or downgraded to one-time.
* **Prepaid plans are unavailable on Loop.** Loop cannot create prepaid subscriptions through this integration, so prepaid plans are hidden from the offer on Loop stores.
* **The customer ends up with two independent subscriptions**, each managed separately in the provider portal.
* **This does not apply to Subscription Upgrade offers**, which modify the existing subscription rather than adding a new one.

See [upselling existing subscribers](/aftersell/subscription-upsell-existing-subscribers) for the full details.

## Template restrictions by provider

The **Prepay for 3 months** starter template sets a prepaid cadence (monthly delivery, quarterly billing). This template is not available on Loop stores because supported frequencies, sync timing, and whether selling plans must pre-exist vary by provider — see each provider's integration guide for details. If you select this template on a Loop store, the wizard blocks it before the confirmation step.

## Provider-specific limitations

Each subscription platform behaves a little differently — supported frequencies, whether selling plans must already exist, and sync timing vary by provider. For the full per-provider details, see the integration guides:

* [Recharge](/aftersell/subscription-upgrades-recharge)
* [Skio](/aftersell/subscription-upgrades-skio)
* [Loop](/aftersell/subscription-upgrades-loop)

## Related

* [Setup & configuration](/aftersell/subscription-upgrades-setup)
* [Fulfillment & 3PL mapping](/aftersell/subscription-upgrades-fulfillment)
* [Troubleshooting](/aftersell/subscription-upgrades-troubleshooting)


# Subscription upgrades with Loop
Source: https://docs.aftersell.com/aftersell/subscription-upgrades-loop

Step-by-step guide to connecting Loop and setting up Subscription Upgrades in Aftersell, including Loop-specific limitations.

This page covers everything specific to using **Loop** with Subscription Upgrades, including its unique limitations. For a full overview of how Subscription Upgrades work, see [Subscription Upgrades](/aftersell/subscription-upgrades).

## Supported features

Loop supports all Subscription Upgrade types:

* Change delivery or billing frequency
* Replace with a different product
* Both – change frequency and replace product
* Add another subscribable item to subscription (see [Add an item](/aftersell/subscription-upgrades-add-item))
* Postpaid frequencies only (prepaid is not supported — see [Limitations](#loop-specific-limitations) below)

## Loop-specific limitations

* **Billing frequency must equal delivery frequency.** Loop does not support prepaid subscriptions through this integration. The billing frequency field is disabled and automatically synced to the delivery frequency. This is the biggest constraint to be aware of if your store relies on prepaid plans.

## Generating your Loop API token

1. Open the Loop app and navigate to **Settings** in the bottom left.
2. Under **Admin**, click **API Tokens**.
3. Set the permissions Aftersell needs: **Read and Write** on Subscription contracts, and **Read** on Orders and Selling plans. Write access is only required for subscriptions.
4. Click **Generate New Token**.
5. Provide a name, select the appropriate scopes, and click **Generate Token**.
6. Click **Show Token** to view and copy your key. Treat it like a password and store it somewhere safe.

For more details, see [Loop's API documentation](https://loop.app/docs).

## Connecting Loop in the setup wizard

When you reach **Step 1: Connect provider** in the Subscription Upgrade wizard:

1. Select **Loop** from the **Subscription provider** dropdown.
2. Paste your API token into the **API token** field.
3. Click **Test API key**. Aftersell validates the token, checking that it authenticates correctly, holds all required scopes, and belongs to your store.
4. Once the test passes (green check), click **Continue** to move to Step 2.

The test result shows one of two states:

* **Green tick — "API key verified".** the token authenticated, all required scopes are present, and the token belongs to your store. **Continue** is now enabled.
* **Red cancel icon.** The check did not come back clean. Read the message beside the icon: either the token was rejected or is missing required scopes. The message names the specific missing scopes. Fix the token in Loop and test again. or Aftersell could not complete the check ("Could not verify the API key. Please try again."), which is a failed call rather than a bad token — in that case just test again.

A could-not-verify result looks exactly like a rejection, so go by the message rather than the icon. **Continue** stays disabled until the check comes back green, and editing the provider or the token clears the previous result.

## Keeping multi-product subscriptions intact

By default, when a frequency or frequency-and-product upgrade applies to a customer with two or more active lines on their Loop subscription, Aftersell splits the upgraded product into a new subscription. This keeps the other items on their original billing cadence.

If the other products on the subscription are add-ons to the upgraded product (rather than standalone subscriptions), you can enable **Don't split multi-product subscriptions** on the offer. When this is on, Aftersell retimes the whole contract to the new frequency instead of splitting it.

**What to expect when this setting is on:**

* The other products on the subscription move to the new frequency too.
* Those products keep the discount from their original frequency's selling plan, but at the new cadence.
* Aftersell does not guarantee correct pricing for sibling items — if a sibling product is on a fixed-price plan with no matching plan at the new frequency, it keeps its original absolute price at the new cadence.

<Warning>
  Only enable this when the other products are add-ons to the upgraded product. If they are independent subscriptions, use the default split behavior so each product stays on its own billing schedule.
</Warning>

This setting is available for **frequency** and **frequency + product** upgrade types on Loop only. It appears as a checkbox in the offer settings panel.

## Before you configure the upgrade (Step 3)

When configuring a frequency change, you can either pick an existing selling plan or set the frequency manually:

* **Use an existing selling plan.** Pick from the selling-plan dropdown. The plan must already exist and be active in your Loop dashboard.
* **Set the frequency manually.** Enter the delivery frequency yourself. Loop accepts any cadence without requiring a matching selling plan. You can also apply a recurring discount when using a manual frequency.

<Note>
  If you set the frequency manually and the customer's subscription has two or more active product lines (a multi-product or bundle contract), the upgrade will fail unless a matching selling plan exists for the target frequency. See [Limitations](#loop-specific-limitations) for details.
</Note>

### Selecting a recurring discount tier

Some Loop selling plans apply different discounts at different points in the subscription — for example, \$20 off the first charge and \$10 off from the second charge onward. When you select a plan like this, the **Recurring discount** field is replaced by a list of radio buttons showing each of the plan's discount tiers with its charge range (for example, "Charge 1" or "Charge 2 onward").

Select the tier you want applied to every future renewal of the upgraded subscription. The selected tier is saved with the offer and applied when a customer accepts the upgrade.

If the selected plan has no discount tiers, or you are setting the frequency manually, the standard free-entry discount field appears instead.

## Verifying an upgrade in Loop

After placing a test order and accepting the upgrade offer:

Go to **Subscriptions** in your Loop dashboard and find the customer's subscription. Loop's upgrade calls are synchronous, so there is no processing delay on Aftersell's side — the change is applied at Loop the moment the call returns. Loop's own subscription *list* can take a little longer to catch up, so if it isn't there yet, wait a few minutes and refresh before treating it as a failure.

If the change isn't there, it didn't land — see below.

## Troubleshooting Loop-specific issues

**I cannot change the billing frequency**

This is expected. Loop does not support prepaid subscriptions through this integration. The billing frequency field is disabled and automatically synced to the delivery frequency.

**The upgrade was accepted but the subscription was not modified**

If the subscription is unchanged, the most common causes are:

* You set the frequency manually and the customer's subscription has two or more active product lines. In this case, Loop requires a matching selling plan for the target frequency. Create the selling plan in Loop, or switch to **Use an existing selling plan** in the offer configuration.
* You used **Use an existing selling plan** and the selected selling plan no longer exists in your Loop dashboard. Create the selling plan in Loop and retry.
* Your API token is expired or lacks the required permissions: **write** on Subscription contracts, **read** on Orders and Selling plans. Go to **Step 1: Connect provider**, re-test your key, and check the error message for the specific missing scopes.
* The eligible product in the funnel does not match what the customer actually subscribed to.

Aftersell automatically retries failed provider calls in a background workflow. If all retries fail, contact support with your store URL, the Shopify order ID, the customer's email, the approximate time the upgrade was accepted, and the provider you are using.

**The selling plan dropdown is empty**

The "Use an existing selling plan" option pulls plans directly from Loop. If the dropdown is empty:

* Confirm selling plans are configured in your Loop dashboard.
* Make sure your API token has **Read** access to Selling plans.
* Go back to **Step 1: Connect provider**, re-test your API key, and continue.

**Temporary in-progress lines appear in my Loop dashboard**

This is expected when a multi-line subscription upgrade uses the default split behavior. Loop handles them in two steps (split, then remove), which can surface temporary lines during the 24-hour sync window. They resolve automatically once the sync completes. If you want to avoid the split entirely, see [Keeping multi-product subscriptions intact](#keeping-multi-product-subscriptions-intact).

***

← Back to [Subscription upgrades overview](/aftersell/subscription-upgrades) · [Setup & configuration](/aftersell/subscription-upgrades-setup) · [What are integrations?](/aftersell/subscription-upgrades-integrations)


# Subscription upgrades with Recharge
Source: https://docs.aftersell.com/aftersell/subscription-upgrades-recharge

Step-by-step guide to connecting Recharge and setting up Subscription Upgrades in Aftersell.

This page covers everything specific to using **Recharge** with Subscription Upgrades. For a full overview of how Subscription Upgrades work, see [Subscription Upgrades](/aftersell/subscription-upgrades).

## Supported features

Recharge supports all Subscription Upgrade types:

* Change delivery or billing frequency
* Replace with a different product
* Both – change frequency and replace product
* Add another subscribable item to subscription (see [Add an item](/aftersell/subscription-upgrades-add-item))
* Prepaid and postpaid frequencies

## Generating your Recharge API token

1. Log in to your Recharge merchant portal.
2. Navigate to **Tools & Apps → API Tokens**.
3. Click **Create an API Token**.
4. Enter a name and contact email.
5. Set the permissions Aftersell needs: **Read and Write** on Subscriptions, and **Read** on Orders and Plans. No Products scope is required.
6. Click **Save** and copy the API key.

The token must hold all four scopes: `read_orders`, `read_subscriptions`, `write_subscriptions`, and `read_plans`. Aftersell checks for all four when you test the key and names any missing ones in the error message.

For more details, see [Recharge's API documentation](https://docs.rechargepayments.com/).

## Connecting Recharge in the setup wizard

When you reach **Step 1: Connect provider** in the Subscription Upgrade wizard:

1. Select **Recharge** from the **Subscription provider** dropdown.
2. Paste your API token into the **API token** field.
3. Click **Test API key**. Aftersell validates the token, checking that it authenticates correctly, holds all required scopes, and belongs to your store.
4. Once the test passes (green check), click **Continue** to move to Step 2.

The test result shows one of two states:

* **Green tick — "API key verified".** the token authenticated, all required scopes are present, and the token belongs to your store. **Continue** is now enabled.
* **Red cancel icon.** The check did not come back clean. Read the message beside the icon: either the token was rejected or is missing required scopes. The message names the specific missing scopes. Fix the token in Recharge and test again. or Aftersell could not complete the check ("Could not verify the API key. Please try again."), which is a failed call rather than a bad token — in that case just test again.

A could-not-verify result looks exactly like a rejection, so go by the message rather than the icon. **Continue** stays disabled until the check comes back green, and editing the provider or the token clears the previous result.

## Verifying an upgrade in Recharge

After placing a test order and accepting the upgrade offer:

Go to **Customers** in your Recharge dashboard, find the customer, and open **Subscriptions**. The active subscription should reflect the new frequency, product, or discount immediately.

Recharge updates in near real-time after acceptance.

## Troubleshooting Recharge-specific issues

**The upgrade was accepted but the subscription was not modified**

The most common causes:

* Your API token is expired or lacks the required permissions. The token must have `read_orders`, `read_subscriptions`, `write_subscriptions`, and `read_plans`. Go to **Step 1: Connect provider**, re-test your key, and check the error message for the specific missing scopes.
* The eligible product in the funnel does not match what the customer actually subscribed to.

Aftersell automatically retries failed provider calls in a background workflow. If all retries fail, contact support with your store URL, the Shopify order ID, the customer's email, the approximate time the upgrade was accepted, and the provider you are using.

**The selling plan dropdown is empty**

The "Use an existing selling plan" option pulls plans directly from Recharge. If the dropdown is empty:

* Confirm selling plans are configured in your Recharge dashboard.
* Make sure your API token has `read_plans` scope.
* Go back to **Step 1: Connect provider**, re-test your API key, and continue.

***

← Back to [Subscription upgrades overview](/aftersell/subscription-upgrades) · [Setup & configuration](/aftersell/subscription-upgrades-setup) · [What are integrations?](/aftersell/subscription-upgrades-integrations)


# Setting up subscription upgrades
Source: https://docs.aftersell.com/aftersell/subscription-upgrades-setup

Build a Subscription Upgrade offer with the four-step wizard in Aftersell: connect provider, pick trigger product, configure upgrade, choose offer.

This guide walks through building a Subscription Upgrade offer with the setup wizard. New to the feature? Start with the [Overview](/aftersell/subscription-upgrades) first. For provider-specific API token steps, see [Integrations](/aftersell/subscription-upgrades-integrations).

## Creating a Subscription Upgrade offer

To set up a Subscription Upgrade, you will use the post-purchase funnel editor. The setup wizard walks you through four steps: connecting your subscription provider, picking the trigger product, configuring the upgrade itself, and choosing the offer product the customer sees on their order.

To open the wizard:

1. In your Aftersell dashboard, go to **Post-purchase funnels**.
2. Click **Add Funnel**.
3. Select the **Subscription Upgrade** template.

The starter screen shows three ready-made templates and two manual options. Each template card shows a before/after diagram of what the subscription becomes. Hover over a card title to see a short description. Select a template to pre-fill the wizard, or choose **Start from scratch** or **Copy an existing funnel** to build it yourself.

The available templates are:

* **Prepay for 3 months** — keeps monthly delivery but moves billing to every 3 months (prepaid). Not available on Loop stores, which bill on every delivery.
* **Replace subscription product** — swaps the subscribed product for a different one.
* **Upgrade to a 3-month supply** — swaps the product and moves both delivery and billing to every 3 months.

After selecting a template or a manual option, the **Set up a subscription upgrade** wizard opens with four steps.

### Step 1: Connect provider

*Add your API key.*

<Frame>
  <img alt="Selecting a subscription provider and entering an API token in the setup wizard" />
</Frame>

Pick your subscription platform and add your API token. Your provider will be used to update the customer's subscription after they accept the upgrade.

#### Pick your provider

From the **Subscription provider** dropdown, select **Recharge**, **Skio**, or **Loop**. The API token field and its helper text update to match the provider you picked.

#### Generate your API token

If you do not already have a token, generate one in your subscription platform. Each provider has different scopes and steps — see the dedicated guide for your provider:

* [Recharge: generating an API token](/aftersell/subscription-upgrades-recharge#generating-your-recharge-api-token)
* [Skio: generating an API token](/aftersell/subscription-upgrades-skio#generating-your-skio-api-token)
* [Loop: generating an API token](/aftersell/subscription-upgrades-loop#generating-your-loop-api-token)

<Note>
  **Loop prerequisite.** Loop does not support prepaid subscriptions through this integration — the billing frequency is locked to match delivery frequency. When using **Use an existing selling plan**, the plan must already exist in your Loop dashboard. When setting the frequency manually, no selling plan is required. See [Subscription upgrades with Loop](/aftersell/subscription-upgrades-loop) for full details.
</Note>

#### Paste, test, and save

Back in the Step 1 panel:

1. Paste your API token into the **API token** field.
2. Click **Test API key**. Aftersell validates the token against your provider, checking that it authenticates correctly, holds all required scopes, and belongs to your store.
3. Once the test passes (green check), click **Continue** to move to Step 2.

The test result shows one of two states:

* **Green tick — "API key verified".** The token authenticated, all required scopes are present, and the token belongs to your store. **Continue** is now enabled.
* **Red cancel icon.** The check did not come back clean. The message beside the icon says which of two things happened: your provider **rejected** the token (revoked, or missing required scopes — the message names the specific problem), or Aftersell **could not complete the check** ("Could not verify the API key. Please try again."), which is a failed call rather than a bad token. Fix the token if it was rejected; otherwise just test again.

There is no third, softer state — a could-not-verify result looks exactly like a rejection, so read the message rather than the icon.

**Continue** stays disabled until the check comes back green. Editing the provider or the token clears the previous result, so re-test after any change. This gate exists to prevent subscription upgrade failures that would otherwise only surface after a customer has been charged.

### Step 2: Trigger product

*Their current plan.*

Select the trigger product. Pick the subscription customers will be upgrading *from*.

1. Click **Choose subscription product**.
2. Only products with active subscription plans appear in the picker.
3. Select the product and variant.
4. Click **Select product**.

Once selected, the trigger card confirms whether the selected variant has an active selling plan in Shopify. A green checkmark means the variant is sold as a subscription and the funnel can fire. A red warning means the variant has no selling plan — the funnel cannot trigger until you add a selling plan to that variant in Shopify, or pick a different one.

The trigger product must have an active selling plan in Recharge, Skio, or Loop, since that is how the upgrade is applied to the customer's subscription.

<Frame>
  <img alt="Choosing the trigger subscription product in the setup wizard" />
</Frame>

<Tip>
  **Why a trigger product?**

  * Only customers buying this subscription will see this post-purchase offer.
  * Adds the selected product as a trigger for this funnel automatically.
  * You can add additional triggers to this funnel once the offer has been created.
</Tip>

<Note>
  Subscription Upgrades target a **single variant**. The trigger and replacement pickers select one variant each, and the funnel fires on a variant-scoped trigger — so selling plans that differ per variant are handled directly, with no need for a funnel per variant.
</Note>

<Warning>
  A funnel with a trigger variant that has no selling plan cannot be activated. The activation toggle is blocked until the variant has a selling plan, or you choose a different trigger product.
</Warning>

Click **Continue** to move to Step 3.

### Step 3: Subscription upgrade

*Frequency & pricing.*

Configure the subscription upgrade. Choose what happens when a customer accepts the upgrade.

<Frame>
  <img alt="Configuring the subscription upgrade type and frequency in the wizard" />
</Frame>

#### Subscription upgrade type

Pick one of four options from the dropdown:

* **Change delivery or billing frequency.** Keep the same product, change how often the customer is billed or shipped to.
* **Replace with a different subscription product.** Keep the same frequency, swap to a different product.
* **Both — change frequency and replace subscription product.** Do both at once.
* **Add another subscribable item to subscription.** Leave the existing subscription as is and add a new product to it, on the subscription's existing cadence.

The fields that appear below the dropdown change based on which option you pick.

#### Which price the Recurring subtotal shows

The **Recurring subtotal** in the offer tells the customer what their next renewal will cost. Which product that price is taken from depends on the upgrade type you picked:

| Upgrade type                                             | Price comes from            |
| -------------------------------------------------------- | --------------------------- |
| Change delivery or billing frequency                     | The **trigger** product     |
| Replace with a different subscription product            | The **replacement** product |
| Both — change frequency and replace subscription product | The **replacement** product |
| Add another subscribable item to subscription            | The **added** item          |

This is the most common source of confusion. A frequency-only upgrade keeps the same product by design, so its recurring subtotal can only ever show the trigger product's price, whatever frequency you set. If you expected a different product's price there, you most likely want **Both — change frequency and replace subscription product** instead.

The quantity used is taken from **Override subscription quantity**, which appears only on the replacement types. On a frequency-only upgrade it is always 1.

#### If you picked "Change delivery or billing frequency"

Choose how to define the new frequency:

* **Use an existing selling plan.** Pick from a dropdown of plans already configured in Recharge, Skio, or Loop. The plan defines the delivery and billing intervals.
* **Set the frequency manually.** Enter delivery and billing frequencies yourself.

If you set the frequency manually:

* **Delivery frequency**, how often the product ships.
* **Billing frequency**, how often the customer is charged.

<Tip>
  **Prepaid upgrades.** Set billing longer than delivery. For example, bill every six months, deliver every month. Customers pay upfront and receive multiple deliveries between charges.
</Tip>

<Note>
  Loop does not support prepaid frequencies. The billing frequency field is automatically synced to delivery frequency for Loop stores.
</Note>

#### If you picked "Replace with a different subscription product"

**Replacement subscription product.** Pick the subscription product the customer will be upgraded *to*. Only products with active selling plans are shown.

1. Click **Choose replacement product**.
2. Select the product (and a variant if applicable).
3. Click **Select product**.

**Override subscription quantity** (checkbox).

* When **off** (default), the existing subscription quantity is preserved on renewal.
* When **on**, enter the quantity that will apply to renewals of the replacement subscription.

Available for Recharge, Skio, and Loop.

#### If you picked "Both — change frequency and replace subscription product"

Both sets of fields appear: the frequency configuration from the first option, and the replacement product picker from the second. Fill in both, or the offer will not work.

#### If you picked "Add another subscribable item to subscription"

**Item to add to the subscription.** Pick the product that will be added to the customer's subscription. Only products with active selling plans are shown, because the added line has to be a recurring line in your subscription platform.

1. Click **Choose item to add**.
2. Select the product (and a variant if applicable).
3. Click **Select product**.

The cadence is inherited from the customer's existing subscription, so there are no frequency fields to set. The displayed price is charged on this Shopify order, and the item then bills with the subscription.

<Note>
  Add-item offers do not support a first-order or recurring discount, so the discount fields are hidden for this type. Prepaid subscriptions are not supported on Skio. For the full behaviour, including how Recharge differs from Skio and Loop, see [Adding an item to an existing subscription](/aftersell/subscription-upgrades-add-item).
</Note>

#### Upgrade timing

By default an upgrade takes effect from the customer's **next billing cycle**, keeping their existing renewal date.

If the timing option is enabled for your store, a checkbox appears under the frequency fields:

> **My fulfillment provider ships the upgraded item on the current order**

Ticking it starts the new billing interval immediately rather than at the next renewal, and it unlocks the **One-time upgrade price** field in Step 4.

<Warning>
  Aftersell does not change the order the customer just placed. This setting only moves the billing interval. Tick it only if your fulfillment provider is set up to recognize the upgrade's placeholder product and ship the upgraded item on the current order.
</Warning>

<Note>
  This checkbox is off by default and is not available on every store. It appears only on the **Change delivery or billing frequency** and **Both — change frequency and replace subscription product** upgrade types, and only once the option has been enabled for your store. Contact support through the in-app chat if you need it.
</Note>

#### Recurring discount

Optional incentive applied to **every future renewal** of the upgraded subscription. Not available for the add-item type.

How this field appears depends on whether the selected selling plan has stepped pricing policies:

* **When a selling plan with discount tiers is selected** (for example, a Loop plan that applies \$20 off on the first charge and \$10 off from the second charge onward), the free-entry field is replaced by a list of radio buttons — one per tier. Each option shows the discount amount and the charge range it applies to (for example, "Charge 1" or "Charge 2 onward"). Select the tier you want applied to every future renewal of the upgraded subscription.
* **When no selling plan is selected, or the selected plan has no discount tiers**, the standard free-entry field appears. Enter the amount and choose **Percentage** or **Fixed amount**.

This discount stays in effect for all future renewals, not just the first cycle.

Click **Continue** to move to Step 4.

### Step 4: Offer product

*A visual placeholder.*

Select the offer product. This is a **visual placeholder only**, not a real product the customer buys.

At the bottom of this step, a **What changes on their subscription** panel shows a live before/after preview of the upgrade based on your current settings. It updates as you fill in the offer product details and reflects the billing cycle, delivery frequency, quantity, and price that will apply after the customer accepts.

<Info>
  This is not an actual product, it is a placeholder to capture the price between upgrades, because Shopify does not allow a subscription to show if one is in the original order.
</Info>

Choose one of two options:

#### Option A: Create new

Aftersell creates an unpublished placeholder product in your Shopify catalog on your behalf.

* **Product image.** Upload the image shown in the offer card.
* **Product title.** The name shown in the offer card, for example Premium upgrade.
* **One-time upgrade price.** On the **Change delivery or billing frequency** and **Both — change frequency and replace subscription product** types this is locked at `0` by default, because your subscription provider charges at the end of the current billing cycle and the placeholder product appears on the Shopify order at `$0.00`. It becomes editable there only when the upgrade-timing checkbox in Step 3 is ticked. On **Replace with a different subscription product** and **Add another subscribable item to subscription** the timing checkbox does not apply, so the price field is always editable. See [Upgrade timing](#upgrade-timing).

  What to put in it depends on the upgrade type:

  * **Frequency, replacement, or both** — the price *difference* between the original and the upgraded subscription. The customer keeps their subscription and this charge covers the delta.
  * **Add another subscribable item** — the charge for the added item on this order. Nothing is being swapped, so there is no difference to compute: this is simply what the customer pays now for the new item, which then recurs with their subscription. See [Adding an item to an existing subscription](/aftersell/subscription-upgrades-add-item).
* **First-order discount.** An optional discount applied only to this upgrade purchase, entered as a percentage (`%`) or a fixed amount. It sits beside **One-time upgrade price** and appears whenever that field is editable, on both the **Create new** and **Pick existing** tabs. On the add-item type the field still appears but is always saved as `0` — add-item offers never carry a discount, so set the price you want on the offer product instead.

<Note>
  **Why a separate offer product?**

  * The image, title, and price you set appear in the offer.
  * On accept, the displayed price is charged and Recharge, Skio, or Loop applies the upgrade.
  * Shopify will not allow a subscription product as a post-purchase upsell after a subscription order, so the product here must be a non-subscription SKU.
</Note>

#### Option B: Pick existing

Pick a product you have already created in Shopify. The trigger product is auto-hidden from the picker since it's a subscription product.

1. Click **Choose offer product**.
2. The picker shows only **products without active subscription plans**.
3. Select the product and click **Select product**.

The customer is shown that product at its **existing Shopify price**. That price is charged on this Shopify order, in addition to the subscription upgrade applied in Recharge, Skio, or Loop on the next cycle.

<Warning>
  The offer product must support one-time purchase. Subscription-only products are filtered out of the picker. Shopify does not allow adding a second subscription to an order that already contains one.
</Warning>

<Frame>
  <img alt="Selecting the offer product with Create new and Pick existing options" />
</Frame>

When Step 4 is complete, click **Create offer**.

## Additional triggers and refinements

The wizard automatically adds the trigger product in Step 2. This section is for any additional triggers you want to layer on top of it.

After the wizard completes, additional triggers are available in the **Triggers** step of the funnel editor. For subscription upgrade funnels, these optional triggers are grouped under a collapsible **Additional triggers** section. The section shows a count of how many optional triggers are active. It opens automatically if the funnel already has optional triggers set, so no active configuration is ever hidden.

### Why product-specific triggers matter

Without a product trigger, your funnel may show to customers who do not have the eligible subscription product in their order. This results in wasted impressions and a subscription modification that silently fails: the offer product gets added to the order, but no subscription is changed in Recharge, Skio, or Loop.

### Recommended trigger setup

The wizard wires this for you — you don't need to set it up by hand.

| Trigger                     | Setting                                                                                                         |
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Variant on subscription** | Set to your eligible (target) variant. Fires only when that variant is in the order **on a subscription line**. |

<Warning>
  **Don't replace this with a Product trigger plus a Subscription trigger.** That older combination is two independent conditions, so an order containing your trigger product as a *one-time* purchase alongside an *unrelated* subscription item satisfies both — the funnel fires, and the upgrade then fails downstream because there is no matching subscription to change. **Variant on subscription** is a single condition that can't come apart that way, and the wizard migrates older funnels off the combo automatically.
</Warning>

All enabled triggers use AND logic. Every condition must be met for the funnel to show.

<Warning>
  If **Show this funnel for all customers** is enabled, it overrides all other triggers and the funnel fires for every checkout. This is not recommended for subscription upgrade funnels.
</Warning>

## Editing an offer after it's been created

You can change a Subscription Upgrade offer after creating it. A Subscription Upgrade funnel keeps a permanent **Setup** step in the funnel editor, which re-opens the same wizard pre-filled from the saved offer — its primary button reads **Save offer** rather than the create-time wording. Use that, or edit the offer's fields directly in its settings.

1. In your Aftersell dashboard, go to **Post-purchase funnels**.
2. Open the funnel that contains your Subscription Upgrade offer.
3. Select the offer to open its settings, then edit the fields inline — trigger product, upgrade type, upgrade frequency and recurring discount, and the offer product's image, title, or price.
4. Save.

<Note>
  If the offer uses **an existing selling plan** for its frequency, the frequency fields are set by that selling plan and can't be edited here. If the plan has stepped discount tiers, the recurring discount field shows those tiers as radio buttons — select the one you want applied to renewals. Switch the offer to setting the frequency manually if you need to enter a custom discount amount instead.
</Note>

Edits only affect orders placed after you save. Existing accepted upgrades — including subscriptions already modified in Recharge, Skio, or Loop — are not retroactively changed.

## Next steps

Once your offer is live, [test and verify it](/aftersell/subscription-upgrades-testing) before relying on it. Also review the [limitations and important notes](/aftersell/subscription-upgrades-limitations) and set up [fulfillment and 3PL mapping](/aftersell/subscription-upgrades-fulfillment).


# Subscription upgrades with Skio
Source: https://docs.aftersell.com/aftersell/subscription-upgrades-skio

Step-by-step guide to connecting Skio and setting up Subscription Upgrades in Aftersell.

This page covers everything specific to using **Skio** with Subscription Upgrades. For a full overview of how Subscription Upgrades work, see [Subscription Upgrades](/aftersell/subscription-upgrades).

## Supported features

Skio supports all Subscription Upgrade types:

* Change delivery or billing frequency
* Replace with a different product
* Both – change frequency and replace product
* Add another subscribable item to subscription (see [Add an item](/aftersell/subscription-upgrades-add-item))
* Prepaid and postpaid frequencies

## Generating your Skio API token

1. In your Skio dashboard, go to **API & Integrations → API**.
2. Enter a name for your new API key and click **Generate API key**.
3. Copy the key immediately. It will only be shown once.
4. Skio issues a single full-access API key, so there are no separate scopes to select. The key grants the subscription edit, create, and cancel access the upgrade needs.

For more details, see [Skio's API documentation](https://docs.skio.com/).

## Connecting Skio in the setup wizard

When you reach **Step 1: Connect provider** in the Subscription Upgrade wizard:

1. Select **Skio** from the **Subscription provider** dropdown.
2. Paste your API token into the **API token** field.
3. Click **Test API key**. Aftersell validates the token, checking that it authenticates correctly and belongs to your store.
4. Once the test passes (green check), click **Continue** to move to Step 2.

The test result shows one of two states:

* **Green tick — "API key verified".** the token authenticated and belongs to your store. **Continue** is now enabled.
* **Red cancel icon.** The check did not come back clean. Read the message beside the icon: either the token was rejected or does not have access to your Skio account. Generate a fresh key in Skio and test again. or Aftersell could not complete the check ("Could not verify the API key. Please try again."), which is a failed call rather than a bad token — in that case just test again.

A could-not-verify result looks exactly like a rejection, so go by the message rather than the icon. **Continue** stays disabled until the check comes back green, and editing the provider or the token clears the previous result.

## Verifying an upgrade in Skio

After placing a test order and accepting the upgrade offer:

Go to **Subscriptions** in your Skio dashboard and find the customer's subscription. The line item, interval, and selling plan should reflect the change immediately.

Skio updates in near real-time after acceptance.

## Troubleshooting Skio-specific issues

**The upgrade was accepted but the subscription was not modified**

The most common causes:

* Your API token is expired or no longer valid. Skio uses a single full-access key, so generate a fresh key in Skio, go to **Step 1: Connect provider**, and re-test it.
* The eligible product in the funnel does not match what the customer actually subscribed to.

Aftersell automatically retries failed provider calls in a background workflow. If all retries fail, contact support with your store URL, the Shopify order ID, the customer's email, the approximate time the upgrade was accepted, and the provider you are using.

**The selling plan dropdown is empty**

The "Use an existing selling plan" option pulls plans directly from Skio. If the dropdown is empty:

* Confirm selling plans are configured in your Skio dashboard.
* Make sure your API key is valid and still has access to your Skio account.
* Go back to **Step 1: Connect provider**, re-test your API key, and continue.

***

← Back to [Subscription upgrades overview](/aftersell/subscription-upgrades) · [Setup & configuration](/aftersell/subscription-upgrades-setup) · [What are integrations?](/aftersell/subscription-upgrades-integrations)


# Testing subscription upgrades
Source: https://docs.aftersell.com/aftersell/subscription-upgrades-testing



Because the offer product and the subscription change happen against different systems, you need to check both to confirm an upgrade worked. Run this test after you [set up an offer](/aftersell/subscription-upgrades-setup) and before you rely on the funnel in production.

## Testing and verifying an upgrade

<Steps>
  <Step title="Place a test order">
    Place a real test order with a small price. Buy the trigger subscription product.
  </Step>

  <Step title="Accept the upgrade">
    Accept the upgrade offer on the post-purchase page.
  </Step>

  <Step title="Check Shopify">
    In **Shopify Admin → Orders**, find the test order. You should see the offer product as a line item. This is expected, it is not the subscription change.
  </Step>

  <Step title="Check Recharge, Skio, or Loop">
    Find the customer's subscription in your provider's dashboard and confirm the change.
  </Step>
</Steps>

**Where to look in each provider:**

* **Recharge.** Customers → find the customer → Subscriptions. The active subscription should reflect the new frequency, product, or discount immediately.
* **Skio.** Subscriptions → find the customer's subscription. The line item, interval, and selling plan should reflect the change.
* **Loop.** Subscriptions → find the customer's subscription. Wait up to 24 hours. Loop's APIs sync asynchronously and the change may not appear immediately, even on a successful upgrade.

## When something looks wrong

If the upgrade did not apply as expected, see [Troubleshooting](/aftersell/subscription-upgrades-troubleshooting). When contacting support, include:

* Your store URL.
* The Shopify order ID.
* The customer's email.
* The approximate time the upgrade was accepted.
* Which provider you are using.


# Subscription upgrades troubleshooting
Source: https://docs.aftersell.com/aftersell/subscription-upgrades-troubleshooting

Fixes for common Subscription Upgrades issues, including upgrade failure alerts, provider connection problems, and empty selling plan dropdowns.

Fixes for the most common Subscription Upgrade issues. If you are still stuck after trying these, contact support with the details listed under [Testing and verifying](/aftersell/subscription-upgrades-testing#when-something-looks-wrong).

## Monitoring upgrade failures

Aftersell monitors for terminal upgrade failures over a rolling 7-day window. If the number of failures crosses the alert threshold, a **warning banner** appears on your home page describing how many upgrades failed and over how many days. The same alert also surfaces in the **Needs attention** panel of the [home page](/aftersell/home/needs-attention).

The alert includes a **Review orders** button that takes you directly to the order browser filtered to subscription upgrade issues, so you can see the affected orders and the specific cause for each failure. It clears automatically once the failure count drops below the threshold within the rolling window. If you see this alert, open the order browser and check the cause shown on each affected order, then refer to the relevant troubleshooting steps below.

<AccordionGroup>
  <Accordion title="I cannot get past Step 1: Connect provider">
    The **Subscription Upgrade** template is never hidden — it is always listed under **Add Funnel**, whatever your provider setup. What blocks you is the Step 1 connection check: **Continue** stays disabled until **Test API key** returns **API key verified** with a green tick.

    Two different outcomes render the same red cancel icon, so read the message beside it:

    * **Your provider rejected the key.** The token is missing required scopes or has been revoked, and the message names the specific problem. Issue a new token in your provider dashboard with the scopes listed in [Setup & configuration](/aftersell/subscription-upgrades-setup), paste it in, and test again.
    * **Aftersell could not reach your provider** — "Could not verify the API key. Please try again." Nothing is necessarily wrong with the token; the call itself failed. Click **Test API key** again.

    Editing the provider or the token clears the previous verdict, so re-test after any change.
  </Accordion>

  <Accordion title="My customer sees an unexpected product in their order">
    This is expected behaviour. The product is the offer product, the placeholder line item added to the Shopify order as a record of the accepted upgrade. To reduce confusion, rename the offer product to something clear and add a description in Shopify Admin explaining what it represents. See [What the customer sees](/aftersell/subscription-upgrades#what-the-customer-sees).
  </Accordion>

  <Accordion title="The upgrade was accepted but the subscription was not modified">
    The Shopify changeset and the provider API call are independent. If the offer product was added to the order but the subscription was not changed, the most common causes are:

    * Your provider API token is expired or lacks the required permissions. For Recharge, the token must have `read_orders`, `read_subscriptions`, `write_subscriptions`, and `read_plans`. Go to **Step 1: Connect provider**, re-test your key, and check the error message for the specific missing scopes.
    * The eligible product in the funnel does not match what the customer actually subscribed to.
    * For Loop, the target selling plan does not exist in your Loop dashboard for the configured frequency.
    * The retry workflow may still be working through its schedule: after a failed call it tries again at +1 hour, then at +24 hours. This is the same for every provider — Loop included, whose upgrade calls are synchronous and show up in the dashboard immediately when they succeed.

    Aftersell automatically retries failed provider calls in a background workflow. The workflow checks the provider's current state before re-running, so a successful but slow upgrade is not applied twice.

    If a replay can't fix the cause, the workflow either **refunds the charge** — when no provider mutation succeeded and the charged line was a placeholder — or flags the upgrade for **manual reconciliation**, leaving the order intact. Net-new subscriptions and box upgrades are never auto-refunded, because the shopper receives real products. Contact support with the details listed in [Testing and verifying](/aftersell/subscription-upgrades-testing#when-something-looks-wrong).
  </Accordion>

  <Accordion title="The selling plan dropdown is empty">
    The "Use an existing selling plan" option pulls plans directly from Recharge, Skio, or Loop. If the dropdown is empty:

    * Confirm selling plans are configured in your provider dashboard.
    * Make sure your API token has read access to Plans (Recharge: `read_plans` scope) or the appropriate scopes (Skio, Loop).
    * Go back to **Step 1: Connect provider**, re-test your API key, and continue.
  </Accordion>

  <Accordion title="I am using Loop and there is no billing frequency field">
    This is expected. On Loop the **Billing frequency** field is not shown at all — only **Delivery frequency**, with the note "Loop syncs billing to delivery — customers are charged on each renewal". Whatever you set as the delivery frequency is also the billing frequency.

    That is also why prepaid subscriptions — a billing frequency longer than the delivery frequency — are not supported on Loop: the integration rejects them outright rather than offering a field you cannot use. The other providers show both fields.
  </Accordion>

  <Accordion title="The order browser shows a Subscription conflict badge">
    The offer product is subscription-only — either the product itself, or every one of its variants — and the customer's checkout already contained a subscription. Shopify does not allow a second subscription on the same order, so the offer was skipped.

    The order details panel spells out which case it was: "The customer's checkout already has a subscription, and the offer product is subscription-only", or "All variants of the offer product are subscriptions, and the customer's checkout already has one." Both are fixed the same way — edit the offer's product selection and swap in a one-time-purchase product, or use the **Create new** option in **Step 4: Offer product** to generate a placeholder.
  </Accordion>

  <Accordion title="My upgrade offer is showing to customers who are not subscribers">
    * Check that **Show this funnel for all customers** is not enabled. This overrides all other triggers.
    * Check the **Variant on subscription** trigger. It shows the funnel only when the order includes one of the selected products *purchased as a subscription*. On a funnel that has a subscription upgrade offer, the wizard owns this trigger and keeps it in sync with the product being upgraded, so it is read-only — the panel reads "Managed by this funnel's subscription upgrade offer." If it is targeting the wrong products, correct the upgrade offer's trigger product rather than the trigger itself.
    * Check funnel priority. A higher-priority funnel with broader triggers may be firing first.

    <Warning>
      Do not try to reproduce this with a separate product trigger plus a subscription trigger. That pairing is exactly what **Variant on subscription** replaced: the two matched independently, so an order containing your trigger product as a one-time purchase *and* an unrelated subscription item satisfied both, fired the funnel, and the upgrade then failed downstream. One trigger, matching product and subscription state together, is the supported setup.
    </Warning>
  </Accordion>
</AccordionGroup>


# Subscription upsells on orders that already have a subscription
Source: https://docs.aftersell.com/aftersell/subscription-upsell-existing-subscribers



Shopify does not let a post-purchase upsell add a subscription to an order that already contains one. Historically that meant a [Subscription Upsell](/aftersell/subscriptions_in_post_purchase_offers) offer was skipped, or downgraded to a one-time purchase, whenever the customer's order already had a subscription in it — exactly the customers most likely to subscribe again.

When you connect a supported subscription provider, Aftersell works around that restriction. Instead of asking Shopify to add the second subscription, Aftersell creates it directly in **Recharge**, **Skio**, or **Loop** when the customer accepts. Your subscription offers now reach subscribers as well as one-time buyers.

## What changes

|                                                                          | Without a connected provider                                    | With Recharge, Skio, or Loop connected     |
| ------------------------------------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------ |
| Order has no subscription                                                | Subscription option shows.                                      | Subscription option shows.                 |
| Order already has a subscription, offer is **subscription-only**         | Offer is dropped for that customer.                             | Offer shows, with its subscription option. |
| Order already has a subscription, offer is **one-time and subscription** | Subscription option is removed; only the one-time option shows. | Both options show.                         |

Nothing changes for one-time offers, and nothing changes for [Subscription Upgrade](/aftersell/subscription-upgrades) offers, which modify the existing subscription rather than adding a new one.

<Note>
  This is a second, independent subscription — not a change to the one the customer already has. If you want to modify the subscription they already own (change its frequency, swap its product, or add an item to it), use [Subscription Upgrade](/aftersell/subscription-upgrades) instead.
</Note>

## Requirements

For a subscription offer to show on an order that already contains a subscription, all of the following must be true:

* A supported subscription provider (**Recharge**, **Skio**, or **Loop**) is connected with a valid API token.
* The customer's order contains at least one subscription line item.
* The offer's purchase option is **Subscription only** or **One-time and subscription**.
* The offer is a regular product upsell, not a Subscription Upgrade offer.

If no provider is connected, the previous behaviour applies: the subscription option is dropped or downgraded to one-time.

## Setting it up

There is no separate offer type to create. Connect a provider and your existing subscription offers gain the extra reach automatically.

1. In your Aftersell dashboard, go to **Settings → Subscription Upgrades**.
2. Select your provider and paste your API token. For provider-specific token steps and required scopes, see [Integrations](/aftersell/subscription-upgrades-integrations).
3. Click **Test API key** and save once the check passes.

The post-purchase funnel editor also surfaces this directly. When an offer in your funnel contains a subscription product and no provider is connected, an **Unlock more reach** banner appears with a **Connect a provider** action. Once a provider is connected, the banner and the previous subscription-limitation warning both disappear for that offer.

<Tip>
  If you previously added a **Subscription trigger** set to *exclude* orders containing a subscription — the workaround recommended before this was possible — remove it. That trigger now prevents the offer from reaching the subscribers it can finally serve.
</Tip>

## What the customer sees

### On the Shopify order

The customer's order contains:

* The **original subscription line item** they bought at checkout.
* The **new item** they accepted post-purchase, charged as a one-time line at the first-cycle price of the plan they chose.

The first cycle is charged on the Shopify order the customer just completed. The recurring subscription itself is created in your subscription provider and bills from the **next** cycle onward.

### In the subscription provider portal

The customer ends up with **two separate subscriptions**: the one from their checkout, and the new one Aftersell created. Each has its own cadence, pricing, and management, so the customer can pause or cancel either independently.

The new subscription reuses the customer, shipping address, and payment context from the subscription already on the order, which is why no additional payment or shipping details are needed at accept time.

### Discounts

The price the customer sees reflects the selling plan they picked:

* **First cycle.** The plan's introductory pricing, plus your offer discount if you set it to apply to subscriptions. This is the amount charged on the Shopify order.
* **Recurring cycles.** The plan's ongoing subscription discount, applied by your provider on every renewal.

## Provider notes

| Provider | Notes                                                                                                                                                                                                                                           |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Recharge | All configured plan cadences can be offered, including prepaid.                                                                                                                                                                                 |
| Skio     | All configured plan cadences can be offered, including prepaid.                                                                                                                                                                                 |
| Loop     | Loop cannot create prepaid subscriptions through this integration. Prepaid plans are automatically hidden from the offer on Loop stores, so a customer is never charged for a plan that could not be created. Non-prepaid plans are unaffected. |

## Limitations

* **A provider connection is required.** Without Recharge, Skio, or Loop connected, this does not apply and subscription offers continue to be dropped or downgraded on subscription orders.
* **Prepaid plans are unavailable on Loop.** They are hidden from the offer rather than failing at accept.
* **One subscription offer per post-purchase flow.** Only the first accepted subscription offer in a funnel goes through. Subsequent subscription offers in the same funnel are still skipped.
* **The order must already contain a subscription for this path to be used.** On orders with no subscription, subscription offers work through Shopify's native Subscription API as documented in [Subscription Upsell](/aftersell/subscriptions_in_post_purchase_offers).
* **Provider failures are retried.** If the subscription cannot be created at the provider after the customer was charged, Aftersell retries in a background workflow. A net-new subscription is **never auto-refunded** if the retries don't succeed: the charged line is a real product the shopper receives, so refunding would hand it over free and still leave no subscription. The case is routed to manual reconciliation instead. See [Troubleshooting](/aftersell/subscription-upgrades-troubleshooting).

## Related

* [Subscription Upsell (full guide)](/aftersell/subscriptions_in_post_purchase_offers)
* [Subscription Upgrades overview](/aftersell/subscription-upgrades)
* [Integrations: Recharge, Skio, and Loop](/aftersell/subscription-upgrades-integrations)
* [Troubleshooting](/aftersell/subscription-upgrades-troubleshooting)


# Subscriptions in post-purchase offers
Source: https://docs.aftersell.com/aftersell/subscriptions_in_post_purchase_offers



This guide is the complete walkthrough for **Subscription Upsell**: offering a customer a brand-new recurring subscription right after they complete checkout on a one-time order. It covers the full setup flow, the Shopify platform limitations every post-purchase app inherits, what the customer sees, fulfillment, testing, and troubleshooting.

<Info>
  **Working with subscriptions in post-purchase?** Aftersell has three subscription-adjacent features, and the right one depends on whether the customer's order already contains a subscription:

  * **Subscription Upsell** (this guide). Add a new subscription line item to a one-time order. The customer keeps their one-time purchase and gets a new recurring subscription on top.
  * [**Subscription Upgrade**](/aftersell/subscription-upgrades). Modify a customer's existing subscription after checkout (change frequency, swap product, or both).
  * [**Replacement Upsell**](/aftersell/replacement_upsells). Swap a one-time product in the order for another product. The replacement can be a subscription version of the same product, a different one-time product, or a different variant or quantity. Replacement Upsell cannot operate on a subscription line, if the order already contains a subscription, use Subscription Upgrade instead.

  **Think of it like this:** Subscription Upgrade *modifies* an existing subscription in some way. Subscription Upsell is *additive only* — it creates a brand-new subscription.

  Subscription Upsell works whether or not the customer already bought a subscription in this order. If they already have one, connect Recharge, Skio, or Loop and Aftersell creates the second subscription in your provider — see [upselling existing subscribers](/aftersell/subscription-upsell-existing-subscribers).
</Info>

<Warning>
  **One subscription per order — unless you connect a provider.** Shopify does not allow a post-purchase upsell to add a subscription to an order that already contains one. Connecting Recharge, Skio, or Loop lifts this for Subscription Upsell, because Aftersell then creates the new subscription in your provider instead of through Shopify ([details](/aftersell/subscription-upsell-existing-subscribers)). Without a provider connected, the rule still applies. Either way, if your funnel has more than one subscription offer, only the first accepted one will land — the rest silently skip. See [Shopify platform limitations](#shopify-platform-limitations) for the full set of rules and recommended trigger setup.
</Warning>

## What is a Subscription Upsell?

Subscription Upsell uses Shopify's native Subscription API to add a new recurring subscription to the customer's order on the post-purchase page. The customer accepts in one click without re-entering payment or shipping. Their one-time purchase stays in the order as is, and the new subscription line item is added alongside it.

The customer journey is four short steps:

1. **Customer completes checkout** on a one-time product.
2. **Sees the Subscription Upsell offer** on the post-purchase page.
3. **Accepts** without re-entering payment or shipping details.
4. **Their first subscription order ships**, and future renewals are billed by your subscription provider on the cadence you configured.

Under the hood, Aftersell uses Shopify's native `add_subscription` post-purchase changeset. Aftersell does not call your subscription app's API directly for this flow, the subscription is created by Shopify and your subscription app picks it up via its own Shopify integration. This is why Subscription Upsell works with any subscription app that uses Shopify's native Subscription API.

The first cycle of the subscription is fulfilled from the **original Shopify order** as a normal line item. Subsequent renewals are managed by your subscription provider, the same as any subscription created during regular checkout.

## When to use a Subscription Upsell

Subscription Upsell works best when:

* Your one-time product is a **consumable or replenishment** (skincare, supplements, pet food, coffee, household goods). Customers already need it again, so the recurring offer feels natural.
* The customer just demonstrated **purchase intent** by completing checkout, which makes them more receptive to a related subscription than they would be on a cold landing page.
* You can offer a **clear value exchange**, typically a first-cycle discount, free shipping on subscription orders, or a small free gift on the first delivery.

Avoid using Subscription Upsell for products with **irregular usage patterns**, very high price points where commitment friction outweighs the discount, or products that customers typically buy as one-off gifts.

## Compatible subscription platforms

Subscription Upsell is fully provider-agnostic on the Aftersell side. Aftersell adds the subscription via Shopify's native `add_subscription` post-purchase changeset, and Shopify routes the enrollment to whichever subscription app you have installed on the Shopify Subscription API. This means any subscription app that uses Shopify's native Subscription API will work without additional setup, including Recharge, Skio, Loop, Stay.ai, Appstle, Smartrr, Bold Subscriptions (when running on Shopify's native subscriptions API), and Shopify's native selling plans.

Selling plans you create in your subscription app are pulled into Aftersell automatically.

For Subscription Upgrade compatibility, which is different and provider-specific, see [Subscription Upgrades](/aftersell/subscription-upgrades).

## Creating a Subscription Upsell offer

To create a Subscription Upsell, build a standard post-purchase offer and select a product that has selling plans enabled in Shopify. There is no separate template, the offer adapts to the product you pick.

To open the offer editor:

1. In your Aftersell dashboard, go to **Post-purchase funnels**.
2. Open an existing funnel or click **Add Funnel** to create a new one.
3. On an empty offer slot, click **Create your first offer** (or **Create offer**) and select the product you want to offer.

If the product has selling plans configured in Shopify, the offer editor automatically shows subscription-related controls.

### Offering subscription products after checkout

If a product has selling plans enabled in Shopify, you can offer it in one of three ways. Choose the right mode for each offer.

#### 1. Only sell as a one-time product

The product is offered as a one-time purchase. No subscription option is shown, even though the product has selling plans in Shopify. The experience feels like a typical post-purchase offer.

Pick this when you want to feature a subscription-enabled product but **not** commit the offer to recurring revenue (for example, a sampler or trial size).

#### 2. Only sell as a subscription

The product must be purchased as a subscription. Customers cannot choose a one-time purchase. The available subscription options come directly from Shopify.

Pick this when you want to fully commit the offer to recurring revenue.

#### 3. Sell as both a subscription and a one-time product

Customers can choose between a one-time purchase or a subscription. The pricing and delivery frequency come from Shopify. This is the most flexible option and the easiest place to lean on a [subscription default](#choosing-a-default-option) and a [first-cycle discount](#subscription-discounts) to nudge customers toward the recurring choice.

### Choosing a default option

If you offer both one-time and subscription options, you can decide which one is preselected when the offer loads. This default selection:

* Guides customer behaviour. Pre-selecting the subscription leans on default-bias and lifts subscription acceptance.
* Highlights your preferred option (such as the subscription).
* Still allows customers to switch before accepting.

Industry data consistently shows that **defaulting to subscription** lifts subscription acceptance by 10 to 15 percent versus defaulting to one-time. Acceptance rates for well-matched post-purchase subscription offers typically fall in the **15 to 30 percent range** when paired with a first-cycle incentive.

<Tip>
  If your goal is recurring revenue, set the default to subscription. If your goal is one-time-purchase optimization with subscription as an option for power users, set the default to one-time.
</Tip>

### Allowed subscription plans

When offering subscription products with multiple selling plans, you can restrict which plans customers can choose using the **Allowed subscription plans** setting. This is useful when you want to promote specific frequencies or pricing tiers without exposing every plan on the product.

#### How allowed subscription plans works

The setting is an allowlist, applied **per variant**. For the variant a customer selects, they see only the allowed plans available for that variant:

* If exactly one allowed plan applies, its name is shown as static text and there is no choice to make.
* If several apply, the customer picks between them in a **Purchase options** dropdown.
* If none apply, that variant falls back to showing all of its own plans.

That per-variant scoping means a single allowlist can correctly handle a product whose variants carry different selling plans.

#### Configuring allowed subscription plans

1. Open your post-purchase offer in the editor.
2. Navigate to the **Variant & Plan Options** section.
3. Use the **Allowed subscription plans** multi-select to search for and select the plans you want to allow. Selected plans appear as removable tags.
4. Save your offer.

If no plans are selected, customers can choose from every plan available for their selected variant.

The editor warns you if any subscription variants aren't covered by your selection — those variants fall back to showing all of their plans.

#### Fallback behaviour

If none of the allowed plans are available for a variant — because a plan was removed or disabled in Shopify, for example — the offer falls back to showing all available plans for that variant, so customers can still complete the purchase.

#### Automatic reset

The allowed plans setting is cleared if you change the product's purchase option to one-time purchase only. This prevents configuration errors when subscription options are removed.

<Tip>
  Use allowed subscription plans when you want to standardize on specific cadences for post-purchase acquisition. If a product has weekly, biweekly and monthly plans, you can allow only the monthly plan to protect margin, even though the product page still offers all three.
</Tip>

### Which selling plan is shown by default

When no plans are selected in **Allowed subscription plans**, the offer preselects the **first selling plan** configured on the product in Shopify. If that variant has more than one plan available, customers can change it in the **Purchase options** dropdown. To control which plan customers see:

* **Restrict the plans** (recommended). Use the **Allowed subscription plans** multi-select. Allow exactly one and customers see only that plan, with no dropdown.
* **Reorder selling plans in Shopify**. The order of selling plans on the product determines which one is shown first.
* **Remove unused selling plans from the product**. If you have multiple frequencies and only want one to surface, the simplest path is to keep only the relevant selling plan attached to the product.

Customers can pick a cadence in the offer whenever more than one plan applies to their variant. If you would rather they didn't, allow a single plan — the dropdown disappears and the plan renders as static text. Customers can still change cadence later in your subscription provider's portal.

The most important factor for retention is matching the cadence to actual product usage. A 30-day shampoo subscription where the bottle lasts 60 days will get cancelled. A 60-day subscription where the bottle lasts 30 days will get skipped. Look at your one-time reorder data to find the natural cadence per product. If you offer multiple cadences, three or four well-chosen frequencies typically outperform a single locked cadence.

## Subscription discounts

When you apply a discount to a Subscription Upsell offer, the discount applies to the **first billing cycle only**. Future recurring orders are charged at the regular subscription price. Customers can see this in the offer experience under the **Recurring subtotal**, which shows what future renewals will cost.

This is different from the recurring discount used by Subscription Upgrade. For Subscription Upgrade discount behaviour, see [Subscription Upgrades](/aftersell/subscription-upgrades).

### What price the customer actually sees

Where the price appears in the offer matters for how the customer reads it. The post-purchase offer shows two distinct prices:

* The **Accept Offer button** and the line-item subtotal reflect the **first-cycle price**, including any first-cycle discount you have configured.
* The **Recurring subtotal** field shows what the customer will be charged on **subsequent renewals** at the regular subscription price.

This works cleanly for typical first-cycle discounts (10 to 25 percent off the first delivery). It can read confusingly if you configure an extreme first-cycle discount such as 100% off the first delivery, because the recurring price (not the \$0 first-cycle price) is the more visible number on the offer. If you intend a free first delivery, be explicit in the offer copy ("First box free, then \$59.99 every 30 days") so customers understand the recurring price they see is the ongoing rate.

### Discount types

You can configure discounts in two ways:

* **Percentage discount.** Reduces the subscription price by a percentage (for example, 15% off).
* **Fixed amount discount.** Reduces the subscription price by a specific dollar amount (for example, \$5 off).

<Warning>
  **The discount only reaches the subscription if you tick "Apply discount to subscriptions".** Without it, the `add_subscription` changeset carries no discount and the subscription bills at full price — the offer's discount applies to the one-time line only.
</Warning>

The discount rides on Shopify's `add_subscription` post-purchase changeset rather than being applied through your subscription app, and it only affects the subscription created by this offer.

### How much to discount

Common discount ranges for post-purchase subscription offers:

* **10 to 15 percent first-cycle discount** is the most common range and produces solid acceptance lift without significant margin loss.
* **20 to 25 percent first-cycle discount** is the upper bound, used to push acceptance higher on competitive products or when the recurring cadence is short (weekly, biweekly).
* **Free gift on first delivery** is an alternative that some merchants find lifts acceptance further than a price discount, because it changes the conversation from "save money" to "get something extra".

Stick to first-cycle discount in most cases. Customers expect it, and your subscription provider supports it without custom work. Step-down discounts (30% first, 20% second, 10% ongoing) are rarely worth the complexity because they are hard to communicate clearly.

Whatever level you pick, make the discount visible in both the offer button and the line-item summary, and make it clear that it applies to the first cycle only.

## Worked examples

Four common Subscription Upsell scenarios, with the exact configuration and what the customer experiences.

### Scenario 1: Standard one-time + subscription with first-cycle discount

**Setup.** Your customer bought a one-time bottle of moisturizer at \$30. You want to offer them a monthly subscription of the same product at \$25 per month, with a 20% first-cycle discount as an acceptance incentive.

**What you set in the offer:**

* Purchase option: Sell as both a subscription and a one-time product.
* Default option: Subscription.
* Selling plan: Monthly, \$25.
* First-cycle discount: 20% off.

**What the customer sees in the offer:**

* The subscription option is preselected.
* Accept Offer button: \$20.00 (first cycle, 20% off \$25).
* Recurring subtotal: \$25.00 every 30 days.

**On accept:**

* Shopify charges them an additional \$20 on this order.
* A monthly subscription is created in your subscription app at \$25.
* The next charge happens in 30 days at \$25.

**On the order:**

* Original bottle (one-time): \$30.
* Subscription bottle (first cycle): \$20.
* Order total: \$50.

### Scenario 2: Free first delivery (100% off first cycle)

**Setup.** Your customer bought a one-time skincare kit. You want to offer them a monthly serum refill with a free first delivery to incentivize trial.

**What you set in the offer:**

* Purchase option: Only sell as a subscription.
* Selling plan: Monthly serum, \$40.
* First-cycle discount: 100% off.

**What the customer sees in the offer:**

* Accept Offer button: \$0.00.
* Recurring subtotal: \$40.00 every 30 days.
* Offer copy (recommended): "First month free, then \$40 every 30 days. Pause or cancel anytime."

**On accept:**

* Shopify charges \$0 for the subscription line on this order.
* A monthly subscription is created in your subscription app at \$40.
* The next charge happens in 30 days at \$40.

**Watch-out.** Because the button reads \$0, customers can misread this as a free-forever offer. Always include the recurring price and the cancellation policy in the offer copy.

### Scenario 3: Restricting to a specific plan (you control the cadence)

**Setup.** You sell coffee that has three selling plans configured in Shopify: weekly, biweekly, and monthly. For your post-purchase offer, you only want to surface the monthly plan because it gives the best margin.

**What you set in the offer:**

* Purchase option: Only sell as a subscription.
* Allowed subscription plans: Monthly (only).

**What the customer sees in the offer:**

* Plan name shown as static text ("Monthly").
* No plan selector dropdown.
* Accept Offer button: monthly price.

**On accept:**

* A monthly subscription is created.
* The customer can change the cadence after acceptance in your subscription app's customer portal.

**When to use:** anytime you want to standardize on a specific cadence for post-purchase acquisition, even if your product page exposes more options.

### Scenario 4: Customer already has a subscription in their cart

**Setup.** A customer is buying both a one-time face wash AND a subscription serum in the same order. After checkout, your post-purchase funnel has a Subscription Upsell offering a vitamin subscription.

**What happens at runtime, if a subscription provider is connected:**

* Aftersell detects the existing subscription line in the order.
* The offer shows with its subscription option intact, and on accept the new subscription is created in Recharge, Skio, or Loop. See [upselling existing subscribers](/aftersell/subscription-upsell-existing-subscribers).

**What happens at runtime, if no provider is connected:**

* Aftersell detects the existing subscription line in the order.
* If the offer is configured as **subscription only**, the offer is dropped from the funnel for this customer. They never see it.
* If the offer is configured as **one-time and subscription**, the offer is auto-downgraded to one-time only. The customer sees the vitamin product available as a one-time purchase, with no subscription option.

**Why this happens.** Shopify allows only one subscription per order. Connecting a provider lets Aftersell create the second subscription outside Shopify, which is why the offer survives. Without one, Aftersell handles the restriction gracefully at runtime, and you can avoid showing the offer entirely by setting a **Subscription trigger** to "do not include a subscription" on the funnel.

**Best practice:** triggers live on the **funnel**, not on individual offers — there is no per-offer Subscription trigger to set. Configure the funnel's Subscription trigger once on its Triggers step. See [Trigger configuration for subscription upsells](#trigger-configuration-for-subscription-upsells).

## What the customer sees

When a customer accepts a Subscription Upsell, three things happen across two systems.

### On the Shopify order

The customer's Shopify order confirmation will include both:

* The **original one-time line item** they bought at checkout.
* The **new subscription line item** added by the upsell, billed at the discounted first-cycle price.

The customer pays for both lines on the original order. The first subscription fulfillment ships from this order as a normal line item.

### In their email confirmations

Shopify sends the standard order confirmation email with both line items. Your subscription provider typically sends its own subscription welcome email that explains the recurring schedule and how to manage the subscription.

If you offer a subscription, make sure your subscription provider's welcome email is configured to send within minutes of acceptance with:

* The customer's name and the product they subscribed to.
* The cadence (every 30 days, every 60 days, etc.).
* The next charge date.
* A direct link to the customer portal where they can pause, skip, or cancel.

### In the subscription provider portal

After accepting, the customer can manage the new subscription in your subscription provider's customer portal. They can typically:

* Pause or skip a delivery.
* Change the cadence.
* Swap products.
* Cancel the subscription.

The portal experience is owned by your subscription provider, not by Aftersell. Make sure the portal is accessible from your store's account area or via the welcome email, otherwise customers will reach support to cancel.

## Subscription fulfillment

How the first cycle ships depends on your store setup.

* **First cycle.** The first subscription order is part of the original Shopify order, so it flows through whatever fulfillment process you use for one-time orders (3PL, in-house, dropship). The subscription line item ships alongside the original one-time purchase.
* **Subsequent renewals.** Future cycles are created by your subscription provider on the renewal cadence. Each renewal becomes a new Shopify order, fulfilled the same way as any other order in your store.

If your 3PL integrates directly with your subscription provider, the renewals usually flow through automatically. If your 3PL syncs only from Shopify orders, no extra setup is needed because each renewal creates a Shopify order.

## Converting a one-time purchase into a subscription

You can also replace a one-time purchase with a subscription version of the same product after checkout. This is functionally a Replacement Upsell, not a Subscription Upsell, because the original one-time line is removed (refunded) and replaced with the subscription. The customer ends up with **only** the subscription, not both.

This is the right choice when the customer's order should ultimately be a recurring purchase rather than a one-off, and you do not want them to receive two separate shipments of the same product.

For the full setup walkthrough, see [How to Set Up a Replacement Upsell for Subscriptions](/aftersell/replacement_upsells).

## Subscription Upgrades

Subscription Upgrade is the feature that modifies a customer's **existing** subscription after checkout. Use it to change the delivery frequency, swap to a different subscription product, do both at once, or add another subscribable item to the existing subscription. The change is applied directly in Recharge, Skio, or Loop. It is a separate feature from Subscription Upsell because Shopify blocks adding a new subscription to an order that already contains one.

For the full setup guide, see [Subscription Upgrades](/aftersell/subscription-upgrades).

## Trigger configuration for subscription upsells

Triggers control when your subscription upsell offer fires. The two most relevant for Subscription Upsell are:

* **Product trigger.** Set this to the original one-time product the customer should have bought for the subscription upsell to make sense. Without a product trigger, the offer can fire on unrelated orders.
* **Subscription trigger.** If **no provider is connected**, set this to **do not include a subscription** so the offer only shows to customers whose orders do not already contain a subscription. This avoids the Shopify "one subscription per order" rule kicking the offer out at runtime. If you **do** have Recharge, Skio, or Loop connected, leave this trigger off — the offer can serve existing subscribers, and excluding them costs you those conversions.

All enabled triggers use AND logic. Every condition must be met for the funnel to show.

<Warning>
  If **Show this funnel for all customers** is enabled, it overrides all other triggers and the offer fires for every checkout. This is rarely the right setting for a Subscription Upsell, because it will fire on orders that already contain a subscription and silently skip.
</Warning>

## Shopify platform limitations

A few Shopify platform rules apply to subscription-related post-purchase offers regardless of which Aftersell feature you use.

### One subscription per order

Shopify does not allow a post-purchase upsell to add a subscription to an order that already contains a subscription. This restriction is set by Shopify and applies to all post-purchase apps.

**Connecting a subscription provider removes this constraint for Subscription Upsell.** When Recharge, Skio, or Loop is connected, Aftersell creates the new subscription in your provider rather than asking Shopify to add it, so subscription offers reach customers whose order already contains a subscription. See [upselling existing subscribers](/aftersell/subscription-upsell-existing-subscribers) for requirements and provider notes.

If **no provider is connected**, Aftersell handles the "subscription already in cart" case automatically in two ways:

* **Subscription-only products** in an offer are dropped from the funnel for that customer.
* **Dual-mode products** (configured as one-time + subscription) are auto-downgraded to one-time-only, so the offer still shows but without the subscription option.

Either way, you can leave a Subscription Upsell offer in your funnel without worrying that it will fire incorrectly on subscription-already-present orders — the offer adapts at runtime.

To modify the subscription the customer already has, rather than adding a second one, use [Subscription Upgrade](/aftersell/subscription-upgrades) instead.

### Subscription-only products

If a product in your offer is configured to sell only as a subscription (no one-time purchase option), and no subscription provider is connected, the offer will be skipped whenever the customer's order already contains a subscription product.

What the funnel editor shows depends on your setup:

* **A provider is connected.** No banner. The limitation does not apply, because Aftersell creates the subscription in your provider.
* **No provider is connected.** An **Unlock more reach** banner with a **Connect a provider** action, explaining that customers whose order already contains a subscription do not see this offer's subscription option. Connecting a provider resolves the limitation rather than working around it.
* **The funnel already excludes subscription orders.** No banner, since the offer never reaches those customers anyway.

Where the older **Subscription limitations** warning banner appears, it lists the affected products and includes a tip: set the **Subscription trigger** to **do not include a subscription** so the offer only shows to customers whose orders do not already have a subscription.

### Multiple subscription offers in the same funnel

If more than one offer in your funnel contains a subscription product, only the first accepted subscription is added to the order. Subsequent subscription offers are skipped. The funnel editor warns you when this conflict is detected, listing the other offers in the funnel that also contain subscription products.

To avoid skipped offers, limit your funnel to one subscription offer, or use the **Subscription trigger** to exclude orders that already contain a subscription.

## Testing a Subscription Upsell

Before going live with a new Subscription Upsell offer:

<Steps>
  <Step title="Place a real test order in Shopify">
    Place a real low-price test order on your store, do not rely on Preview Mode for this step. Preview Mode renders the funnel visually and lets you click through Accept and Decline to walk through the customer experience, but it is sandboxed: no order is created, no subscription is created in your subscription provider, no charges happen, and no emails or webhooks fire. Use Preview Mode for layout and copy review, and a real test order for end-to-end verification.
  </Step>

  <Step title="Accept the upsell on the post-purchase page">
    After checkout, the post-purchase offer will appear. Accept the subscription upsell to trigger the real changeset.
  </Step>

  <Step title="Check Shopify">
    In **Shopify Admin -> Orders**, find the test order. You should see both line items: the original one-time product and the new subscription product, with any first-cycle discount applied.
  </Step>

  <Step title="Check your subscription provider">
    Find the customer's new subscription in your provider's dashboard. Confirm the cadence, the next charge date, and the product.
  </Step>

  <Step title="Trigger a renewal in your sandbox">
    If your subscription provider supports test renewals, advance the next-charge date and confirm the renewal creates a new Shopify order at the regular (non-discounted) price.
  </Step>
</Steps>

If something looks wrong, see [Troubleshooting](#troubleshooting) below.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The subscription option is not showing up in my offer editor">
    For subscription controls to appear in the offer editor, the product you selected must have at least one active selling plan in Shopify. Check that your subscription app has created selling plans for this product, and that the selling plans are active and assigned to the product.
  </Accordion>

  <Accordion title="How does Aftersell pick which selling plan to show?">
    The offer preselects the first selling plan configured on the product in Shopify, and customers can change it in the **Purchase options** dropdown when more than one plan applies to their variant. To control which plan they see, restrict the offer with the **Allowed subscription plans** multi-select, reorder selling plans on the product in Shopify so the desired one is first, or remove unused selling plans from the product entirely. Allowing exactly one plan removes the dropdown.
  </Accordion>

  <Accordion title="Can the customer pick their delivery frequency on the post-purchase offer?">
    Yes, when more than one plan applies to the variant they select — the offer shows a **Purchase options** dropdown. To prevent that, use **Allowed subscription plans** to allow a single plan; the cadence then renders as static text. Customers can still change cadence afterwards in your subscription provider's portal.
  </Accordion>

  <Accordion title="I want to show this subscription-enabled product as one-time only">
    Use the **One-time purchase only** mode in the offer's purchase-option setting. Aftersell has three modes for subscription-enabled products: **One-time purchase only**, **Subscription only**, and **One-time purchase and subscription**. Selecting **One-time purchase only** hides the subscription option entirely, even when the product has active selling plans. See [Offering subscription products after checkout](#offering-subscription-products-after-checkout) for details on all three modes.
  </Accordion>

  <Accordion title="My customer accepted the subscription upsell but the subscription is not in my subscription app">
    This is one of the most disruptive failure modes for Subscription Upsell because the customer was charged but the subscription was never created in your subscription provider. The most common root cause, by a wide margin, is a **selling plan that was deactivated between the offer rendering and the customer accepting**. Shopify accepts the changeset because it has a valid selling plan ID at offer render time, but if the plan is deactivated before the customer accepts, no subscription is enrolled downstream and no error is surfaced.

    Other common causes:

    * **Subscription app webhook is failing.** Any subscription app that picks up new subscriptions from Shopify relies on Shopify webhooks. Check webhook delivery health in your subscription app's logs.
    * **Selling plan was unlinked from the product** but still has an active ID. Shopify accepts the changeset and the line item lands, but the subscription provider has no record to act on.

    **Important:** there is no automatic retry on the native `add_subscription` path — Shopify owns the enrollment there, so Aftersell has nothing to replay. (The separate provider path, used when the order already contains a subscription, *is* covered by the [subscription-upgrade retry workflow](/aftersell/subscription-upgrades-troubleshooting).) If this happens to a customer:

    1. Confirm the selling plan is still active in Shopify and assigned to the product.
    2. Check your subscription app's order import / webhook logs for the affected order.
    3. If the subscription is truly missing, your subscription app's support team can usually manually enroll the customer from the order ID.

    If multiple customers are affected, contact Aftersell support with the order IDs and your subscription provider, but expect the fix to happen on the subscription provider side, not in Aftersell.
  </Accordion>

  <Accordion title="The CTA button shows the recurring price instead of the first-cycle discount">
    This usually surfaces when the first-cycle discount is extreme (for example 100% off the first cycle). The Accept button reflects the first-cycle price, but if that price reads identically to the recurring price (because of edge cases or formatting), it can look like the discount is not applied. Confirm in the offer preview that the discount is configured correctly, and rely on the offer copy ("First box free, then \$X every Y days") to make the terms unambiguous to customers.
  </Accordion>

  <Accordion title="My customer's order was charged without the subscription discount on the second cycle">
    Discounts apply to the **first billing cycle only** by default. If your customer is asking why their second or third order does not have the discount, that is the expected behaviour. Recurring orders charge at the regular subscription price, which the customer saw as the **Recurring subtotal** in the offer.
  </Accordion>

  <Accordion title="The offer is showing on orders that already contain a subscription">
    If you have Recharge, Skio, or Loop connected, this is expected and the offer works: Aftersell creates the new subscription in your provider. See [upselling existing subscribers](/aftersell/subscription-upsell-existing-subscribers).

    If no provider is connected, Shopify blocks adding a second subscription and the offer silently skips at runtime. Either connect a provider, or stop the offer from showing to those customers by setting the **Subscription trigger** to **do not include a subscription**.
  </Accordion>

  <Accordion title="Only one of my subscription offers is firing in the funnel">
    Shopify allows only one subscription per order. If you have multiple subscription offers in the same funnel, the first accepted one wins and the rest are skipped. Either limit your funnel to one subscription offer, or use the Subscription trigger to exclude orders that already have a subscription.
  </Accordion>

  <Accordion title="The customer cannot find the subscription in their account">
    The new subscription is managed in your subscription provider's customer portal, not directly in Shopify. Make sure the portal is linked from your store's account area, and confirm your subscription provider's welcome email is configured to send immediately after acceptance.
  </Accordion>

  <Accordion title="I want to refund or cancel the new subscription after the customer accepted">
    The first cycle was paid for as part of the Shopify order, so refunds work the same as any other line item. Cancellation of future cycles happens in your subscription provider, not in Aftersell. Refunding the line in Shopify does not automatically cancel the subscription, you have to cancel it in the provider portal as well.
  </Accordion>
</AccordionGroup>


# Taxes
Source: https://docs.aftersell.com/aftersell/taxes

How tax is calculated and shown on post-purchase upsells

Aftersell uses Shopify's tax calculation logic for post-purchase upsells. This means that all tax settings from your store will automatically be applied to post-purchase upsells, including state-specific taxes and whether or not taxes are included in the total price. You should not need to change anything.

# Common issues

## Taxes are not shown in the editor/preview

When editing your post-purchase upsells in Aftersell, the offer preview will not show taxes. This is to avoid confusion since there is no "correct" tax value to show. The amount of tax owed depends on many factors, including the address of the customer.

## Taxes are not shown if the price breakdown is hidden

Taxes are only visible to customers for upsells with the price breakdown included. Single product upsells include the price breakdown by default. Multi-product offers hide the price breakdown by default due to the smaller screen space per product.

You can enable or disable the price breakdown in the offer editor. The setting is named slightly differently depending on the offer type:

* **Single-product offers** — "*Show shipping and tax breakdown*", in the **Price breakdown** section
* **Multi-product offers** — "*Show price breakdown?*", in **General settings**
* **Build-a-box offers** — "*Show price breakdown*", in **General settings**

## Taxes are not shown if they are \$0

For products which are not taxed, such as groceries in Canada, Aftersell will not show a tax line in the price breakdown.

# Limitations

## Dynamic tax-inclusive pricing is not supported

Aftersell does not support [dynamic tax-inclusive pricing](https://help.shopify.com/en/manual/international/pricing/dynamic-tax-inclusive-pricing). This is due to a limitation of the Shopify post-purchase API that is [described here](https://help.shopify.com/en/manual/international/pricing/dynamic-tax-inclusive-pricing#considerations-for-using-dynamic-tax-product-pricing).

For stores using [regular tax-inclusive pricing](https://help.shopify.com/en/manual/taxes/location#include-taxes-in-product-prices), Aftersell will correctly include taxes in the prices for post-purchase upsells.

## Avalara AvaTax is not supported

[Avalara AvaTax](https://help.shopify.com/en/manual/taxes/tax-services) does not work with post-purchase upsells. The tax charged for post-purchase upsells will be *correct* for variants with the tax code P0000000. However, the tax will be *incorrect* for any variants with a specific tax code, such as P1234567. This is a limitation of the Shopify post-purchase API.


# Testing / previewing your post-purchase offer
Source: https://docs.aftersell.com/aftersell/testing_post_purchase_offers

How to see your post-purchase offer the way a customer does. There is no test page — you place a real order that meets Shopify's post-purchase requirements and your funnel's triggers.

There is no dedicated **test page** or one-click preview button that renders your post-purchase offer exactly as a customer sees it. Aftersell doesn't have one, and Shopify's post-purchase page can't be opened on demand — it only appears inside a live checkout.

To see the real offer, you place an order that satisfies **both** of these at once:

1. **Shopify's post-purchase eligibility requirements** — the platform-level conditions that decide whether the post-purchase page loads at all.
2. **Your funnel's trigger conditions** — the targeting rules that decide which funnel (if any) fires for that order.

If either set isn't met, no offer shows. The rest of this guide covers what you can preview without an order, and how to place an order that qualifies.

***

## What you can preview without placing an order

Inside the funnel and offer editor you can preview the offer's **content and flow** — each step of the funnel, the products, and the discount that will be applied. This is useful for checking your setup, but it is **not** the live experience:

* It does **not** render your store's branding, fonts, or colours.
* It does **not** run Shopify's eligibility checks, so it can't tell you whether a given order would actually show the offer.

For the real customer experience — branding, the rendered page, and eligibility all included — you need a live order.

***

## Place an order that qualifies

The post-purchase page appears after payment is confirmed but before the Thank You page. For it to appear, the order has to clear Shopify's requirements and match a funnel.

### Before you order

* **Aftersell is the active post-purchase app.** In Shopify, go to **Settings → Checkout → Post-purchase page** and confirm Aftersell is selected. Only one app can hold this slot.
* **The funnel is published and active** in the Aftersell admin.
* **The order will match your triggers.** When a funnel has multiple triggers, *all* of them must be met. To take targeting out of the equation while testing, temporarily set the funnel to **Show this funnel for all customers**, or make sure your test order matches the existing triggers. See [How to configure post-purchase triggers](/aftersell/how_to_configure_post_purchase_triggers) and [Understanding conditional logic for post-purchase triggers](/aftersell/understanding_conditional_logic_for_post_purchase_triggers).

### Shopify's post-purchase requirements

These are Shopify-imposed and apply to every post-purchase app. The order must:

* Be paid with a **supported credit card** that Shopify can vault (Shopify Payments, Shop Pay as a saved card in standard checkout, or another direct credit-card processor embedded in checkout). Wallets, accelerated buttons, BNPL, bank transfers, and full gift-card payments will **not** show the offer.
* Be worth **at least \$0.50**.
* Be placed in the store's **default currency** through the **Online Store** sales channel.
* Have a **shipping address**, and no duties or landed costs.

This is the short list. For the full breakdown of every reason an offer can be skipped, see [Why isn't my post-purchase offer displaying?](/aftersell/why_isnt_my_1_click_offer_displaying) and [Payment methods](/aftersell/payment_methods).

<Warning>
  **Shopify's test payment gateway (Bogus Gateway) and \$0 test orders do not trigger post-purchase offers.** Shopify needs a real, vaulted credit card and an order value of at least \$0.50, so the usual \$0 test-order trick won't work here. Place a low-value real order with a supported card, then refund or cancel it afterward. (This is different from **Thank You Page** widgets, which you *can* test with a \$0 order — see [Testing your widgets](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell#testing-your-widgets).)
</Warning>

### Steps

1. Confirm the setup above (post-purchase app, funnel active, triggers).
2. Add a product that matches your funnel's triggers to the cart.
3. Check out with a **supported credit card**, in your default currency, with a shipping address, for at least \$0.50.
4. After payment, the post-purchase offer appears before the Thank You page. Review it as a customer would.
5. **Refund or cancel** the test order, and **reset any triggers** you changed for the test.

***

## If the offer doesn't appear

Open **Apps → Aftersell → Order Browser**, find the order, and check the Post-purchase section — it shows the exact ineligibility reason for that order. Start there rather than guessing.

* [Why isn't my post-purchase offer displaying?](/aftersell/why_isnt_my_1_click_offer_displaying) — every cause, in order.
* [Order Browser overview](/aftersell/order_browser_overview) — how to read the eligibility reason.
* [Does multi-currency checkout impact Aftersell?](/aftersell/does_multi_currency_checkout_impact_aftersell) — if you use Shopify Markets or multiple currencies.

If most of your real orders use unsupported payment methods, set up [Thank You Page upsells](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell) as well — they work with every payment method.


# Translating post-purchase funnels
Source: https://docs.aftersell.com/aftersell/translating_post_purchase_funnels

This article explains how to translate post-purchase funnels and Thank You pages in Aftersell.

Aftersell supports translations for post-purchase funnels in two ways: automatic system text translation via the Language setting in the funnel editor, and manual translation for content you write directly.

***

## How language translation works

When you select a language on an offer in the funnel editor, Aftersell automatically translates all system-level text for that offer, including pricing labels, button text, subscription labels, quantity selectors, and other non-editable strings. You don't need to configure anything else for the translation to take effect.

For new V2 offers, Aftersell also seeds the default offer copy — headlines, subheads, timer headings, the "before you go" text, and the offer description — in the offer's language at creation time. If you later change the language on an offer, any copy that is still the built-in default is automatically re-translated to the new language. Copy you have customized is left untouched.

**Settings > Translations** is where you can set a store-wide default language for new offers and optionally customize or override auto-translated strings for any language. It doesn't control which language an offer displays after creation. That's set per offer in the editor.

***

## Setting a default offer language

You can set a default language that is applied to all new post-purchase V2 offers when they are created. This affects the language of the default offer copy (headlines, subheads, timer headings, and other default text) as well as the system text language.

1. Go to **Settings**
2. Select **Translations**
3. Under **Post-purchase**, find the **Default post-purchase language** section
4. Select your preferred language from the **Offer language** dropdown
5. Click **Save**

New offers created after saving use this language by default. You can still change the language on any individual offer in the funnel editor. This setting does not affect existing offers or checkout translations.

> 💡 If no default language is set, new offers are created in English.

***

## Step 1: Set the language on your offer

To apply a language to an offer:

1. Open your funnel in the Aftersell editor
2. Select the offer you want to translate
3. Open the **Language** section
4. Select a language from the **Language** dropdown

<img alt="Funnel editor Language dropdown switching an offer from English to Spanish" />

All system text on the offer, including pricing labels, subscription labels, and other non-editable strings, will automatically translate to the selected language. Aftersell supports 32 languages.

For new V2 offers, the default offer copy (headlines, subheads, timer headings, and offer description) is also created in the selected language. If you change the language on an existing offer, any copy that is still the built-in default is automatically re-translated to the new language.

***

## Step 2 (optional): Customize auto-translated strings

If you want to override any of the default translated strings for a specific language, you can do so in **Settings > Translations**.

1. Go to **Settings**
2. Select **Translations**
3. Under **Post-purchase upsell translations**, choose a language from the language dropdown
4. Update any fields you want to override for that language

When an offer's language matches a language you've configured here, your custom strings are applied. If no custom strings exist for that language, Aftersell's default translations are used.

### Fields available in Settings > Translations

| Field                                       | Description                                                                                                                       |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Free                                        | Label shown when a product is free                                                                                                |
| Shipping                                    | Shipping label                                                                                                                    |
| Taxes                                       | Tax label                                                                                                                         |
| Subtotal                                    | Subtotal label                                                                                                                    |
| Total                                       | Total label                                                                                                                       |
| OR (multi-product divider)                  | Divider text shown between products in multi-product offers                                                                       |
| Quantity                                    | Quantity label                                                                                                                    |
| Unavailable                                 | Label shown when a product is unavailable                                                                                         |
| Show price breakdown                        | Price breakdown toggle label                                                                                                      |
| Save amount                                 | Savings label (e.g. `Save {AMOUNT}`)                                                                                              |
| Subscribe & Save                            | Subscription option label                                                                                                         |
| Subscription disclaimer                     | Disclaimer text below subscription pricing                                                                                        |
| Recurring subtotal                          | Recurring charge label                                                                                                            |
| Purchase options                            | Purchase options label                                                                                                            |
| Variant selection required (dropdowns)      | Prompt shown when a dropdown variant hasn't been selected                                                                         |
| Variant selection required (button)         | Prompt shown when a button variant hasn't been selected                                                                           |
| Minimum quantity message                    | Message shown when minimum quantity requirement hasn't been met                                                                   |
| Discount                                    | Discount label                                                                                                                    |
| Tax adjustment for replacement upsells      | Tax adjustment label for replacement-type upsells                                                                                 |
| Shipping adjustment for replacement upsells | Shipping adjustment label for replacement-type upsells                                                                            |
| Refund for replacement upsells              | Refund label for replacement-type upsells                                                                                         |
| Video player — back to offer                | Label on the button that closes the video player and returns the customer to the offer (default: "Back to offer")                 |
| Video player — desktop hint                 | Hint text shown below the back button on desktop (default: "Double-click outside the video or press Esc to return to the offer.") |
| Video player — mobile hint                  | Hint text shown below the back button on mobile (default: "Double-tap outside the video to return to the offer.")                 |
| Video player — unavailable title            | Heading shown when the video is unavailable (default: "Video unavailable")                                                        |
| Video player — unavailable body             | Body text shown below the heading when the video is unavailable (default: "This video is no longer available.")                   |
| Verified buyer                              | Label shown on the verified-buyer indicator in the Trust Badge / testimonials widget                                              |
| Add to box                                  | Label for the action that adds a product to the box (Box widget)                                                                  |
| Remove from box                             | Label for the action that removes a product from the box (Box widget)                                                             |
| Box progress — below the minimum            | Message shown while the box has fewer items than its minimum (e.g. `Add {COUNT} more`)                                            |
| Box progress — no maximum                   | Message showing how many items are in the box when it has no maximum (e.g. `{COUNT} selected`)                                    |
| Box progress — up to a maximum              | Message showing box progress toward a maximum (e.g. `{COUNT} selected, up to {MAX}`)                                              |
| Box progress — exact size                   | Message shown when the box has a fixed required size (e.g. `{COUNT} of {MAX} selected`)                                           |
| Box is full                                 | Label shown when the box has reached its maximum size                                                                             |

The following button-text fields are available when custom button text is enabled for your account:

| Field                                   | Description                                                         |
| --------------------------------------- | ------------------------------------------------------------------- |
| Pay Now                                 | Accept-button label shown for paid offers                           |
| Add now for free products               | Accept-button label shown for free-product offers                   |
| Confirm accept for paid products        | Confirmation-step button label for paid offers                      |
| Confirm accept for free products        | Confirmation-step button label for free-product offers              |
| Decline this offer                      | Decline-button label                                                |
| Upgrade for replacement upsells         | Accept-button label for replacement/upgrade-type upsells            |
| Confirm upgrade for replacement upsells | Confirmation-step button label for replacement/upgrade-type upsells |

***

## Translating product names, variants, and options

In addition to system text, you can translate the product-level strings that appear on your offer — including product titles, variant names, option names, and subscription plan names. These come from your store's published translations in Shopify.

### How it works

When you configure a non-default product details language on an offer, Aftersell fetches translated strings from Shopify's Storefront API using the translations you've set up in **Shopify Admin > Settings > Languages** (via the Translate & Adapt app or another translation tool). The translated strings are applied on top of the canonical product data, so inventory, pricing, and other product details are unaffected.

### Setting up product details translation

1. Open your funnel in the Aftersell editor
2. Select the offer you want to configure
3. Open the **Language** section
4. Under **Product details language**, choose one of the following options:
   * **Use default store language** — no translation applied; product strings display as configured in Shopify Admin (default)
   * **Use selected locale language** — product strings are translated to match the shopper's checkout locale automatically
   * **Select specific language** — product strings are always translated to a language you choose from the dropdown
5. If you select **Select specific language**, choose the target language from the **Language** dropdown that appears below

> ⚠️ You must add the target language to your store in **Shopify Admin > Settings > Languages** before it can be used here. Aftersell reads translations from your store's published languages.

### Granting required permissions

When any offer is configured for product details translation, a banner appears on the Funnels page and in the funnel editor asking you to authorize Aftersell to read your store's translations. Click **Update App** in the banner to grant the required permissions. The banner disappears automatically once the permissions are granted.

Without these permissions, product strings display in the default store language regardless of your product details language setting.

### What gets translated

| Content                                    | Translated                    |
| ------------------------------------------ | ----------------------------- |
| Product title                              | ✅                             |
| Product description                        | ✅                             |
| Variant names                              | ✅                             |
| Option names (e.g. Size, Color)            | ✅                             |
| Option values (e.g. Small, Red)            | ✅                             |
| Subscription plan names                    | ✅                             |
| Pricing, inventory, and other product data | ❌ (always from Shopify Admin) |

### Multi-product offers

For multi-product offers, the product details language setting applies to the entire offer, not individual products. You can find it in the **Language** section at the offer level in the funnel editor.

***

## Step 3: Manually translate remaining content

Some content is not auto-translated and needs to be updated manually in the editor:

**Badges** - Badge text (e.g. Best Seller, Trending) cannot currently be translated.

**FAQ and Text widgets** - Replace the existing copy in each widget with your translated text.

**Image widgets** - Text inside images cannot be edited. Upload a new version of the image in the target language. For multi-language support, use different images per language-specific funnel.

<Frame>
  <img alt="Funnel offer editor with arrows mapping Text, Timer, and Product details widgets to the offer preview" />
</Frame>

**Thank You page** - The Thank You page is tied to its funnel. Open the Thank You page editor for the relevant funnel and update the widget text to match.

> 💡 For new V2 offers, the default offer copy (headlines, subheads, timer headings, and offer description) is automatically created in the offer's language. You only need to manually update copy that you have customized or that falls outside the default offer copy.

***

## Multi-language setups using language triggers

For fully localized experiences across multiple languages, the recommended approach is to create separate funnels per language using the **Language trigger**.

For example:

* Create one funnel targeting **English** customers, write all content in English, and set the offer language to English
* Create a second funnel targeting **French** customers, write all content in French, and set the offer language to French

This keeps each funnel fully localized while leveraging auto-translation for system text.

***

## Need Help?

If you have questions about language setup or need help configuring translations, reach out through the in-app chat or by email. Our support team is happy to help.


# Understanding conditional logic for post-purchase triggers
Source: https://docs.aftersell.com/aftersell/understanding_conditional_logic_for_post_purchase_triggers

This article explains how conditional logic works for post-purchase triggers

We will be going over the conditional logic between multiple triggers as well as the logic within each trigger. This will help ensure that your funnels display correctly and target the right customers.

Understanding how these triggers operate is fundamental for crafting efficient and impactful funnels tailored to specific customer behaviors.

Upsell triggers are conditions set within Aftersell to display upsell funnels based on variables such as customer behavior and specific order attributes.

This diagram shows you an overview of the conditional logic:

By managing priorities correctly, businesses can ensure their most relevant funnels are displayed to appropriate customer segments, thereby optimizing conversions.

<img alt="Customer Attribute Triggers panel illustrating AND between triggers and OR within each trigger" />

***

# The "AND" Logic Between Triggers

Each enabled trigger is evaluated independently and they **all** must be satisfied for the post-purchase action to occur. This means that every trigger must return a match for the funnel to appear to customers.

* For example, if you have a trigger set for both **Customer Location = US** and another one for **Order Value > \$50**, the order must meet **both** conditions to qualify.

***

# The "OR" Logic Within Each Trigger

Within a single trigger, multiple options can be selected. These options are evaluated using an **OR** conditional logic. This means that only one of the options within a trigger needs to match for that trigger to be satisfied.

* For example, if a trigger is configured for **Product Category = Shoes, Socks or Pants**, an order only needs to match one of those product categories for the funnel to activate.

**Note:** Some triggers, such as the *Product Quantity Trigger*, allow you to switch the condition logic from **OR** to **AND**.

<img alt="Product quantity trigger with the Condition Logic dropdown set to AND highlighted" />

***

# Putting It All Together

In summary, an order qualifies when **every enabled trigger** is met, and within each trigger, **at least one** of its options matches the order or customer.

For example, setting a funnel for orders with 'Minimum Order Value > \$100' and 'Shipping Method = Express' requires both criteria to be fulfilled for activation.

In simple terms:

* Each trigger must be true (**AND** logic).
* Within each trigger, only one matching option is needed (**OR** logic).

This setup keeps post-purchase rules flexible, accurate, and easy to understand.

***

Best practices include layering specific and broad triggers, regularly reviewing funnel priorities, and testing scenarios for accuracy and effectiveness.

If you're interested in learning more about all available Post-Purchase Triggers, see our comprehensive reference article here:

[Post-purchase Triggers](/aftersell/post_purchase_triggers)

This includes resources on managing funnel priorities and ensuring compliance with best practices.


# Understanding out of stock variants
Source: https://docs.aftersell.com/aftersell/understanding_out_of_stock_variants

This article explains how Aftersell handles out-of-stock variants for upsell products on the post purchase page

# **Overview**

Upsell products may have one or multiple variant options (such as size or color). Aftersell handles out-of-stock variants differently depending on how many options a product has, to ensure a smooth customer experience and prevent unavailable selections.

***

# **Out of Stock Variant Logic**

### **Products with a Single Variant Option**

If a product has **only one variant option** and that variant is **out of stock**, it is **hidden entirely.** For example,

* The blue variant for this Notebook product is out of stock

  <img alt="Select Products dialog showing the Notebook Blue variant marked Out of Stock" />

* Therefore, on the post purchase page, the blue variant will not show up as an option

  <img alt="Post-purchase page with the Notebook colour dropdown listing only White and Black" />

This prevents customers from interacting with a product that cannot be fulfilled.

***

### **Products with Multiple Variant Options**

If a product has multiple variant options, **all variant options are displayed**, including those that are out of stock. By default, Aftersell will **preselect an in-stock variant**, if one is available. However, if a customer manually selects an **out-of-stock variant**, it will be clearly marked as **unavailable** and cannot be added.

For example,

* The blue/small variant for this T-shirt product is out of stock

  <img alt="Select Products dialog showing the T-shirt blue Small variant marked Out of Stock" />
* However, the variant will still appear on the live post-purchase page, but customers will not be able to purchase it if selected.

  <img alt="Post-purchase T-shirt offer with an out-of-stock variant showing an Unavailable button" />

This approach gives customers full visibility into available options while preventing invalid selections.

**NOTE:** This logic applies even if all variant settings are unchecked in the editor.

***

# **Pre-Order and Pre-Sale Variants**

The out-of-stock logic above applies to variants that can no longer be sold once their inventory runs out — Shopify's default **"Stop selling when out of stock"** behavior.

Pre-order and pre-sale variants are handled differently. In Shopify, these variants have **"Continue selling when out of stock"** enabled (an inventory policy of *continue*). Aftersell checks a variant's inventory **policy**, not just its quantity on hand, so a continue-selling variant is treated as **available** even when its tracked inventory is 0 or negative.

As a result, pre-order/pre-sale variants behave like in-stock variants on the post-purchase page:

* **Single variant option:** the variant is **shown** (not hidden), and customers can add it.
* **Multiple variant options:** the variant is **selectable and purchasable** — it is not marked as unavailable.

This lets you run pre-order or pre-sale offers as post-purchase upsells without the variant being suppressed for having no stock on hand.

<Note>
  To enable this behavior, turn on **Continue selling when out of stock** for the variant in Shopify (under the product's variant **Inventory** settings). A variant left on the default *stop selling when out of stock* follows the out-of-stock logic described above once its inventory reaches 0.
</Note>

<Note>
  Exception: if your offer is configured to hide products that are out of stock, continue-selling variants with 0 or negative inventory are hidden along with regular out-of-stock variants.
</Note>

***

# **Hiding variants that aren't published to your Online Store**

By default, Aftersell can offer variants that are in stock but excluded from your Online Store sales channel in Shopify — for example, variants you keep available for retail or wholesale but deliberately hide from your web storefront.

To stop those variants appearing in post-purchase offers, go to **Settings → Inventory**, find the **Unpublished variants** section, and tick **Hide unpublished variants from post-purchase offers**. The setting is off by default.

## How it works

With the setting on, Aftersell checks each variant's publication status on the Online Store sales channel before including it in an offer. Variants that aren't published are excluded. If every variant of a product is excluded, the product is dropped from the offer entirely.

The filter applies to both live offers and the offer editor preview, so what you see in the editor matches what customers get.

<Note>
  This setting needs the `read_publications` permission in Shopify. Ticking the box prompts you to grant it, and the setting only takes effect once you accept.
</Note>

<Warning>
  The check is **fail-open**. If the permission is missing, or the lookup to Shopify errors or times out, the variant is still offered rather than hidden. Treat this as a merchandising preference rather than a guarantee that an unpublished variant can never appear.
</Warning>


# Welcome to Aftersell
Source: https://docs.aftersell.com/aftersell/welcome_to_aftersell

An introduction to Aftersell

At Aftersell, we help Shopify brands increase Average Order Value (AOV), improve checkout conversion rates, and boost customer retention.

Our suite of comprehensive features, such as Post-Purchase Upsells, Product Page Upsells, Checkout Upsells and Rokt Thanks, empowers you to enhance every step of the customer journey. These tools are built to create seamless, high-converting shopping experiences that drive real revenue growth. We're grateful to have you here!

***

## **What You’ll Find Here**

Explore detailed guides and best practices for getting the most out of Aftersell:

* **Post-purchase upsells**: Learn how to [design offers](/aftersell/post_purchase_branding_settings), [track conversions](/aftersell/conversion_tracking_web_pixels), [manage fulfillment](/aftersell/fulfillment) and more.
* [**Product Page Upsells (PDP Upsells)**](/aftersell/product_page_upsells): Discover how to display targeted, high-impact offers on your product pages.
* [**Thank You Page**](/aftersell/thank_you_page_extensions_overview), [**Checkout**](/aftersell/checkout-dashboard-overview), and [**Rokt Thanks**](/aftersell/rokt_thanks_settings): Enhance customer engagement and retention at every step of the purchase journey.
* **Frequently Asked Questions**: Find quick answers and troubleshooting tips.

***

Whether you're new to Aftersell or looking to fine-tune your upsell strategy, this site is your go-to resource for **increasing sales and improving the customer experience**.

***

## Getting help in the admin

A help icon is available next to the page title on most pages in the Aftersell admin. Click it to open a panel with documentation links curated to the page you're on.

From the help panel you can:

* **Browse curated articles** — links relevant to the current page open directly in the documentation site.
* **Browse all docs** — opens the full Aftersell documentation at [docs.aftersell.com](https://docs.aftersell.com/aftersell).

If you need to speak with someone, use the Intercom chat launcher in the bottom-right corner of the admin to contact the support team.


# What is Upcart?
Source: https://docs.aftersell.com/aftersell/what_is_upcart

Upcart is our cart drawer solution, this article goes over it in more detail.

Simply put, Upcart is a **cart drawer** built by the team at Aftersell. This article will cover what that means, what it does, and why it's helpful for your business.

Already interested? Check out [Upcart's Documentation](/upcart/welcome_to_upcart) or [install it now](https://apps.shopify.com/upcart-cart-builder). If you're intrigued and want to learn more, this article gives a general overview of Upcart.

***

# Why Does This Matter?

Convenience is a big win for a business! It makes the order process as **smooth** as possible, **decreasing order churn**. Having it built into the storefront also means **skipping the loading times** provided by Shopify's built in cart solution, the Shopify Cart Page.

# What's So Special About Upcart?

While there are plenty of cart drawer solutions out there, here's why Upcart may be right for you and your business.

## Fully Customizable

Upcart allows you to insert additional content almost anywhere on the cart. You're given access to **Custom HTML** and **Custom CSS** fields. Not only that, but the HTML field also supports **JavaScript** too! This gives you the power to make Upcart YOUR cart drawer solution.

If you feel like you're missing something, you can design it with HTML. If you don't like the way something looks, you can tweak it with CSS. Should you want something cool to happen, you can build it with JavaScript.

You can reference our public API to view all of Upcart's functions:

[Upcart Public API](https://rokt.notion.site/upcart-public-api)

## Multiple Modules to Pick From

Upcart has a ton of modules you can mix & match together to give your customers the experience they deserve. You can tailor it to your goals.

Want to see what's available? [Click here to dive into the available modules!](/upcart/add_ons_module)

## Quality Customer Support

If you [check out our reviews right now](https://apps.shopify.com/upcart-cart-builder/reviews?sort_by=newest), you'll see an abundance talking about the quality of our Customer Support team. This brings all our installers peace of mind knowing that they have support when they need it. If you have questions, suggestions, or concerns, please do not hesitate to contact us.

## Pricing Built For You

Not only do we offer a 14-day free trial, but Upcart's pricing is also fully based on your store's order volume.

This means the pricing scales based on how many orders your store gets per month. For a more detailed breakdown of cost, please reference [Upcart's pricing article](/upcart/upcart_pricing_structure).

***

# Where Can I Find It?

Upcart can be installed from the Shopify App Store. Click below and we'll take you there!

[Install Upcart](https://apps.shopify.com/upcart-cart-builder)


# Why are post-purchase items being shipped separately?
Source: https://docs.aftersell.com/aftersell/why_are_post_purchase_items_being_shipped_separately

This article outlines how Shopify Shop Promise works with post-purchase upsells.

If your store uses [Shopify Shop Promise](https://www.shopify.com/shop-promise) and post-purchase items are being shipped separately from the original order, this is because post-purchase upsells are not supported by Shop Promise.

# Affected Orders

Orders that are covered by the **Shop Promise Guarantee** will be affected by this issue.

You can identify if an order is covered by a Shop Promise by viewing the order in the Orders tab of your store's admin console and looking for two things:

1. The Shop Promise logo on the shipping information
2. A message in the timeline notifying you that the order is covered by a Shop Promise Guarantee

<img alt="Shopify order details highlighting the Shop Promise badge on the expected delivery date" />


# Activating and configuring Rokt Thanks
Source: https://docs.aftersell.com/aftersell/activating_and_configuring_rokt_thanks

How to enable and design Rokt Thanks on the confirmation page

In order to generate additional revenue from Rokt Thanks on your Thank You page, Order Status page, and customer account pages, you must first set-up and enable Rokt Thanks from the Aftersell admin. To do so:

Navigate to the *Rokt Thanks* tab in the navigation menu.

Click "Get Started"

On the **Your store** step, pick your industry from the **Your industry** dropdown, then pick the matching sub-category from **Your products/services**. Both are required — **Save & Continue** stays disabled until each is set, and the second dropdown only becomes selectable once you have chosen an industry. If you do not see the exact industry or sub-category, choose the closest match.

Click "Save & Continue" to move onto the next step. There is no separate consent checkbox in this wizard — Rokt Thanks is covered by the terms you accepted when you first set up Aftersell. For reference, see our [Terms and Conditions](https://www.rokt.com/policies/aftersell-powered-by-rokt-services-agreement) & [Privacy Policy](https://www.rokt.com/policies/privacy-policy).

In order to get paid for your Rokt Thanks offers, you'll need to provide a PayPal email address. If you do not have a PayPal account, you can still enter the email address that you wish to receive payments through, and PayPal will help you create an account once your first payment has been processed. Learn more about payouts [here](/aftersell/rokt_thanks_payouts).

<Frame>
  <img alt="Rokt Thanks payouts setup step showing the PayPal email field" />
</Frame>

Afterwards, the app will show you a loading screen while we create your Rokt account and give you access to our Rokt Thanks feature. This **does not** enable Rokt Thanks on your store right away.

Once your account is created, enable Rokt Thanks by clicking the "Enable" button in the setup walkthrough.

<Frame>
  <img alt="Rokt Thanks setup checklist with the Enable button highlighted" />
</Frame>

**NEXT:** We'll be placing the offers on your store.

## **App block placement**

Rokt Thanks is built on Shopify's Checkout Extensibility framework, requiring app block placement on Shopify pages for it to render. The app block we use for Rokt Network products is called the 'Rokt Thanks' block.

To place this block on your Thank You page and Order Status page, simply click on the 'Edit Thank you page' and 'Edit Order status page' buttons from the Rokt Thanks admin to be redirected to the Shopify Checkout Editor.

<Frame>
  <img alt="Shopify checkout editor with the Rokt Thanks app block being added" />
</Frame>

From there, in any of the sections on your page, click 'Add block' and select 'Rokt Thanks' from the list of Aftersell blocks.

<Frame>
  <img alt="Shopify checkout editor Add block panel with Rokt Thanks selected from the Aftersell blocks" />
</Frame>

Once placed, make sure to click "Save".

<Frame>
  <img alt="Save button highlighted in the Shopify checkout editor toolbar" />
</Frame>

When you navigate back to the Rokt Thanks admin, we will detect the block placement automatically and your task checklist will update. Please note that the setup will remain incomplete until the app blocks are saved successfully in the Shopify Checkout Editor.

<Frame>
  <img alt="Rokt Thanks setup checklist showing the Thank You and Order Status page blocks placed" />
</Frame>

***

## **Rokt Vaulted Rewards (Customer Account Pages)**

**Overview**

Shopify has introduced a new generation of customer account pages - specifically the Profile and Orders pages - which support app blocks. If your store has migrated to these new account pages, you can now display Rokt Thanks ads in these placements, the same way they appear on your Thank You page.

This represents a meaningful incremental revenue opportunity, with an estimated 10-20% uplift on top of your current placements.

**Requirements**

Your store must be using Shopify's new customer account pages. You can confirm this by checking your login experience:

Click on the "My Account" button in your storefront's navigation bar. If the login screen shows a "Continue with Shop" button in a distinctive purple/indigo color and uses Shop Pay authentication, **your store is using the new account pages and is eligible for this placement.**

<Frame>
  <img alt="Storefront sign-in screen with a purple Continue with Shop button and More sign-in options" />
</Frame>

Logged in view:

<Frame>
  <img alt="Logged-in customer account view after signing in with Shop" />
</Frame>

**Step 1: Complete setup**

A new card will appear on the "Rokt Thanks" tab in Aftersell. Click "Start setup" and a loader will appear. While loading, two new pages will be created in your account - one for Orders and one for Profile - with all dependencies attached automatically.

<Frame>
  <img alt="Start Setup card on the Rokt Thanks tab creating the new Orders and Profile pages" />
</Frame>

**Step 2: Grant data access**

Certain access scopes are required for Rokt to display on your Account pages. There is no separate button for this — **Start setup** requests `customer_read_customers` and `customer_read_orders` for you as soon as the pages are created, and Shopify opens an "Update data access" prompt. Approve it to continue.

<Frame>
  <img alt="Shopify Update data access prompt listing the customer and store data scopes Aftersell requests" />
</Frame>

**Step 3: Place App Blocks**

Once permissions are granted, click "Edit Orders page" to open your Shopify editor.

<Frame>
  <img alt="Rokt Thanks setup checklist at four of five tasks with the Edit Orders Page button highlighted" />
</Frame>

We'll need to add the "Rokt Thanks" app block to **<u>both</u>** the Profile and Order pages. So repeat these following steps for both surfaces.

First, select the surface from the dropdown at the top of the Shopify Editor.

<Frame>
  <img alt="Shopify editor page selector dropdown open, highlighting the Orders and Profile account surfaces" />
</Frame>

Click "Add Block" and select "Rokt Thanks".

<Frame>
  <img alt="Shopify editor Add block panel with the Aftersell Rokt Thanks block highlighted" />
</Frame>

Once placed, make sure to click "Save". Repeat the same steps for the other surface.

<Warning>
  The setup guide only tracks the **Orders** page block. It will show this step as complete once that one is placed, even if the Profile block is still missing — so check the Profile surface yourself before considering setup finished.
</Warning>

<Frame>
  <img alt="Save button highlighted in the Shopify checkout editor toolbar" />
</Frame>

That's it - Rokt Thanks is now live on your account pages.

<Frame>
  <img alt="Example live Rokt Thanks offer for HelloFresh free meals with Claim and Decline buttons" />
</Frame>

<Note>
  Vaulted rewards is available to stores using Shopify's new customer accounts. If you don't see the vaulted rewards option in your Rokt Thanks admin, your store may not be eligible yet.
</Note>

***

## **Appearance**

In Shopify's Extensibility framework, there are some appearance options available to you. These customization options are controlled by Shopify from within their Checkout Editor. You can access the Checkout Editor via Shopify's Settings > Checkout > Customize.

Rokt Thanks will specifically inherit the typography selected for your checkout pages as well as the Button and Accent colors specified in the Color section.

<Frame>
  <img alt="Shopify Checkout Editor accent, button, and typography settings with callouts showing the Rokt Thanks offer inheriting them" />
</Frame>

***

## **Preview the placement**

To view the placement on your actual pages, follow these steps:

1. Enable Rokt Thanks in the Aftersell admin
2. Ensure the 'Rokt Thanks' app blocks are placed on your Thank You page, Order Status page, and (if eligible) customer account pages via the Shopify Checkout Editor
3. Wait 10 minutes after enabling the placement before conducting a test purchase
4. Make a test purchase on your store and view the pages

If Rokt Thanks is not showing as expected click the button below to learn more:

[Learn More](/aftersell/why_is_rokt_thanks_not_showing_on_my_confirmation_page)


# Adding a checkout widget to your Shopify checkout
Source: https://docs.aftersell.com/aftersell/adding_a_checkout_widget_to_your_shopify_checkout

How to customize Shopify checkout with Aftersell widgets, add app blocks like Testimonials, and adjust their position before going live

After [creating your first checkout widgets in Aftersell](/aftersell/creating_your_first_checkout_widget), the next step is to add the widgets in your Shopify checkout.

***

## Step 1: Navigate to Shopify checkout customization page

There are two ways to do this:

1. Navigate to the "Settings" tab in Shopify. Click on "Checkout" in the left hand side navigation. Click "Customize" next to your desired checkout profile.
2. Click on the "Open Shopify Checkout Editor" in the bottom right of the Aftersell checkout editor page.

The first option will give you more granularity on which checkout profile you are editing, whereas the second option will bring you to the live profile version of your checkout. We recommend testing on a draft version first to ensure everything is working as you desire before setting it live.

<img alt="Shopify checkout settings with the Checkout tab and the Customize button highlighted" />

***

## Step 2: Add an app block

Click "Add app block" in the Shopify checkout customization page.

<img alt="Shopify checkout editor with an arrow pointing to the Add app block button" />

You will be presented with the different widget options that Aftersell offers. In this example, we will be selecting the Trust Badges Widget.

<img alt="Shopify block picker listing Aftersell by Rokt widget options such as Trust Badges Widget" />

After selecting your desired widget, select the correct placement and then press save in the top right corner. You may want to consider checking the "Include app block in Shop Pay" option if you want your checkout widgets displaying in the Shop Pay checkout.

<img alt="Trust Badges Widget block settings with a placement dropdown and the Save button highlighted" />

***

## Step 3: Change app block position

Drag and drop the app block to your desired location and press save in the top right corner.

<img alt="Dragging an Aftersell app block to reposition it in the Shopify checkout editor" />


# Affiliate program
Source: https://docs.aftersell.com/aftersell/affiliate_program

This article outlines how to join and earn with the Aftersell affiliate program. 

If you're a fan of Aftersell and know others who would benefit from it, we've made it easy for you to earn extra income by simply sharing the word.

The Aftersell Affiliate Program offers you the opportunity to earn a **15% commission every month for up to 12 months** for each new customer you refer who continues to use the app.

***

### How It Works

1. **Sign Up** - Visit our affiliate page, submit your application, and receive your personalized referral link.
2. **Share Your Link** - Promote your link through the channels you already use, such as social media, blogs, email newsletters, YouTube, or direct messages. Share it wherever you naturally connect with your audience.
3. **Earn Commission** - When someone subscribes to Aftersell using your link and remains a paying customer, you'll receive **15% of their monthly subscription for up to 12 months.**

***

### Commission Structure

* **Rate:** 15% of the referred customer's monthly subscription fee.
* **Duration:** Commissions are paid for up to 12 months, provided the referred customer continues to use the app.

***

### Payouts

* **Timing:** Commissions are paid on the 15th of the following month.
* **Payment methods:** PayPal, Stripe, or direct deposit.
* **Minimum payout:** \$5.
* **Delivery:** Payments arrive within 2–10 business days after processing.
* **Setup required:** You must connect a payment provider in your PartnerStack dashboard to receive payouts.

***

### Rules and conditions

* Referrals must be made using your personalized affiliate link. Commissions cannot be earned retroactively if a referral was made without it.
* You must sign up for the program to receive your referral link before sharing.
* The referred customer must be a new Aftersell customer and remain a paying subscriber for commissions to be paid.
* Referrals are tracked with a cookie that lasts 30 days from the moment someone clicks your link. If they click your link again, the 30 days starts over. The cookie is read when the store installs Aftersell, and the referral is then recorded against your PartnerStack account.

***

### Application review process

Applications are reviewed by the Affiliates team on a first-come, first-serve basis.

* **Timeline:** Applications typically take up to 7 business days to review. This may be slightly extended during weekends or holidays.
* **Notification:** You will receive an email once your application has been reviewed.

<Note>
  Application reviews are handled in the order they are received and cannot be expedited. If you have recently applied, please allow the full review period before following up. For any questions about your application, send a message via your **PartnerStack account** once it has been created and our Affiliates team will be happy to help.
</Note>

***

### Who Is This For?

This program is ideal for:

* Influencers and content creators
* Bloggers and writers
* Ecommerce coaches and consultants
* Anyone connected to online store owners

Whether you have a large following or a small, engaged network within the Shopify community, your referrals can add up quickly.

***

**Ready to start earning?**

[Join the program](https://aftersellbyrokt.partnerstack.com/?group=affiliateaftersell)

<Tip>
  Already a member? For any questions about the Affiliate Program, send a message via your PartnerStack account and our Affiliates team will be happy to help.
</Tip>


# Aftersell billing & pricing
Source: https://docs.aftersell.com/aftersell/aftersell_billing_pricing

Understand Aftersell's plans, how your monthly bill is calculated from order volume, how the Earn & Save program can offset your bill, and answers to common billing questions.

Aftersell pricing scales with your store's order volume. Every plan is a low base fee plus a small per-order fee on each order above 500 per month, with a hard monthly cap so your bill never exceeds the plan's maximum.

<img alt="An image showing the Aftersell pricing plans" />

If your store qualifies for the Earn & Save program, its matching discount can offset most or all of your Aftersell bill (see the Offset your bill with Earn & Save section below).

## Plans

| Plan              | Monthly price                                                   | What's included                                                                                                                              |
| :---------------- | :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pre-purchase**  | \$59.99/mo + \$0.03 per order above 500 (caps at \$599.99/mo)   | Cart drawer; product page upsells; tiered rewards; cart upsells                                                                              |
| **Post-purchase** | \$34.99/mo + \$0.05 per order above 500 (caps at \$999.99/mo)   | Post-purchase upsells; thank-you page; checkout\*                                                                                            |
| **Complete**      | \$79.99/mo + \$0.07 per order above 500 (caps at \$1,359.99/mo) | Cart drawer; product page upsells; post-purchase upsells; thank-you page; checkout\*                                                         |
| **Aftersell Max** | Custom. [Talk to sales](mailto:support@aftersell.com)           | Everything in Complete, plus a dedicated merchant success manager, advanced Write and Read MCP access, and advanced templates. No free trial |

<Info>
  \*Checkout requires Shopify's Checkout Extensibility, which is available to **Shopify Plus** merchants only.
</Info>

Aftersell Max is built for high-volume brands doing 50,000 or more orders a month that need enterprise terms and dedicated support. It does not include a free trial. To discuss it, reach out via in-app chat or email <a href="mailto:support@aftersell.com">[support@aftersell.com](mailto:support@aftersell.com)</a>.

***

## How your bill is calculated

Your monthly bill is your plan's **base fee** plus the **per-order fee on every order above 500** that month, up to the plan's **monthly cap**.

<Note>
  **Store orders** refers to the total number of orders placed on your Shopify store in the last 30 days. This includes every order on your store. The first 500 orders each month are not charged a per-order fee.
</Note>

For example, at 17,300 orders in a month, 16,800 orders are billable (17,300 minus the first 500):

| Plan          | Base fee | Per-order fee   | Bill at 17,300 orders |
| :------------ | :------- | :-------------- | :-------------------- |
| Pre-purchase  | \$59.99  | 16,800 × \$0.03 | \$563.99              |
| Post-purchase | \$34.99  | 16,800 × \$0.05 | \$874.99              |
| Complete      | \$79.99  | 16,800 × \$0.07 | \$1,255.99            |

Because your bill tracks order volume, it can rise or fall month to month. Once your usage would exceed the plan cap, your bill stays flat at the cap no matter how much more your store grows.

***

## Offset your bill with Earn & Save

Your Aftersell bill can be reduced through **Earn & Save**, an opt-in program with two parts that work together:

* **Earn (Rokt Thanks).** When you activate [Rokt Thanks](/aftersell/activating_and_configuring_rokt_thanks), vetted brands show their offers on your order confirmation page, and you earn revenue each time a customer accepts one. On average, stores earn about \$0.30 to \$0.50 per accepted offer, and these earnings pay out to you in full.
* **Save (the matching discount).** Each billing cycle, Earn & Save adds a discount to your Aftersell bill sized to match your Rokt Thanks earnings from the last 30 days, up to your bill amount. This is the part that lowers what you pay Aftersell.

The two are separate, and this is the important distinction: running Rokt Thanks earns you payouts, but the **bill discount comes only from Earn & Save**, which your store must qualify for and enroll in. Eligibility starts at **1,000 or more orders per month**, so a store can earn through Rokt Thanks without yet qualifying for the Earn & Save discount.

When your earnings match or exceed your bill, the discount can bring your Aftersell charge as low as \$0. When they are smaller, the discount covers part of the bill and you pay the remainder. Either way, your Rokt Thanks earnings still pay out to you in full.

What you earn depends on your order volume and how often customers accept offers, so higher engagement means higher earnings. See the [Earn & Save Program](/aftersell/earn-save) page for eligibility, enrollment, and how the matching discount appears on your bill.

***

## Free trial

Every new install on the Pre-purchase, Post-purchase, or Complete plan includes a 30-day free trial. You can use your plan during the trial at no charge, and billing begins right after the trial ends, on your next Shopify invoice. Aftersell Max does not include a free trial.

If you previously uninstalled Aftersell and are reinstalling, your free trial eligibility is determined automatically based on your account history at the time of reinstall. If you have questions about your specific trial status, contact the Aftersell support team.

***

## When you're charged

Aftersell submits your charge to Shopify once every 30 days, starting from the day your plan first became billable. Each charge is calculated from your store's order volume over the previous 30 days. For example, if your charge fires on April 1, it reflects your order volume across the previous 30 days, and your next charge fires around 30 days later.

The charge continues for as long as your plan is active. Turning individual widgets or settings off inside the Aftersell admin does not stop it. The charge stops only when you uninstall Aftersell.

***

## Your Billing page

To open the Billing page, navigate to **Settings → Billing** in the Aftersell admin. It is organized into these sections:

| Section             | What it shows                                                                                                                                                               |
| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Billing summary** | What you'll pay this cycle and when it is due.                                                                                                                              |
| **Current plan**    | Your active plan with an "Active" status badge, your orders in the last 30 days, your current position against the plan cap, and how your monthly charge is building.       |
| **Earn & Save**     | Matching discount status, lifetime savings, and an enrollment progress card if your store is eligible. See the <a href="/aftersell/earn-save">Earn & Save Program</a> page. |
| **Payment history** | A table of past charges showing date, base amount, matching discount, and final total.                                                                                      |

***

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What happens to my existing pricing?">
    If you are already an Aftersell merchant, nothing changes automatically. You stay on your current plan and pricing, because your plan is grandfathered. The plans on this page apply to new merchants.

    If you would like to move to a current plan, [open the billing page](#your-billing-page) and select one. <br />**One thing to know:** the new Aftersell Cart is available only on current plans, so adding it means moving to the Complete plan.
  </Accordion>

  <Accordion title="How do I change my plan?">
    Open **Settings** in the left-hand navigation under Aftersell, select **Billing**, then choose **Compare plans** on the Current plan card. From the comparison, pick the plan you want and confirm the switch.

    Keep in mind that the base price is a starting point, not the whole bill. Each plan scales with your order volume through the per-order fee, up to the plan cap, so a higher-volume store pays more than the base.

    If your store is on a grandfathered plan, contact the Aftersell support team to move to a current plan rather than switching here.
  </Accordion>

  <Accordion title="Which plans include the Aftersell Cart?">
    The Aftersell Cart is available on the **Pre-purchase**, **Complete**, and **Aftersell Max** plans.
  </Accordion>

  <Accordion title="How can I lower my Aftersell bill?">
    Eligible stores can offset their bill through the Earn & Save program: your Rokt Thanks earnings pay out to you in full, and Earn & Save adds a matching discount to your Aftersell bill, up to your bill amount. Earn & Save eligibility starts at 1,000 or more orders per month. See the <a href="/aftersell/earn-save">Earn & Save Program</a> page for details.
  </Accordion>

  <Accordion title="How do I get a refund?">
    To request a refund, contact the Aftersell support team via the in-app chat or email <a href="mailto:support@aftersell.com">[support@aftersell.com](mailto:support@aftersell.com)</a>. Include your store URL, the charge date and amount you are requesting a refund for, and a short explanation of why.

    What happens next depends on the status of the charge in Shopify's billing system:

    * **Charge already paid.** Refunds are processed via Shopify's refund flow and post back to your original payment method.
    * **Charge sent to Shopify but not yet collected.** A refund cannot be processed directly. You can either wait for Shopify to collect the charge and request the refund afterwards, or request an app credit equivalent to the amount.
    * **Charge not yet submitted.** In some cases the Aftersell support team can stop the charge from being submitted, so it never appears on your Shopify bill.

    Refunds are reviewed individually. Standard Shopify refund processing times apply once approved.
  </Accordion>

  <Accordion title="How can I cancel my subscription?">
    You can cancel your subscription directly from the Aftersell app. Navigate to **Settings → Billing** and click **Uninstall** in the row of buttons on the **Current plan** card. A modal will guide you through selecting a cancellation reason and confirming the uninstall. This cancels your subscription and removes the app from your store in one step.

    After uninstall, your settings and data are retained for up to 1 year, so a reinstall within that year finds your configurations, widgets, and funnels already in place. To avoid charges for the next billing cycle, uninstall at least one day before your next billing date.

    For the full cancellation walkthrough, see <a href="/aftersell/how_do_i_cancel_my_aftersell_subscription">How do I cancel my Aftersell subscription</a>.
  </Accordion>

  <Accordion title="Do you still offer a Checkout-only plan?">
    No. The old **Checkout** plan is no longer offered. Checkout is now bundled into the **Post-purchase** and **Complete** plans.

    If your store is still on a legacy Checkout-only plan, you stay on your current pricing because it's grandfathered in. To move to a current plan (for example, to add the Aftersell Cart) [open the billing page](#your-billing-page) and select one.

    Checkout still requires Shopify's Checkout Extensibility, which is available to **Shopify Plus** merchants only.
  </Accordion>

  <Accordion title="Why was I billed after uninstalling?">
    Shopify collects app billing charges on your Shopify subscription's billing cycle, not on the day the charge is submitted. So even though Aftersell may have submitted a charge before you uninstalled, Shopify collects it on the next Shopify billing cycle.

    If you uninstalled but were still billed, this usually means the uninstall happened after the billing cycle had already processed. To avoid this, uninstall at least one day before your next billing date.
  </Accordion>
</AccordionGroup>


# Aftersell & Constructor integration
Source: https://docs.aftersell.com/aftersell/aftersell_constructor_integration

This article explains how to set up the Aftersell and Constructor product recommendation integration, including API keys and recommendation pods.

Constructor is an alternative product recommendation engine that can power your Automatic Upsells. Aftersell connects to your [Constructor](https://constructor.com/) account and pulls product recommendations from the recommendation pods you've configured there.

## Availability

Constructor appears as an option for every store under **Aftersell > Settings > Automatic upsells**. It isn't tied to any other Aftersell feature, so you don't need Aftersell Strategies or any other add-on to use it. To actually connect it, you'll need a Constructor account with recommendation pods set up.

## What you'll need from Constructor

Gather these from your Constructor account before you start:

* **API key (Index key).** Identifies your Constructor index. Aftersell uses it to load your pods during setup and to request recommendations for your shoppers. For how to create one, see Constructor's [API key documentation](https://docs.constructor.com/docs/integrating-with-constructor-retrieving-results-getting-started#api-key). **Required.**
* **API token.** Lets Aftersell read the list of recommendation pods in your account so it can validate the Pod IDs you enter. It's used during setup; the recommendations themselves don't need it.
* **A Pod ID for each surface** you want to power (Post-Purchase, Checkout, and Thank You page). **Required.** See below for what a pod is.

If you're not sure where to find your keys or how to create pods, reach out to Constructor.

## What is a Pod ID?

A **pod** is a saved recommendation configuration in your Constructor account. Each pod has its own ID and uses a **Constructor Strategy** to decide what to show. Aftersell currently supports these Constructor Strategies:

* Best Sellers
* Alternative
* Complementary
* Bundles

You point each upsell surface at a pod by entering that pod's ID in Aftersell. So the workflow is: create the pods you want in Constructor, then copy each pod's ID into the matching field in Aftersell.

<Note>
  These are **Constructor Strategies**. They are unrelated to the **Aftersell Strategies** feature — the two just happen to share the word "strategy."
</Note>

## Steps to set up the integration

1. In **Constructor**, create a recommendation pod for each placement you want to power (Post-Purchase, Checkout, and Thank You page), and note each pod's ID.
2. In **Aftersell**, go to the **Settings** tab, then open the **Automatic upsells** section.
3. Under **Product recommendations app**, select **Constructor**.
4. Enter your **Constructor API key (Index key)** and **Constructor API token**.
5. Enter the Pod ID for each surface:
   * **Post-Purchase Upsells Pod ID**
   * **Checkout Page Pod ID**
   * **Thank You Page Pod ID**
6. **Save your changes.** Aftersell validates the Pod IDs against your Constructor account. If a pod ID doesn't exist or was mistyped, you'll see an error naming the pod — fix it and save again.
7. Create your Automatic Upsells in the funnel editor and activate the funnel. Place a test order that meets the funnel's trigger requirements to confirm recommendations are returned.

## Where the setting applies

* The recommendation source you pick applies to **Post-Purchase**, **Checkout**, and **Thank You page** upsells. **Product Page Upsells always use Shopify Recommendations**, regardless of the provider you choose.
* Smart Funnel reads from this same setting. If you switch providers, Smart Funnel picks up the change automatically.


# Aftersell & Inveterate integration
Source: https://docs.aftersell.com/aftersell/aftersell_inveterate_integration

This article explains how to set up the Aftersell and Inveterate integration.

The integration between Inveterate and **Aftersell** makes it simple to promote your **membership program as a post-purchase upsell**. It ensures your membership product works seamlessly within an Aftersell funnel, helping you drive more recurring revenue.

For example, if a customer buys a pair of shoes, you can offer your Inveterate **membership** immediately after checkout, adding value and encouraging ongoing engagement.

After a customer places an order, they’ll see a post-purchase screen where they can join your membership with just a single click.

## How to Set Up the Integration

1. **Install [Aftersell](https://apps.shopify.com/aftersell) and** [Inveterate](https://apps.shopify.com/inveterate) from the Shopify App Store.
2. **Create a new funnel** in the Aftersell dashboard.
3. **Set targeting rules** to define when and to whom the upsell appears.
4. **Build your upsell offer** by selecting your Inveterate **membership product**.
5. **Save and enable** the funnel to begin displaying the offer post-purchase.

For more details, check out the full guide here: [Inveterate+Aftersell Integration Guide](https://help.inveterate.com/help-center/guides/integrations/aftersell)


# Aftersell & Nosto integration
Source: https://docs.aftersell.com/aftersell/aftersell_nosto_integration

This article explains how to set up the Aftersell and Nosto integration. 

Nosto is an alternative product recommendation engine utilized by more than 2,500 merchants, which can be integrated with your Automatic Upsells. Aftersell can connect to your Nosto account and leverage their algorithm for product recommendations.

We suggest visiting their [website](https://www.nosto.com/) if you have any inquiries regarding the product recommendation algorithm they employ.

## Steps to setup the integration

If you're interested, you’ll need to follow the steps below to set up Nosto through Aftersell:

1. Search for [Nosto](https://apps.shopify.com/nosto-personalization-for-shopify) in the Shopify App Store and **install the app.**
2. Navigate to the "**Settings**" section of the Nosto app, then click on "**Authentication Tokens**."
   * If you don't see any API tokens, you'll need to reach out to Nosto Support to obtain one before proceeding.
3. After you obtain the API token, click the blue "Decrypt" button:
   <Frame>
     <img alt="Nosto Authentication tokens page with the API_APPS role Decrypt button" />
   </Frame>
   This will open a window displaying the API key. Ensure you click "**Copy to Clipboard**" to copy the API key, and remember to **keep it private**. <img alt="Nosto Decrypt popup revealing the API secret with a Copy to Clipboard button" />
4. Now that you have the API key, return to Aftersell and navigate to the "**Settings**" tab on the left side of the app. Then, go to the Automatic Upsells section.
5. Ensure that "**Nosto**" is selected as your Product Recommendations app and that you have pasted the API token from earlier into the Nosto API key field: <img alt="Aftersell Automatic upsells settings with Nosto selected and the Nosto API key field" />
6. **Save your changes**, and Nosto is now connected. Next, we need to set up some Automatic Upsells for it to utilize.
7. Go to the funnel editor and create an Automatic Upsell.
   * You can choose to create either a single Automatic Upsell or multiple; there’s no limit to how many you can set up. <img alt="Funnel editor Upsells step with the Create your first offer button" />
8. If you’re ready to test it out, ensure that the funnel with your Automatic Upsells is active. Once it’s active, place an order on your store that meets the funnel's trigger requirements. This will enable you to check if the product recommendations are functioning correctly.
   * If you recently installed Nosto, we recommend waiting a few hours to allow its product recommendation algorithm to activate on your store. Otherwise, it may not yet have recommendations for your customers.

***

## Choosing a Nosto algorithm

Once Nosto is selected as your Product Recommendations app, each Automatic Upsell gains a **Nosto Algorithm** section in the funnel editor. Use it to pick which of Nosto's algorithms supplies that offer's recommendations:

| Algorithm                       | What it returns                                                                   |
| ------------------------------- | --------------------------------------------------------------------------------- |
| **Bought Together**             | Products frequently bought together with the item the recommendation is based on. |
| **Viewed Together (smart)**     | Products frequently viewed in the same session, ranked by Nosto's smart model.    |
| **Relationship Score Based**    | Products with the strongest overall relationship score to the source product.     |
| **Best Sellers — Most Buys**    | Your top sellers by number of purchases.                                          |
| **Best Sellers — Most Views**   | Your top sellers by number of product views.                                      |
| **Best Sellers — Most Revenue** | Your top sellers by total revenue.                                                |
| **Browsing History**            | Products drawn from the shopper's own browsing history.                           |

The setting is per offer, so different Automatic Upsells in the same funnel can use different algorithms. This section only appears while Nosto is the selected provider.

***


# Aftersell & Rivo integration
Source: https://docs.aftersell.com/aftersell/aftersell_rivo_integration

This article explains how to set up the Aftersell and Rivo integration.

**Rivo** and **Aftersell** seamlessly integrate to help you boost revenue by offering **membership upsells post-purchase.** With Aftersell’s powerful post-purchase upsell features, you can promote **Rivo memberships** to grow your subscriber base and increase your **average order value**.

***

## Why Combine Rivo with Aftersell?

* **Turn buyers into members** by upselling memberships post-purchase.
* **Boost customer retention** by enrolling more customers into your membership program.
* **Increase AOV** by offering memberships as a value-packed upsell.

***

## How to Set Up the Integration

## 1. Install Both Apps

* Add [Rivo](https://www.rivo.io/) to your Shopify store.
* Install **Aftersell** from the [Shopify App Store](https://apps.shopify.com/aftersell).

## 2. Set Up Your Rivo Membership

* Configure your **membership tiers and pricing** in the Rivo dashboard.
* Ensure your **membership product** is active and available for purchase.

## 3. Create Your Aftersell Upsell Offer

* Open **Aftersell** and go to **Post-purchase funnels**.
* Click **Add funnel**, then **Create manually**. (The same screen also offers **Guided setup** if you'd rather be walked through it.)
* In the funnel editor, on the **Upsell 1** card, click **Create your first offer** and select your **Rivo membership** as the upsell product.
* Customize the messaging to highlight the benefits of joining your membership program.

## 4. Launch the Offer

* Enable the **post-purchase upsell flow**.
* Test your checkout experience to ensure the Rivo membership offer is showing correctly.

***

## Next steps

Your customers can now easily add a **Rivo membership** after they complete their purchase, helping you **increase recurring revenue** and **maximize customer lifetime value**.

For more help, contact the Rivo team via email at [help@rivo.io](mailto:help@rivo.io).


# Aftersell & Skio integration
Source: https://docs.aftersell.com/aftersell/aftersell_skio_integration

This article explains how to set up the Aftersell and Skio integration.

**Skio** is a modern subscription platform built for DTC brands, offering seamless account management, flexible selling plans, and powerful retention tools. It integrates directly with **Aftersell**, enabling you to offer post-purchase subscription upsells that boost AOV and customer lifetime value.

***

## How to Enable Subscription Upsells with Skio and Aftersell

## 1. Install the Apps

Download both [Skio](https://apps.shopify.com/skio-subscriptions) and [Aftersell](https://apps.shopify.com/aftersell) from the Shopify App Store.

## 2. Set Up Selling Plans in Skio

* In the Skio dashboard, create your **Selling Plans** and organize them as needed.
* These plans define the subscription options and are required for Aftersell to recognize your Skio-powered subscription products.

## 3. Configure Post-Purchase Upsells in Aftersell

* Open the **Aftersell** app and navigate to the **post-purchase upsell** section.
* Create a new upsell offer and select a **Skio subscription product** linked to your selling plan.
* This setup allows customers to easily add or upgrade to a subscription immediately after checkout.

**Note:** Ensure your Skio selling plans are fully set up before creating your upsell offer in Aftersell.

## Selling-plan picker for subscription upgrades

When you configure a subscription upgrade offer with an upgrade type of **Frequency only** or **Both**, a selling-plan picker is shown in the offer edit panel. This lets you select a specific Skio selling plan to apply to the upgrade, giving you precise control over which subscription option is offered to customers.


# Aftersell & Stay.AI integration
Source: https://docs.aftersell.com/aftersell/aftersell_stayai_integration

This article explains how to set up the Aftersell and Stay.ai integration.

**Stay AI** is a powerful subscription management platform built to help e-commerce brands drive retention and boost customer lifetime value. One of its standout features is the ability to create flexible, data-driven selling plans that adapt to customer behavior. Stay AI integrates seamlessly with **Aftersell**, allowing you to offer post-purchase subscription upsells and further maximize the value of each customer.

***

To enable subscription-based upsells using **Stay.ai** and **Aftersell**, follow the steps below:

## 1. Install the Apps

* Download both the **[Stay.ai](https://apps.shopify.com/stay-ai)** [app](https://apps.shopify.com/stay-ai) and the **[Aftersell](https://apps.shopify.com/aftersell)** [app](https://apps.shopify.com/aftersell) from the Shopify App Store.

## 2. Set Up Selling Plans in Stay.ai

* In the **Stay.ai** dashboard, navigate to **Subscription Setup > Selling Plans**.
* Create your **Selling Plans** and organize them into **Selling Plan Groups**

  * These plans define your subscription options and are required for Aftersell to recognize your subscription products.

## 3. Configure Subscription Upsells in Aftersell

Open the Aftersell app, go to the post-purchase upsell section, and create an upsell offer. Select a subscription product (linked to your Stay.ai selling plan) as the upsell item. The shopper can now subscribe right after checkout.

The connection between Aftersell and Stay.ai is enabled through Shopify's native Selling Plans, so make sure your selling plans are fully configured in Stay.ai before creating the upsell in Aftersell.

***

You can learn more about the integration in this [Aftersell x Stay AI Integration](https://help.retextion.com/en/articles/9406520-aftersell-integration)

## Supported Aftersell features with Stay.ai

| Feature                                                                                                              | Supported with Stay.ai?                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Subscription Upsell (offer a subscription post-purchase)                                                             | Yes — it works through Shopify's native Selling Plans. On an order that **already contains a subscription**, the offer falls back to a one-time purchase, or is skipped entirely if the offer is set to subscription-only or the product can only be sold as a subscription. |
| Subscription Upgrade (swap a one-time purchase into a subscription, or change frequency on an existing subscription) | Not available with Stay.ai yet                                                                                                                                                                                                                                               |

Subscription Upgrade is not available with Stay.ai at this time. For the current list of supported providers and setup steps, see the [Subscription Upgrades guide](/aftersell/subscription-upgrades).

<Note>
  **Why the subscription upsell changes on a subscription order.** Shopify's post-purchase API cannot add a subscription to an order that already contains one. Aftersell works around this for Recharge, Skio, and Loop by creating the second subscription in the provider directly on accept, but that path needs one of those three providers connected — Stay.ai does not qualify for it.

  So with Stay.ai, on an order that already contains a subscription, what happens depends on how the offer is configured — not just on what the product supports:

  * **Offer purchase option set to subscription-only** → the offer is **not shown at all**, even if the product could be bought one-time. The order browser reports it as a subscription conflict.
  * **Product can only be sold as a subscription** (every variant requires a selling plan) → **not shown**, whatever the offer's purchase option.
  * **Anything else** (the offer allows a one-time purchase and the product supports one) → the offer is shown, but **downgraded to a one-time purchase**.

  Subscription upsells on orders with no subscription in them are unaffected.
</Note>


# Aftersell & Yotpo reviews integration
Source: https://docs.aftersell.com/aftersell/aftersell_yotpo_reviews_integration

This article explains how to set up the Aftersell and Yotpo Reviews integration.

Aftersell works with most product review apps automatically, including Judge.me, Stamped, ReviewsIO, Junip, Okendo, Shopify Reviews, and many more - review stars are displayed on your offers without any credentials. Yotpo Product Reviews requires additional setup described below.

## Setting up Yotpo integration

1. Download the [Yotpo app](https://apps.shopify.com/yotpo-social-reviews) in the Shopify app store

2. In the Yotpo app, tap the Profile icon in the top right corner of the screen, then choose `Account Settings > General Settings`. You will find your App Key at the bottom of the General Settings section:

   <img alt="Yotpo General Settings page with an arrow pointing to the App Key field" />

   * For more information, click [here](https://support.yotpo.com/docs/finding-your-yotpo-app-key-and-secret-key)

3. Open the Aftersell app, then go to `Settings > Product Reviews`

4. Select **Yotpo** from the review integrations list

5. Paste your App Key in the **Yotpo app key** field

6. Click **Save changes**

The integration is complete. Review stars will display on your upsell offers for products with Yotpo reviews.

## Syncing reviews

For the testimonials widget, Aftersell imports reviews from Yotpo and stores them so they can be displayed in checkout. The first import happens automatically within 24 hours, and then once a week after that.

To import reviews immediately:

1. Go to `Settings > Product Reviews`
2. Find the **Yotpo reviews** section
3. Click **Sync now**

The sync status shows when reviews were last imported and when the next sync is available.


# Post-purchase analytics
Source: https://docs.aftersell.com/aftersell/analytics_in_aftersell

Understand your post-purchase funnel performance and product page upsell metrics in Aftersell.

This page covers analytics for post-purchase funnels (including A/B tests and multivariate tests) and product page upsells in Aftersell. For checkout widget analytics, see [Checkout Analytics](/aftersell/checkout_analytics).

<Warning>
  Analytics reflect data at the time of the transaction. If an order is later refunded, partially paid, or cancelled, the accepted offer count and associated revenue are not retroactively adjusted. An offer that was accepted will continue to count as an accepted offer in your analytics regardless of what happens to the order afterward. Keep this in mind when comparing analytics data to your actual payout or revenue reports.
</Warning>

<Note>
  **Are analytics real-time?** Yes. Post-purchase funnel analytics update in near real-time. Impressions, accepted offers, and revenue are recorded as offer events happen, and the numbers are calculated fresh each time you open the Analytics page — there is no fixed reporting delay or overnight batch. Refresh the page to pull the latest figures.

  Two exceptions to keep in mind: the **Custom Data** CSV exports cover complete UTC days only (see [Custom Data Tab](#custom-data-tab)), and internal Rokt/RevOps reporting warehouses are refreshed on a daily schedule separate from this dashboard.
</Note>

***

## General notes about graphs

<Note>
  The large summary numbers at the top of each graph are weighted averages of the data shown. This method gives a more accurate overall view than a simple average. For example, three days of conversion rates are shown:

  * **Day 1:** 3 accepted / 10 shown = 30%
  * **Day 2:** 1 accepted / 9 shown = 11%
  * **Day 3:** 5 accepted / 15 shown = 33%

  The summary number is calculated as: `(3 + 1 + 5) ÷ (10 + 9 + 15) = 26.5%` not a simple average like `(30 + 11 + 33) ÷ 3 = 24.7%`. Weighted averages ensure that days with more impressions have the right impact on your totals.
</Note>

Throughout the analytics dashboard, you can hover over the **ⓘ info icon** next to any metric to see how that value is calculated. The formulas listed in the tables below match the tooltip calculations shown in the dashboard.

***

## Exporting your data

Aftersell analytics export in two file formats, depending on which control you use:

| Control                                                | Where it is                                                             | File format              |
| ------------------------------------------------------ | ----------------------------------------------------------------------- | ------------------------ |
| **Export** button (top-right of the tab)               | **Funnels**, **Checkout**, **Product Page Upsells**, and **Tests** tabs | Excel workbook (`.xlsx`) |
| **Export to CSV** button on a single chart             | Line and area chart cards                                               | `.csv`                   |
| **Export to CSV** on the Top Performing Products table | Funnels and Checkout tabs                                               | `.csv`                   |
| **Custom Data** tab downloads                          | [Custom Data tab](#custom-data-tab)                                     | `.csv`                   |

* The tab-level **Export** button downloads everything on the current tab as a single Excel workbook (`.xlsx`), with a separate sheet for each chart and table. The **Summary** tab does not have an Export button.
* A single chart's **Export to CSV** button downloads just that chart's data series as a `.csv` file, including the comparison series when **Compare** is turned on.

<Note>
  Cards on [custom dashboards](#custom-dashboards) and [report widgets](/aftersell/reports_widgets) each have their own **Export to CSV** control that downloads that card's underlying data as a `.csv` file.
</Note>

***

## Funnels Tab

The Funnels tab shows analytics for your post-purchase funnels. You can filter by a specific funnel using the "Select a funnel" dropdown or view "All funnels" combined. You can also filter by offer position using the **Filter offers** button, which opens an interactive funnel diagram — click any offer node to include or exclude it from the charts and tables. Selected offers appear as coloured tags in the filter bar, and you can remove them individually by clicking a tag. The available offer positions are Upsell 1, Upsell 2, Upsell 3, Downsell 1, Downsell 2, and Thank You page. Some metrics such as Revenue per visit and Product profit per visit show separate values for Post-purchase upsells and Thank You page.

<Note>
  Product profit analytics is currently in Beta. Aftersell tracks the cost of upsell items at the time of purchase to provide insights into profitability. Data will start tracking one day after activating. Product profit data is not available for historical data prior to activation. Contact our support team to enable product profit analytics for your store.
</Note>

### Funnels Tab Metrics

| Metric                       | What it measures                                                                                                                                                                                                                                                             | Formula                                                                                                                 |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Revenue**                  | The total revenue generated by Aftersell from Post-purchase and Thank You page offers, in the shop currency. This is the gross amount before any costs to the store, but after any discount the customer received. Revenue from other products in the order is not included. | `sum(upsell revenue) + sum(downsell revenue) + sum(TY page upsell revenue)`                                             |
| **Revenue per visit**        | The average revenue per unique page visit. A unique visit is counted once per customer, even if they view the page multiple times on a single order. This is the recommended way to measure performance over time.                                                           | Post-purchase: `post-purchase revenue / unique post-purchase visits` TY Page: `TY page revenue / unique TY page visits` |
| **Product profit**           | The total product profit generated by Aftersell. Calculated by subtracting the cost of goods sold from revenue.                                                                                                                                                              | `sum(revenue) - sum(cost of goods sold)`                                                                                |
| **Product profit per visit** | The average product profit per unique page visit. Similar to revenue per visit but accounts for cost of goods sold.                                                                                                                                                          | Post-purchase: `post-purchase profit / unique post-purchase visits` TY Page: `TY page profit / unique TY page visits`   |
| **Impressions**              | The total number of times funnel offers were viewed. Counted once per order, even if the same offer is seen multiple times during the same order.                                                                                                                            | `sum(offer views across all selected funnel offer types)`                                                               |
| **Conversion rate**          | The percentage of offer views that resulted in an accepted offer.                                                                                                                                                                                                            | `(accepted offers / offer impressions) x 100`                                                                           |
| **Accepted offers**          | The total number of offers accepted. Counted when a customer clicks "Accept" and completes the purchase.                                                                                                                                                                     | `sum(accepted offers across all selected funnel offer types)`                                                           |
| **Product profit margin**    | The ratio of product profit to revenue. If your products had no costs, this would be 100%.                                                                                                                                                                                   | `(product profit / revenue) x 100`                                                                                      |
| **Average upsell value**     | The average revenue per accepted upsell item. Particularly useful when using dynamic products in offers.                                                                                                                                                                     | `revenue / accepted offers`                                                                                             |

<Tip>
  Revenue per visit is the recommended way to measure post-purchase funnel performance over time because it accounts for unique visits rather than raw impressions.
</Tip>

### Top Performing Products Table

This table highlights post-purchase upsells and the revenue generated from them.

| Column                                                                                                        | How it is calculated                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Product**                                                                                                   | The upsold product name                                                                                                                                     |
| **One column per offer slot** — Upsell #1, Upsell #2, Upsell #3, Downsell #1, Downsell #2, and Thank you page | The conversion rate for that product in that slot: (accepted upsells containing the product in that slot / impressions for that product in that slot) x 100 |
| **Revenue**                                                                                                   | Total revenue generated from accepted upsells of this product                                                                                               |
| **RPV**                                                                                                       | Revenue per visit for this product                                                                                                                          |

There is no single "Conversion rate" column — the rate is broken out per offer slot, so you can see where in the funnel a product converts.

<Note>
  The conversion rate in this table is based on the number of accepted offers, not the number of individual product units sold. For example, if a customer accepts one offer containing 3 units of a product, it counts as 1 accepted offer. However, the revenue column reflects the total value of all units purchased through that offer.
</Note>

### Resetting analytics on an offer card

You can reset the analytics displayed on an individual offer card in the funnel editor without affecting your overall funnel analytics or the analytics page.

To reset analytics for a standalone offer:

1. Open your funnel in the **Aftersell admin**.
2. Locate the offer card you want to reset.
3. Click the **Reset analytics** icon button (displayed between the **Edit offer** and **Delete offer** icons on the card).
4. Confirm the reset in the dialog that appears.

After the reset, the offer card recomputes its displayed metrics (impressions, revenue, profit, conversion rate, revenue per visit, and profit per visit) using only data from the reset point forward. No analytics data is deleted — the analytics page and other reports are unaffected.

<Note>
  The reset analytics action is available on standalone offers only. For A/B test and multivariate test offers, use the **Reset analytics** option in the test's three-dot menu instead. See [Post-Purchase A/B Testing](/aftersell/post_purchase_a_b_testing) for details.
</Note>

***

### Deleted Funnels

Deleting a funnel does **not** remove its historical analytics data. Revenue and performance from deleted funnels are still included when **"All funnels"** is selected in the Funnel dropdown. However, once a funnel is deleted, it will no longer appear in the dropdown and cannot be viewed individually. Historical data is preserved for overall reporting, but funnel-specific breakdowns are no longer accessible.

***

### Subscription upgrades view

If a subscription provider is connected to Aftersell, a **One-time purchase / Subscription upgrades** toggle appears below the headline charts on the Funnels tab. Use it to switch between the one-time purchase charts and the subscription upgrades charts — only one set is shown at a time. When no provider is connected, the toggle is not shown and only the one-time charts appear.

An **info icon** sits beside the toggle. Hover over it for a data-freshness note: one-time metrics are live, while subscription data is updated every 30 minutes, so it can trail your live numbers.

The **Subscription upgrades** option is greyed out when it isn't available for the current view; the tooltip explains why:

* **There are no subscription upgrade offers in the selected funnel.**
* **Subscription upgrades aren't available for the selected period or offer filter** — the current date range or offer filter excludes subscription data.
* **Checking this funnel for subscription upgrade offers…** — Aftersell is still determining whether the funnel has subscription upgrade offers.

When you view a subscription funnel (or **All funnels** when at least one funnel has subscription upgrades), the headline chart area also shows **Revenue** and **Additional MRR** side by side. Revenue is your one-time upsell revenue as usual; Additional MRR is the recurring monthly revenue your offers added in the period — new subscriptions they created plus products they added to existing subscriptions (contract price normalized to a month, not cash collected; churn is not subtracted). When no subscription funnels are present, only the Revenue chart is shown, at full width.

#### Subscription upgrades charts

With **Subscription upgrades** selected, the section shows these charts. Use the **Select a funnel** and **Select an offer** dropdowns to narrow them.

| Chart                       | What it measures                                                                                                                                                                                                                                                           |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MRR change**              | Monthly recurring revenue gained or lost when an offer changed an existing subscription's delivery frequency or swapped its product. Moving a shopper to a longer billing cycle lowers this by design. Adding a product isn't counted here — that money is Additional MRR. |
| **Subscriptions started**   | Brand-new subscriptions your offers created, per day. Adding a product to an existing subscription doesn't count here — it counts under Subscriptions modified.                                                                                                            |
| **Subscriptions modified**  | Plan changes on subscriptions your offers created or changed, per day.                                                                                                                                                                                                     |
| **Subscriptions cancelled** | Cancellation events on subscriptions your offers created or changed, per day. See [Subscriptions cancelled chart](#subscriptions-cancelled-chart) below.                                                                                                                   |
| **Active subscriptions**    | Subscriptions your offers created or changed that were still active at the end of the most recent measured day. A balance, not a running total — the chart shows how it moved. Narrows by funnel only.                                                                     |
| **Refunds**                 | Refunded value on subscription upgrade orders, per day.                                                                                                                                                                                                                    |

Coverage notes may appear when data is incomplete — for example, where a provider has never sent cancellation data, Active subscriptions can only rise, so read it as an upper bound.

#### Subscriptions cancelled chart

The Subscriptions cancelled chart counts cancellation **events**, not distinct subscriptions, so a subscription that cancels more than once can be counted more than once. It narrows by funnel only — the offer and device filters don't apply. Cancellations reach Aftersell over your subscription provider's webhook; if the webhook isn't set up or needs attention, the chart is replaced by a locked card with a prompt to configure it:

| Lock state         | What it means                                     | Action                                                              |
| ------------------ | ------------------------------------------------- | ------------------------------------------------------------------- |
| **Set up webhook** | No webhook has been configured for your provider. | Open Subscription Upgrades settings and complete webhook setup.     |
| **Update webhook** | Your webhook credentials are out of date.         | Open Subscription Upgrades settings and update your signing secret. |
| **Fix webhook**    | Your provider refused the webhook registration.   | Open Subscription Upgrades settings and re-register the webhook.    |

Click the button on the locked card to go straight to the Subscription Upgrades settings page.

***

## Tests Tab

The Tests tab tracks performance for post-purchase A/B tests and multivariate tests. This tab is exclusively for post-purchase funnel tests.

<Note>
  Checkout widget A/B test performance (Version A vs. Version B) is not shown in the Tests tab. To view checkout A/B test results, use the widget editor analytics view or the Checkout dashboard. See [Checkout A/B Testing](/aftersell/checkout_analytics) for details.
</Note>

### Selecting a Test

1. Use the **Select a Funnel** dropdown to choose the funnel containing your test.
2. Use the **Select a Test** dropdown to choose the specific test you want to analyze.

The test card shows the test name, status (for example "Finished" or "Not Running"), the variables tested (for example "Layout"), the start date, and an impression progress bar showing how many impressions the test has received out of the target (for example "0/5364 impressions").

### Top Groups

The Top 3 Groups section shows your test variations ranked by performance. Each group represents a variation (for example, Group 1 = Layout A, Group 2 = Layout B). You can sort the groups using the **Sort by** dropdown, which includes the following options: Profit Per Visit, Profit, Revenue Per Visit, Revenue, and Conversion Rate.

Click on any group to view its individual analytics. Click **See all groups** to expand and compare all test groups side by side.

### Group-level Analytics

When you select a group, you see performance metrics for that specific variation.

| Metric                | What it measures                                                                                            | Formula                                                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Profit per visit**  | The average product profit per unique visit for this variation. Takes into account cost of goods sold.      | `profit for this variation / unique visits for this variation`                |
| **Profit**            | The total product profit generated by this variation.                                                       | `revenue for this variation - cost of goods sold for this variation`          |
| **Revenue per visit** | The average revenue per unique visit for this variation. Accounts for both conversion rate and order value. | `revenue for this variation / unique visits for this variation`               |
| **Revenue**           | Total revenue generated by this variation.                                                                  | `sum(upsold product revenue for this variation)`                              |
| **Conversion rate**   | Percentage of offer views that resulted in an accepted offer for this variation.                            | `(accepted offers for this variation / impressions for this variation) x 100` |

### Performance by Variable

This view shows how each variable performs on average across all other variables. Use the dropdown to switch between the following metrics.

| Variable              | What it shows                                     |
| --------------------- | ------------------------------------------------- |
| **Profit per visit**  | Average profit per visit for each variable value  |
| **Profit**            | Total profit for each variable value              |
| **Revenue per visit** | Average revenue per visit for each variable value |
| **Revenue**           | Total revenue for each variable value             |
| **Conversion rate**   | Conversion rate for each variable value           |
| **Impressions**       | Total impressions for each variable value         |

Use this to isolate which individual changes between variations had the most impact on performance.

### Key Metrics to Evaluate When Selecting a Winner

A winning variation should perform well across multiple metrics, not just one:

* **Higher profit per visit** - Each unique visit generated more profit after accounting for cost of goods sold.
* **Higher revenue per visit** - Each unique visit generated more revenue.
* **Higher conversion rate** - More customers accepted the offer.
* **Comparable or better average upsell value** - The accepted offers are generating equal or higher revenue per acceptance.

***

## Product Page Upsells Tab

The Product Page Upsells tab shows analytics for upsells displayed on your product pages.

<Note>
  Product page upsells do not currently support A/B testing.
</Note>

If analytics data could not be fully loaded, a warning banner appears at the top of the tab: **"Product page analytics may be incomplete — Some analytics data couldn't be loaded. Refresh the page to try again."** Refreshing the page will attempt to reload the data.

### Product Page Upsells Metrics

| Metric                    | What it measures                                                                                       | Formula                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| **Revenue**               | The total revenue from product page upsells.                                                           | `sum(PDP upsell revenue)`                                      |
| **Revenue per view**      | The average revenue generated per unique view on product page upsells.                                 | `revenue / unique impressions`                                 |
| **Unique impressions**    | The number of unique views on product page upsells.                                                    | `sum(unique PDP views)`                                        |
| **Conversion rate**       | The percentage of unique visitors who completed an order with a product page upsell.                   | `(upsold orders / unique impressions) x 100`                   |
| **Purchased products**    | The number of products purchased through a product page upsell.                                        | `sum(PDP products purchased)`                                  |
| **Upsold orders**         | The number of orders that included a product purchased through a product page upsell.                  | `sum(orders with PDP upsell)`                                  |
| **Revenue per order**     | The average revenue per order containing a product page upsell.                                        | `revenue / upsold orders`                                      |
| **Average upsell value**  | The average revenue per product page upsell product purchased.                                         | `revenue / purchased products`                                 |
| **Profit**                | The total profit from product page upsells. Calculated by subtracting cost of goods sold from revenue. | `sum(PDP upsell revenue) - sum(PDP upsell cost of goods sold)` |
| **Profit per view**       | The average profit generated per unique view on product page upsells.                                  | `profit / unique impressions`                                  |
| **Average upsell profit** | The average profit per product page upsell product purchased.                                          | `profit / purchased products`                                  |
| **Profit per order**      | The average profit per order containing a product page upsell.                                         | `profit / upsold orders`                                       |

***

## Custom dashboards

Custom dashboards live in the separate Reports section, not on this Analytics page. See [Reports Overview](/aftersell/reports_overview) and [Reports Dashboards](/aftersell/reports_dashboards) for details on building and viewing dashboards.

***

## Custom Data Tab

<Note>
  This feature is in beta and is available on request. Contact the support team to enable access.
</Note>

The Custom Data tab provides advanced exports for detailed analytics analysis. Each export downloads as a `.csv` file. You can export data for a 30-day period ending on any fully complete UTC day.

### Available Exports

<AccordionGroup>
  <Accordion title="Latency Metrics CSV">
    Exports post-purchase upsell latency metrics per session, including:

    * TTI (Time to Interactive)
    * RTTI (Relative Time to Interactive)
    * PTTI (Perceived Time to Interactive)
  </Accordion>

  <Accordion title="Upsell Breakdown CSV">
    Exports per-upsell daily totals with the following columns:

    * Store Name
    * Date
    * Upsell Name
    * Upsell Type
    * Sum of Impressions
    * Sum of Clicks
  </Accordion>

  <Accordion title="Funnel Breakdown CSV">
    Exports per-funnel daily totals with the following columns:

    * Store Name
    * Date
    * Funnel ID
    * Upsell Name
    * Sum of Impressions (unique visits)
    * Revenue
    * Revenue Per Visit
  </Accordion>
</AccordionGroup>

### How to Export Custom Data

1. Go to **Analytics** in your Aftersell dashboard.
2. Click the **Custom Data** tab.
3. Select an end date (must be a fully complete UTC day in the past).
4. Click the download button for the export you want:
   * **Download Latency CSV**
   * **Download Upsell Breakdown CSV**
   * **Download Funnel Breakdown CSV**

All exports cover the 30-day period ending at the end of the selected date.

***

**Want to go further?**

* [Order Browser Overview](/aftersell/order_browser_overview) - understand how Aftersell is performing across your orders
* [Order Browser Troubleshooting](/aftersell/order-browser-troubleshooting) - resolve common issues with your order data
* [Post-purchase Best Practices](/aftersell/best_practices) - tips to improve conversion across all your offers


# Automatic upsells not working
Source: https://docs.aftersell.com/aftersell/automatic_upsells_not_working

This article outlines how to troubleshoot when automatic upsell products do not show up in checkout, post-purchase, or thank-you page.

Automatic upsells are a powerful tool for increasing sales by showing relevant products at checkout, post-purchase, or on the thank-you page. However, there are times when these AI upsell offers do not appear or are skipped as intended. These troubleshooting steps will help you identify and resolve common issues preventing automatic upsells from working or being skipped.

## Which recommendation source is Aftersell using?

The recommendation source is set in **Aftersell > Settings > Automatic upsells** under the **Product Recommendations app** dropdown. The option you pick determines where recommendations come from, and where to look when they are missing.

* **Shopify** (default). Uses Shopify's own Recommendation API. Recommendations are generated from your store's order history, so purchase correlation, order frequency, and product affinity all feed into what gets suggested. Missing or thin recommendations are managed in the [Shopify Search & Discovery app](https://apps.shopify.com/search-and-discovery), covered in the next section.
* **Nosto**. Uses your connected Nosto account's algorithm. Requires a Nosto API key. See [Nosto integration](/aftersell/aftersell_nosto_integration) for setup.
* **Constructor**. Uses your connected Constructor account. Requires a Constructor API key (Index key), an API token, and a Pod ID for each surface (Post-Purchase, Checkout, and Thank You page). See [Constructor integration](/aftersell/aftersell_constructor_integration) for setup.

This setting applies to Post-Purchase, Checkout, and Thank You page upsells. Product Page Upsells always use Shopify Recommendations, regardless of the option you pick.

Smart Funnel pulls from the same setting. If you switch sources, Smart Funnel picks up the change automatically.

## 1. No "Related products" in Search & Discovery

Use the [Shopify Search & Discovery app](https://apps.shopify.com/search-and-discovery) to view “**Related products**” in the *Recommendations* page. For stores with very few orders or for recently added products, Shopify may not auto-generate “Related products”. You can manually add “Related products” by clicking on the product title and using the section titled “Edit related products”.

For more details on how “Related products” are selected, see this [Shopify help document](https://shopify.dev/docs/themes/product-merchandising/recommendations).

## 2. Excluded products in Aftersell

Go to *`Aftersell > Settings > Automatic upsells >` Excluded products* to check if you have exclude products from automatic upsells. Look for selected collections that have a large number of products, such as “**All Products**”. If you have excluded too many products then there won’t be any "**Related products**" to show. We recommend keeping the exclusion list small and only excluding products that you absolutely do not want to upsell. Additionally, if you select "All products collection" as an exclusion, it will exclude every product in your store, effectively disabling upsells entirely. Be cautious with your exclusion settings, especially during specific periods when exclusions are active, as they might unintentionally prevent upsells from displaying.

NOTE: Even if you don’t exclude every product from your store, you might still be excluding all items in the “**Related products**” section.

## **3. Password protected online store**

Automatic upsells do not work for stores that require a password. This includes development stores and stores that are password-protected before launch.

* We recommend testing with specific products instead of automatic upsells on these stores.


# Can I advertise with Rokt Thanks and promote my business on other sites?
Source: https://docs.aftersell.com/aftersell/can_i_advertise_with_rokt_thanks_and_promote_my_business_on_other_sites

Can I become an advertiser on Rokt Thanks?

Currently, this is reserved to Shopify stores with over 50,000 monthly orders.

To learn how you can join our advertising network, [request a demo](https://www.aftersell.com/demo) from one of our experts.


# Group bundle lines from another app
Source: https://docs.aftersell.com/aftersell/cart/sdk-use-case-bundles

Use setInternalProperties to tell the Aftersell Cart which lines belong to the same bundle, so they render as one item instead of several unrelated lines.

Most bundle apps build a bundle by adding **each component as its own cart line**, then linking them with line item properties of their own design. Shopify's Ajax API hands those lines to the cart with no indication that they belong together, so by default the drawer shows a three-part bundle as three unrelated items, each with its own price and quantity stepper.

`setInternalProperties` is how you tell the cart they're one thing.

## How grouping works

The cart groups lines on two **canonical properties**. It doesn't know your bundle app's property names, so you translate: read whatever the app wrote, and stamp the canonical pair onto each line with a [line transform](/aftersell/cart/sdk-hooks#registerlinetransform).

| Property                      | Required | Value                                                       |
| ----------------------------- | -------- | ----------------------------------------------------------- |
| `_aftersell_cart_bundle_id`   | Yes      | A shared ID. Every line carrying the same ID is one bundle. |
| `_aftersell_cart_bundle_role` | No       | Set to `parent` on the line the bundle should display as.   |

These go through `setInternalProperties`, not through Shopify. They're a **render-only overlay**: they never reach `properties`, are never persisted to Shopify, and never appear on the order.

## Step 1: find out what your app writes

Every bundle app names its properties differently, so start by looking at a real cart. Add a bundle on your storefront, then run this in the browser console:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.actions.getCart().items.forEach((line) => {
  console.log(line.title, line.properties);
});
```

You're looking for a property shared across the bundle's lines. It's usually a hidden property (the name starts with `_`) holding an ID, a reference, or the bundle's name. Something like `_bundle_id`, `_bundle_ref`, or `_parent_id` is typical. Note the exact key, and whether one line is marked as the main product.

## Step 2: map it onto the canonical properties

Paste into **Cart settings → Custom script → Initialization**, replacing the property names with the ones you found:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerLineTransform((line) => {
  const props = line.properties;
  if (!props) return;

  const bundleId = props._bundle_id;
  if (!bundleId) return;

  line.setInternalProperties({
    _aftersell_cart_bundle_id: bundleId,
    // Mark the main product so the bundle renders under it.
    _aftersell_cart_bundle_role: props._bundle_role === 'main' ? 'parent' : 'child',
  });
});
```

That's the whole integration. Once two or more lines share an ID, the cart folds them into one bundle.

<Note>
  If your app doesn't mark a main product, leave `_aftersell_cart_bundle_role` off entirely. The cart picks an anchor for you.
</Note>

## What you get

Once lines are grouped, the anchor line carries a [`bundle` object](/aftersell/cart/sdk-cart-object#bundles) and the drawer renders the bundle as a single item:

* **Children nest under the anchor** instead of appearing as separate rows.
* **Quantity is atomic.** Changing the bundle's quantity scales every member together, using each child's `perAnchorQty` ratio, so a bundle with two of one component keeps that two-to-one relationship.
* **Removal is atomic.** Removing the bundle removes every member line in one request, rather than leaving orphaned components behind.
* **One price row.** What it shows follows the **bundle price** setting on the [Cart items](/aftersell/cart/cart-items-block) block: the total of all members, or the main product's price alone.

## How the anchor is chosen

The anchor is the line the bundle displays as. The cart picks it in this order:

1. The line with `_aftersell_cart_bundle_role` set to `parent`.
2. Otherwise, the **highest-priced** member.
3. Otherwise, the first member in the cart.

The price fallback is usually right, since bundle apps tend to put the discount on the main product. Set the role explicitly when it isn't, for example when the main product is the cheapest item or is free.

## Rules worth knowing

* **A bundle needs at least two lines.** A single line carrying a bundle ID is left alone and renders normally.
* **Shopify native bundles are already handled.** Lines that Shopify itself marks as componentized are skipped by this grouping and adapted automatically. You only need this for apps that add separate lines.
* **The transform runs on every render.** Keep it cheap and free of side effects. Don't call actions or fetch from inside it.
* **Merging is additive.** Your properties merge with any set by another transform. On a genuine conflict over the same key, the last-registered transform wins.
* **Grouping runs after hiding and renaming**, and before sorting. So a line you hide with `setHidden` never becomes part of a bundle, and a [comparator](/aftersell/cart/sdk-hooks#registerlinecomparator) sees the anchor, not the children.

<Warning>
  **Grouped children leave `state.items`.** Once lines are folded into a bundle, only the anchor appears in `getCart().items` and in event payloads; the children move to `anchor.bundle.children`. They also stop counting toward `itemCount`.

  The **cart total is unaffected**, because totals come straight from Shopify. Grouping changes presentation, never what the shopper pays.
</Warning>

## Reading a bundle back

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('cart_updated', (state) => {
  state.items.forEach((line) => {
    if (!line.bundle) return;
    console.log(line.title, 'is a bundle of', line.bundle.children.length, 'items:');
    line.bundle.children.forEach((child) => {
      console.log('  ', child.quantity, 'x', child.title);
    });
  });
});
```

To act on a bundle's lines, use `bundle.memberKeys`, which holds the `key` of every member including the anchor.

## Using it for other things

Bundle grouping is what `setInternalProperties` was built for, but the overlay is a general channel for **render-only data you derive from a line**. Anything you put there is readable at `line.internalProperties` and in a [Custom code block](/aftersell/cart/custom-code-blocks), without touching the real cart:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerLineTransform((line) => {
  if (line.properties?._preorder_ship_date) {
    line.setInternalProperties({ _badge: `Ships ${line.properties._preorder_ship_date}` });
  }
});
```

Use it when the value is **derived** and display-only. If the data needs to survive to the order, it belongs in a real line item property, set with a hidden `properties[...]` input on the product form so it reaches Shopify whoever performs the add.

## Where to go next

* **[`registerLineTransform`](/aftersell/cart/sdk-hooks#registerlinetransform)**: the hook this runs through.
* **[Cart object](/aftersell/cart/sdk-cart-object#bundles)**: the shape of `bundle` and its children.
* **[Cart items block](/aftersell/cart/cart-items-block)**: the bundle price setting.


# Auto-add a free gift at a threshold
Source: https://docs.aftersell.com/aftersell/cart/sdk-use-case-free-gift

A Cart SDK use case that adds a free gift when the cart total crosses a threshold, and removes it if the total drops below.

Watch the cart total and keep a free gift in sync with it: add the gift once the shopper crosses a spend threshold, remove it if they drop back below.

<Note>
  For a merchant-configured version with tiers, per-market rules, and a progress bar, use the [Rewards](/aftersell/cart/rewards-block) block, with no code. This is for when your rule is something the block can't express.
</Note>

## The snippet

Paste into **Cart settings → Custom script → Initialization**, and set the two constants:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const FREE_GIFT_VARIANT_ID = 1234567890; // the gift product's variant id
const THRESHOLD_CENTS = 5000;            // $50.00, since totals are in cents

function reconcileGift(state) {
  const gift = state.items.find((line) => line.variantId === FREE_GIFT_VARIANT_ID);
  const qualifies = state.totalPrice >= THRESHOLD_CENTS;

  if (qualifies && !gift) {
    window.aftersell.cart.actions.addItem(FREE_GIFT_VARIANT_ID, 1);
  } else if (!qualifies && gift) {
    window.aftersell.cart.actions.removeItem(gift.key);
  }
}

window.aftersell.cart.events.on('cart_loaded', reconcileGift);
window.aftersell.cart.events.on('cart_updated', reconcileGift);
```

## How it works

**`reconcileGift`** describes the state the cart *should* be in, then makes at most one change to get there:

* Qualifies and the gift isn't there → [`addItem`](/aftersell/cart/sdk-actions#additemvariantid-quantity) adds it.
* Doesn't qualify and the gift is there → [`removeItem`](/aftersell/cart/sdk-actions#removeitemkey) removes it, by the line's `key`.
* Otherwise → do nothing.

It runs on both [`cart_loaded`](/aftersell/cart/sdk-events#cart_loaded) (so a cart that already qualifies on page load gets the gift) and [`cart_updated`](/aftersell/cart/sdk-events#cart_updated) (so it reacts to every change afterward). Because `cart_loaded` replays to late subscribers, this works no matter when your script runs.

<Warning>
  **The `!gift` / `gift` guards are what stop this looping.** Adding the gift fires `cart_updated`, which runs `reconcileGift` again, and the second pass finds the gift already present, so it does nothing. Strip the guards and you get an infinite loop. See [the two rules](/aftersell/cart/sdk-events#the-two-rules).
</Warning>

Note that adding the gift **raises the cart total**, so a threshold near a product's price can oscillate: adding a \$0 gift is safe, but a gift with a price could push the cart above the threshold on its own. Keep the gift free, or compare against a total that excludes it.

## Adapting it

**Gate on item count instead of spend:**

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const qualifies = state.itemCount >= 3;
```

**Gate on a specific product being in the cart:**

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const qualifies = state.items.some((line) => line.productId === TRIGGER_PRODUCT_ID);
```

**Only in certain countries.** Read [`context`](/aftersell/cart/sdk-overview#context), which is available before the cart loads:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const ELIGIBLE = ['US', 'CA'];

// Only register the handlers for eligible countries.
if (ELIGIBLE.includes(window.aftersell.cart.context.customer_country)) {
  window.aftersell.cart.events.on('cart_loaded', reconcileGift);
  window.aftersell.cart.events.on('cart_updated', reconcileGift);
}
```

**Exclude the gift from the threshold** so it can't hold itself up:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const subtotalWithoutGift = state.items.reduce(
  (sum, line) => (line.variantId === FREE_GIFT_VARIANT_ID ? sum : sum + line.finalLinePrice),
  0
);
const qualifies = subtotalWithoutGift >= THRESHOLD_CENTS;
```

**Mark the gift so it reads as a gift.** A [line transform](/aftersell/cart/sdk-hooks#registerlinetransform) can change a line's title, variant title, hidden state, and internal properties — so relabel it:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerLineTransform((line) => {
  if (line.variantId === FREE_GIFT_VARIANT_ID) {
    line.setTitle('Free gift 🎁');
  }
});
```

<Note>
  A line transform **cannot hide a line's quantity controls** — its only setters are `setTitle`, `setVariantTitle`, `setHidden`, and `setInternalProperties`. If a shopper changes the gift's quantity, correct it from a `cart_updated` handler instead.
</Note>

## Where to go next

* **[Rewards block](/aftersell/cart/rewards-block)**: the no-code version, with tiers.
* **[Actions](/aftersell/cart/sdk-actions)**: `addItem`, `removeItem`, and the rest.
* **[Events](/aftersell/cart/sdk-events)**: why the guards matter.


# Hide and relabel cart lines
Source: https://docs.aftersell.com/aftersell/cart/sdk-use-case-hide-lines

A Cart SDK use case using line transforms and comparators to hide app-injected lines, rename them, and control the order they render in.

Hide lines the shopper shouldn't see, rename lines that read badly, and control the order everything renders in, all without touching what's actually in the cart.

This replaces the older pattern of hiding cart elements with CSS or `style.display = 'none'`. A line transform is applied every time the cart renders, so it survives updates, re-renders, and drawer re-opens.

## Hide a line

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Hide free lines from the drawer. The cart total is unchanged.
window.aftersell.cart.hooks.registerLineTransform((line) => {
  if (line.finalLinePrice === 0) {
    line.setHidden(true);
  }
});
```

<Warning>
  **Hiding is not removing.** A hidden line stays in the shopper's cart, stays in the total, and goes through to checkout; it just isn't drawn in the drawer. It does drop out of `getCart().items` and `itemCount`, so your own code stops seeing it too. If you want it gone for real, use [`removeItem`](/aftersell/cart/sdk-actions#removeitemkey).
</Warning>

Common things worth hiding:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerLineTransform((line) => {
  // An app-injected line, tagged with a private property.
  if (line.properties?._bundle_child) {
    line.setHidden(true);
  }

  // A specific SKU that shouldn't be shopper-managed.
  if (line.variantId === HIDDEN_VARIANT_ID) {
    line.setHidden(true);
  }

  // Gift cards issued by a loyalty app.
  if (line.isGiftCard && line.finalLinePrice === 0) {
    line.setHidden(true);
  }
});
```

## Relabel a line

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerLineTransform((line) => {
  // Flag discounted lines.
  if (line.finalLinePrice < line.originalLinePrice) {
    line.setTitle(`${line.title} (On sale)`);
  }

  // Make the subscription cadence read naturally.
  if (line.sellingPlan) {
    line.setVariantTitle(`Delivered ${line.sellingPlan.name.toLowerCase()}`);
  }

  // Drop a meaningless variant label.
  if (line.variantTitle === 'Default Title') {
    line.setVariantTitle(null);
  }
});
```

The four setters available on a line:

| Setter                            | Effect                                                                                                                           |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `setHidden(bool)`                 | Hide the line from the drawer.                                                                                                   |
| `setTitle(string)`                | Change the displayed title.                                                                                                      |
| `setVariantTitle(string \| null)` | Change the displayed variant label. `null` removes it.                                                                           |
| `setInternalProperties(obj)`      | Merge render-only properties, for a [Custom code block](/aftersell/cart/custom-code-blocks) to read. Never persisted to Shopify. |

## Control the order

A comparator takes the same shape `Array.prototype.sort` expects, and runs after hiding and renaming:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Subscriptions first, then everything else.
window.aftersell.cart.hooks.registerLineComparator((lineA, lineB) => {
  return (lineB.sellingPlan ? 1 : 0) - (lineA.sellingPlan ? 1 : 0);
});
```

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Push free gifts and add-ons to the bottom.
window.aftersell.cart.hooks.registerLineComparator((lineA, lineB) => {
  return (lineA.finalLinePrice === 0 ? 1 : 0) - (lineB.finalLinePrice === 0 ? 1 : 0);
});
```

Return `0` for pairs you don't care about. Comparators compose as tie-breakers, so the first to return a non-zero value decides that pair and returning `0` hands the decision to the next one instead of forcing an order on it.

## Hide a whole block, not a line

A line transform works on cart lines. To show different **block** settings by country, market, or currency (for example different Rewards tiers), use [conditions in the cart editor](/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency). No code required, and it survives cart redesigns. Cart total and cart contents are **not** editor condition types.

Reach for the SDK when your rule is something conditions can't express (product IDs in the cart, a custom total, and so on). In that case, query the [shadow root](/aftersell/cart/sdk-overview#shadowroot) for a public `cart-external-*` class:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('cart_updated', (state) => {
  const root = window.aftersell.cart.shadowRoot;
  if (!root) return;

  const rewards = root.querySelector('.cart-external-rewards');
  if (!rewards) return;

  const hasExcluded = state.items.some((line) => EXCLUDED_PRODUCT_IDS.includes(line.productId));
  rewards.style.display = hasExcluded ? 'none' : '';
});
```

<Warning>
  This runs after each render, so the block can flash into view before your code hides it. Conditional rendering doesn't have that problem, so prefer it wherever it fits.
</Warning>

## Things to get right

* **Transforms are set-up calls.** Register them at the top of your Initialization script; no `ready()` needed.
* **Everyone's transforms run.** Yours composes with any registered by other apps. You can't replace theirs, and they can't drop yours.
* **A transform can't change price, quantity, or identity.** It only changes what renders. Use the [actions](/aftersell/cart/sdk-actions) for real changes.
* **A transform that throws is skipped silently.** The rest still run. Check [`aftersellCartDebugEvents`](/aftersell/cart/sdk-overview#debugging) while developing.
* **`registerLineTransform` returns an unregister function**, if you need to undo it later.

## Where to go next

* **[Hooks](/aftersell/cart/sdk-hooks)**: the full hook reference.
* **[Cart object](/aftersell/cart/sdk-cart-object)**: every field you can branch on.
* **[Custom CSS](/aftersell/cart/custom-css)**: the `cart-external-*` class convention.


# Show metafield data on cart lines
Source: https://docs.aftersell.com/aftersell/cart/sdk-use-case-metafields

A Cart SDK use case using registerCartEnricher to pull metafields from the Shopify Storefront API onto every cart line, then render them.

The cart knows what Shopify's Ajax API tells it: titles, prices, quantities, properties. It doesn't know your metafields. A **cart enricher** fetches extra product or variant fields from the Storefront API and attaches them to every matching line, so you can show a delivery estimate, a "ships separately" warning, an ingredient list, or anything else you store on the product.

Typical uses: per-product delivery windows, allergen or ingredient badges, a custom "low stock" flag, loyalty point multipliers, subscriber-only pricing.

## Register the enricher

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerCartEnricher({
  id: 'delivery',
  onType: 'Product',
  fragment: `
    deliveryWindow: metafield(namespace: "custom", key: "delivery_window") { value }
    shipsSeparately: metafield(namespace: "custom", key: "ships_separately") { value }
  `,
});
```

Three fields:

| Field      | Description                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `id`       | Namespace for the result; it lands at `line.metadata[id]`. Must be unique; a second registration with the same `id` is ignored. |
| `onType`   | `'Product'` or `'ProductVariant'`. Also the join key, so product ID vs. variant ID.                                             |
| `fragment` | A GraphQL field selection (no outer braces) spliced into the Storefront query. Braces must balance.                             |

Whenever the cart loads or changes, Aftersell fetches your fragment for every product or variant in the cart. The fetch is **non-blocking**: the cart renders immediately and re-emits `cart_updated` once the data lands. A slow or failing fragment never delays or breaks the cart.

## Read the data

Because enrichment is asynchronous, `line.metadata.delivery` is `undefined` until the first fetch resolves. Always guard the read.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('cart_updated', (state) => {
  state.items.forEach((line) => {
    const deliveryWindow = line.metadata.delivery?.deliveryWindow?.value;
    if (!deliveryWindow) return; // not fetched yet

    console.log(line.title, 'arrives in', deliveryWindow);
  });
});
```

## Render it in the cart

Enrichment puts the data on the line; a [Custom code block](/aftersell/cart/custom-code-blocks) in React mode draws it. Add the block as a **Cart items sub-block** so it renders once per line and receives that line as `props.line`:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomCode(props) {
  const data = props.line?.metadata?.delivery;
  const window_ = data?.deliveryWindow?.value;

  if (!window_) return null;

  return (
    <div className="cart-external-custom-code_html" style={{ fontSize: '12px', opacity: 0.7 }}>
      Arrives in {window_}
    </div>
  );
}
```

<Warning>
  Enriched values come back from the Storefront API **as-is and unsanitized**. Render them as text, as above, and never with `dangerouslySetInnerHTML` or by writing raw HTML.
</Warning>

## Variant-level data

Set `onType: 'ProductVariant'` when the metafield lives on the variant rather than the product:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerCartEnricher({
  id: 'pricing',
  onType: 'ProductVariant',
  fragment: `
    anchorPrice: metafield(namespace: "custom", key: "anchor_price") { value }
    subscriberPrice: metafield(namespace: "custom", key: "subscriber_price") { value }
  `,
});
```

## More than metafields

The fragment is spliced into a Storefront API query, so anything the API exposes on a `Product` or `ProductVariant` works, not just metafields:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerCartEnricher({
  id: 'productInfo',
  onType: 'Product',
  fragment: `
    tags
    vendor
    productType
    availableForSale
  `,
});
```

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Then: warn about anything from a drop-ship vendor.
window.aftersell.cart.events.on('cart_updated', (state) => {
  const hasDropship = state.items.some((line) => {
    const tags = line.metadata.productInfo?.tags;
    return tags?.includes('dropship');
  });
});
```

## Things to get right

* **Guard every read.** `metadata` defaults to `{}` and your namespace is `undefined` until the fetch resolves. The cart renders before the data arrives, always.
* **Each `id` is its own namespace.** Multiple enrichers coexist without colliding, including ones registered by other apps.
* **Metafields must be Storefront-visible.** A metafield that isn't exposed to the Storefront API returns `null`. Check the definition in Shopify admin if you get nothing back.
* **Keep the fragment small.** It runs for every product in the cart, on every cart change. Ask for the fields you use, not everything.
* **Register at set-up time.** It's a hook, so it belongs at the top of your Initialization script.
* **Braces must balance.** No outer braces around the fragment, but any nested selection needs its own matching pair. An unbalanced fragment is rejected.

## Where to go next

* **[`registerCartEnricher`](/aftersell/cart/sdk-hooks#registercartenricher)**: the full hook reference.
* **[Custom code blocks](/aftersell/cart/custom-code-blocks)**: rendering the data.
* **[Cart object](/aftersell/cart/sdk-cart-object)**: where `metadata` sits on a line.


# Open the drawer from a page builder
Source: https://docs.aftersell.com/aftersell/cart/sdk-use-case-page-builder

A Cart SDK use case for making Replo, PageFly, GemPages, and custom add-to-cart buttons open the Aftersell Cart drawer.

Aftersell intercepts add-to-cart on standard Shopify product forms. Landing page builders often add to the cart their own way, using a JavaScript call instead of a form submit, so the item lands in the cart but the drawer stays shut, or the shopper gets redirected to `/cart`.

## The fix, in one line

After the builder's add-to-cart finishes, tell the cart to refetch and open:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.actions.refresh().then(() => {
  window.aftersell.cart.actions.open();
});
```

Add this as a **second action** on the button, after the builder's own "add to cart", and turn off the builder's "go to cart" or "redirect after add" option.

<Note>
  Try [`open_on_background_add`](#the-no-code-option-first) first, since it often solves this without touching the button at all.
</Note>

## The no-code option first

Aftersell detects adds it didn't handle itself in two ways. Both run at all times — they are attached together at boot and neither suppresses the other, so one add can be announced by both — and each announcement applies the open rule independently:

* **On the wire.** Aftersell watches for requests to Shopify's cart endpoints. If the add followed a real click or keypress within about three seconds, it counts as shopper-driven, and the drawer opens according to your normal **Open cart when an item is added** setting. Any builder that adds through Shopify's Ajax cart API (`/cart/add.js`) lands here, which is the common case — so try your button first, it may already work with no changes at all.
* **[Shopify's standard cart events](https://shopify.dev/docs/storefronts/themes/best-practices/standard-events).** An add announced this way is always treated as a *background* add, whether or not a shopper clicked. Background adds don't open the drawer unless you opt in:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.configure({ open_on_background_add: true });
```

Paste that into **Cart settings → Custom script → Initialization**. If the drawer now opens after your builder's add button, you're done, with no per-button work, and it covers every page.

<Note>
  `open_on_background_add` also covers adds with no shopper gesture at all — another app or script writing to the cart. Turn it on only if you want those to pop the drawer too.
</Note>

If neither path opens the drawer, fall back to the explicit call below.

## Per-builder setup

### Replo

1. Open your page in the Replo editor and select the **Add to Cart** button.

2. In the right sidebar, open the **Interactions** tab.

3. Under **On Click**, click `+` and choose **Run JavaScript**.

4. Paste:

   ```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
   window.aftersell.cart.actions.refresh().then(() => {
     window.aftersell.cart.actions.open();
   });
   ```

5. Select the **Add Product to Cart** interaction again and turn **Go to cart after?** off.

6. Preview, confirm the drawer opens, then publish.

Repeat on each page that has an add-to-cart button.

### PageFly and GemPages

Both let you attach custom JavaScript to a button click or add a custom code element to the page. Use the same snippet, wired to run after the builder's add-to-cart action, and disable any "redirect to cart" setting on the button.

### Your own button

If you're adding to the cart yourself, skip the round trip and use the SDK's own action, which updates the cart and can open the drawer in one step:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
document.querySelector('#my-add-button').addEventListener('click', () => {
  window.aftersell.cart.actions.addItem(VARIANT_ID, 1).then(() => {
    window.aftersell.cart.actions.open();
  });
});
```

Use `refresh()` only when something *else* changed the cart and you need Aftersell to catch up:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
fetch('/cart/add.js', { method: 'POST', /* … */ })
  .then(() => window.aftersell.cart.actions.refresh())
  .then(() => { window.aftersell.cart.actions.open(); });
```

## When the builder's button should bypass Aftersell entirely

Sometimes the opposite is true: a form needs its own flow, and Aftersell's interception gets in the way. Exempt just that form:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.hooks.registerSkipAddToCartRule((form) =>
  form.hasAttribute('data-skip-aftersell')
);
```

Then add `data-skip-aftersell` to the form. This is better than [`skip_add_to_cart_interceptor`](/aftersell/cart/sdk-configure#skip_add_to_cart_interceptor), which turns interception off for every form on the page.

Simpler still, if you can edit the form's markup: add the class **`aftersell-cart-skip-atc`** to the `<form>` and Aftersell skips it, no script needed.

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<form action="/cart/add" method="post" class="aftersell-cart-skip-atc">
```

## Troubleshooting

| Symptom                               | Likely cause                                                                                                                                                       |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Item added, drawer stays shut         | The builder isn't emitting Shopify's standard cart events. Use the explicit `refresh()` + `open()` call.                                                           |
| Shopper is redirected to `/cart`      | The builder's "go to cart after add" option is still on. Turn it off.                                                                                              |
| Drawer opens but shows stale contents | `open()` ran before `refresh()` resolved. Chain them with `.then()`, as above.                                                                                     |
| Nothing happens at all                | Actions called before the cart loaded warn in the console and do nothing. Wrap in `window.aftersell.cart.ready().then(…)` if the button can be clicked that early. |
| Works on one page, not another        | Most builders apply interactions per page. Repeat the setup on each.                                                                                               |

Check [`window.aftersellCartDebugEvents`](/aftersell/cart/sdk-overview#debugging) if a call seems to do nothing, since SDK failures are swallowed rather than thrown.

## Where to go next

* **[Configure](/aftersell/cart/sdk-configure#open_on_background_add)**: `open_on_background_add` and the other drawer options.
* **[Actions](/aftersell/cart/sdk-actions)**: `refresh`, `open`, and `addItem`.
* **[Hooks](/aftersell/cart/sdk-hooks#registerskipaddtocartrule)**: exempting a single form.


# Require terms before checkout
Source: https://docs.aftersell.com/aftersell/cart/sdk-use-case-terms-checkbox

A Cart SDK use case that adds a terms and conditions checkbox to the Aftersell Cart and blocks checkout until the shopper accepts.

Add a checkbox under the checkout button and stop the shopper proceeding until they tick it. Useful for terms acceptance, age gates, and made-to-order acknowledgements.

<Warning>
  **The `checkout` event can't cancel checkout.** It fires as a notification just before the browser navigates, so returning `false` or calling `preventDefault` does nothing. The only way to gate checkout is to stop the button responding to clicks *before* it's pressed, which is what this page shows.

  Treat this as a UI deterrent, not a legal guarantee. A determined shopper can still reach checkout directly.
</Warning>

## How it works

Three pieces:

1. A **Custom code block** below the checkout button renders the checkbox.
2. While the box is clear, the block adds a class to the cart's checkout and express-payment buttons through the [shadow root](/aftersell/cart/sdk-overview#shadowroot).
3. **Custom CSS** makes that class disable clicks.

## Step 1: Add the checkbox block

Add a [Custom code block](/aftersell/cart/custom-code-blocks) below your Checkout button block, switch it to **React component** mode, and paste:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomCode(props) {
  const [accepted, setAccepted] = useState(false);

  useEffect(() => {
    const root = window.aftersell?.cart?.shadowRoot;
    if (!root) return;

    const targets = root.querySelectorAll(
      '.cart-external-checkout-button, .cart-external-express-buttons'
    );
    targets.forEach((el) => el.classList.toggle('checkout-gated', !accepted));
  }, [accepted, props.cart]);

  return (
    <div style={{ width: '100%', fontSize: '14px', textAlign: 'center' }}>
      <label style={{ display: 'flex', gap: '6px', justifyContent: 'center', alignItems: 'center' }}>
        <input
          type="checkbox"
          checked={accepted}
          onChange={(e) => setAccepted(e.target.checked)}
        />
        <span>
          I accept the{' '}
          <a href="https://yourstore.com/terms" target="_blank" rel="noopener noreferrer">
            Terms &amp; Conditions
          </a>
        </span>
      </label>
      {!accepted && (
        <div style={{ color: '#c00', fontWeight: 600, marginTop: '6px' }}>
          Please accept the terms above to continue.
        </div>
      )}
    </div>
  );
}
```

Click **Compile**, then turn on **"Use custom template"**. The block renders nothing until you do.

The `props.cart` dependency matters: it re-applies the class after the cart re-renders, which would otherwise wipe it.

## Step 2: Add the CSS

In **Cart settings → Custom CSS**:

```css theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.checkout-gated {
  pointer-events: none !important;
  opacity: 0.5 !important;
}
```

`pointer-events: none` is what actually blocks the click; the opacity just shows the shopper why.

## Step 3: Test it

In [preview](/aftersell/cart/previewing-carts), confirm that:

* The checkout button is dimmed and doesn't respond to clicks on load.
* Ticking the box enables it; clearing it disables the button again.
* Express payment buttons are gated too.
* Adding or removing an item doesn't re-enable the button while the box is clear.

That last one is the common failure. If the button re-enables itself after a cart change, the effect isn't re-running. Check that `props.cart` is in the dependency array.

## Tracking who accepted

The checkbox is browser-only state; it never reaches the order. To record acceptance, stamp it onto every line as a property at add-to-cart time:

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<input type="hidden" name="properties[_terms_version]" value="2026-01">
```

Add that to your product form in the theme. Shopify reads `properties[...]` straight off the form, so the value reaches the order whoever performs the add: Aftersell, the theme, or another app.

A property prefixed with `_` stays out of the buyer-facing line but still reaches Shopify, so it appears on the order. This records *which* terms version was live, not that the shopper ticked the box.

## Things to get right

* **Only target `cart-external-*` classes.** The `cart-internal-*` twins are the cart's own plumbing, not a handle for your code. See [Custom CSS](/aftersell/cart/custom-css).
* **Check `shadowRoot` exists** before using it. It's `undefined` until the cart boots.
* **The block renders nothing until the cart loads**, so the checkout button is never briefly live before the gate applies.
* **A React block that throws renders nothing** and the rest of the cart carries on, which here means an unguarded checkout button. Test in preview before publishing.

## Where to go next

* **[Custom code blocks](/aftersell/cart/custom-code-blocks)**: React mode and its props.
* **[Custom CSS](/aftersell/cart/custom-css)**: the public class convention.
* **[Events](/aftersell/cart/sdk-events#checkout)**: what the `checkout` event can and can't do.


# Checkout dashboard overview
Source: https://docs.aftersell.com/aftersell/checkout-dashboard-overview



The Checkout dashboard is your central hub for managing all Checkout widgets and pages, as well as monitoring general performance. This article covers the layout of the dashboard and what each section does.

For a detailed breakdown of how Pages and Standalone widgets work, including setup, configuration, block IDs, and placement - see [**<u>Pages & Standalone Widgets: A Complete Guide</u>**](/aftersell/pages-vs-standalone-widgets).

<img alt="Aftersell Checkout dashboard What's new modal introducing Pages and analytics" />

***

## **Dashboard metrics**

At the top of the Checkout dashboard, you'll find a summary of your checkout performance across four key metrics:

* **Revenue**: Total revenue attributed to your Checkout upsells widgets
* **AOV**: Average order value of orders that included a Checkout widget 
* **Impressions**: Total number of checkout sessions where at least one widget was displayed. Several widgets shown in the same session still count once
* **Conversion**: The Percentage of checkout sessions with widget impressions that resulted in a completed purchase

Use the date selector in the top-left to filter all metrics by a custom date range (e.g., last 30 days). This applies to all metrics on the Checkout dashboard, including those shown in the Pages and Standalone widgets tables.

<img alt="Checkout dashboard metrics bar showing Revenue, AOV, Impressions, and Conversion tiles" />

***

## **Pages**

A Page is a group of related widgets that are displayed together on your checkout based on a shared set of trigger conditions (which can include multiple conditions). While widgets are grouped within a Page and triggered at the same time, each widget still needs to be configured individually and requires its own app block placement. This setup helps coordinate when widgets appear, but does not eliminate the need to manage each widget separately.

The Pages section displays the following information for each page:

| **Column**          | **Description**                                                                           |
| :------------------ | :---------------------------------------------------------------------------------------- |
| **Priority**        | The order in which pages are evaluated when multiple pages are active                     |
| **Name**            | The name of the page                                                                      |
| **Triggers**        | The conditions under which this page is shown (or "Show to all" to show to all customers) |
| **Widgets**         | Icons representing the widget types included in the page                                  |
| **Impressions**     | How many times this page has been shown                                                   |
| **Page conversion** | The conversion rate for this page                                                         |
| **AOV**             | Average order value attributed to this page                                               |

Each page has action buttons on the right:

* **Edit** (pencil icon): Open the page editor
* **View analytics** (bar chart icon): View analytics for this specific page
* **Duplicate** (duplicate icon): Create a copy of the page, including all its widgets and trigger configuration. The duplicated page is created in an inactive state with the name prefixed by "(Duplicated)" so it doesn't conflict with the original's display rules. You can then rename and activate it when ready.
* **Active toggle**: Turn the page on or off without opening it. This is the only control on the row that changes whether the page is live.

Use **Manage priority** to control the order in which your pages are evaluated, and **Create page** to add a new page.

***

## **Standalone widgets**

Standalone widgets are individual widgets that function independently, each with their own triggers and priority configured at the variant-level.

The Standalone widgets section shows the following for each widget:

| **Column**            | **Description**                                                                                                                    |
| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| **Name**              | The widget name (e.g., "Default upsell", "Additional upsell 1")                                                                    |
| **Variants**          | The number of variants configured for this widget                                                                                  |
| **Active variants**   | How many of those variants are currently active                                                                                    |
| **Placement status**  | Whether the widget has been placed in your Shopify Checkout editor. Shows **Incomplete** (red) if placement has not been completed |
| **Impressions**       | Total impressions for this widget                                                                                                  |
| **Widget conversion** | Conversion rate for this widget                                                                                                    |

Each standalone widget also has:

* **Edit** (pencil icon): Open the widget editor
* **View analytics** (bar chart icon): View analytics for this specific widget

**Note:** A maximum of **3 blocks** can be added for Standalone widgets. Each block can contain multiple variants, but no more than 3 blocks per widget can be created.

***

## **Analytics**

You can view analytics for any individual Page or Standalone widget directly from the dashboard by clicking the **bar chart icon** next to it. Analytics can also be accessed from within the page or widget editor.

This allows you to monitor and compare performance across your different widgets and pages to see what's working best for your store.


# Checkout A/B testing
Source: https://docs.aftersell.com/aftersell/checkout_a_b_testing

Learn how to set up, manage, and analyze A/B tests for your checkout widgets in Aftersell

# Checkout A/B Testing

A/B testing (also known as split testing) lets you compare two versions of a checkout widget to determine which performs better. A/B testing is currently only available for standalone widgets and is not yet supported for pages. Each version is shown to a portion of your checkout traffic, and performance is tracked separately so you can identify the higher-performing version.

By testing variations of your offers, you can improve conversion rates, increase revenue, and make data-driven decisions about your upsell strategy.

<Note>
  This page covers A/B testing for checkout widgets only. If you are looking to test your post-purchase offers, see [A/B Testing for Post-Purchase Offers](/aftersell/post_purchase_a_b_testing).
</Note>

<Note>
  Checkout widgets are only available to Shopify Plus merchants due to Shopify's Checkout Extensibility API restrictions.
</Note>

## How checkout A/B testing works

Standalone checkout widgets support two versions within a single block. When both versions are active, traffic is split 50/50 between them, labeled **Version A** and **Version B** in the analytics view. Each version is shown to a separate portion of customers, and their performance is tracked independently so you can compare results and identify a winner.

Each version has its own configuration and settings, making it possible to test meaningful differences between offers.

<Note>
  A/B testing is currently only available for standalone widgets. Pages do not support A/B testing yet.
</Note>

### What you can test

A/B testing is supported on both **upsell widgets** and **content widgets**.

**Upsell widgets** - You can test:

* **Products**: Different products, product types, or recommendation strategies (specific product vs. AI recommendations vs. most expensive product)
* **Discounts**: Different discount amounts or types (percentage vs. fixed dollar)
* **Widget mode**: Single product upsell, multi-product upsell, or checkmark upsell
* **Blank (Skip)**: Use an empty version as a control to measure whether showing an upsell helps or hurts checkout conversion

**Content widgets** (trust badges, testimonials, cart controls, notes, text, images, reward bar) - You can test:

* Different badge or testimonial content
* Different messaging or copy
* Showing vs. not showing a content widget (using Blank/Skip as a control)

## Test types

When adding a new version to a standalone widget, you choose one of three test types:

### Duplicate content

Duplicate content creates a new version that is a copy of an existing version. Use this when you want to test a small change - such as a different discount amount or a different product - while keeping everything else the same. Because the starting point is identical, any performance difference is more likely to be caused by the single change you made. This is the most common starting point for A/B tests because it minimizes variables and makes results easier to interpret.

### New content

New content creates a blank version that you configure from scratch. Use this when you want to test a fundamentally different offer - such as a different widget mode, a completely different product category, or a different trigger strategy. New content versions give you full flexibility but require more setup time. This type is best suited for broader tests where you want to compare two distinct approaches rather than a single incremental change.

### Blank (Skip)

Blank (Skip) creates an empty version that shows nothing to the customers it is assigned to. Use this as a control group to measure the baseline - what happens when no widget is shown at all. Comparing a Blank version against an active offer helps you understand whether your widget is helping or hurting checkout conversion. This is especially useful if you are concerned that showing a widget might increase checkout abandonment for certain customer segments.

## Setting up a checkout A/B test

### Step 1: Open or create a standalone widget

1. Open the Aftersell app from your Shopify Admin
2. Navigate to **Checkout** in the left sidebar
3. Scroll to the **Standalone widgets** section
4. Either open an existing standalone widget by clicking the pencil (edit) icon, or click **Create widget** to create a new one

### Step 2: Add a version

1. Inside the widget editor, add a new version
2. Choose one of the three test types: **Duplicate content**, **New content**, or **Blank (Skip)**
3. Configure the new version - set the product, discount, widget mode, and any other settings you want to test

### Step 3: Check your triggers

Triggers belong to the widget, not to an individual version — the **Select triggers** card sits above the version tabs, and both Version A and Version B are served under the same conditions. There is nothing to configure per version, and targeting itself cannot be A/B tested.

For a full list of available trigger options, see [Checkout Triggers](/aftersell/checkout_triggers).

### Step 4: Verify placement in the Shopify Checkout editor

1. Open the Shopify Checkout editor from your Shopify Admin
2. Confirm the app block for this standalone widget is placed in your desired location
3. The widget will not display to customers until it has been placed

Your A/B test is now live.

## How traffic is split

Checkout A/B tests use a **50/50 split** between two active versions (Version A and Version B). Traffic is evenly distributed between the versions automatically and cannot be manually adjusted.

If you pause a version, all traffic goes to the surviving version. To run a valid A/B test, leave both versions running.

## Managing your test

Once your A/B test is running, you can manage it at any time from within the widget editor.

### Pausing a version

Open the **Manage A/B test** menu and choose **Pause version A** or **Pause version B**. The paused version stops receiving traffic and the surviving version takes all of it. Choose **Reactivate split test** to return to the 50/50 split. There is no per-version active toggle — the **Active** switch in the widget header governs the whole widget, both versions together.

### Editing a version

Open the version and make your changes directly. For accurate results, avoid making significant changes to a version while the test is running, as this can make it harder to interpret what drove any performance differences.

### Deleting a version

Delete a version to permanently remove it from the widget. Once deleted, the version and its data cannot be recovered. All traffic will go to the remaining active version.

### Selecting a winner

When you are ready to end the test and commit to one version:

1. Identify the higher-performing version based on its analytics
2. Pause or delete the losing version
3. The winning version will now receive 100% of traffic

## Understanding your A/B test results

When an A/B test is running, you can view Version A and Version B performance by clicking the bar chart icon next to the widget on the Checkout dashboard. The metrics shown depend on the widget type - upsell widgets and content widgets show different metrics.

For a complete breakdown of all widget-level metrics, per-version analytics, and the Analytics tab Checkout graphs, see [Checkout Analytics](/aftersell/checkout_analytics).

## Limitations

### A/B testing is within the same widget type only

A/B testing in Aftersell compares two versions of the **same widget type**. For example, you can test two different trust badge configurations against each other, or test an upsell offer against Blank (Skip). You cannot A/B test across different widget types - for example, you cannot test a trust badge widget against an image widget in the same A/B test.

### A/B testing is not available for pages

A/B testing is currently only available for standalone widgets. Pages do not support A/B testing yet.

### Placement testing is not supported

You cannot A/B test different widget placements (for example, testing whether an upsell performs better in the order summary vs. above the payment section). A/B testing compares the content within a single widget in a fixed placement.

## Best practices

### Test one element at a time

When you change multiple elements at once, it becomes difficult to know which change drove the result. Isolate one variable per test for clear, actionable insights.

**Good**: Test 10% discount vs. 20% discount (one variable changed)

**Avoid**: Test 10% discount + Product A vs. 20% discount + Product B (two variables changed at once)

### Use Blank (Skip) as a control

Running a Blank (Skip) version against an active widget is one of the most valuable tests you can run. It tells you whether showing the widget at all is helping or hurting your checkout conversion rate. If the Blank version performs better on checkout completion, it may be worth reconsidering the offer entirely or adjusting your targeting.

### Monitor checkout abandonment

A higher upsell conversion rate is good, but make sure it is not coming at the cost of increased checkout abandonment. Check the **Checkout abandonment rate** in Analytics > Checkout tab regularly while running A/B tests. For content widgets, the per-version analytics view also includes a Checkout abandonment rate metric.

### Common test ideas

**Upsell widget tests**

* Specific product vs. AI recommendations vs. most expensive product
* Complementary product vs. same product (replenishment)
* 10% off vs. 20% off
* Percentage discount vs. fixed dollar amount
* Discount vs. no discount
* Single product upsell vs. checkmark upsell
* Multi-product upsell vs. single product upsell
* Active offer vs. Blank (Skip) to measure the net impact of showing an upsell

**Content widget tests**

* Trust badge with vs. without specific badges
* Different testimonial content
* Different note or text messaging
* Active content vs. Blank (Skip) to measure the impact of showing the content widget

## Frequently asked questions

### Do A/B tests stop running automatically after reaching statistical significance?

No. A checkout A/B test keeps running until you end it yourself — there is no automatic stop when a result reaches statistical significance. Review each version's performance in analytics, and when you're confident in a winner, end the test manually by deactivating or deleting the losing version (see [Selecting a winner](#selecting-a-winner)). Aftersell never stops a test or picks a winner for you.

***

## Need help?

If you have questions about setting up or analyzing your checkout A/B tests, chat with our support team using the live chat at the bottom right of the app.


# Checkout analytics
Source: https://docs.aftersell.com/aftersell/checkout_analytics

Understand your checkout upsell performance across the Checkout dashboard, Analytics tab, and widget-level metrics in Aftersell

This page covers all analytics related to checkout widgets in Aftersell, including the Analytics tab Checkout graphs, widget-level analytics by widget type, and per-version A/B test breakdowns. For post-purchase funnel and product page analytics, see [Post-Purchase Analytics](/aftersell/analytics_in_aftersell). For checkout A/B test setup and management, see [Checkout A/B Testing](/aftersell/checkout_a_b_testing).

<Warning>
  Checkout widgets are only available to Shopify Plus stores due to Shopify's Checkout Extensibility API restrictions.
</Warning>

<Warning>
  Analytics reflect data at the time of the transaction. If an order is later refunded, partially paid, or cancelled, the accepted offer count and associated revenue are not retroactively adjusted. An offer that was accepted will continue to count as an accepted offer in your analytics regardless of what happens to the order afterward. Keep this in mind when comparing analytics data to your actual payout or revenue reports.
</Warning>

***

## General Notes About Graphs

<Note>
  The large summary numbers at the top of each graph are weighted averages of the data shown. This method gives a more accurate overall view than a simple average. For example, three days of conversion rates are shown:

  * **Day 1:** 3 accepted / 10 shown = 30%
  * **Day 2:** 1 accepted / 9 shown = 11%
  * **Day 3:** 5 accepted / 15 shown = 33%

  The summary number is calculated as: `(3 + 1 + 5) ÷ (10 + 9 + 15) = 26.5%` not a simple average like `(30 + 11 + 33) ÷ 3 = 24.7%`. Weighted averages ensure that days with more impressions have the right impact on your totals.
</Note>

Throughout the analytics dashboard, you can hover over the **ⓘ info icon** next to any metric to see how that value is calculated. The formulas listed in the tables below match the tooltip calculations shown in the dashboard.

***

## Checkout Dashboard

The Checkout dashboard is the main overview for all checkout widget performance. It is accessible from the **Checkout** section in the left sidebar of the Aftersell app. For a full breakdown of all Checkout dashboard sections, columns, and summary metrics, see [Checkout Dashboard Overview](/aftersell/checkout-dashboard-overview).

***

## Analytics Tab - Checkout Graphs

The Analytics section of the Aftersell dashboard includes a dedicated Checkout tab with graphs and metrics for your overall checkout performance.

### Filtering by Page

You can filter your checkout analytics by specific pages or widget types using the "Select a page" dropdown at the top of the Checkout tab. This allows you to analyze performance for:

* **Overall (pages + standalone widgets)** - Shows combined analytics for all checkout pages and standalone widgets. This is the default view.
* **Standalone widgets** - Shows analytics only for widgets that are not part of a checkout page.
* **Individual checkout pages** - Shows analytics for a specific checkout page by name.

When you select a page filter, all graphs and metrics on the Checkout tab update to show data only for that selection. This helps you understand which pages or widget configurations are performing best.

<Tip>
  Inactive pages are labeled with "(Inactive)" in the dropdown but still show historical analytics data.
</Tip>

### Checkout Tab Metrics

| Metric                        | What it measures                                                                                                                   | Formula                                            |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| **Revenue**                   | The total checkout revenue generated by Aftersell upsell widgets.                                                                  | `sum(upsell widget revenue)`                       |
| **Impressions**               | The total number of times checkout upsell widgets were viewed.                                                                     | `sum(widget views)`                                |
| **Upsell revenue per order**  | The average upsell revenue per purchased order. This is the recommended way to measure performance over time for checkout widgets. | `checkout upsell revenue / purchased orders`       |
| **Accepted upsell rate**      | The percentage of unique visitors who accepted an upsell offer.                                                                    | `(accepted offers / unique visitors) x 100`        |
| **Unaccepted upsell rate**    | The percentage of customers who initiated the checkout process but did not accept an upsell.                                       | `(1 - (accepted offers / unique visitors)) x 100`  |
| **Checkout abandonment rate** | The rate at which customers go to checkout without completing the order. This is measured separately from any offers shown.        | `(1 - (purchased orders / unique visitors)) x 100` |
| **Total revenue per order**   | The average total store revenue from purchased orders where Aftersell checkout widgets were placed on the checkout page.           | `total store revenue / purchased orders`           |
| **Accepted offers**           | The total number of Aftersell upsell offers that were accepted.                                                                    | `sum(accepted offers)`                             |
| **Average upsell value**      | The average revenue per accepted upsell item. Particularly useful when using dynamic products in offers.                           | `upsell revenue / accepted offers`                 |
| **Product profit**            | The total product profit generated by Aftersell. Calculated by subtracting the cost of goods sold from the revenue.                | `sum(upsell revenue) - sum(cost of goods sold)`    |
| **Product profit per order**  | The average product profit per purchased order. Similar to revenue per order but accounts for cost of goods sold.                  | `product profit / purchased orders`                |
| **Product profit margin**     | The ratio of product profit to revenue. If your products had no costs, this would be 100%.                                         | `(product profit / revenue) x 100`                 |

<Tip>
  Upsell revenue per order is the recommended metric for measuring checkout widget performance over time.
</Tip>

### Top Performing Products Table

This table highlights checkout upsells and the revenue generated from them. It works the same way as the one in the Funnels tab, but only includes checkout upsells.

<Note>
  The conversion rate in this table is based on the number of accepted offers, not the number of individual product units sold. For example, if a customer accepts one offer containing 3 units of a product, it counts as 1 accepted offer. However, the revenue column reflects the total value of all units purchased through that offer.
</Note>

To view this table, go to the **Analytics** section in your Aftersell dashboard, click on the **Checkout** tab, and scroll to the **Top Performing Products** section.

***

## Widget-Level Analytics

You can view analytics for individual widgets by clicking the bar chart icon next to any widget on the Checkout dashboard. The metrics shown depend on the widget type.

### Pages

Pages are groups of related widgets with a shared trigger. Click the bar chart icon next to a page on the Checkout dashboard to view its analytics.

| Metric                       | What it measures                                                          | Formula                                  |
| ---------------------------- | ------------------------------------------------------------------------- | ---------------------------------------- |
| **Sessions with page**       | The number of unique checkout sessions where this page was displayed.     | `sum(widget views)`                      |
| **Cart conversion rate**     | The percentage of sessions that resulted in a completed purchase.         | `(purchased orders / impressions) x 100` |
| **Average order value**      | The average total order value for sessions where this page was displayed. | `total store revenue / purchased orders` |
| **Upsell revenue per order** | The average upsell revenue per purchased order.                           | `upsell revenue / purchased orders`      |

### Standalone Upsell Widgets

Upsell widgets display product offers that customers can accept during checkout. Click the bar chart icon next to an upsell widget on the Checkout dashboard to view its analytics.

| Metric                       | What it measures                                                                                                                                                                                            | Formula                                                    |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Upsell revenue per order** | The average upsell revenue per purchased order.                                                                                                                                                             | `upsell revenue / purchased orders`                        |
| **Sessions with widget**     | The number of unique checkout sessions where this widget was displayed. If a customer views a page multiple times on a single order, it is counted as one session.                                          | `sum(widget views)`                                        |
| **Upsell conversion rate**   | The percentage of purchased orders that accepted an upsell from this widget. An order that accepts upsells across multiple widget placements is counted once per placement, so this rate can exceed 100%.   | `(orders with upsells / purchased orders) x 100`           |
| **Orders with upsells**      | The sum of widget placements per order where at least one upsell was accepted. An order that accepts upsells in two placements contributes twice; multiple offers accepted within one placement count once. | `sum(placements per order with at least 1 accepted offer)` |
| **Purchased orders**         | The number of purchased orders where this widget was displayed. This is the denominator used by the upsell conversion rate and per-order revenue metrics.                                                   | `sum(purchased orders)`                                    |

<Note>
  The widget analytics modal on the Checkout dashboard charts the first four of these — Upsell revenue per order, Sessions with widget, Upsell conversion rate, and Orders with upsells. **Purchased orders** is the denominator behind two of them rather than a chart of its own; it appears as a chart only in the widget analytics modal inside the checkout editor.
</Note>

<Note>
  When an A/B test is running on an upsell widget, these same 4 metrics are split to show **Version A** and **Version B** separately, allowing direct comparison between versions. A/B test results are only available at the widget level and are not shown in the general Analytics tab. For setup instructions, see [Checkout A/B Testing](/aftersell/checkout_a_b_testing).
</Note>

### Standalone Content Widgets

Content widgets are every non-upsell category: **Rewards**, **Trust Badges**, **Testimonials**, **Cart Controls**, **Notes**, **Text**, and **Images**. These widgets do not offer upsell products but can influence checkout behavior, and all of them get the same set of charts. Click the bar chart icon next to a content widget on the Checkout dashboard to view its analytics.

| Metric                        | What it measures                                                                                                                                                   | Formula                                      |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| **Sessions with widget**      | The number of unique checkout sessions where this widget was displayed. If a customer views a page multiple times on a single order, it is counted as one session. | `sum(widget views)`                          |
| **Cart conversion rate**      | The percentage of sessions that resulted in a completed purchase.                                                                                                  | `(purchased orders / impressions) x 100`     |
| **Average order value**       | The average total order value for sessions where this widget was displayed.                                                                                        | `total store revenue / purchased orders`     |
| **Checkout abandonment rate** | The percentage of sessions that did not complete their purchase.                                                                                                   | `(1 - purchased orders / impressions) x 100` |

<Note>
  When an A/B test is running on a content widget, these same 4 metrics are split to show **Version A** and **Version B** separately, allowing direct comparison between versions.
</Note>

### Why Widget Analytics May Show Zero Values

If you see 0% conversion, \$0 revenue, and 0 orders for a widget or a specific version, this does not mean the data is missing or broken. It means no customer has completed the relevant action through that widget or version yet.

This is normal in the following situations:

* The widget was recently created and has not yet received enough traffic
* The widget's triggers are not matching any customers in the current date range
* The widget or variant is newly active and sessions are still accumulating
* For A/B tests, it is normal for the widget to show overall metrics while the per-version view still shows zeros, especially if the test was recently started

Give the widget time to accumulate sessions before drawing conclusions.

***

## Exporting checkout analytics

The **Checkout** tab exports the same way as the rest of the Analytics page:

* **Export** button (top-right of the Checkout tab) — downloads the whole tab as an Excel workbook (`.xlsx`), with a separate sheet for each chart and table.
* **Export to CSV** on an individual chart card — downloads that chart's data series as a `.csv` file, including the comparison series when **Compare** is on.
* **Export to CSV** on the **Top Performing Products** table — downloads the table as a `.csv` file.

For the full list of analytics exports and their formats, see [Exporting your data](/aftersell/analytics_in_aftersell#exporting-your-data).

***

**Want to go further?**

* [Checkout A/B Testing](/aftersell/checkout_a_b_testing) - set up and manage A/B tests for your checkout widgets
* [Checkout Dashboard Overview](/aftersell/checkout-dashboard-overview) - full breakdown of the Checkout dashboard


# Checkout branding settings
Source: https://docs.aftersell.com/aftersell/checkout_branding_settings

This article walks you through the Checkout Branding settings and how to use each section to customize your checkout.

The branding settings let you customize the look and feel of your checkout, from colors and typography to buttons, form fields, and page layout. These tools make it easy to align your checkout design with your brand identity.

# How to access it

Open the **Checkout** dashboard in Aftersell and click **Edit branding** at the top of the page.

<Note>
  Editing branding here requires a **Shopify Plus** plan. Shopify only lets apps read and write checkout branding on Plus, so on other plans these settings cannot be saved. If your store is not on Plus, make the same changes in the Shopify checkout editor instead: **Settings → Checkout → Customize** in your Shopify admin.
</Note>

<img alt="Aftersell Checkout dashboard with an arrow pointing to the Edit branding button" />

The editor is organized into three groups: **Design system**, **Customizations**, and **Advanced**.

***

# Design system

Design system settings are the foundation. Components across the checkout inherit from them unless a more specific setting overrides them.

## Global colors

Your brand and system colors, used across your store and post-purchase experiences. Components use these colors when no color scheme is set.

**Brand colors**

* **Brand** – your primary brand color.
* **Accent** – used for interactive and highlighted elements.
* **Decorative** – used for supporting decorative elements.

**Status and system colors**

* **Success** – confirmation states.
* **Warning** – cautionary messages.
* **Critical** – errors and alerts.
* **Info** – informational messages.

<Note>
  Surface and button colors are not set here. They live under **Advanced > Color schemes**.
</Note>

## Typography

* **Font size** – set the **Base size** and the **Scale ratio** that derives the rest of the type scale.
* **Primary font** – used for most components such as regular text, buttons, and form controls. Choose a **Font family**, **Base weight**, and **Bold weight**.
* **Secondary font** – used for heading components, with the same three controls.

## Corner radius

Sets the shared corner radius values that buttons, form fields, containers, and other components reference. You define three sizes: **Small**, **Medium**, and **Large**.

***

# Customizations

## Buttons

Configured separately for **Primary buttons** (the main action on a page) and **Secondary buttons** (supporting actions). Each has:

* **Corner radius** – Small, Medium, Large, or None (squared).
* **Background** – Solid or None.
* **Vertical padding** and **Horizontal padding**.
* **Show border**.

<Note>
  Button colors are inherited from color schemes. If no scheme value is set, global colors are used.
</Note>

## Form fields

Applies to all supported field types:

* **Corner radius**
* **Label position** – Inside or Outside.
* **Show border**

**Field-specific overrides** let you depart from those shared styles for particular field types: **Text field borders**, **Dropdown borders**, **Choice list group spacing**, and **Checkbox corner radius**.

## Product thumbnails

Controls how product images appear on the page:

* **Show border**
* **Border radius**
* **Fit**
* **Badge background color** – Accent (scheme accent color) or Base (scheme base color).

## Header

* **Layout** – **Placement** (Top bar, Left section, or Right section) and **Alignment** (Left, Center, or Right).
* **Container** – **Padding**, **Color scheme**, and **Show divider**.

<img alt="Checkout page with the store name header highlighted at top left" />

## Content area

Controls the **Divider** between the main and order summary areas: **Show divider**, **Border style**, and **Border weight**.

## Main area

* **Section containers** – the background and border wrapper around each section: **Background**, **Show border**, **Border style**, **Border weight**.
* **Section dividers** – the lines shown between sections.

## Order summary

* **Container** – the **Color scheme** applied to the overall order summary container.
* **Section dividers** – **Show divider**, **Border style**, **Border weight**.
* **Section containers** – the background and border around each section: **Show border**, **Background**, **Border style**, **Border weight**, **Color scheme**, **Corner radius**, **Padding**, and **Shadow**.

<img alt="Order summary product thumbnail with a highlighted image border" />

## Footer

* **Layout** – **Placement** and **Alignment**.
* **Container** – **Show footer content**, **Padding**, **Color scheme**, and **Show divider**.

***

# Advanced

## Color schemes

Color schemes are reusable sets of surface, text, and button colors that other sections point at. Two schemes are available:

* **Scheme 1 - Main area**
* **Scheme 2 - Supporting areas**

Each scheme is split into three groups:

* **Buttons** – used for the main payment button and secondary actions. **Primary button** and **Secondary button** are configured separately, each with its own default and hover state.
* **Form controls** – used for text fields, dropdowns, and choice lists.
* **Base surfaces** – the surface background, body text, and supporting roles: border, accent (links and focus), decorative (subtle highlights), and icon color.

Wherever a section offers a **Color scheme** control, you can point it at **Scheme 1**, **Scheme 2**, or **Transparent**.


# Checkout customization limitations
Source: https://docs.aftersell.com/aftersell/checkout_customization_limitations

This article outlines notable limitations regarding checkout customizations

The Shopify API's used in Aftersell's checkout customization feature come with [some limitations](https://shopify.dev/docs/api/functions/reference/payment-customization#limitations-and-considerations). We aim to detail those here to prepare you for its usage. Additionally, it's important to note that these limitations extend beyond payment customizations and also include restrictions related to price displays on checkout and cart buttons.

# Payment Customization Limitations

## Payment method naming

The "Credit Card" payment option seen on the checkout page is actually called "Shopify Payments" for the purposes of the API. This can be confusing, but keep this in mind when targeting this payment method for any sort of customization.

For example, when ordering items alphabetically, the "Credit Card" option will be ordered by its true name of "Shopify Payments", meaning it may appear closer to the bottom of the list.

## Renaming

You can't rename payment methods that have logos as a name, such as Shop Pay, Apple Pay and Google Pay. This includes all wallets.

## Reordering

You can remove wallets from the Express section of checkout, but you can't reorder them.

## Draft Orders

Payment customizations are not currently supported in draft orders.


# Checkout customizations
Source: https://docs.aftersell.com/aftersell/checkout_customizations

This article outlines customizable actions for configuring payment and delivery methods.

Checkout customizations allow you to adjust delivery and payment methods to better meet customer needs and enhance the customers' shopping experience.

[Payment Methods](#payment-methods)

[Delivery Methods](#delivery-methods)

[Actions](#actions)

[Trigger condition](#trigger-condition)

## Payment Methods

You can set payment method customization(s) to show tailored payment options to customers when they finalize their purchase.

## Delivery Methods

You can set delivery method customization(s) to show tailored delivery options to customers when they finalize their purchase.

***

## Actions

You can set three actions for Checkout customizations:

1. **Rename:**

* To rename a payment/delivery method, select **Add method to rename** and choose a matching logic such as "**is**".

* Then choose what to do with the name: **replace with**, **add suffix**, or **add prefix**.

  For example, if the payment method is labeled as "bank deposit", you can replace it with "BD", or add a prefix or suffix while keeping the original name.

2. **Move:**

* To reorder payment/delivery methods, choose **Sort alphabetically**, **Sort alphabetically (reverse)**, **Set to the top** (based on conditions like "**contains**", "**does not contain**", or "**is not**"), or **Set manually** to arrange them in your own order.

* Delivery methods additionally offer **Sort by price (low to high)** and **Sort by price (high to low)**. These two are not available for payment methods.

3. **Hide:**

* To hide a payment/delivery method, you can set conditions such as:

  If the method is

  If the method contains

  If the method does not contain

  If the method is not

  If it includes all methods

  For example, you might specify "payment method is bank deposit" to hide it. This action ensures that the selected payment method will not appear in the checkout options.

  Delivery-method customizations also let you hide on **cost value** (greater or less than an amount) and on **type** / **type is not**.

Note: You can add more than one customization, by clicking on **Add new action**.

***

## Trigger condition

You can also define specific trigger conditions under which these customizations will be applied:

<img alt="Select a trigger condition modal listing Cart and Discount condition options" />


# Checkout translations
Source: https://docs.aftersell.com/aftersell/checkout_translations

Customize the system text shown in your checkout widgets for each language using the Checkout Translations section in Settings.

Aftersell automatically translates system text in your checkout widgets (upsells, cart controls, and testimonials) based on the customer's language. You can override any of these default translations per language from **Settings > Translations**.

***

## How checkout translations work

When a customer reaches checkout, Aftersell detects their language and applies the appropriate translations to all system-generated strings in your checkout widgets. These include labels like "Adding...", "Sold Out", "Remove", and "Read more".

The **Checkout translations** section in **Settings > Translations** lets you override the default translated strings for any supported language. Your overrides apply on top of the bundled defaults. Each field arrives pre-filled with the bundled default, and saving one as empty hides that label for customers in that language — see [Blank field behavior](#blank-field-behavior).

***

## Supported languages

Checkout translations currently support 32 languages:

Arabic, Bulgarian, Chinese, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hebrew, Hungarian, Italian, Japanese, Korean, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovenian, Spanish, Swedish, Turkish, and Ukrainian.

***

## Customizing checkout translations

1. Go to **Settings**
2. Select **Translations**
3. Scroll to the **Checkout translations** section
4. Choose a language from the language dropdown
5. Update any fields you want to override for that language
6. Click **Save**

Your overrides are saved alongside your post-purchase translations in a single save action.

To reset all fields for a language back to the bundled defaults, click **Reset defaults**.

***

## Available fields

The following strings are available for customization. Sensitive strings (such as commerce CTAs, savings claims, and "Verified buyer") are system-managed and cannot be overridden.

### Upsell widget

| Field                                       | Description                                                                                            |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Adding (loading state)                      | Text shown while a product is being added to the cart                                                  |
| Removing (loading state)                    | Text shown while a product is being removed                                                            |
| Sold out badge                              | Label shown when a product is out of stock                                                             |
| Quantity (upsell label)                     | Quantity selector label on upsell widgets                                                              |
| Purchase option (upsell label)              | Label for the purchase option selector                                                                 |
| One-time purchase (upsell)                  | Label for the one-time purchase option                                                                 |
| Upsell error message                        | Message shown when adding or removing a product fails                                                  |
| Discount suffix (appended to "20%" / "\$6") | The word shown after the discount amount next to the product title, e.g. the "OFF" in "(20% OFF)"      |
| Review count label                          | Label for review counts — use `{{count}}` as a placeholder for the number (e.g. `({{count}} reviews)`) |

### Cart controls widget

| Field                              | Description                                             |
| ---------------------------------- | ------------------------------------------------------- |
| Remove (cart action)               | Text for the remove item action                         |
| Modify (cart action)               | Text for the modify item action                         |
| Variant (cart label)               | Label for the variant selector                          |
| Quantity (cart label)              | Label for the quantity selector                         |
| One time purchase (cart)           | Label for the one-time purchase option in cart controls |
| Subscription (cart label)          | Label for the subscription option                       |
| Discount calculating (cart status) | Status text shown while a discount is being calculated  |
| Retry (cart action link)           | Link text shown when a discount calculation fails       |

### Testimonials widget

| Field                    | Description                                   |
| ------------------------ | --------------------------------------------- |
| Read more (testimonials) | Text for the "Read more" link on testimonials |

***

## Blank field behavior

Saving a field as empty hides that label entirely for customers in that language. Every field arrives pre-filled with the bundled default, so a blank field is always something you cleared deliberately, and it always means "hide" — it never falls back to the default. To go back to the default wording, use **Reset defaults** rather than clearing the field. This is intentionally different from post-purchase translation behavior and is useful if you want to suppress a specific label for a given language.

***

## Need help?

If you have questions about checkout translations or need help configuring them, reach out through the in-app chat or by email.


# Checkout triggers
Source: https://docs.aftersell.com/aftersell/checkout_triggers

This article explains how to create and manage triggers and the underlying logic, so you can understand what customers will see.

Triggers enable you to segment your customers and display a customized set of widgets for each of them. By using triggers, you can design more precise and personalized widgets:

* [Products](#products)
* [Cart](#cart)
* [Discount](#discount)
* [Customer](#customer)
* [Advanced](#advanced)

  <img alt="Scrolling through the trigger condition categories in the Aftersell trigger picker" />

***

### **Products**

The Product Trigger works by displaying the widget only if the customer has purchased a specific product.

* Specific products:

  Use this option for individual products or variants. Select the products you want to trigger the widget. When a customer purchases any of these products, the widget will appear.

* Specific collections:

  This option works when any item in the cart belongs a specific collection. Select the collection you want to trigger the widget. When a customer purchases any item from the collection, the widget will appear.

  * You can set the product/collection trigger to show for all customers or conditionally based on the following criteria:

    1. Contains at least one of:

    Shows the widget if the cart contains at least one of the selected products/collections.

    2. Does not contain any of:

    Shows the widget if the cart does not contain any of the selected products/collections.

* Quantity of specific product:

  For example, 2 or more of a specific product

  Set the trigger to show the widget if a customer purchases two or more of a specific product.

* Product tag:

  Shows the widget if any product in the cart has one of the specified Shopify tags. Tag matching is case-insensitive.

  For example, set the trigger to include the tag `summer-collection` to show the widget only when a tagged product is in the cart.

* Product type:

  Shows the widget if any product in the cart belongs to one of the specified product types.

  For example, set the trigger to include `Apparel` to show the widget only when an apparel product is in the cart.

* Variant name:

  Shows the widget if any cart variant title matches one of the specified strings. Matching is case-insensitive.

  For example, set the trigger to include `Large` to show the widget only when a large-size variant is in the cart.

* Product metafield:

  Shows the widget if any product in the cart has a metafield (identified by namespace and key) whose value matches the specified condition (equals or contains).

  > **Note:** Metafield values are evaluated at the time the widget is displayed, not at order placement. If a customer removes the matching product and adds a different product after the widget loads, the widget may still appear.

* Variant metafield:

  Shows the widget if any variant in the cart has a metafield (identified by namespace and key) whose value matches the specified condition (equals or contains).

  > **Note:** Same evaluation timing applies as with product metafields above.

***

### **Cart**

* Subtotal:

  The combined value of all items before discounts, tax, and shipping.
* Quantity:

  The total number of items in the cart. You can set this trigger to show the widget when the cart quantity is greater than, less than, or exactly equal to a specified number.
* Subscription purchase:

  Indicates if any item in the cart is a subscription.
* Cart attribute:

  Shows the widget based on a cart-level attribute key and value (equals or contains). This is useful for targeting customers based on data set by other apps or integrations (for example, loyalty status set by a third-party app).

  > **Note:** Only one distinct cart attribute key can be used across all active checkout widgets. If another widget already uses a cart attribute trigger with a different key, you must use the same key or update the other widget. The same key can be reused across multiple widgets with different values.

***

### **Discount**

* Applied discount titles:

  Verify if a specific discount is applied during checkout
* Discount value:

  Track the total sum of discounts applied at checkout

***

### **Customer**

* Shipping country:

  Target specific shipping destinations

* Customer language:

  Display personalized content based on the customer's language.

  For example, show French content exclusively to French-speaking customers.

* Customer tags:

  Target specific customer tags.

* Device type:

  Target a specific device type — desktop or mobile.

  You can set the customer language trigger to "**is French**" and translate all editable fields in the widget to French.

***

### **Advanced**

* Group of triggers:

  Combine multiple triggers for complex logic

  For example, show a widget if a customer has both product X and product Y in their cart.

  You can set the product trigger condition to contain both product X and product Y, so the widget will appear accordingly.


# Checkout widget types
Source: https://docs.aftersell.com/aftersell/checkout_widget_types

This document covers various checkout widgets you can add with Aftersell to enhance your Shopify Plus checkout experience

There are a variety of checkout widget options to select from. In this article, we will walk through the different widget options, what they do, and available customizations:

* [Upsells](#upsells)
* [Cart Controls](#cart-controls)
* [Rewards](#rewards)
* [Trust Badges](#trust-badges)
* [Testimonials](#testimonials)
* [Notes](#notes)
* [Images](#images)
* [Text](#text)

<img alt="Aftersell Checkout editor showing widget cards for upsells, cart controls, rewards, trust badges, notes, images, and text" />

***

## Upsells

Offer products to your customers during checkout to **help increase your AOV.**

<img alt="Checkout order summary highlighting a Sticker Pack upsell offer with an Add button" />

Upsell Widgets have a few different configurations to select from.

* **Single Product Upsell:** Offer one product to your customer.
* **Multi-Product Upsell:** Show multiple products in either a stack or carousel layout. Allow customers to accept multiple offers.
* **Checkmark Upsell:** Upsell a single product with a checkbox instead of an Add to Cart button. This is commonly used for cheaper add-ons such as shipping protection or first in line shipping.

### Product selection options

When creating upsell offers, you can choose how products are selected:

* **Specific Products:** Manually select individual products to upsell.
* **Collection:** Select a collection and choose up to 5 random products from that collection to display. Products already in the cart are automatically excluded.
* **AI Recommendations:** Let Aftersell automatically recommend products based on the customer's cart contents.
* **Most Expensive Product:** Automatically upsell the most expensive product from the customer's cart.

When browsing the **Products** tab in the product picker, you can check **Active products only** to hide Draft and Archived products from the list. This filter is off by default and only applies to the Products tab — Collections are not affected.

<img alt="Checkout highlighting a Shipping Protection checkmark upsell with a Yes add to order checkbox" />

### Product types

When adding products to your upsell widget, you can choose from several product types:

* **Specific product** - Select a particular product from your store to display
* **Automatic upsell** - Recommends complementary products based on cart contents, using the recommendation provider set under **Settings > Automatic upsells** (Shopify by default, or Nosto or Constructor if you've connected one)
* **Most expensive product** - Shows the most expensive item from the customer's cart
* **Spend threshold** - Intelligently recommends products to help customers reach reward thresholds (requires rewards bar to be enabled)
* **Collection** - Display products from a specific collection
* **Strategy** - Dynamically select a product using rule-based targeting. Only shown on stores that have [Strategies](/aftersell/strategies_overview) enabled

The **spend threshold** product type works with your rewards bar to suggest products that help customers reach goals like free shipping or discounts. It automatically selects the most relevant product based on how close the customer is to the threshold.

### Variant name display

When a customer selects a variant for a checkout upsell product, the variant name appears as small subdued text below the product title. This helps customers confirm they are adding the correct variant to their order.

The variant name only appears when the product has multiple variants — it is hidden for single-variant products (those with only a "Default Title" variant).

### Subscription plan locking

* When you hide a variant option, customers won't see it in the checkout upsell.
* The default value you select is automatically applied to the product.
* Only variants matching your selected default values will be available to customers.
* If you hide multiple options, only variants matching all selected defaults will be shown. When creating upsells for subscription products, you can lock the upsell to a specific subscription plan. This prevents customers from changing the subscription plan at checkout, ensuring they receive the exact subscription option you've configured.

**How to configure subscription plan locking:**

1. Open your upsell widget in the Checkout editor.
2. Set the **Purchase option** to **Subscription**.
3. In the **Subscription plan** dropdown, select a specific plan instead of "Any plan (customer chooses)".
4. The plan is now locked - customers will see this plan at checkout but cannot change it.

**Customizing the locked plan display:**

* Hide the Color option and set the default to "Black"
* Keep the Size option visible
* Customers will only see size options for the black t-shirt

When a plan is locked, you can customize how it appears to customers at checkout:

* **Show subscription option on checkout** - Toggle whether the subscription option row (label + plan name) appears at checkout. Enabled by default.
* **Subscription option label** - Customize the label shown above the plan name (default: "Subscription"). For example, you might change this to "Subscribe", "Delivery", or another term that fits your brand.
* **Plan name** - Override the plan name displayed at checkout. By default, the plan name from Shopify is used.

**Upsell style settings**

These controls are not related to subscription locking. They live under **Show style settings** in the upsell editor, and the four image and card options below only appear once you tick **Try new look** (off by default).

* **Product image corner radius** - Apply rounded corners to product images. Choose from:
  * None - Square corners
  * Base - Slightly rounded corners
  * Large - More rounded corners (default)
  * Fully Rounded - Maximum rounding
* **Product image size** - Control image dimensions:
  * Default - Standard size (64px for vertical layouts)
  * Small - Smaller images (48px for vertical, taller aspect ratio for horizontal)
  * Medium - Medium images (72px for vertical, square aspect ratio for horizontal) (default)
  * Large - Larger images (96px for vertical, shorter aspect ratio for horizontal)
* **Product image display** - Choose how images fill their container:
  * Fill - Image stretches edge-to-edge (default)
  * Bordered - Adds a visible border around the image
* **Card padding** - Set inner spacing between the card edge and content:
  * None - No padding
  * Tight - Minimal spacing
  * Base - Standard spacing
  * Loose - Maximum spacing (default)
* **Button width style** - Control how the add-to-cart button width is displayed across upsells. Choose from:
  * Auto (default) - Button width varies based on whether variant selectors are present
  * Compact (uniform small) - All buttons use compact width for consistent sizing
  * Full width (uniform large) - All buttons use full width for consistent sizing

<Note>
  **Button width style** is shown for every upsell type except Checkmark, and is not behind **Try new look**.
</Note>

**Plans are automatically locked when:**

* You select a specific subscription plan (as described above)
* The product has only one subscription plan available

In both cases, customers cannot change the subscription plan at checkout.

### Upsell button text

For non-checkmark upsell widgets, you can customize the text displayed on the upsell buttons. These fields are available when the feature is enabled for your account — contact support to request access.

By default, the buttons show:

* **Add** for standard upsells
* **Upgrade • \$X savings** for replacement upsells where the customer saves money
* **Upgrade • \$X** for replacement upsells where the product costs more

#### Upsell button text

You can customize the text on the add button for standard and replacement upsells. When you enter custom text, the savings or cost suffix is still appended automatically for replacement offers (e.g. `Buy Now • $5 savings`).

#### Replacement button text

You can set a separate custom prefix for the button on replacement offers. This overrides both the default "Upgrade" prefix and any text entered in the **Add button text** field for replacement offers. The price suffix (e.g. `• $5.00 savings`) is always appended automatically.

For example, entering `Trade up` produces `Trade up • $5.00 savings` on a replacement offer where the customer saves \$5.

> 💡 **Tip:** The `{Amount}` placeholder is not substituted in the replacement button text field — it is treated as literal text. Use the **Upsell button text** field with `{Amount}` if you need full control over the label format.

#### Using the `{Amount}` placeholder

You can include `{Amount}` in the **Upsell button text** field to embed the price or savings amount directly in your label. When `{Amount}` is present, your text becomes the entire button label — the automatic suffix is not appended.

| Button text                  | Offer type               | Result                 |
| ---------------------------- | ------------------------ | ---------------------- |
| `Save {Amount} by upgrading` | Replacement (savings)    | `Save $5 by upgrading` |
| `Upgrade for {Amount} more`  | Replacement (extra cost) | `Upgrade for $5 more`  |
| `Get yours for {Amount}`     | Standard upsell          | `Get yours for $10`    |

The placeholder is case-insensitive — `{Amount}`, `{amount}`, and `{AMOUNT}` all work.

> ⚠️ **Note:** If you use `{Amount}` in a standard (non-replacement) upsell, the product price is substituted. The placeholder is always replaced with a formatted amount, so a free product renders the formatted zero (for example `\$0.00`) rather than dropping the placeholder.

### Max accepted offers

For **Single Product Upsell** and **Multi-Product Upsell** widgets, you can set a limit on how many offers a customer can accept from a single widget during a checkout session.

Once a customer has accepted the configured number of offers, the widget stops showing additional offers for the remainder of that checkout session.

* **Leave blank** — No limit is applied. The widget continues to show offers regardless of how many the customer has accepted.
* **Set a positive number** — The widget stops displaying offers once the customer has accepted that many from this widget.

To configure this setting, open your upsell widget in the Checkout editor and enter a value in the **Max number of accepted offers** field.

> 💡 **Tip:** This setting is not available for Checkmark Upsell widgets.

***

### Discounts

Discounts can be **configured directly within the upsell widget**. This discount automatically gets applied when the customer selects to add the upsell product to their order.

#### Adding a discount to your upsell

When configuring an upsell widget, you can add a discount by clicking the **"Add discount"** button. You'll see two options:

* **Pick existing** - Select from discounts you've already created. You can search through your existing discounts to find the one you want to apply.
* **Create new** - Create a new discount directly in the editor by setting:
  * **Title** - The discount code text shown to customers in checkout (e.g., "SAVE")
  * **Amount** - Choose between a percentage discount or a fixed amount discount, then enter the value

Once a discount is applied to your upsell, it appears as a badge that you can click to change or remove.

You can manage all your checkout discounts in one place. See [Managing checkout discounts](/aftersell/managing_checkout_discounts) to learn how to view, edit, and delete discounts.

#### Hiding the discount amount text

When a discount is applied to your upsell, a savings suffix (e.g. "(20% OFF)" or "(\$6 OFF)") appears next to the product title by default. You can hide this suffix by enabling **Hide discount amount text** in the **Show additional settings** section of the upsell editor.

* When enabled, the savings suffix is hidden. The discounted price itself still displays normally.
* When disabled (default), the savings suffix appears next to the product title.

> 💡 **Tip:** This setting is per-widget. If you have multiple upsell widgets, you can configure each one independently.

#### Customizing the discount suffix label

The "OFF" text in the savings suffix (e.g. "20% OFF") can be customized in **Settings > Translations**. Look for the **Discount suffix** row and enter your preferred label (e.g. "saved", "off", or a translated equivalent). The default value is "OFF".

#### Showing the discounted price when the Aftersell discount is skipped

When **Skip upsell discount if a non-Aftersell discount is already applied?** is enabled, the widget hides the configured upsell discount from the preview price by default. If your cart-level discount already matches your upsell discount (so the customer pays the same discounted price regardless), you can enable **Show the discounted price in the widget even when the AfterSell discount is skipped?** to keep the preview price in sync with what the customer will actually be charged.

> ⚠️ **Important:** This setting changes the displayed price in the widget for both preview and live customers, but does not apply an Aftersell discount. Only enable this if your cart-level discount matches your upsell discount exactly — otherwise customers may see an incorrect price.

This checkbox is only visible when **Skip upsell discount if a non-Aftersell discount is already applied?** is already turned on.

#### Limiting how many units get the discount

By default, a discount applies to every unit of an accepted upsell product — including any additional units a customer adds using the quantity selector or Cart Controls. You can cap this with the **Limit how many units get the discount** toggle.

When enabled, a **Maximum discounted quantity** field appears where you set the cap. Units up to the cap receive the discount; any additional units are charged at full price.

**Example:** You offer a product with a 100% discount and set the cap to 1. If a customer raises the quantity to 3, only 1 unit is free — the other 2 are charged at full price.

* **Toggle off (default):** Every unit of the accepted upsell product is discounted.
* **Toggle on:** Only the number of units you specify receive the discount. Extra units are charged full price.

> 💡 **Tip:** This setting is useful when you want to offer a strong discount (such as a free item) without allowing customers to multiply the savings by increasing the quantity.

#### How discounts work

* Aftersell discounts follow the same rules as any other Shopify discount. For two discounts to combine, both must be explicitly set to combine in Shopify Admin. For example, if Aftersell creates a discount code and you also have a separate discount like "10% off", both need combination enabled. If either one is not set to combine, they will not combine. Shopify's standard discounting rules apply throughout:
  * Shopify only allows one line-item discount per product at a time. If a product already has a discount applied, an additional upsell discount will not stack on the same line item
  * Order-level and line-item discounts can combine if both are set to "combinable" in Shopify Admin For full details on Shopify's combination rules, refer to [Shopify's discount combination documentation](https://help.shopify.com/en/manual/discounts/combining-discounts/discount-combinations). **Important limitations** There are a few scenarios where discounts may fail to apply:
  * **Multiple discounts on the same product:** If an Aftersell upsell discount is configured for a product that already has a discount applied, the Aftersell discount will not stack
  * **Incorrect collection setup:** If discounts target collections, ensure all relevant products belong to the correct collection. Hidden collections can be used to include specific products without making them visible to customers
  * **Third-party app conflicts:** Checkout discount functionality is not currently supported when another app is dynamically modifying your checkout. If you are running an app that does this, discounts added by Aftersell may not apply as expected.
    For example, if an app adds pricing or add-ons at checkout and recalculates the order total, this can interfere with how Aftersell applies discounts.

***

## Upsell Review Stars

Checkout upsells can display star ratings on offer products to help increase conversions. Ratings are pulled from your product review app's metafields and only appear when valid review data exists for the product.

* Please note that this is currently available on Aftersell's Checkout version 2 and not version 1, due to api limitations.

**How to enable**

* Open **Checkout** and edit the upsell.
* Enable **Show product review ratings**.
* *(Optional)* Open **Advanced product review settings** to customize the display.

**Advanced settings**

* Set a **minimum rating** to display (0-5, default 4.0).
* Choose where stars appear (**below title** or **below price**).
* Customize **filled and unfilled star colors**.
* Show or hide the **numeric rating** and **review count**.

<img alt="Advanced product review rating settings with minimum rating, position, and star color fields" />

**Supported review apps**\
We support review apps that store ratings in product metafields, including:

* Shopify Product Reviews
* Junip
* Okendo
* Growave
* Fera
* Stamped
* Loox
* REVIEWS.io
* Automizely Reviews
* Judge.me
* Ali Reviews
* Trustoo
* Rivo
* Rivyo
* Vitals

Ratings won't display for products without review data. If multiple supported review apps are installed, the app with the highest review count is used. Yotpo isn't supported for Checkout V2 upsell ratings because it requires a separate API.

### Troubleshooting: reviews show in editor but not on live checkout

If you enable **Show product review ratings** and see stars in the editor preview but not on your live checkout, your review app's metafields may not have Storefront API access enabled.

The editor reads product data through the Admin API (which can access all metafields), while live checkout reads through the Storefront API (which only accesses metafields that have been explicitly granted storefront access). When this mismatch is detected, a warning banner appears in the editor listing the affected products.

**To fix this:**

1. Go to **Settings → Custom data → Products → Metafields** in your Shopify Admin.
2. Find the `reviews.rating` and `reviews.rating_count` metafield definitions.
3. Enable **Storefront API access** for each definition.

Alternatively, check your review app's settings for a **Storefront API sync** option and enable it there.

***

## Cart Controls

Surface a modify link below every product line item to allow editing directly on the checkout page.

The following functionality is supported for cart controls:

* Variant selector: Allow customers to change to another in-stock variant.
* Quantity selector: Allow customers to change the quantity of a product.
* Remove item: Allow customers to remove upsell products. Turning on **Show Remove Item Button** reveals **Allow Removal of Non-Upsell Products**, which extends removal to the items the customer originally added.
* Subscription selector: Allow customers to change the currently selected subscription option (e.g. from every 60 days to every 30 days).
* Subscription upgrade: Allow customers to upgrade a one time purchase to a subscription.
* Custom text: Add custom text below each line item.

<img alt="Checkout cart item with a Modify link and an Upgrade to Subscribe and save button highlighted" />

### Product review ratings

Cart controls can display star ratings for in-cart products to help build trust and increase conversions. Ratings are pulled from your product review app's metafields and only appear when valid review data exists for the product.

**How to enable**

1. Open **Checkout** and edit the cart controls widget.
2. Navigate to the **Product review ratings** section.
3. Enable **Show product review ratings**.
4. *(Optional)* Customize the display settings.

**Settings**

* Set a **minimum rating** to display (0-5, default 4.0). Products below this rating won't show stars.
* Choose where stars appear (**below product title** or **below cart controls**).
* Customize **filled star color** (default: #fdcc0d) and **unfilled star color** (default: #d1d5db).
* Show or hide the **rating value** (e.g., 4.5) and **review count** (e.g., 123 reviews).

**Supported review apps**\
We support review apps that store ratings in product metafields, including:

* Shopify Product Reviews
* Junip
* Okendo
* Growave
* Fera
* Stamped
* Loox
* REVIEWS.io
* Automizely Reviews
* Judge.me
* Ali Reviews
* Trustoo
* Rivo
* Rivyo
* Vitals

Ratings won't display for products without review data. If multiple supported review apps are installed, the app with the highest review count is used.

### Subscription products

The **Subscription products** section inside **Subscription management** lets you control which subscription plans are available to shoppers for specific products in the cart controls widget.

By default, the subscription selector and upgrade button use whichever plans Shopify returns for a product. With per-product subscription plan controls, you can narrow the selectable plans and set a default plan for each product.

**How to configure subscription plan controls:**

1. Open your cart controls widget in the Checkout editor.
2. Expand the **Subscription management** section.
3. Under **Subscription products**, select **Add product** and pick a product that has selling plans configured in Shopify.
4. Open the product's row and use **Plans customers can choose** — select **Select plans** to open the picker, then tick the plans shoppers may select. Chosen plans appear as removable tags, and there's a **Select all** action.
5. Use the **Default plan** dropdown to set which plan the subscription upgrade applies for that product. Its own default is **First available plan**.
6. Save your changes.

<Note>
  **Subscription products** is a heading, not a collapsible panel — the section that expands is **Subscription management**. Until you add a product it reads "No products added yet", and the per-product controls in steps 4 and 5 only appear once a product row exists.
</Note>

**How it works:**

* **Plans customers can choose** — Narrows the subscription selector to only the plans you tick. If a product variant supports none of them, all of that variant's own plans are shown instead, so shoppers are never left without a subscription option.
* **Default plan** — Sets the plan the subscription upgrade applies for that product. If it isn't compatible with the variant in the cart, the first selectable plan is used instead.
* **Unconfigured products** — Products without a row here keep all their plans and use Shopify's default ordering.

The subscription upgrade button itself is controlled separately, higher up in **Subscription management**: tick **Allow Subscription Upgrade Button** to enable it. Doing so reveals a text field for the button's wording, which defaults to `Upgrade to {{subscription_group}}` — the variable is replaced with the first subscription group available for the product.

> 💡 **Tip:** If you select all available plans for a product, the configuration normalises back to "every plan." This means any new plans you add in Shopify later are automatically included, rather than being silently excluded.

### Product targeting

You can control which products display cart controls using the **Visibility** settings in the cart controls widget editor:

* **All products in cart:** Cart controls appear for every product (default).
* **Only selected products:** Cart controls appear only for products you select. Click **Select products** to choose which products should display cart controls.
* **All products except selected:** Cart controls appear for all products except those you select. Click **Select products** to choose which products should not display cart controls.

This allows you to customize the checkout experience based on specific products. For example, you might want to enable subscription upgrades only for certain products, or prevent customers from removing specific items from their cart.

**How to configure product targeting:**

1. Open your cart controls widget in the Checkout editor.
2. Navigate to the **Visibility** section.
3. Select your preferred targeting mode from the **Apply cart controls to** dropdown.
4. If you selected **Only selected products** or **All products except selected**, click the **Select products** button to choose your products.
5. Save your changes.

***

## Rewards

Show a reward bar (spend X get Y) in your checkout to incentive adding more products. This goal can either be based on Order Value or Item Count.

**Rewards work well alongside the upsell widget.** Make it easy for a customer to add an extra product to their order to achieve the reward. You can use the **spend threshold** product type in your upsell widget to automatically recommend products that help customers reach the reward threshold.

<img alt="Checkout rewards bar showing progress toward free shipping highlighted above the cart" />

**Keep in mind**, any rewards you're offering will need to be created through Shopify. This can be done by creating Automatic Discounts if you are offering a discount, or by modifying your Shipping Rules if you are offering free shipping.

### Amount basis

When configuring a reward based on Order Value, you can choose how the cart total is calculated using the **Amount basis** setting:

* **Order total** — Uses the full order total, including shipping and taxes.
* **Subtotal** — Uses the pre-discount merchandise subtotal (before any discount codes are applied).
* **Subtotal after discounts (excludes tax and shipping)** — Uses the cart total after discounts, shipping, and taxes are subtracted. This matches how Shopify evaluates free-shipping thresholds, so the reward bar accurately reflects whether the customer has truly reached the threshold when a discount code is applied.

> 💡 **Tip:** If you offer free shipping as a reward, use **Subtotal after discounts (excludes tax and shipping)** to ensure the bar matches Shopify's own free-shipping evaluation. With other bases, a discount code can cause the bar to show "unlocked" while Shopify still charges shipping.

***

## Trust Badges

Build trust badges with custom icons and text in order to increase checkout conversion rate. The badges can be stacked vertically, or displayed horizontally.

<img alt="Checkout trust badges for Secure Payments, 30-Day Guarantee, and Fast Shipping with icons" />

Trust badges are great for building a **sense of trust** with your brand and highlighting your value proposition, which can help **lower your abandoned checkout rate.**

***

## Testimonials

Display customer reviews directly on checkout to build trust and lower your abandoned checkout rate.

<img alt="Checkout testimonial with a five-star customer review quote highlighted below the total" />

### Testimonials modes

Aftersell offers two types of testimonials widgets:

* **Classic Testimonials** - Testimonials you write yourself. Still available; Flex Testimonials is the newer option that pulls real reviews from your review app.
* **Flex Testimonials** - Automatically pulls customer reviews from your review app (Judge.me, Klaviyo, Okendo, or Yotpo). This is the recommended option for all merchants.

### Switching from Classic to Flex Testimonials

If you're using Classic Testimonials, you should switch to Flex Testimonials to display reviews from your review app:

1. Open **Checkout** in Aftersell
2. Navigate to the **Classic Testimonials** widget tab
3. Click **Switch to review app widget** in the banner at the top
4. Configure your review app credentials in **Settings > Product Reviews** (see [Review app integrations](#review-app-integrations) below)

You can switch back at any time by clicking **Switch back to manually written reviews** on the banner shown while Flex Testimonials is active.

<img alt="Aftersell banner prompting to switch to the review app widget for real customer reviews" />

### Flex Testimonials configuration

Flex Testimonials offers two selection modes:

* **Manual selection** - Choose specific reviews to display in your testimonials widget
* **Dynamic** - Automatically fetch and display reviews based on products in the customer's cart

#### Dynamic mode

In dynamic mode, Aftersell imports reviews from your review app and stores them so they can be displayed in the checkout widget. The first import happens automatically within 24 hours, and then once a week after that.

To import reviews immediately, go to **Settings > Product Reviews** and click **Sync now** for your review app.

You can configure:

* **Max reviews to show** - Control how many reviews appear, from 1 to 3
* **Display type** - Choose between horizontal carousel or vertical stack layout
* **Minimum rating** - Set the minimum star rating for reviews to display
* **Truncate review text after (optional)** - Set a maximum character length for review text. When a review exceeds this limit, it's clipped with an ellipsis and a "Read more" button appears. Clicking "Read more" opens a popover with the full review. Leave blank for no limit (default).

### Review app integrations

To use Flex Testimonials, you need to configure your review app credentials in **Settings > Product Reviews**. Aftersell supports:

* **Judge.me** - Requires your Private API token
* **Klaviyo** - Requires your private API key
* **Okendo** - Requires your User ID
* **Yotpo** - Requires your App Key

See the following guides for setup instructions:

* [Judge.me integration](/aftersell/judgeme_reviews_integration)
* [Klaviyo integration](/aftersell/klaviyo_reviews_integration)
* [Okendo integration](/aftersell/okendo_reviews_integration)
* [Yotpo integration](/aftersell/aftersell_yotpo_reviews_integration)

***

## Notes

Allows your customer to add notes to their order. These notes can either be written manually by the customer, or be pre-written notes. Pre-written notes are excellent when your store offers gift wrapping or eco packaging, and you want to give your customers an easy way to opt-in.

***

## Images

Upload a custom image which can be inserted in the checkout.

***

## Text

Insert a banner in your checkout with the text of your choice.

Choose between **four different styles** for the text widget.

* **Information:** A blue background with a blue information icon.
* **Success:** A green background with a green checkmark icon.
* **Critical:** A red background with a red exclamation point icon.
* **Warning:** A yellow background with a yellow warning triangle icon.


# Compare at price not reflecting for checkout upsells (Shopify Plus)
Source: https://docs.aftersell.com/aftersell/compare_at_price_not_reflecting_for_checkout_upsells_shopify_plus

This article outlines the troubleshooting steps to follow when compare-at prices are not displaying correctly for checkout upsells.

If product discounts aren’t appearing at checkout even though checkout upsells are published, this may be related to how **compare-at prices** display in Shopify for EEA (European Economic Area) stores.

## Why This Happens

Shopify automatically uses the **compare-at price** feature to meet the **European Price Indication Directive (PID)**. When enabled, Shopify shows the lowest price in the past 30 days instead of an active discount. You can read [Shopify's documentation](https://help.shopify.com/en/manual/compliance/legal/pricing-indication-directive) for more details.

## How to Fix

If your primary market is in the EEA:

1. Go to **Products** in your Shopify admin.
2. Open the product.
3. Under **Pricing**, set the **Compare-at price** to the lowest price in the last 30 days or more.
4. Set the **Price** to your new sale price.
5. Click **Save**.

**Note:** The **Compare-at price** must be higher than the **Price** to display a discount.

If your store’s primary market isn’t in the EEA:

1. Go to **Settings** > **Markets** in Shopify.
2. Click **Preferences**.
3. Deselect **Hide compare-at prices for EEA customers**.
4. Click **Save**.

If the issue continues after adjusting these settings, clear your browser cache and test again. If it persists, contact **Aftersell Support** for further assistance.


# Configuring Shopify web pixels
Source: https://docs.aftersell.com/aftersell/configuring_shopify_web_pixels

Setting up conversion tracking using Web Pixels with post-purchase upsells

[Shopify Web Pixels](https://help.shopify.com/en/manual/promoting-marketing/pixels) are Shopify's solution for tracking data on purchases such as conversion rates. There are two primary ways you will interact with them:

* App Web Pixels
* Custom Web Pixels

# App Web Pixels

Some app pixels, (e.g. Omega Facebook Pixel) integrate directly with Shopify Web Pixels. These apps require no further setup to work with Aftersell.

# Custom Web Pixels

Custom pixels allow for bespoke solutions if no app pixel can be found on the Shopify marketplace to meet your needs. The following details how to convert existing order status page tracking scripts to use custom pixels. Please note the [potential risks of custom pixels](https://help.shopify.com/en/manual/promoting-marketing/pixels/overview#potential-risks) before proceeding.

If you use Google Tag Manager specifically, then Shopify provides [helpful documentation for completing this migration](https://help.shopify.com/en/manual/promoting-marketing/pixels/custom-pixels/gtm-tutorial).

There are 3 core steps to creating a custom pixel for conversion tracking.

1. Preparing the 3rd party JavaScript SDK
2. Setting up conversion tracking using web pixels
3. Connecting your custom pixel

## 1. Preparing the 3rd party JavaScript SDK

You will want to remove any HTML present in the provided pixel code. Any JavaScript that is loaded through an HTML `<script>` tag should instead be loaded through a JavaScript-only approach.

This process is covered in more detail [here](https://help.shopify.com/en/manual/promoting-marketing/pixels/custom-pixels/code#third-party-sdk).

An example using Google Tag Manager

*Original pixel code:*

```
<!-- Global site tag (gtag.js) - Google Analytics -->  
<script async src="https://www.googletagmanager.com/gtag/js?id=YOUR_PIXEL_ID"></script>  
<script>  
  window.dataLayer = window.dataLayer || [];  
  function gtag(){dataLayer.push(arguments);}  
  gtag('js', new Date());  
  gtag('config', ''YOUR_PIXEL_ID'');  
</script>
```

*After removing HTML & reworking `<script>` tags:*

```
const script = document.createElement('script');  
script.setAttribute('src', 'https://www.googletagmanager.com/gtag/js?id=YOUR_PIXEL_ID');  
script.setAttribute('async', '');  
document.head.appendChild(script);  
  
window.dataLayer = window.dataLayer || [];  
function gtag(){dataLayer.push(arguments);}  
gtag('js', new Date());  
gtag('config', 'YOUR_PIXEL_ID');
```

Note that Google's pixel SDK doesn't automatically transmit data from a Shopify custom pixel. To transmit data, you need to subscribe to events.

## 2. Setting up conversion tracking using web pixels

To track conversion using custom pixels, subscribe to the `checkout_completed` event provided by Shopify. This event is triggered either on the post-purchase page, if one is displayed to your customer, or on the thank you page if not. This event only triggers once in either case, so no extra logic is required to avoid double-counting a purchase.

```
analytics.subscribe("checkout_completed", (event) => {  
  // process event using 3rd party pixel tracking code  
});
```

Use this reference to see which data points you can retrieve from the `event`.

[Shopify checkout\_completed event](https://shopify.dev/docs/api/web-pixels-api/standard-events/checkout_completed)

An example of a custom Meta pixel

*Tracking code triggering when a checkout is completed:*

```
!function(f,b,e,v,n,t,s)  
{if(f.fbq)return;n=f.fbq=function(){n.callMethod?  
n.callMethod.apply(n,arguments):n.queue.push(arguments)};  
if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';  
n.queue=[];t=b.createElement(e);t.async=!0;  
t.src=v;s=b.getElementsByTagName(e)[0];  
s.parentNode.insertBefore(t,s)}(window, document,'script',  
'https://connect.facebook.net/en_US/fbevents.js');  
  
// replace YOUR_PIXEL_ID with the pixel ID provided by third-party  
fbq('init', YOUR_PIXEL_ID);  
  
analytics.subscribe("checkout_completed", (event) => {  
  fbq('track', 'Purchase', {  
    currency: event.data?.checkout?.currencyCode,  
    value: event.data?.checkout?.totalPrice?.amount,  
  });  
});
```

## 3. Connecting your custom pixel

Before you add a custom pixel, remove or modify any existing pixels to ensure customer events aren't counted twice. Existing pixel code should be manually removed from any place it exists, such as `theme.liquid`, `checkout.liquid` (Plus merchants only), and the Additional scripts in your checkout settings.

Once that is done, follow these steps to connect a custom pixel to your store.

1. Navigate to Settings > Customer Events > Custom Pixels > Add Custom Pixel

   1. Enter a name for your custom pixel.
2. Paste your custom pixel code in the "Code" section.
3. Ensure the customer privacy settings are properly configured.
4. Click "Save" on your custom pixel.
5. Click "Connect" to set your custom pixel live!


# Conversion tracking (web pixels)
Source: https://docs.aftersell.com/aftersell/conversion_tracking_web_pixels

Pixels, conversion tracking, customer events, and how they are affected by Aftersell

# Shopify Web Pixels

Shopify recommends using [Web Pixels](https://help.shopify.com/en/manual/promoting-marketing/pixels) for conversion tracking and will deprecate other methods of conversion tracking in the future. Shopify Web Pixels are tools that collect and leverage customer behavior data, enabling better targeted marketing campaigns and comprehensive analytics. These pixels can be added using Shopify’s Customer Events API, allowing third-party applications like Aftersell to build seamless integrations for data collection and tracking purposes.

Aftersell automatically works with Web Pixels. **If you are already using Web Pixels, you do not need to make any changes.** Conversion tracking will not be affected by post-purchase upsells. Aftersell does not require its own web pixel to be enabled in Shopify’s system as it seamlessly integrates with Shopify Web Pixels for tracking post-purchase upsells and conversions.

**If you are not using Web Pixels, you must switch your existing conversion tracking scripts to Web Pixels** to work with post-purchase upsells. To do so, [please follow this guide](/aftersell/configuring_shopify_web_pixels). If you do not use Web Pixels, then your conversion tracking accuracy will be decreased due to missed conversions from customers that close their browser tab on the post-purchase page and never reach the thank-you page. Additionally, the Facebook & Instagram app, also known as the Meta Pixel, operates independently from Shopify Web Pixels when using the "Maximum" data sharing setting. For specific questions on Meta app’s behavior with Web Pixels, contacting Shopify support is recommended.

If you are using Elevar, you can follow the documentation on the [Elevar website here](https://docs.getelevar.com/docs/how-to-update-my-post-purchase-tracking-to-the-latest-recommendation). For more questions about configuring Shopify Web Pixels, consult the [Configuring Shopify Web Pixels guide](/aftersell/configuring_shopify_web_pixels).

FAQ

# Does Aftersell Provide Its Own Web Pixel?

Not for post-purchase upsell tracking. Aftersell integrates with Shopify's Web Pixel infrastructure automatically there, so no pixel needs enabling and no configuration is required.

There is one exception. Stores that go through the **Rokt Ads** onboarding grant Aftersell the customer-events and pixel scopes, and Aftersell then installs an app web pixel for them. On those stores an **Aftersell** entry appears under **App pixels** in Shopify's Customer events settings — see [Web pixel activation](/aftersell/dtc_ads_onboarding_guide_web_pixel_activation).

# How Does the Facebook & Instagram App Interact with Shopify Web Pixels?

The Facebook & Instagram app, also known as the Meta Pixel, operates independently from Shopify Web Pixels when using the "Maximum" data sharing setting. For detailed information about Meta app behavior in relation to post-purchase activities, reaching out to Shopify Support is advised.

### I've previously used a solution suggested by the Aftersell team to deal with conversion tracking pixels in the past, will this still work?

These solutions will still work, but we recommend switching to Shopify Web Pixels. Shopify will eventually deprecate other forms of conversion tracking. Switching to Web Pixels will future-proof your analytics.

### Can I track additional products added through post-purchase upsells?

Shopify Web Pixels do not support tracking additional products from post-purchase upsells. The `checkout_completed` event is triggered instantly once the post-purchase loads to ensure the data can be tracked even if the customer closes the page immediately. This means any upsell items added to the order through post-purchase upsells will not be included in the event data.


# Creating an unpublished automated collection
Source: https://docs.aftersell.com/aftersell/creating_an_unpublished_automated_collection

This article explains how to create an unpublished automated collection.

Many features in Aftersell utilize collections, such as funnel triggers and exclusions for automatic upsells. To improve targeting and provide greater control for these features, you can create unpublished automated collections. Automated collections allow you to select products based on specific criteria, including price, weight, tags, and more.

An unpublished collection is not visible on any of your sales channels, meaning it will not be displayed to customers anywhere; it is intended for internal use only.

***

## How to create an unpublished automated collection

1. Navigate to your Shopify admin, then go to `Products > Collections`, and click on "**Create New Collection.**"
2. Select Conditions

   <img alt="Shopify Smart collection type selected with a Price is less than condition" />
3. Unpublish from sales channels

   <img alt="Manage sales channels dialog with all channels unchecked to unpublish the collection" />

***

## Best practices

We recommend using a descriptive name for your unpublished automated collections to help you easily locate them within Aftersell and allow other team members to differentiate them. Here are some examples of suggested collection names:

* Aftersell Exclude "Test"
* Aftersell Exclude Below \$5
* Aftersell Trigger Vendor XYZ
* Aftersell Trigger Above 3kg

Please note that the name does not affect Aftersell's functionality; it is intended solely for organizational purposes.

***


# Creating your first checkout widget
Source: https://docs.aftersell.com/aftersell/creating_your_first_checkout_widget

Guide through setting up a checkout widget in Aftersell, from selecting and creating the widget to customizing its style and behavior.

In this article, we'll walk you through the process of setting up a checkout widget in Aftersell. To learn about the different widget types that are available, [click here](/aftersell/checkout_widget_types).

Let's get started.

***

## Step 1: Selecting your widget

First things first, select the widget that aligns with your needs. Whether it's an upsell or testimonial widget, Aftersell offers a range of choices to cater to your preferences.

In this tutorial, we are going to select the upsell widget.

<img alt="Aftersell Checkout page showing widget cards for Upsells, Cart Controls, Rewards, and Testimonials" />

***

## Step 2: Creating your widget

Click "Create Upsell" to start building out your upsell widget.

<img alt="Checkout Editor Upsells panel with an arrow pointing to the Create upsell button" />

***

## Step 3: Selecting a preset

Choose from a list of optimized widget presets or opt to start from scratch.

<img alt="Create new campaign screen with preset options like single and multi product upsells" />

***

## Step 4: Edit styling and behaviour

It's time to fine-tune the details. Adjust the styling and behavior of your widget to perfection. Tweak the triggering logic, refine the product selection, or add that final touch of polish to the design.

<img alt="Single product upsell editor showing trigger, product, and styling settings with live preview" />

***

## Step 5: Enable widget status

Ensure your widget status is set to active.

<img alt="Checkout Editor with the upsell Status toggle switched on to activate the widget" />

With your checkout widget now live in Aftersell, the final step awaits, placing the widget into your Shopify checkout. Looking to learn how? Click below to dive deeper into the process.

[Learn More](/aftersell/adding_a_checkout_widget_to_your_shopify_checkout)


# Custom web SDK integration for Rokt Thanks
Source: https://docs.aftersell.com/aftersell/custom_web_sdk_integration_for_rokt_thanks

This article is for brands that do not use Shopify Checkout but still want to take advantage of Aftersell’s Rokt Thanks offers.

Overview

If your store uses a **custom checkout flow**, you can still access Rokt Thanks offers by installing the **Rokt Web SDK** (a small JavaScript snippet).

Installing the SDK is typically straightforward and requires minimal technical expertise. If needed, the Aftersell technical support team can assist you throughout the process.

***

## Initial Questions

Before you begin, answer the following questions to ensure a smooth integration:

1. **Can you (or someone on your engineering team) add a code snippet to the confirmation page?**\
   The confirmation page, also known as the **thank-you page**, appears immediately after checkout.
2. **What user data or properties are available on the confirmation page?**\
   We’ll need access to [specific properties](https://www.notion.so/rokt/Custom-Web-SDK-integration-for-Rokt-Thanks-306ee2db8608815899eadad3811b5ff3) related to purchased items and customer information. The more data that is available, the more relevant and accurate your Rokt Thanks offers will be.
3. **Is there an easy way to access this data using JavaScript?**\
   For example, can you query the cart or order details on the confirmation page?

***

## Implementation Steps

## Step 1: Review and Confirm

* Review the questions above and confirm which data properties can be accessed.
* Once ready to proceed, you’ll need an **accountId**, which will be provided by an Aftersell engineer.

To create your account, please provide the following details:

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{  
  "firstName": "",  
  "lastName": "",  
  "primaryEmail": "",  
  "websiteUrl": "",  
  "countryCode": "",  
  "brand": ""  
}
```

***

## Step 2: Choose Installation Method

Decide whether you’d like to:

* **Install the integration yourself**, or
* **Work directly with an Aftersell engineer** (a testing environment may be required for assisted setup).

If you choose to install it yourself, you can follow [**Rokt’s documentation**](https://docs.rokt.com/developers/integration-guides/getting-started/?layer1=siteMonetization) or the summarized steps below.\
Not all steps in Rokt’s setup guide are required, but the guide is provided as a reference.

***

## Step 3: Install the Integration Script

a. **Copy the [starter integration script](#)**(provided below).

b. **Add the script** between the `<head></head>` tags of any page where you want to display a Rokt Thanks offer (typically your order confirmation page).

i. Populate all required **customer and transactional data properties**.

ii. Replace `"rokt_account_id_here"` with the **accountId** provided by your Aftersell engineer.

c. **Test your implementation** using [Rokt’s testing guide](https://docs.rokt.com/developers/integration-guides/web/testing) to ensure placements load correctly.

d. Work with our team to customize the placement so it matches your brand's look and feel.

## Properties (***Bolded and Italicized*** properties are highly recommended)

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const cartItems = [  
        {  
            'itemPrice': '',  
            'itemQuantity': '',  
            'majorcat': '',  
            'majorcatid': '',  
            'minorcat': '',  
            'minorcatid': '',  
            'productname': '',  
            'sku': '',  
        },  
        {  
        ...  
        }  
]
```

Customer/order properties

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{  
        attributes: {  
          
	        // Required  
	        amount: '', //In $  
	        firstname: '',  
	        lastname: '',  
	        billingzipcode: '',  
	        Country: '',  
	        Language: '',  
	        currency: '',  
	        cartItems: JSON.stringify(cartItems), //From above  
	        email: '',  
	  
	        //Order Data  
	        clientcustomerid: '',  
	        cartId: '',  
	        subtotal: '',  
	        totalTax: '',  
	        totalShipping: '',  
	        margin: '',  
	        paymenttype: '',  
	        ccbin: '',  
	  
	        //Customer Data  
	        customerType: '',  
	        hasAccount: '',  
	        isReturning: '',  
	        lastVisited: '',  
	        isLoyalty: '',  
	        loyaltyTier: '',  
	        mobile: '',  
	        title: '',  
	        age: '',  
	        gender: '',  
	        dob: '',  
	        billingAddress1: '',  
	        billingAddress2: '',  
	        billingCity: '',  
	        billingState: '',  
	        billingCountry: '',  
	        shippingAddress1: '',  
	        shippingAddress2: '',  
	        shippingCity: '',  
	        shippingState: '',  
	        shippingZipcode: '',  
	        shippingCountry: '',  
  
        },
```

## Starter Script

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<!-- Main Tag -->  
<script type="module">  
    const target = document.head || document.body;  
    const script = document.createElement("script");  
    script.type = "text/javascript";  
    script.src = "https://apps.rokt.com/wsdk/integrations/launcher.js";  
    script.fetchpriority = "high";  
    script.crossOrigin = "anonymous";  
    script.async = true;  
    script.id = "rokt-launcher";  
    target.appendChild(script);  
    await new Promise((resolve) =>  
        window.Rokt  
        ? resolve()  
        : document  
            .getElementById("rokt-launcher")  
            .addEventListener("load", () => resolve())  
    );  
  
    const launcher = await window.Rokt.createLauncher({   
        accountId:'rokt_account_id_here',  
        sandbox: true,  
    });  
      
    const cartItems = [  
        {  
            'itemPrice': '',  
            'itemQuantity': '',  
            'majorcat': '',  
            'majorcatid': '',  
            'minorcat': '',  
            'minorcatid': '',  
            'productname': '',  
            'sku': '',  
        },  
        {  
            'itemPrice': '',  
            'itemQuantity': '',  
            'majorcat': '',  
            'majorcatid': '',  
            'minorcat': '',  
            'minorcatid': '',  
            'productname': '',  
            'sku': '',  
        }  
    ];   
  
    const selection = await launcher.selectPlacements({  
        identifier: 'order_confirmation_page_identifier',  
        attributes: {  
          
        // Required  
        amount: '',  
        firstname: '',  
        lastname: '',  
        billingzipcode: '',  
        Country: '',  
        Language: '',  
        currency: '',  
        cartItems: JSON.stringify(cartItems),  
        email: '',  
  
        //Order Data  
        clientcustomerid: '',  
        cartId: '',  
        subtotal: '',  
        totalTax: '',  
        totalShipping: '',  
        margin: '',  
        paymenttype: '',  
        ccbin: '',  
  
        //Customer Data  
        customerType: '',  
        hasAccount: '',  
        isReturning: '',  
        lastVisited: '',  
        isLoyalty: '',  
        loyaltyTier: '',  
        mobile: '',  
        title: '',  
        age: '',  
        gender: '',  
        dob: '',  
        billingAddress1: '',  
        billingAddress2: '',  
        billingCity: '',  
        billingState: '',  
        billingCountry: '',  
        shippingAddress1: '',  
        shippingAddress2: '',  
        shippingCity: '',  
        shippingState: '',  
        shippingZipcode: '',  
        shippingCountry: '',  
  
        },  
    });  
  
</script>
```


# Data and privacy
Source: https://docs.aftersell.com/aftersell/customer_data_and_privacy

What customer data Aftersell handles, how data-deletion and privacy requests work, and where to find the official privacy policy.

This page explains, at a merchant level, what customer data Aftersell handles and how privacy and data-deletion requests are processed. It is a practical summary, not a legal document.

<Note>
  The authoritative legal terms are in the [Rokt Privacy Policy](https://www.rokt.com/policies/privacy-policy) and the [Aftersell (powered by Rokt) Services Agreement](https://www.rokt.com/policies/aftersell-powered-by-rokt-services-agreement). Where this page and those policies differ, the policies apply.
</Note>

***

## What data Aftersell handles

Aftersell operates as an app installed on your Shopify store. Your Shopify store remains the canonical record of your customers — Aftersell stores only the limited identifiers it needs to attribute upsell offers to orders, such as checkout tokens, Shopify customer IDs, and offer/funnel journey records.

Each Shopify store is treated as an independent data controller. Data belonging to one store is never mixed with, or exposed to, another store.

<Note>
  If your store also uses **Rokt Thanks**, Rokt may process additional data to serve and measure partner offers. This is covered by the same [Rokt Privacy Policy](https://www.rokt.com/policies/privacy-policy) linked above, and shoppers can manage their preferences through the controls Rokt presents at the point of the offer.
</Note>

***

## Data-privacy requests

Aftersell supports Shopify's mandatory data-privacy (GDPR/CCPA) webhooks. When Shopify sends one of these requests on behalf of a shopper or a store, Aftersell handles it automatically:

| Shopify request                                      | What Aftersell does                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Customer data request** (`customers/data_request`) | The request is logged internally. Because your Shopify store holds the canonical customer record and Aftersell stores only limited identifiers, there is usually little additional data to return; anything that needs manual fulfillment is escalated to [privacy@rokt.com](mailto:privacy@rokt.com). |
| **Customer redact** (`customers/redact`)             | Deletes the data associated with that customer. If your store uses Rokt Thanks, the deletion is also propagated to Rokt for that customer (this is an asynchronous process that can take up to 30 days to fully complete).                                                                             |
| **Shop redact** (`shop/redact`)                      | Fired after you uninstall the app. Cleans up your store's integration records.                                                                                                                                                                                                                         |

You do not need to configure anything for these to work — they are handled for every store.

***

## Submitting a request

* **Shoppers** should contact the store they purchased from. The store (as the data controller) can initiate a data request or deletion through Shopify, which Aftersell then honors automatically.
* **Merchants** who need to escalate a specific data request — for example, exporting data that Rokt may hold for a Rokt Thanks–integrated store — can email [privacy@rokt.com](mailto:privacy@rokt.com).

***

## Data retention after cancellation

When you cancel Aftersell, your settings, funnels, widgets, and configurations are retained for up to one year. Uninstalling does not delete them, so if you reinstall within that year they are simply still there — there is no restore step to run. After one year, that data may be removed. See [How do I cancel my Aftersell subscription?](/aftersell/how_do_i_cancel_my_aftersell_subscription) for the full cancellation flow.

Uninstalling the app also triggers Shopify's `shop/redact` request, which cleans up your integration records as described above.

***

**Related**

* [Rokt Privacy Policy](https://www.rokt.com/policies/privacy-policy)
* [Aftersell (powered by Rokt) Services Agreement](https://www.rokt.com/policies/aftersell-powered-by-rokt-services-agreement)
* [How do I cancel my Aftersell subscription?](/aftersell/how_do_i_cancel_my_aftersell_subscription)


# Does Aftersell have a developer API?
Source: https://docs.aftersell.com/aftersell/does_aftersell_have_a_developer_api

Aftersell does not provide a developer API. Shopify's Post Purchase API and Checkout Extensibility limit changes to those available in the app.

Aftersell does not offer a general-purpose developer API for configuring the app. Due to the nature of working with Shopify's Post Purchase API and Checkout Extensibility environments we're limited in what we can edit, and all of the changes available to us are made in the app itself.

There is one public API: the [Aftersell Strategies API](/aftersell/strategies_api_reference_evaluate_strategy). It evaluates a strategy against the context you send and returns the products to show. It is available on stores that have Aftersell Strategies enabled, and requests are authenticated with a store-specific API key you generate in the Aftersell admin and send in the `X-Strategy-Api-Key` header.


# Does multi-currency checkout impact Aftersell?
Source: https://docs.aftersell.com/aftersell/does_multi_currency_checkout_impact_aftersell

This article explores how multi-currency checkout affects the functionality of Aftersell.

If your store has multi-currency enabled, 1-click upsell offers will only appear for orders made in your **store's default currency.** For instance, if your store's default currency is GBP and the order was placed in USD, the offer will **not** display. This limitation is a result of Shopify's multi-currency infrastructure. \
To address this, consider aligning your store's default currency with the currency most commonly used by your customers. This can improve the visibility and performance of post-purchase upsells by providing a localized shopping experience.

### Steps for Changing Store Currency

1. Evaluate your customer base to determine the predominant purchasing currency.
2. Update your store's default currency in Shopify to match the target market's currency.
3. Wait for up to 24 hours for Shopify to fully convert your store to the new currency.
4. Verify that post-purchase upsells are visible to customers in the target market. No additional steps are required after the currency change for upsells to appear.

This restriction is due to Shopify’s post-purchase limitations, which are explained further [here](/aftersell/why_isnt_my_1_click_offer_displaying). You can also review [Shopify's documentation](https://shopify.dev/docs/apps/checkout/product-offers/post-purchase#limitations-and-considerations) for additional details. Shopify's infrastructure imposes unique constraints on multi-currency capabilities, emphasizing the need for merchants to carefully plan their store's currency settings to optimize post-purchase app functionalities.

***

[Thank you page](/aftersell/thank_you_page_scripts_overview) offers are not subject to the same limitations as 1-click offers, making them an excellent alternative in this scenario. We recommend setting up upsells to capture orders that may not see 1-click offers due to these restrictions. Moreover, setting up dedicated upsell offers tailored to key customer segments can further ensure these offers align with multi-currency functionalities. Consider leveraging Shopify Markets for enhanced configuration.


# DTC ads onboarding guide | web pixel activation
Source: https://docs.aftersell.com/aftersell/dtc_ads_onboarding_guide_web_pixel_activation

This article outlines how to integrate the Rokt Conversions Web Pixel

# **Overview**

The Rokt Conversions Web Pixel enables accurate attribution of conversions from your Shopify store to Rokt campaigns. This helps optimize your marketing performance by tracking user activity through Shopify’s Web Pixels API.

***

## **Step 1: Install the Aftersell App**

You will be provided with a special installation link by your account manager.

* Click the link to be redirected to the Shopify App Store.
* You will be prompted to install the Aftersell app.

  <img alt="AfterSell by Rokt permission request listing customer data and pixel access scopes" />
* Click **Install** to continue.

After installation, Aftersell may display a permission request within the app for scopes related to pixel tracking — specifically `read_customer_events` and `write_pixels`. Click **Approve** to grant these permissions. Accepting these scopes allows Aftersell to inject and activate the Rokt Web Pixel automatically.

***

## **Step 2: Accept Terms and Conditions**

After granting the required permissions:

* You will be prompted to review and accept our Terms and Conditions.

  <img alt="Rokt Thanks onboarding form with a Terms and Conditions checkbox and Enable now button" />
* Press **Enable now** to proceed.

***

## **Step 3: Activate Free Plan**

Following the Terms and Conditions:

* You will be prompted to accept the **Aftersell Free Plan (Rokt Ads)**.
* Click **Approve** to complete the activation.

  <img alt="Shopify approval screen for the AfterSell Free Plan Rokt Ads charge with Approve button" />
* Once approved, your onboarding is complete, and you will be redirected to the Rokt Ads dashboard, where you will see your newly created **One Platform Account ID**. (While it is being created the card reads *Generating One Platform Account ID*.)

<img alt="Welcome to Rokt Ads page showing the pixel activation notice and the account ID" />

***

## **Step 4: Web Pixel Activation**

After completing onboarding, the Web Pixel installation will be triggered automatically.

Please allow up to **5 minutes** for the activation to complete.

***

## **To Verify Pixel Activation:**

1. On the Rokt Ads page (inside Aftersell), click the link labeled **Customer Events Page**. This will take you directly to the right page in your Shopify Admin.
2. Alternatively:\
   Navigate manually to Shopify Admin → Settings → Customer Events.
3. Once there:\
   Under App Pixels, look for "Aftersell".\
   Ensure the status is listed as Connected.

   <img alt="Shopify Customer events settings showing the AfterSell by Rokt pixel marked Connected" />

If the pixel does not appear immediately or shows "Disconnected," it may still be processing. Please wait a few minutes and refresh the page.

***

## **Additional Notes:**

This activated web pixel does three things:

1. Adds a cookie when a customer lands on your site from one of your Rokt campaigns. Rokt will automatically add the “rtid” query parameter to the URL of the landing page.
2. Records conversions. If the customer has a cookie from step i) then the conversion will be attributed to your Rokt campaign.
3. Forwards Shopify's standard storefront events to Aftersell — page, product and collection views, searches, cart adds and removes, checkout steps, and checkout completion. This is the part that runs on analytics consent alone.

The following settings will be applied automatically by the web pixel app.

1. *Permission: Analytics.* The pixel extension declares analytics consent only — marketing and preferences are both off. This is most relevant for customers in the EU and UK. Conversion sending is checked separately at runtime: if the shopper has not granted marketing consent, the Rokt conversion is skipped while the standard storefront events still flow. To learn more, see [Shopify’s documentation here](https://help.shopify.com/en/manual/promoting-marketing/pixels/custom-pixels/manage#customer-privacy).
2. *Data sale: Data collected does not qualify as data sale.* Conversion data is collected to optimize and monitor advertising campaigns and is not sold by Rokt.
3. For details on the Web Pixels API, see [Shopify’s developer documentation here](https://shopify.dev/docs/api/web-pixels-api).


# Earn & Save program
Source: https://docs.aftersell.com/aftersell/earn-save



Earn & Save is an opt-in program for Aftersell merchants. When you enroll, two things happen each cycle:

* Your Rokt Thanks earnings pay out to you in full.
* Aftersell adds a matching discount on top of your Aftersell bill, sized to match your earnings from the last 30 days, up to your bill amount.

If your earnings are less than your bill, the matching discount only covers part of the bill, and you still owe the remainder. Your Rokt Thanks earnings always pay out to you in full, regardless of whether the discount fully covers your bill.

Earn & Save is not a trial, and it does not change your existing Aftersell plan. As long as Rokt Thanks stays active on your store and you remain enrolled, the matching discount keeps applying each cycle. Your features, your base plan price, and your maximum monthly charge all stay the same.

## How Earn & Save works

Earn & Save has two sides: the earnings you generate through Rokt Thanks, and the matching discount Aftersell adds to your monthly bill.

**Earn.** When you enable Rokt Thanks, vetted brands like Disney+, HelloFresh, and Venmo show their offers on your post-purchase confirmation page. Every time a customer clicks "Yes, please!" on one of those offers, you earn revenue. On average, merchants earn around \$0.30 to \$0.50 USD per transaction. Rokt pays these earnings out to you in full via PayPal (or wire/ACH if you have that set up).

**Save.** Each billing cycle, Aftersell adds a matching discount on top of your Aftersell bill, sized to match your Rokt Thanks earnings from the last 30 days, up to your bill amount. The discount is added by Aftersell, not deducted from your earnings.

If your earnings fully cover your bill, your Aftersell charge for that cycle can be as low as \$0. If your earnings are smaller than your bill, the discount only covers part of the bill and you pay the remainder. Either way, your Rokt Thanks earnings pay out to you in full.

## At a glance

|                                   |                                                                                                               |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------ |
| **Who is it for?**                | Any Aftersell store with 1,000 or more monthly orders.                                                        |
| **What is it?**                   | An opt-in program layered on top of your existing pricing plan.                                               |
| **What does it cost?**            | Nothing. There is no separate fee.                                                                            |
| **What changes about my plan?**   | Nothing. Your features, base plan price, and maximum monthly charge stay the same.                            |
| **When does the discount start?** | On your upcoming Aftersell bill, irrespective of how long you have been enrolled.                             |
| **Where do my earnings go?**      | Rokt pays them out to you in full via PayPal (or wire/ACH if set up), separately from the Aftersell discount. |

## How the matching discount is calculated

Each billing cycle, Aftersell looks at your Rokt Thanks earnings from the **last 30 days** and adds a matching discount to your Aftersell bill, sized to match those earnings. The discount is capped at your bill amount, so it never exceeds what you would have paid.

How this plays out depends on how much you earned in the last 30 days:

| Last 30 days earnings   | Matching discount        | What you pay Aftersell     |
| :---------------------- | :----------------------- | :------------------------- |
| **Exceed your bill**    | Caps at your bill amount | **\$0**                    |
| **Match your bill**     | Covers the full bill     | **\$0**                    |
| **Less than your bill** | Matches your earnings    | The remainder of your bill |

Either way, your Rokt Thanks earnings continue to pay out to you in full.

On your Aftersell admin (Settings → Billing), the matching discount shows the exact 30-day earning window it was sized to match, for example "May 5 to June 3 Rokt earnings". Hover the info icon next to the line for the full breakdown.

<Note>
  If your plan bills more than one Aftersell charge (for example, a grandfathered Post-purchase and Checkout plan), the charges are billed together on the same day for Earn & Save merchants. The matching discount applies to the combined Aftersell bill, not to each charge separately.
</Note>

## Am I eligible?

Your store qualifies for Earn & Save if it processes **at least 1,000 orders per month**.

Earn & Save applies to your total Aftersell bill, whatever plan you are on (current or grandfathered) and whichever features it includes. The matching discount applies to your full Aftersell charge each cycle.

What you actually earn through Rokt Thanks depends on factors like your traffic, order volume, and offer relevance to your customers. Higher engagement generally leads to higher earnings.

If your store does not currently meet the 1,000 monthly order threshold, you can still use Aftersell on a standard paid plan. Eligibility is re-evaluated continuously, so Earn & Save will surface in your admin if your store crosses the threshold later.

## Enrolling in Earn & Save

The enrollment flow depends on your current Aftersell setup. Some stores see additional steps, others enroll in a single click.

<Steps>
  <Step title="Confirm any updated terms (only if prompted)">
    Some stores are required to confirm updated subscription terms before enrolling. You will see a prompt in your Aftersell admin if this applies to your store. If you do not see a prompt, skip to step 2.

    This typically applies to stores on an older Aftersell billing plan that includes the Checkout feature. Confirming the updated terms does not change your features or your base plan price. It only authorizes Aftersell to add the matching discount line to your future bills.
  </Step>

  <Step title="Enable Rokt Thanks">
    Open the Rokt Thanks dashboard in your Aftersell admin and click **Enable**. Then place at least one Rokt Thanks app block on a customer-facing page. Your Thank You page is the recommended starting point. Completing both of these actions activates Rokt Thanks on your store and starts your Earn & Save discount. The setup guide on the dashboard tracks more than these two, though - it also asks for the block on your Order status page, and on your customer account Orders page if your store is eligible - so it stays marked **Incomplete** until those are placed too.

    If you need help with block placement, see <a href="/aftersell/activating_and_configuring_rokt_thanks">Activating and Configuring Rokt Thanks</a>.
  </Step>
</Steps>

<Note>
  Setting up your payouts (PayPal or wire/ACH) is a separate step that is not required for Earn & Save to apply the matching discount to your bill. Payout setup only affects how you receive your Rokt Thanks earnings. See [Rokt Thanks Payouts](/aftersell/rokt_thanks_payouts) for details.
</Note>

## Maximizing your earnings

The more visible the Rokt Thanks block is on your store, the more opportunities your customers have to interact with offers. A few practical things you can do to increase visibility:

**Place the block above the fold.** Buyers do not always scroll the confirmation page. Place the Rokt Thanks block in the **Main** section of your Thank You page, just below the order-confirmation banner, so it appears without scrolling. Avoid the Order Summary column and the Footer.

**Add the block to multiple surfaces.** Rokt Thanks can render on up to four customer-facing pages: your Thank You page, your Order Status page, your customer account Profile page, and your customer account Orders page (if you are on Shopify's new customer accounts, also called Vaulted Rewards). Placing the block on all four surfaces can lift earnings by an estimated 10 to 20 percent on top of the Thank You page alone. See <a href="/aftersell/activating_and_configuring_rokt_thanks#rokt-vaulted-rewards-customer-account-pages">Rokt Vaulted Rewards</a>.

**Keep Rokt Thanks active.** The matching discount only applies while Rokt Thanks is active and generating earnings. If you disable or remove the Rokt Thanks block, earnings stop and the discount stops on the next cycle. You can re-enable anytime.

## What you see on your bill and payouts

Earn & Save shows up in three places. Each handles a different part of the program.

|                                         |                                                                                                                                                                         |
| :-------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Shopify invoice**                     | Your Aftersell charge for the cycle, with the matching discount already applied. The charge can be as low as \$0 if the discount fully covers it.                       |
| **PayPal (or wire/ACH)**                | Your Rokt Thanks earnings, paid out by Rokt directly on their normal payout schedule (approximately 90 days after the end of the month the earnings were generated in). |
| **Aftersell admin, Settings → Billing** | The current cycle's matching discount, the 30-day window it was sized to match, and your lifetime savings from the program.                                             |

## Worked examples

<Note>
  These examples use current plan pricing. Existing merchants are grandfathered on the plan and pricing they signed up under, so your own base fee and monthly cap may differ. Earn & Save works the same way on any plan. See [Aftersell billing & pricing](/aftersell/aftersell_billing_pricing) for the current plans.
</Note>

### Scenario 1: matching discount covers part of the bill

You are on the Post-purchase plan. Based on your order volume, your Aftersell bill for this cycle is \$149.99. Your Rokt Thanks earnings from the last 30 days are \$80.

|                                     |                                    |
| :---------------------------------- | :--------------------------------- |
| Post-purchase charge                | \$149.99                           |
| **Aftersell bill this cycle**       | **\$149.99**                       |
| Rokt Thanks earnings (last 30 days) | \$80                               |
| Matching discount added to bill     | \$80 off (sized to match earnings) |
| **What you pay Aftersell**          | **\$69.99**                        |
| **Earnings paid out to you**        | **\$80**                           |

The matching discount of \$80 is applied to your bill, leaving \$69.99 still due. You also receive your \$80 in Rokt Thanks earnings, paid out by Rokt directly.

### Scenario 2: matching discount covers the full bill

You are on the Post-purchase plan. Your store is high-volume, doing 20,000 or more orders per month, which puts your Post-purchase charge at the maximum of \$999.99 (the highest the Post-purchase charge can reach, regardless of how high your order volume goes). Your Rokt Thanks earnings from the last 30 days are \$1,200.

|                                     |                                                      |
| :---------------------------------- | :--------------------------------------------------- |
| Post-purchase charge                | \$999.99 (maximum)                                   |
| **Aftersell bill this cycle**       | **\$999.99**                                         |
| Rokt Thanks earnings (last 30 days) | \$1,200                                              |
| Matching discount added to bill     | \$999.99 off (sized to earnings, capped at the bill) |
| **What you pay Aftersell**          | **\$0**                                              |
| **Earnings paid out to you**        | **\$1,200**                                          |

Your earnings exceed your bill, so the matching discount caps at \$999.99 and your Aftersell charge for the cycle is \$0. You still receive your full \$1,200 in Rokt Thanks earnings, paid out by Rokt directly. The discount does not grow beyond your bill amount.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Can my Aftersell bill really be $0?">
    Yes. When your Rokt Thanks earnings from the last 30 days reach or exceed your bill amount, the matching discount covers the full bill and you pay \$0 for that cycle. You continue to receive your full earnings from Rokt Thanks, paid out separately.

    Whether your bill reaches \$0 depends on your earnings each cycle. It is possible, not guaranteed.
  </Accordion>

  <Accordion title="Why isn't my bill $0?">
    The matching discount is sized to match your Rokt Thanks earnings from the last 30 days. If your earnings did not reach your bill amount, the discount is sized to match whatever you earned, and the remainder of the bill is still due. Your Rokt Thanks earnings continue to pay out to you in full.
  </Accordion>

  <Accordion title="Are my apps free as long as Rokt Thanks is enabled?">
    Only when your Rokt Thanks earnings consistently meet or exceed your Aftersell bill. If you earn \$50 in a 30-day period and your bill is \$349, your matching discount is \$50 and the remaining \$299 is still due.

    For high-volume stores with strong engagement, it is common for earnings to fully cover the bill each cycle. For smaller stores, Earn & Save is best thought of as a recurring savings on your subscription, not free service.
  </Accordion>

  <Accordion title="What happens to earnings beyond my Aftersell bill amount?">
    The matching discount is capped at your bill amount, so the discount itself does not grow beyond that. Your earnings always pay out in full regardless, so you still receive everything Rokt Thanks earned for you during that cycle. Earnings and the discount are separate.
  </Accordion>

  <Accordion title="I enrolled but my bill did not change. Why?">
    A few common reasons:

    * **Rokt Thanks is not yet enabled or showing offers.** Open the **Rokt Thanks** tab in your Aftersell admin and check the setup guide there - it should show Rokt Thanks enabled and your app blocks placed. Settings → Billing gives you a quick read too: the Earn & Save card carries an **Active** / **Inactive** badge, and if your Thank you page block is missing it shows the nudge "Almost there, finish your Rokt Thanks setup to start earning a matching discount." The Rokt Thanks tab is still where you fix it.
    * **You have not earned yet.** The discount is sized to match your last 30 days of Rokt Thanks earnings. If you only just enabled Rokt Thanks, give it a billing cycle to start earning.
    * **You are still ramping up.** Earnings depend on traffic, order volume, and offer relevance. Results vary by store and grow over time.
  </Accordion>

  <Accordion title="What happens if I turn off Rokt Thanks?">
    You stay enrolled in the program, but the matching discount only applies while Rokt Thanks is active and generating earnings. If you disable Rokt Thanks, the discount stops on the next cycle. You can turn Rokt Thanks back on anytime to resume.
  </Accordion>

  <Accordion title="I already had Rokt Thanks set up before Earn & Save existed. Do I still need to do anything?">
    It depends on your current Aftersell billing plan. If you are on an older Aftersell plan that includes the Checkout feature, you may be prompted to confirm updated subscription terms when you enroll. Look for the Earn & Save prompt in your Aftersell admin. If you do not see a prompt, you can enroll without confirming any new terms.
  </Accordion>

  <Accordion title="When will I get my first Rokt Thanks payout?">
    Earnings are paid out approximately 90 days after the end of the month the revenue was generated in. Payouts are also subject to a minimum threshold based on your payout method.

    Full details are on the [Rokt Thanks Payouts](/aftersell/rokt_thanks_payouts) page.
  </Accordion>

  <Accordion title="I closed the Earn & Save card by accident. How do I find it again?">
    The Earn & Save card is always accessible from your Aftersell admin under **Settings → Billing**, where **Start saving** appears on both the Earn & Save card and the billing summary. The card stays available as long as your store is eligible.

    You can also add a **View Earn & Save** shortcut to your home page: select the pencil icon on the [Quick actions](/aftersell/home/quick-actions) widget and tick it. It isn't one of the default actions, so it appears only once you add it.
  </Accordion>

  <Accordion title="I do not see the Earn & Save option in my Aftersell admin. Why?">
    Earn & Save is only surfaced for stores that meet the eligibility threshold of 1,000 monthly orders. If you have recently crossed that threshold and do not see the program, reach out to support and we can confirm your eligibility status.
  </Accordion>

  <Accordion title="Can I check how much I have saved over time?">
    Yes. The Earn & Save card on Settings → Billing shows your lifetime savings from the program, alongside the current cycle's matching discount.
  </Accordion>

  <Accordion title="Does Earn & Save change my Aftersell features or plan?">
    No. Earn & Save sits on top of whichever standard plan you are on. Your features, your base plan price, and your maximum monthly charge stay the same. The only difference is the matching discount that gets added to your bill.
  </Accordion>

  <Accordion title="How do I leave Earn & Save?">
    You can stop the matching discount in two ways:

    * **Disable Rokt Thanks.** Earnings stop, and the discount stops on the next cycle. You can re-enable anytime.
    * **Leave the program entirely.** Contact the Aftersell support team via in-app chat. Your standard plan billing resumes on the next cycle.
  </Accordion>
</AccordionGroup>

## Need help?

* For program questions or setup issues, contact the Aftersell support team via in-app chat or email [support@aftersell.com](mailto:support@aftersell.com).
* For Rokt Thanks payout-specific questions, see [Rokt Thanks Payouts](/aftersell/rokt_thanks_payouts).
* Include your store URL and a brief description of the issue for faster help.

### Related pages

* [What is Rokt Thanks?](/aftersell/what_is_rokt_thanks)
* [Activating and Configuring Rokt Thanks](/aftersell/activating_and_configuring_rokt_thanks)
* [Rokt Thanks Settings](/aftersell/rokt_thanks_settings)
* [Rokt Thanks Payouts](/aftersell/rokt_thanks_payouts)
* [Aftersell Billing & Pricing](/aftersell/aftersell_billing_pricing)


# FAQ widget (Thank You Page)
Source: https://docs.aftersell.com/aftersell/faq-widget-thank-you-page

Configure the Thank You Page FAQ widget in Aftersell to answer common customer questions right after checkout.

The FAQ widget displays common questions and answers on the Thank You page to reduce post-purchase support requests. This page covers every setting on the widget. For the full funnel setup and Shopify editor steps, see [How to configure thank-you page widgets](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell).

Add the widget from the **Thank You Page** section of your funnel by clicking **Add Widget** and selecting **FAQs**.

## Add FAQ items

1. Click **Add FAQ Item**.
2. Enter your **question** text.
3. Enter your **answer** text.
4. Repeat for additional FAQ items.
5. Reorder items by dragging and dropping.
6. Click **Save**.


# How to configure thank-you page widgets
Source: https://docs.aftersell.com/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell

Step-by-step guide to setting up and configuring Thank You Page widgets in Aftersell

Thank You Page (TYP) widgets in Aftersell are a powerful way to engage customers after a purchase and increase sales. This guide provides step-by-step instructions for configuring and enabling TYP widgets within your post-purchase funnels. TYP widgets work in conjunction with Post-Purchase offers, providing multiple opportunities to maximize customer conversions after checkout.

***

## What are Thank You Page widgets?

Thank You Page widgets allow you to display additional content and product recommendations to customers immediately after checkout. They are highly customizable and do not face the same [Shopify limitations](/aftersell/why_isnt_my_1_click_offer_displaying) as post-purchase upsells. Thank You Page widgets enable you to:

* Tailor offers to specific customer actions (funnel triggers)
* Showcase personalized product recommendations
* Engage customers in a non-intrusive way
* Add [testimonials](/aftersell/thank_you_page_testimonials_widget), [FAQs](/aftersell/thank_you_page_faq_widget), [text content](/aftersell/thank_you_page_text_widget), and [images](/aftersell/thank_you_page_image_widget) to your Thank You page

Each TYP widget is tied to a specific funnel, ensuring you retain flexibility and control for different customer journeys.

***

## Step-by-step setup guide

### Step 1: Create or select a funnel

1. Navigate to **Post-purchase Funnels** in your Aftersell admin.
2. Click **Add funnel**, then pick a template or choose to create one manually — or select an existing manual funnel.
3. Name your funnel (e.g., "Thank You Page Upsells - All Orders").

<img alt="Thank You Page product recommendation widget previewing a snowboard upsell in the Shopify editor" />

### Step 2: Configure funnel triggers

Define when your funnel should run. The triggers you set here apply to the entire funnel, including both Post-Purchase offers and Thank You Page widgets.

Thank You Page widgets do not have separate trigger settings. Whatever triggers are configured for the funnel will also determine when the corresponding Thank You Page widgets display.

1. In the funnel settings, click **Triggers**.
2. Select trigger conditions based on:
   * Customer tags
   * Product purchased
   * Cart value
   * Order count
   * Collection
   * Discount codes used
3. Click **Save Triggers**.

For step-by-step instructions on how to configure funnel triggers, including detailed targeting options and examples, refer to our [Funnel Triggers setup guide](/aftersell/how_to_configure_post_purchase_triggers).

***

### Step 3: Add TYP widgets to your funnel

1. Scroll to the **Thank You Page** section in your funnel.
2. Click **Edit extensions page** (or **Edit scripts page**, if your store has not yet migrated to Thank You page extensibility) to open the Thank You Page editor.
3. Pick a widget type from the sidebar and click **Enable** to turn it on. Every widget type already has its own tab — there is no separate "add" step. The available types are:
   * [**Product Recommendation**](/aftersell/thank_you_page_product_recommendation_widget) - Display upsell product recommendations
   * [**Testimonials**](/aftersell/thank_you_page_testimonials_widget) - Show customer reviews to build trust and social proof
   * [**FAQs**](/aftersell/thank_you_page_faq_widget) - Answer common customer questions
   * [**Text**](/aftersell/thank_you_page_text_widget) - Share messages, discount codes, or brand stories
   * [**Image**](/aftersell/thank_you_page_image_widget) - Display a custom image or banner
   * **Gift with purchase** - Offer a free gift alongside the order. This tab only appears once the feature has been enabled for your store; contact support if you would like it turned on.

For the settings available on each widget type, see the individual widget pages linked above.

***

### Save your funnel configuration

1. Review all widget settings.
2. Click **Save Funnel** at the top of the page.
3. Set funnel status to **Active**.

***

* **Max reviews to show** - How many reviews appear, from **1 to 3** (defaults to 3)
* **Display type** - Choose between horizontal carousel or vertical stack layout
* **Minimum rating** - Set the minimum star rating for reviews to display
* **Truncate review text after (optional)** - Set a maximum character length for review text

## Enabling widgets in Shopify

Widgets created in Aftersell must be added to your Thank You page or Order Status page in the Shopify editor, otherwise they will not display to customers. We recommend placing the app blocks on both pages.

### Step 1: Open Shopify editor

1. In your Aftersell admin, click **Open Shopify Editor**.
2. This opens the Shopify checkout customization editor.

<img alt="Callout pointing to the Open Shopify editor button above the product selection list" />

<img alt="Aftersell prompt with an Open Shopify editor button for placing widgets" />

### Step 2: Add widgets to the Thank You page

1. In the Shopify editor, navigate to **Thank You page**.
2. Click **Add app block** or **Add section**.
3. Select the Aftersell block matching the widget you configured. Each widget type is published as its own app block: **TY Product Recommendation Widget**, **TY Testimonials Widget**, **TY FAQs Widget**, **TY Text Widget**, **TY Image Widget**, or **TY Gift with Purchase**.
4. Position the widget block where you want it to appear.
5. Repeat steps 2-4 for every widget you enabled, one block each.
6. Click **Save**.

<Tip>
  Place your widget toward the top of the Thank You page for best visibility. Widgets positioned lower on the page may not be seen on all devices, particularly on mobile where customers are less likely to scroll.
</Tip>

<img alt="Shopify theme editor Add app block menu with the Aftersell Thank You widget selected on the Thank You page" />

### Step 3: Add widgets to the Order Status page

Repeat the same steps on the **Order Status page** in the Shopify editor so customers who return to their order confirmation still see your widgets.

<img alt="Adding an Aftersell app block to the Shopify Order status page in the checkout editor" />

### Step 4: Publish your changes

1. Review the page in the preview.
2. Click **Publish** in the top-right corner.
3. Confirm the publication.

Your TYP widgets are now live and will display to customers based on your funnel triggers.

***

1. Set the widget **Title** (it defaults to "FAQs").
2. Click **Add FAQ**.
3. Enter your **question** text.
4. Enter your **answer** text.
5. Repeat for additional FAQ items. Each row has its own **Remove** button.
6. Click **Save**.

## Testing your widgets

Shopify's checkout preview may not always display widgets correctly. Follow these steps to test:

1. **Set triggers to "Show for all customers"** (temporarily) to see widgets in preview.
2. **Place a test order** using a real checkout flow:
   * Use Shopify's test payment gateway
   * Create a free product for testing
   * Use a discount code to make the order \$0
3. **Verify widgets appear** on the Thank You page immediately after checkout.
4. **Test widget functionality:**
   * Click product recommendations
   * Verify checkout flow for upsells
   * Confirm order handling works as configured
5. **Reset triggers** to your desired targeting rules after testing.

<Note>
  FAQ items appear in the order you add them, and **Add FAQ** always appends to the bottom — you cannot insert one part-way up the list. There is no drag-and-drop reordering either, so to move an item you have to remove everything from that position onward and re-add them in the order you want.
</Note>

***

## Advanced configuration

### Combining with post-purchase upsells

For maximum conversion, combine TYP widgets with post-purchase offers:

1. Add **Post-purchase Offers** to your funnel (before Thank You page).
2. Configure **TYP widgets** as a second touchpoint.
3. Customers who decline post-purchase offers will still see TYP widgets.
4. This creates multiple conversion opportunities in the customer journey.
5. Choose a **Select style** — **Plain text** or **Banner**. Choosing Banner reveals a **Select type of banner** option.
6. Enter your **Heading text** (optional).
7. Enter your **Content**.
8. Click **Save**.

<Note>
  These are plain text fields, not a rich-text editor — there is no toolbar for bold, italics, lists, or links. Use the Banner style or an [Image widget](#configure-image-widgets) if you need more visual emphasis.
</Note>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget not displaying">
    * Verify funnel status is set to **Active**.
    * Check that funnel triggers match your test order conditions.
    * Confirm widgets are enabled in the funnel configuration.
    * Ensure the widget block is added to the Thank You page in the Shopify editor and positioned toward the top of the page.
  </Accordion>

  <Accordion title="Thank You page not triggering">
    * Customers sometimes skip the Thank You page if they close the browser immediately after purchase.
    * Ensure Thank You page offers are correctly set up in the Shopify editor.
    * Verify the widget block is positioned correctly on the page.
  </Accordion>
</AccordionGroup>

***

## Limitations

<Note>
  Countdown timers are not available on the Thank You page. This is a Shopify platform restriction and cannot be changed within Aftersell.
</Note>

Each funnel's Thank You Page widgets must be customized individually. There is no option to standardize them across multiple funnels. This ensures all offers are specific to the triggers and customer behavior for each funnel.

***

<Note>
  Countdown timers on the Thank You page product recommendation widget are off by default and are not available on every store. Once the feature is enabled for yours, the widget's banner section gains **Enable timer**, **Timer duration**, and **Timer start** (page load or order created) controls, and the remaining time is inserted wherever you place the `{TIMER}` placeholder in your banner text. Contact support if you would like it turned on.
</Note>

**Want to go further?**

* [Post-Purchase Best Practices](/aftersell/best_practices) - tips to improve conversion across all your offers
* [How to Configure Post-Purchase Offers](/aftersell/how_to_configure_post_purchase_triggers) - set up your full post-purchase funnel


# How do I cancel my Aftersell subscription?
Source: https://docs.aftersell.com/aftersell/how_do_i_cancel_my_aftersell_subscription

Cancelling and unsubscribing from Aftersell

This guide walks through how to cancel your Aftersell subscription. Cancelling Aftersell uninstalls the app from your Shopify store and ends your subscription. Your settings, funnels, widgets, and configurations are retained for up to 1 year, so you can restore them if you reinstall within that window.

## Before you cancel

If you are considering cancelling, these alternatives may address what you are looking to solve:

* **Reduce your bill with Earn & Save.** Eligible stores can lower their Aftersell subscription cost through the Rokt Thanks Earn & Save program. Your Rokt Thanks earnings pay out to you in full, and a matching discount is applied to your monthly bill up to your bill amount. See the <a href="/aftersell/earn-save">Earn & Save Program</a> page for details and eligibility.
* **Contact support before cancelling.** If a specific issue is driving your decision, our support team may be able to resolve it. Reach us via in-app chat or email [support@aftersell.com](mailto:support@aftersell.com).

## How to cancel

To cancel your Aftersell subscription and uninstall the app:

<Steps>
  <Step title="Open the Billing page">
    In the Aftersell admin, navigate to **Settings → Billing**.
  </Step>

  <Step title="Click Uninstall">
    On the **Current plan** card, click **Uninstall** in the row of buttons at the bottom of that card, beside **Compare plans** and **View pricing tiers**. A confirmation modal will open. (Don't scroll to the bottom of the page looking for it — the Payment history card renders below the Current plan card.)
  </Step>

  <Step title="Select a cancellation reason">
    In the modal, select the reason or reasons that best describe why you are cancelling. Your answer helps the Aftersell team improve the product.
  </Step>

  <Step title="Answer any follow-up questions">
    Depending on the reason you select, additional questions may appear. Answering these is optional but appreciated.
  </Step>

  <Step title="(Optional) Add additional comments">
    Use the "Something else" field to share any additional context you would like to provide.
  </Step>

  <Step title="Review your final invoice">
    The Final invoice banner displays any pending usage charges that will appear on your next Shopify invoice. Review these before confirming.
  </Step>

  <Step title="Confirm the uninstall">
    Click **Uninstall** to confirm. Your subscription is cancelled and the app is removed from your Shopify store in a single step.
  </Step>
</Steps>

## What happens after cancellation

* **Your subscription** ends immediately. No new charges will be submitted for the upcoming billing cycle.
* **Pending charges** that were already submitted to Shopify before cancellation will still be collected on your next Shopify invoice. To avoid charges for the next cycle, cancel at least one day before your next billing date.
* **Your data** (settings, funnels, widgets, configurations) is retained for up to 1 year after cancellation.
* **If you reinstall within 1 year**, your previous configuration is still there and there is no restore step to run — uninstalling never deletes your funnels, widgets, or settings. Onboarding asks you to accept a plan again, and everything else is waiting as you left it. After 1 year, data may be removed and a reinstall will start you on a fresh setup.
* **Your theme stays clean.** Aftersell does not leave any code behind in your Shopify theme when uninstalled. All storefront integration runs through Shopify app embeds and app extensions, which Shopify removes automatically when the app is uninstalled. You do not need to manually edit theme files to clean up after cancellation.

<Note>
  Shopify collects app charges on its own billing cycle, not on the day a charge is submitted. If you uninstall after a charge has been submitted for the current cycle, that charge will still be collected on the next Shopify invoice. For more on this timing, see the "Why was I billed after uninstalling?" section of the <a href="/aftersell/aftersell_billing_pricing">Aftersell Billing & Pricing</a> page.
</Note>

## Need help?

For questions about cancellation, pending charges, or your final invoice, contact the Aftersell support team via in-app chat or email [support@aftersell.com](mailto:support@aftersell.com).

### Related pages

* <a href="/aftersell/aftersell_billing_pricing">Aftersell Billing & Pricing</a>
* <a href="/aftersell/earn-save">Earn & Save Program</a>


# How to configure checkout widgets
Source: https://docs.aftersell.com/aftersell/how_to_configure_checkout_widgets

Enable and place Aftersell checkout widgets in Shopify Plus: upsells, cart controls, rewards, trust badges, testimonials, notes, images, and text.

This guide walks you through how to configure and place checkout widgets in Aftersell, from enabling widgets to optimizing placement in Shopify Checkout for maximum conversion rates..

**Note:** Checkout widgets are only available to Shopify Plus merchants due to Shopify's Checkout Extensibility API restrictions.

***

## Step 1: Enable your widget in Aftersell

Before adding widgets to your checkout, you need to enable them in the Aftersell admin.

1. Navigate to the **Checkout** tab in your Aftersell admin
2. Select the widget type you want to configure ([Upsells](#upsells), [Cart Controls](#cart-controls), [Rewards,](#rewards) [Trust Badges,](#trust-badges) [Testimonials](#testimonials), [Notes](#notes), [Images](#images), or [Text](#text))
3. Click **Create** to build a new widget or select an existing widget to edit
4. Configure your widget settings (see [Widget types and configuration](#widget-types-and-configuration) below)
5. Click the **Enable** toggle in the top right corner of the widget settings
6. For restricted or advanced upsells, make sure you enable custom triggers before proceeding

***

## Step 2: Open the Shopify Checkout Editor

There are two ways to access the Shopify Checkout Editor:

**Option 1: From Shopify Admin**

1. Go to **Settings** in your Shopify Admin
2. Click **Checkout** in the left navigation
3. Click **Customize** next to your desired checkout profile

**Option 2: From Aftersell**

1. Click the **Open Shopify Checkout Editor** button in the bottom right of the Aftersell Checkout editor page

💡 **Tip:** Option 1 gives you more control over which checkout profile you're editing. We recommend testing on a draft version first before setting it live.

<img alt="Shopify admin home with the Settings link highlighted to open the checkout editor" />

***

## Step 3: Add the app block to your checkout

1. In the Shopify Checkout Editor, click **Add app block**
2. Select your desired Aftersell widget from the list of available widgets
3. Choose the correct placement for your widget (see [Available placements](#available-placements) below)
4. If you want your widgets to display in Shop Pay checkout, check the [**Include app block in Shop Pay**](/aftersell/show_checkout_widgets_in_shop_pay) option
5. Click **Save** in the top right corner

<img alt="Shopify Checkout Editor with an arrow pointing to the Add block button in the sidebar" />

***

## Step 4: Position your widget

1. Drag and drop the app block to your desired location within the selected placement area
2. Click **Save** in the top right corner

<img alt="Shopify Checkout Editor block list beside a live checkout preview showing Aftersell widgets" />

***

## Widget types and configuration

## Placements

Placements are created in the Aftersell Checkout editor and allow you to run multiple widgets of the same type on the same checkout page.

For example, if you want to display two upsell offers on the same page, each must be assigned to a different placement.

### Available placements

* **Default placement**: The primary placement. Every widget type starts here.
* **Additional placement 1**: A second placement slot for displaying another widget of the same type on the same page.
* **Additional placement 2**: A third placement slot for further separation.

You can also create new placements directly from the placement dropdown in Aftersell by selecting **+ Add new placement**.

<img alt="Aftersell Checkout editor showing the placement dropdown above the Upsells list and preview" />

***

### Placing a widget inside a shipping option row

Most checkout widget types — Upsells, Rewards, Trust badges, Testimonials, Notes, Images, and Text — can be placed directly inside a shipping option row in the Shopify Checkout Editor. Cart Controls is the exception: it has no shipping-option target and cannot be placed in a row. When placed there, the widget renders inside the row for whichever shipping method the customer currently has selected.

This lets you attach an offer or message to a specific shipping method — for example, showing an upsell or trust badge inside the selected shipping rate row.

**How to set it up:**

1. Configure and enable your widget in the Aftersell admin as normal.
2. Open the Shopify Checkout Editor.
3. Click **Add app block** and select your Aftersell widget.
4. Drag the app block into the **Shipping** section of the checkout, placing it inside a shipping option row.
5. Select the matching placement (for example, **Default placement**) in the app block settings.
6. Click **Save**.

**Things to keep in mind:**

* The widget renders only inside the row for the shipping method the customer has selected. It does not appear in every row simultaneously.
* The shipping section — and any widgets placed inside it — does not render for local pickup or digital-only carts.
* Upsell widgets placed in a shipping option row can add products to the cart directly from inside the row.

***

### When to use multiple placements

Use multiple placements when you want to:

* Display more than one widget of the same type on a single checkout page
* Show widgets in different sections of the page
* Target different audiences with different offers
* Run widgets with similar or overlapping triggers

Aftersell uses a priority system. You cannot run multiple widgets with identical triggers within the same placement. If two widgets share the same trigger conditions in one placement, only one will display based on priority.

To use similar triggers, assign each widget to a different placement so they can run independently without conflict.

***

## Matching placements in the Shopify Checkout Editor

Each placement in Aftersell corresponds to a separate app block in the Shopify Checkout Editor. The placement selected in Shopify must match the placement set in Aftersell.

For example, if a widget is assigned to **Additional placement 1** in Aftersell, the app block in Shopify must also be set to **Additional placement 1**.

If placements do not match, the widget may not appear or may display in the wrong location.

**Important:** A placement mismatch is one of the most common reasons a widget fails to display. If a widget is not appearing, confirm the placement matches in both Aftersell and Shopify before troubleshooting further.

<img alt="Shopify Checkout Editor Upsell Widget block settings with the Placement dropdown set to an additional placement" />

***

### Upsells

Offer products to customers during checkout to increase your average order value (AOV).

**Configuration options:**

**Widget modes:**

* **Single Product Upsell:** Display one product with an Add to Cart button
* **Multi-Product Upsell:** Show multiple products in a stack or carousel layout, allowing customers to accept multiple offers
* **Checkmark Upsell:** Display a single product with a checkbox instead of an Add to Cart button (ideal for low-cost add-ons like shipping protection)

**Product selection methods:**

* **Specific Products:** Manually select individual products to upsell
* **Collection:** Select a collection and display up to 5 random products (products already in cart are automatically excluded)
* **Automatic upsell(s):** Automatically recommend products based on cart contents
* **Most Expensive Product:** Automatically upsell the most expensive product from the cart
* **Spend threshold:** Recommend products that help customers reach reward thresholds (only selectable once **Show rewards bar** is enabled on the same upsell widget)
* **Strategy:** Dynamically select a product using rule-based targeting. Only shown on stores with [Strategies](/aftersell/strategies_overview) enabled

**Additional features:**

* Add discounts directly within the widget
* Lock subscription plans to specific options
* Display product review stars (requires compatible review app)
* Set a maximum number of accepted offers per widget (Single and Multi upsell types only)

[Learn more about upsell widgets](/aftersell/checkout_widget_types#upsells)

***

### Cart Controls

Allow customers to modify their cart directly on the checkout page.

**Available controls:**

* **Variant selector:** Change to another in-stock variant
* **Quantity selector:** Adjust product quantities
* **Remove item:** Show Remove Item Button removes upsell products from the cart. A paired setting, **Allow Removal of Non-Upsell Products** (off by default), extends removal to everything in the cart
* **Subscription selector:** Change subscription frequency
* **Subscription upgrade:** Upgrade one-time purchases to subscriptions
* **Custom text:** Add custom text below line items

**Product targeting:**

* Apply to all products in cart
* Apply only to selected products
* Apply to all products except selected ones

**Additional features:**

* Display product review stars for in-cart products

[Learn more about cart controls](/aftersell/checkout_widget_types#cart-controls)

***

### Rewards

Display a progress bar showing customers how close they are to earning a reward.

**Configuration options:**

* Reward basis: **Cart total** or **Item count**
* Amount basis (for Cart total): **Order total (includes shipping and tax)**, **Subtotal (before discounts)**, or **Subtotal after discounts (excludes tax and shipping)**
* Reward message and styling
* Progress bar colors and design

**Best practices:**

* Pair with upsell widgets to help customers reach reward thresholds
* Use spend threshold product type in upsells to automatically recommend products that close the gap
* Create rewards in Shopify using Automatic Discounts (for discount rewards) or Shipping Rules (for free shipping)
* Use **Subtotal after discounts (excludes tax and shipping)** as the amount basis when offering free shipping, so the bar matches Shopify's own threshold evaluation when discount codes are applied

[Learn more about rewards](/aftersell/checkout_widget_types#rewards)

***

### Trust Badges

Build trust with custom icons and text to increase checkout conversion rates.

**Configuration options:**

* Badge layout: Vertical stack or horizontal display
* Custom icons and text for each badge
* Styling and spacing options

**Best practices:**

* Highlight security features (secure checkout, SSL encryption)
* Showcase guarantees (money-back guarantee, free returns)
* Display shipping benefits (free shipping, fast delivery)

[Learn more about trust badges](/aftersell/checkout_widget_types#trust-badges)

***

### Testimonials

Display customer reviews directly on checkout to build trust.

**Configuration options:**

* **Flex Testimonials (recommended):** Automatically pulls real reviews from your review app (Judge.me, Klaviyo, Okendo, or Yotpo)
* Selection mode: Manual (choose specific reviews) or Dynamic (automatically fetch reviews based on cart contents)
* Display type: Horizontal carousel or vertical stack
* Minimum rating filter

**Setup requirements:**

* Configure review app credentials in Settings > Product Reviews
* Reviews sync automatically within 24 hours, then weekly

[Learn more about testimonials](/aftersell/checkout_widget_types#testimonials)

***

### Notes

Allow customers to add notes to their order.

**Configuration options:**

* Manual notes: Free-text field for customer input
* Pre-written notes: Checkboxes for options like gift wrapping or eco-packaging

[Learn more about notes](/aftersell/checkout_widget_types#notes)

***

### Images

Upload and display custom images in your checkout.

**Configuration options:**

* Image upload
* Width adjustment slider
* No minimum size requirement

[Learn more about images](/aftersell/checkout_widget_types#images)

***

### Text

Insert a banner with custom text in your checkout.

**Configuration options:**

* **Container Style:** **Plain Text** (the default) or **Badge**. The banner colors below only appear once you choose Badge
* **Banner Type** (Badge only):
  * **Info (Blue):** Blue background with information icon
  * **Success (Green):** Green background with checkmark icon
  * **Warning (Yellow):** Yellow background with warning triangle icon
  * **Critical (Red):** Red background with exclamation point icon
* Text size on the **Body** field (Small or Base) — the Heading field has no size control
* Alignment on both the Heading and Body fields
* Spacing: None, Extra Tight, Tight, Base, Loose, or Extra Loose

[Learn more about text](/aftersell/checkout_widget_types#text)

***

## Troubleshooting

### Widgets not displaying

If your widgets aren't showing after setup:

1. Verify widget is enabled in Aftersell admin
2. Check app block is added in Shopify Checkout Editor
3. Confirm app block is saved in Shopify Checkout Editor
4. Verify the correct placement is selected. When adding an app block in the Shopify Checkout Editor, you must choose the matching placement, such as Default placement, Additional placement 1, or Additional placement 2. If the wrong placement is selected, the widget may not appear or may display in the wrong location. Remove the app block and re-add it, ensuring the intended placement is selected.
5. For Shop Pay: Verify "Include app block in Shop Pay" is checked
6. Clear browser cache or try incognito mode
7. Wait a few minutes for changes to propagate

### Shop Pay widgets not showing

To display widgets in Shop Pay checkout:

1. Open the widget in Shopify Checkout Editor
2. Check the **Include app block in Shop Pay** option under Checkout behaviour
3. Save your changes

<img alt="Shopify Checkout Editor sidebar showing the Aftersell Upsell Widget app block under Main" />

[Learn more about Shop Pay Widgets](/aftersell/show_checkout_widgets_in_shop_pay)

***

## Next steps

* [Learn about checkout triggers](/aftersell/checkout_triggers) to show widgets conditionally
* [Set up checkout A/B testing](/aftersell/checkout_a_b_testing) to optimize placements
* [Configure checkout branding](/aftersell/checkout_branding_settings) to match your store design
* [Explore advanced upsell strategies](/aftersell/best_practices) to maximize AOV


# How to install Rokt Thanks on Tapcart
Source: https://docs.aftersell.com/aftersell/how_to_install_rokt_thanks_on_tapcart

A Setup Guide for TapCart App Studio

## What is Rokt Thanks?

Rokt Thanks displays personalized, non-intrusive offers to your customers on the post-purchase confirmation screen. It's a simple way to generate passive revenue from every order without impacting the customer experience.

This guide walks through how to install Rokt Thanks within your TapCart mobile app using a Custom Code Block. The setup takes just a few minutes.

## Before you start

You will need the following:

* **TapCart Enterprise plan** - Custom Code Blocks are only available on Enterprise. If you're unsure about your plan, check with your TapCart account rep.
* **Your Rokt Account ID** - your Aftersell account manager will provide this. If you don't have it yet, just reach out and we'll send it over.

## Step 1: Create a Custom Block

Log in to your TapCart dashboard and open the App Studio editor. Create a new Custom Block.

## Step 2: Paste the code snippet

In the Custom Block editor, switch to the Dev section. Clear any placeholder code and paste the snippet below:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
import * as React from "react"
 
export default function RoktPlacement({
  blockConfig,
  tapcartData,
  translations,
  pageState,
  useActions,
}) {
  const containerRef = React.useRef(null)
 
  React.useEffect(() => {
    const loadRokt = async () => {
      try {
        await new Promise((resolve, reject) => {
          if (document.getElementById("rokt-launcher")) {
            resolve()
            return
          }
          const script = document.createElement("script")
          script.type = "text/javascript"
          script.src =
            "https://apps.rokt.com/wsdk/integrations/launcher.js"
          script.fetchPriority = "high"
          script.crossOrigin = "anonymous"
          script.async = true
          script.id = "rokt-launcher"
          script.addEventListener("load", () => resolve())
          script.addEventListener("error", (error) => reject(error))
          document.head.appendChild(script)
        })
 
        const launcher = await window.Rokt.createLauncher({
          accountId: "YOUR_ACCOUNT_ID",
          sandbox: true,
        })
 
        await launcher.selectPlacements({
          identifier: "TapCart.success",
          attributes: {
            email: tapcartData?.customer?.email || "",
            firstname:
              tapcartData?.customer?.firstName || "",
            lastname:
              tapcartData?.customer?.lastName || "",
          },
        })
      } catch (error) {
        console.error("Rokt SDK failed to load:", error)
      }
    }
 
    loadRokt()
  }, [])
 
  return <div id="rokt-placeholder" ref={containerRef} />
}
```

<Info>
  ### Replace Your Account ID

  In the snippet above, find the line `accountId: "YOUR_ACCOUNT_ID"` and replace `YOUR_ACCOUNT_ID` with the Account ID provided by your Aftersell account manager.

  Once updated, save the Custom Block.
</Info>

## Step 3: Add to your Post Purchase page

Navigate to your Post Purchase page in TapCart's visual editor. Drag the Custom Block you just created onto the page and drop it wherever you'd like the offers to appear.

## Step 4: Let us know

Once you've completed the steps above, let your Aftersell account manager know. We'll finalize a quick configuration on our end and confirm when everything is live.

The snippet is initially set to sandbox mode (`sandbox: true`), which loads test offers so you can preview the placement. `sandbox` is an option on the launcher in the snippet itself, not a setting on our side — so once we've confirmed everything looks right, edit the Custom Block, change `sandbox: true` to `sandbox: false`, and save. You'll start earning revenue from that point.

## Summary

| Step | Action                                                                                              |
| ---- | --------------------------------------------------------------------------------------------------- |
| 1    | Create a Custom Block in TapCart's App Studio editor                                                |
| 2    | Paste the code snippet into the Dev section (replace `YOUR_ACCOUNT_ID` with your actual Account ID) |
| 3    | Drag the Custom Block onto your Post Purchase page                                                  |
| 4    | Notify your Aftersell account manager so we can finalize setup                                      |

## Frequently asked questions

**Do I need to be on TapCart Enterprise?**

Yes. Custom Code Blocks in App Studio require TapCart's Enterprise plan.

**Will this slow down my app?**

No. The script loads asynchronously and won't block your page from rendering.

**Can I choose where the offer appears on the page?**

Absolutely. Once the Custom Block is saved, you can drag it to any position on your Post Purchase page using TapCart's visual editor.

**What kind of offers will my customers see?**

Rokt Thanks serves relevant, non-intrusive offers from premium advertisers tailored to each customer.


# Image widget (Thank You Page)
Source: https://docs.aftersell.com/aftersell/image-widget-thank-you-page

Configure the Thank You Page Image widget in Aftersell to display a custom image or banner on the post-checkout page.

The Image widget displays a custom image or banner on the Thank You page, useful for promotions, community links, or brand imagery. This page covers every setting on the widget. For the full funnel setup and Shopify editor steps, see [How to configure thank-you page widgets](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell).

Add the widget from the **Thank You Page** section of your funnel by clicking **Add Widget** and selecting **Image**.

## Upload and size the image

1. Click the upload area to add your image.
2. Upload a JPG, PNG, or supported image file.
3. Adjust the **Image width** slider (50-500px) to control how large the image appears.
4. Click **Save**.


# Checkout upsells
Source: https://docs.aftersell.com/aftersell/implementing_strategies_checkout_upsells

Use a Strategy to dynamically choose the product shown in a Shopify Plus checkout upsell widget.

## Overview

When configuring a checkout upsell widget, you can fill the product slot in a few ways: hand-pick a specific product, let AI recommend one, or attach a **Strategy**. Each is a different tool for a different job.

Strategies are for **dynamic merchandising in real time** - pairing the right accessory with a parent product, suggesting a complementary item, or surfacing a different product depending on what's already in the cart. Where checkout **triggers** decide *which* widget appears for a given shopper, a Strategy decides *what product goes inside it*. Triggers are the gateway, Strategies are the brain behind the experience.

***

## Attaching a Strategy to a Checkout Widget

Strategies are attached **per widget**, not to the checkout as a whole. You can mix Strategy-driven widgets and static-product widgets in the same checkout.

1. Open the checkout widget you want to edit.
2. In the **Select product type** menu, choose **Strategy**.
3. In the Strategy picker, search for and select the Strategy you want to use.
4. Click **Confirm**, then save the widget.

Once attached, the widget displays the Strategy's name in place of a specific product. Each time the checkout loads, the Strategy is evaluated and the returned product is rendered in the widget.

<Tip>
  Give your Strategies clear, descriptive names. The Strategy name is what shows up in the widget editor once attached, and it's the easiest way to know at a glance which Strategy is driving which widget.
</Tip>

***

## What the Strategy Sees

Checkout has a **narrower context** than post-purchase. The Strategy is evaluated as the checkout page loads, before the order is placed - so customer history and session attribution aren't available yet. The following is what gets sent automatically:

#### Product context

The line items currently in the cart are sent as the input products. Triggers like **product tags**, **product collections**, **product type**, **vendor**, and **product metafields** all evaluate against these items.

**Selling plan doesn't evaluate here.** Checkout line items don't carry a selling plan in this payload, so a **Selling plan** trigger never matches on checkout widgets.

#### Cart context

* **Subtotal** - the cart subtotal.
* **Item count** - total quantity across all lines.
* **Line count** - number of distinct line items.

<Warning>
  **Customer and session triggers won't match in checkout.** Customer tags, order count, country, locale, and UTM parameters are not part of the checkout payload. If a Strategy used in a checkout widget relies on these triggers, those rules will never fire, and only product- or cart-scoped rules (or the Catch all) will be able to return a product.
</Warning>

***

## What Happens When the Strategy Returns

The product(s) returned by the Strategy **replace** the placeholder in the widget - they don't add to it. The shopper sees the widget as if you had hand-picked that product yourself.

The widget fills its slots from the returned products in priority order, up to the number of offers the widget is configured to show. A single-offer widget uses the first returned product.

***

## When No Product Is Returned

If no rules match and the Strategy returns no products, the widget is **not shown** to the shopper - the slot disappears entirely from the checkout.

To keep your widget firing, configure a **Catch all** in the Strategy so there is always a fallback product to return. See the [Building Strategies](/aftersell/strategies_building_in_app) page for how to set up a Catch all.

***

## Evaluation Timing

By default, a Strategy on a checkout widget is evaluated **once, when the checkout page loads**. The product chosen at page load remains the product shown, even if the shopper adds or removes items during checkout.

If the widget has **flexible trigger re-checking** enabled, the Strategy is instead re-evaluated whenever the cart changes during checkout, and the widget updates to reflect the new cart - similar to how the [Upcart integration](/aftersell/implementing_strategies_upcart_upsells) behaves. Plan your rules around whichever mode the widget uses: a fixed snapshot at checkout load, or a live re-evaluation on every cart change.

***

## Tips for Checkout Strategies

* **Design around products and cart only.** Customer- and session-scoped triggers will never match in checkout, so build Strategies around product attributes (tags, collections, metafields) and cart shape (subtotal, item count, line count).
* **Use Catch all as a safety net.** A Strategy without a Catch all will hide the widget if nothing matches. A simple Catch all keeps the slot showing *something*.
* **Mix dynamic and static widgets.** Not every widget has to be Strategy-driven. A common pattern is a Strategy on the primary upsell widget (most personalized) and a static product on a secondary widget (proven seller).


# Custom integration
Source: https://docs.aftersell.com/aftersell/implementing_strategies_custom_integration

Call the Strategies API directly to power custom storefront experiences - PDP carousels, custom cart upsells, and anywhere else Aftersell's native surfaces don't reach.

## Overview

When neither Aftersell's native surfaces (post-purchase, checkout, Upcart) nor a packaged integration fits, you can call the Strategies API yourself from your Shopify theme and render the returned products however you like.

The pattern is the same in every case: build a context payload from Liquid (so Shopify attributes like the current product, cart contents, and customer fields are filled in at render time), `POST` it to `/api/public/strategy/evaluate`, and render the response.

This page covers two implementation patterns:

* **PDP context** - drop a section onto product pages that calls the API with the **currently-viewed product** and renders a carousel of returned recommendations.
* **Cart context** - render an upsell block inside a custom cart that calls the API with **all current cart line items** and renders the returned products.

The shape of the **product context** is what differs between the two: a single product on PDP, an array of all line items in cart.

***

## What You'll Need

1. **Your Strategy API key.** In Aftersell, go to **Settings → Product Strategy** and, in the **Security Token** card, copy your token (this is your Strategy API key).
2. **The Strategy ID.** Open the Strategy you want to run in the Aftersell Strategy editor and copy its ID.
3. **Theme code access.** You'll be adding a Liquid section (PDP) or block (custom cart) to your Shopify theme - Online Store → Themes → ... → Edit code.

<Warning>
  Your Strategy API key sits in client-side theme code, which makes it visible to anyone who views the page source. Treat it as a public storefront credential and rotate it from Aftersell **Settings → Product Strategy** if it's ever exposed in a way you didn't intend.
</Warning>

***

## PDP Context: Section Snippet

This pattern adds a Shopify section to your product page. When the page renders, Liquid embeds the current product, cart, and customer attributes into the payload, then JavaScript posts to the Strategies API and renders the returned products in a Splide carousel.

### Installing

1. In your Shopify admin, go to **Online Store → Themes**, click **...** on your theme, and select **Edit code**.
2. Under the **Sections** folder, create a new file named `aftersell-upsell-carousel.liquid`.
3. Paste the snippet below into the new file and replace `YOUR_STRATEGY_API_KEY` with the API key from Aftersell.
4. Save.
5. Open your product template (typically `templates/product.json` or `sections/main-product.liquid`) and add the **Aftersell Carousel** section where you want the carousel to appear. From the theme editor, you can also drag it onto the product page directly.
6. In the section's settings, paste your **Strategy ID**.

### What the section sends

For each PDP view, the payload includes:

* **products** - a single-element array containing the currently-viewed product (productId, variantId, quantity, price, handle, title, vendor, productType, tags, collections, sellingPlan).
* **cart** - subtotal, item count, line count of the shopper's current cart (omitted if the cart is empty).
* **cartToken** - so the API can stitch this evaluation into the same session.
* **customer** - tags, country, province, locale, order count, total spent, and accepts-marketing flag, but **only if the shopper is logged in**.
* **session** - currency code from `shop.currency`.

The section does not send UTM parameters by default. If you want UTM-based targeting on PDP, capture them client-side and add them to the `session` object before the fetch.

### The snippet

```liquid theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{% comment %}
  Aftersell Carousel (Splide)
  Type: Section — save to sections/aftersell-upsell-carousel.liquid
{% endcomment %}

{% if product %}

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@splidejs/splide@4.1.4/dist/css/splide-core.min.css">
<script src="https://cdn.jsdelivr.net/npm/@splidejs/splide@4.1.4/dist/js/splide.min.js" defer></script>

<div id="aftersell-upsell-{{ section.id }}" class="aftersell-upsell-carousel" style="display:none" {{ section.shopify_attributes }}>
  <h2 class="aftersell-heading">{{ section.settings.heading | default: 'You might also like' }}</h2>
  <div class="aftersell-carousel-wrapper">
    <button class="aftersell-arrow aftersell-arrow--prev" aria-label="Previous" disabled>&#8592;</button>
    <div class="aftersell-track-container">
      <div class="splide" id="aftersell-splide-{{ section.id }}">
        <div class="splide__track">
          <ul class="splide__list">
            <li class="splide__slide"><div class="aftersell-skeleton"></div></li>
            <li class="splide__slide"><div class="aftersell-skeleton"></div></li>
            <li class="splide__slide"><div class="aftersell-skeleton"></div></li>
            <li class="splide__slide"><div class="aftersell-skeleton"></div></li>
          </ul>
        </div>
      </div>
    </div>
    <button class="aftersell-arrow aftersell-arrow--next" aria-label="Next" disabled>&#8594;</button>
  </div>
</div>

<style>
.aftersell-upsell-carousel { font-family: Modernist, sans-serif; max-width: 1300px; margin: 0 auto; padding: 24px 0 0; box-sizing: border-box; }
.aftersell-heading { font-family: Modernist, sans-serif; font-size: 30px; font-weight: 700; line-height: 45px; color: #0C0A09; margin: 0; }
.aftersell-carousel-wrapper { display: flex; align-items: center; gap: 8px; }
.aftersell-track-container { overflow: hidden; flex: 1; min-width: 0; }
.aftersell-card { display: flex; flex-direction: column; box-sizing: border-box; height: 100%; }
.aftersell-card-link { text-decoration: none; color: inherit; display: block; flex: 1; }
.aftersell-card-image { aspect-ratio: 1; overflow: hidden; background: #f5f5f5; border-radius: 8px 8px 0 0; position: relative; }
.aftersell-card-image img { width: 100%; height: 100%; object-fit: cover; display: block; transition: transform 0.3s ease; }
.aftersell-card-image:hover img { transform: scale(1.04); }
.aftersell-card-badge { position: absolute; top: 10px; left: 8px; background: #c60006; color: #fff; font-size: 11px; font-weight: 500; padding: 4px 8px; border-radius: 16px; z-index: 1; }
.aftersell-card-body { padding: 6px 0 0; display: flex; flex-direction: column; }
.aftersell-card-vendor { font-size: 13px; font-weight: 550; text-transform: uppercase; color: #1d4481; margin: 0; }
.aftersell-card-title { font-size: 13px; font-weight: 700; color: #0C0A09; margin: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
.aftersell-card-price { font-size: 13px; color: #0C0A09; margin: 0; display: flex; gap: 6px; align-items: center; flex-wrap: wrap; }
.aftersell-card-price--compare { text-decoration: line-through; color: #595959; }
.aftersell-card-price--sale { font-weight: 700; color: #c60006; }
.aftersell-card-actions { padding: 6px 0 0; display: flex; flex-direction: column; margin-top: auto; }
.aftersell-variant-select { width: 100%; font-size: 13px; padding: 0.35rem 0.5rem; border: 1px solid #DBDBDB; border-radius: 4px; background: #fff; color: #0C0A09; cursor: pointer; }
.aftersell-cta { padding: 16px 12px; background: #c50007; color: #FFFFFF; border: none; border-radius: 5px; font-size: 16px; font-weight: 700; cursor: pointer; width: 100%; display: flex; align-items: center; justify-content: center; transition: background 0.2s, opacity 0.2s; }
.aftersell-cta:hover:not(:disabled) { opacity: 0.85; }
.aftersell-cta:disabled { opacity: 0.5; cursor: default; }
.aftersell-cta--added { background: #1d4481; }
.aftersell-cta--unavailable { background: #999; cursor: default; }
.aftersell-arrow { width: 30px; height: 90px; background: rgba(255,255,255,0.6); border: 1px solid #DBDBDB; border-radius: 5px; cursor: pointer; display: flex; align-items: center; justify-content: center; flex-shrink: 0; padding: 0; }
.aftersell-arrow:disabled { opacity: 0.3; cursor: default; }
.aftersell-skeleton { border-radius: 8px; background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%); background-size: 200% 100%; animation: aftersell-shimmer 1.4s infinite; aspect-ratio: 0.75; width: 100%; }
@keyframes aftersell-shimmer { 0% { background-position: 200% 0; } 100% { background-position: -200% 0; } }

#aftersell-splide-{{ section.id }} .splide__arrows,
#aftersell-splide-{{ section.id }} .splide__pagination { display: none !important; }

@media (max-width: 768px) {
  .aftersell-upsell-carousel { padding: 16px 16px 0; }
  .aftersell-arrow { display: none; }
  .aftersell-carousel-wrapper { gap: 0; }
}
</style>

<script>
(function() {
  var BACKEND_URL  = 'https://start.aftersell.app';
  var API_KEY      = 'YOUR_STRATEGY_API_KEY';
  var STRATEGY_ID  = {{ section.settings.strategy_id | json }};
  var SHOP_DOMAIN  = {{ shop.permanent_domain | json }};
  var CTA_LABEL    = '{{ section.settings.cta_label | default: "Add to cart" }}';
  var MAX_PRODUCTS = {{ section.settings.max_products | default: 8 }};
  var CURRENCY     = {{ shop.currency | default: "USD" | json }};
  var SECTION_ID   = {{ section.id | json }};
  if (!SHOP_DOMAIN || !STRATEGY_ID) return;

  var fmt;
  try {
    fmt = new Intl.NumberFormat('en-US', { style: 'currency', currency: CURRENCY });
  } catch(e) {
    fmt = { format: function(n) { return '$' + parseFloat(n).toFixed(2); } };
  }
  function money(str) { return fmt.format(parseFloat(str) || 0); }

  function gidToNumeric(gid) {
    return gid ? String(gid).split('/').pop() : null;
  }

  function priceHtml(price, compareAt) {
    var hasSale = compareAt && parseFloat(compareAt) > parseFloat(price);
    return hasSale
      ? '<span class="aftersell-card-price--compare">' + money(compareAt) + '</span>'
        + '<span class="aftersell-card-price--sale">' + money(price) + '</span>'
      : '<span class="aftersell-card-price--current">' + money(price) + '</span>';
  }

  var productContext = {
    productId:   'gid://shopify/Product/{{ product.id }}',
    variantId:   'gid://shopify/ProductVariant/{{ product.selected_or_first_available_variant.id }}',
    quantity:    1,
    price:       {{ product.price | divided_by: 100.0 }},
    handle:      {{ product.handle | json }},
    title:       {{ product.title | json }},
    vendor:      {{ product.vendor | json }},
    productType: {{ product.type | json }},
    tags:        {{ product.tags | json }},
    collections: [{% for col in product.collections %}'gid://shopify/Collection/{{ col.id }}'{% unless forloop.last %},{% endunless %}{% endfor %}],
    sellingPlan: {% if product.selected_selling_plan %}'subscription'{% else %}'one-time'{% endif %}
  };

  var cartContext = {
    subtotal:  {{ cart.total_price | divided_by: 100.0 }},
    itemCount: {{ cart.item_count }},
    lineCount: {{ cart.items.size }}
  };

  {% if customer %}
  var customerContext = {
    customerId:       'gid://shopify/Customer/{{ customer.id }}',
    tags:             {{ customer.tags | json }},
    {% if customer.default_address.country_code %}countryCode: {{ customer.default_address.country_code | json }},{% endif %}
    {% if customer.default_address.province_code %}provinceCode: {{ customer.default_address.province_code | json }},{% endif %}
    locale:           {{ request.locale.iso_code | json }},
    orderCount:       {{ customer.orders_count }},
    totalSpent:       {{ customer.total_spent | times: 1.0 }},
    acceptsMarketing: {{ customer.accepts_marketing }}
  };
  {% endif %}

  var blockEl  = document.getElementById('aftersell-upsell-' + SECTION_ID);
  var splideEl = document.getElementById('aftersell-splide-' + SECTION_ID);
  var list     = splideEl.querySelector('.splide__list');
  var prevBtn  = blockEl.querySelector('.aftersell-arrow--prev');
  var nextBtn  = blockEl.querySelector('.aftersell-arrow--next');
  var splideInstance = null;

  function getCartToken() {
    var t = {{ cart.token | json }};
    if (t) return Promise.resolve(t);
    return fetch('/cart.js').then(function(r){ return r.json(); }).then(function(c){ return c.token || null; }).catch(function(){ return null; });
  }

  function evaluate() {
    getCartToken().then(function(cartToken) {
      if (!cartToken) return;
      return fetch(BACKEND_URL + '/api/public/strategy/evaluate', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'X-Strategy-Api-Key': API_KEY },
        body: JSON.stringify({
          shopDomain:  SHOP_DOMAIN,
          strategyId:  STRATEGY_ID,
          context: {
            products:  [productContext],
            cartToken: cartToken,
            cart:      cartContext.itemCount > 0 ? cartContext : undefined,
            {% if customer %}customer: customerContext,{% endif %}
            session:   { currencyCode: CURRENCY }
          }
        })
      });
    }).then(function(res) { if (!res) return; return res.json(); })
    .then(function(data) {
      if (!data || !data.success || !data.products || !data.products.length) {
        clearSkeletons(); return;
      }
      renderCards(data.products.slice(0, MAX_PRODUCTS));
    }).catch(function(err) {
      console.error('[AfterSell carousel] Error:', err);
      clearSkeletons();
    });
  }

  function renderCards(products) {
    if (!products || !products.length) {
      blockEl.style.display = 'none'; return;
    }

    blockEl.style.display = '';

    list.innerHTML = products.map(function(p, i) {
      var img      = p.images && p.images[0] ? p.images[0].src : '';
      var alt      = (p.images && p.images[0] && p.images[0].altText) || p.title;
      var variants = p.variants || [];
      var availableVariants = variants.filter(function(v) {
        return v.availableForSale !== false;
      });
      var isDefaultVariant = variants.length === 1 && variants[0].title === 'Default Title';
      var showSelect       = !isDefaultVariant && availableVariants.length >= 1;
      var firstVariant     = availableVariants.length ? availableVariants[0] : null;
      var firstVariantId   = firstVariant ? gidToNumeric(firstVariant.variantId) : null;
      var anyAvailable     = availableVariants.length > 0;

      var onSale = p.compareAtPrice && parseFloat(p.compareAtPrice) > parseFloat(p.price);
      var badge  = '';
      if (onSale) {
        var pct = Math.round((1 - parseFloat(p.price) / parseFloat(p.compareAtPrice)) * 100);
        badge = '<span class="aftersell-card-badge">Save ' + pct + '%</span>';
      }
      var vendor = p.vendor ? '<p class="aftersell-card-vendor">' + p.vendor + '</p>' : '';

      var selectHtml = '';
      if (showSelect) {
        var options = availableVariants.map(function(v) {
          return '<option value="' + gidToNumeric(v.variantId) + '"'
            + ' data-price="'   + (v.price         || p.price) + '"'
            + ' data-compare="' + (v.compareAtPrice || '')     + '"'
            + '>' + v.title + '</option>';
        }).join('');
        selectHtml = '<select class="aftersell-variant-select" aria-label="Select variant">' + options + '</select>';
      }

      var atcLabel = anyAvailable ? CTA_LABEL : 'Sold Out';
      var atcClass = anyAvailable ? 'aftersell-cta' : 'aftersell-cta aftersell-cta--unavailable';
      var atcBtn   = '<button class="' + atcClass + '"'
        + (firstVariantId ? ' data-variant-id="' + firstVariantId + '"' : '')
        + (anyAvailable ? '' : ' disabled')
        + '>' + atcLabel + '</button>';

      var productUrl = p.url + (p.url.indexOf('?') > -1 ? '&' : '?') + 'ref=aftersell';

      return '<li class="splide__slide">'
        + '<div class="aftersell-card" data-idx="' + i + '">'
        + '<a class="aftersell-card-link" href="' + productUrl + '">'
        + '<div class="aftersell-card-image">' + badge
        + (img ? '<img src="' + img + '" alt="' + alt + '" loading="lazy">' : '')
        + '</div>'
        + '<div class="aftersell-card-body">'
        + vendor
        + '<p class="aftersell-card-title">' + p.title + '</p>'
        + '<p class="aftersell-card-price" data-price-el>' + priceHtml(p.price, p.compareAtPrice) + '</p>'
        + '</div></a>'
        + '<div class="aftersell-card-actions">'
        + selectHtml
        + atcBtn
        + '</div></div></li>';
    }).join('');

    attachCardEvents();
    initSplide();
  }

  function attachCardEvents() {
    list.addEventListener('change', function(e) {
      if (!e.target.classList.contains('aftersell-variant-select')) return;
      var select  = e.target;
      var card    = select.closest('.aftersell-card');
      var opt     = select.options[select.selectedIndex];
      var priceEl = card.querySelector('[data-price-el]');
      var btn     = card.querySelector('.aftersell-cta');
      priceEl.innerHTML     = priceHtml(opt.getAttribute('data-price'), opt.getAttribute('data-compare'));
      btn.dataset.variantId = opt.value;
      btn.disabled          = false;
      btn.textContent       = CTA_LABEL;
      btn.className         = 'aftersell-cta';
    });

    list.addEventListener('click', function(e) {
      var btn = e.target.closest('.aftersell-cta');
      if (!btn || btn.disabled) return;
      var variantId = btn.dataset.variantId;
      if (!variantId) return;

      e.preventDefault();
      btn.disabled    = true;
      btn.textContent = 'Adding…';

      fetch('/cart/add.js', {
        method: 'POST',
        credentials: 'same-origin',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          id: parseInt(variantId, 10),
          quantity: 1,
          properties: {
            "_source": "Aftersell",
            "_attribution": "CTA"
          }
        })
      })
      .then(function(r) {
        if (!r.ok) throw new Error('Cart add failed: ' + r.status);
        return r.json();
      })
      .then(function() {
        btn.textContent = 'Added!';
        btn.classList.add('aftersell-cta--added');
        if (typeof window.theme !== 'undefined' && window.theme.cart && window.theme.cart.open) {
          window.theme.cart.open();
        }
        setTimeout(function() {
          btn.textContent = CTA_LABEL;
          btn.classList.remove('aftersell-cta--added');
          btn.disabled = false;
        }, 2500);
      })
      .catch(function(err) {
        console.error('[AfterSell carousel] Add to cart error:', err);
        btn.textContent = 'Try Again';
        btn.disabled    = false;
      });
    });
  }

  function initSplide() {
    function mount() {
      if (typeof window.Splide === 'undefined') {
        setTimeout(mount, 50);
        return;
      }

      splideInstance = new Splide('#aftersell-splide-' + SECTION_ID, {
        type:       'slide',
        perPage:    4,
        perMove:    4,
        gap:        '10px',
        pagination: false,
        arrows:     false,
        speed:      350,
        drag:       false,
        breakpoints: {
          768: { perPage: 2, perMove: 2, drag: 'free', snap: true },
          480: { perPage: 1, perMove: 1, drag: 'free', snap: true, padding: { right: '25%' } }
        }
      }).mount();

      function updateArrows() {
        var idx = splideInstance.index;
        var end = splideInstance.length - splideInstance.options.perPage;
        prevBtn.disabled = idx <= 0;
        nextBtn.disabled = idx >= end;
      }

      prevBtn.addEventListener('click', function() { splideInstance.go('<'); });
      nextBtn.addEventListener('click', function() { splideInstance.go('>'); });
      splideInstance.on('moved', updateArrows);
      updateArrows();
    }
    mount();
  }

  function clearSkeletons() { list.innerHTML = ''; }

  evaluate();
})();
</script>

{% endif %}

{% schema %}
{
  "name": "Aftersell Carousel",
  "settings": [
    { "type": "text",  "id": "strategy_id",  "label": "AfterSell Strategy ID", "default": "ADD_ID_HERE" },
    { "type": "text",  "id": "heading",      "label": "Heading",               "default": "You might also like" },
    { "type": "text",  "id": "cta_label",    "label": "CTA Button Label",      "default": "Add to cart" },
    { "type": "range", "id": "max_products", "label": "Max Products to Show",  "default": 8, "min": 1, "max": 20, "step": 1 }
  ],
  "presets": [{ "name": "Aftersell Carousel" }]
}
{% endschema %}
```

<Frame>
  <img alt="A Strategy-powered product carousel rendered on a Shopify product page" />
</Frame>

### Customizing

The section schema exposes four merchant-editable settings: **Strategy ID**, **Heading**, **CTA Button Label**, and **Max Products to Show**. Add or remove settings in the `{% schema %}` block to expose more knobs to the theme editor.

The CSS is scoped under `.aftersell-*` class names and includes a Splide-driven 4-up carousel that drops to 2-up at 768px and 1-up at 480px. Edit it freely to match your theme - none of it is required for the API call to work.

***

## Cart Context: Custom Cart Upsell Block

This pattern is structurally the same as the PDP one, with one key difference: the **product context array** is built from the cart's line items instead of the currently-viewed product. The Strategy then receives every item the shopper has added and returns recommendations based on the cart as a whole.

The implementation lives wherever your custom cart code lives - a Liquid section that renders the cart drawer, a custom block in a headless storefront, or a theme template like `cart.liquid`. The shape of the API call and the response handling are identical to the PDP example - only the `products` array differs.

The structure looks like:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
var products = {{ cart.items | json }}.map(function(item) {
  return {
    productId: 'gid://shopify/Product/' + item.product_id,
    variantId: 'gid://shopify/ProductVariant/' + item.variant_id,
    quantity:  item.quantity,
    price:     item.price / 100
    // ...other fields as needed
  };
});
```

The rest of the payload (cart, customer, session, cartToken) and the `fetch` call to `/api/public/strategy/evaluate` are unchanged from the PDP pattern above - only the `products` array swaps from `[productContext]` to the cart-derived array.

***

## What Happens When the Strategy Returns

The response shape is the same regardless of which context you sent:

```json theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{
  "success": true,
  "products": [ /* enriched recommended products */ ],
  "evaluationId": "f3a1c2e0-...",
  "resolution": { "strategyId": "...", "matchedRuleIds": [...], "fallbackUsed": false },
  "meta": { "servedFromCache": false, "processingTimeMs": 12, "data": {} }
}
```

The `evaluationId` is a unique id for this evaluation. If you capture it and attach it to the products you render, you can attribute the resulting order back to the exact recommendation that produced it - see [Attribution](#attribution) below.

How you render the `products` array is entirely up to your theme code. The PDP snippet above renders them as a carousel of cards with variant pickers and add-to-cart buttons; a custom cart block might render them as a vertical list inside the drawer.

For the full request and response schema, see the [Evaluate Strategy API reference](/aftersell/strategies_api_reference_evaluate_strategy).

***

## When No Product Is Returned

If the Strategy returns no products (`products: []`), it's up to your code how to handle it. The PDP snippet above hides the carousel entirely. A custom cart block might fall back to the cart's default upsell list, or simply render nothing.

To avoid an empty response, configure a **Catch all** in the Strategy so there is always a fallback product to return. See the [Building Strategies](/aftersell/strategies_building_in_app) page for how to set up a Catch all.

***

## Tips for Custom Integrations

* **Build context in Liquid.** Liquid runs at render time and has access to the full Shopify object graph - product, cart, customer, shop, request. Use it to populate the payload server-side rather than reaching for client-side calls.
* **Keep the API key out of public repos.** It will end up in your theme code, which is shipped to the browser - that's fine. But don't paste the same theme into a public repository or share the bundle externally.
* **Use a Catch all.** Storefront experiences look broken when a slot disappears. A Catch all with a small set of safe defaults keeps the UI consistent.
* **Cache where it makes sense.** The Strategies API does light caching server-side (`meta.servedFromCache`), but for high-traffic PDPs you may also want to debounce or memoize calls on the client (e.g. don't re-call when the same product is rendered twice in a session).

***

## Attribution

When a shopper clicks the add-to-cart button in the snippet, the `/cart/add.js` call attaches **line item properties** to the cart item:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: {
  "_source": "Aftersell",
  "_attribution": "CTA"
}
```

These properties travel with the line item all the way through to the Shopify order, where they appear on the line item record. You can use them downstream to attribute revenue, filter orders, or feed analytics tools that read line item properties.

The keys and values are conventions, not requirements - the API call works the same regardless of what you put here. Change them to fit your own attribution model. For example:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: {
  "_source": "PDP Carousel",
  "_strategy_id": "{{ section.settings.strategy_id }}",
  "_campaign": "summer-2026"
}
```

<Tip>
  Property keys that begin with an underscore (`_`) are hidden from the cart and checkout UI but still attach to the order. Use the underscore prefix for attribution-only metadata you don't want shoppers to see.
</Tip>

Apply the same pattern in the cart-context implementation - any add-to-cart call you make from a custom upsell block can carry whatever properties you need.

### Attributing back to the evaluation

To tie an order back to the **exact evaluation** that recommended the product - rather than just "came from a Strategy" - capture the `evaluationId` from the response and attach it to the line item under the `__as_offer_id` property. AfterSell reads this key, so orders tagged with it attribute to the specific evaluation in reporting.

In the `evaluate()` handler, hold onto the id from the response:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.then(function(data) {
  if (!data || !data.success || !data.products || !data.products.length) {
    clearSkeletons(); return;
  }
  evaluationId = data.evaluationId; // declare `var evaluationId;` alongside your other state
  renderCards(data.products.slice(0, MAX_PRODUCTS));
})
```

Then include it in the add-to-cart properties:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: Object.assign(
  { "_source": "Aftersell", "_attribution": "CTA" },
  evaluationId ? { "__as_offer_id": evaluationId } : {}
)
```

Keep the double underscore on `__as_offer_id` - it's the key AfterSell looks for, and the underscore prefix keeps it hidden from shoppers. If `evaluationId` is absent (for example, no products were returned), skip the property rather than sending an empty value.


# Post-purchase upsells
Source: https://docs.aftersell.com/aftersell/implementing_strategies_post_purchase_upsells

Use a Strategy to dynamically choose the product shown in a post-purchase upsell offer.

## Overview

When configuring a post-purchase offer, you can fill the product slot in a few ways: hand-pick a specific product, let AI recommend one, or attach a **Strategy**. Each is a different tool for a different job.

Strategies are for **dynamic merchandising in real time** - pairing the right accessory with a parent product, suggesting the next step in a routine, or surfacing a complementary item. Where triggers initiate a funnel + layout; a Strategy then decides what products go inside it. Triggers are the gateway, Strategies are the brain behind the experience.

***

## Attaching a Strategy to a post-purchase offer

Strategies are attached **per offer step**, not to the funnel as a whole. You can mix strategy-driven steps and static-product steps in the same funnel.

1. Open the funnel you want to edit and go to the **Upsells** section.
2. On the upsell slot you want to configure, click **Create your first offer** (or **+** to add another offer).
3. Under **Select type**, choose **Single product upsell** or **Multi product upsell**.
4. Under **Select product type**, choose **Strategy**.
5. In the Strategy picker, search for and select the Strategy you want to use.
6. Click **Confirm**, then save the funnel.

<Frame>
  <img alt="Selecting Strategy as the product type when creating a post-purchase upsell offer" />
</Frame>

Once attached, the offer step displays the Strategy's name in place of a specific product. Each time the offer is shown, the Strategy is evaluated and the returned product is rendered.

<Tip>
  Give your Strategies clear, descriptive names. The Strategy name is what shows up in the funnel editor once attached, and it's the easiest way to know at a glance which Strategy is driving which offer step.
</Tip>

***

## What the Strategy sees

When a post-purchase offer evaluates a Strategy, the following context is sent automatically. You don't need to configure any of it - it's pulled from the shopper's order and session as the offer is prepared.

#### Product context

The line items from the just-completed order are sent as the input products. Triggers like **product tags**, **product collections**, **product type**, **vendor**, and **product metafields** all evaluate against these items.

**Selling plan doesn't evaluate here.** The order's line items don't carry a selling plan in this payload, so a **Selling plan** trigger never matches on post-purchase offers.

#### Cart context

* **Subtotal** - the order subtotal.
* **Item count** - total quantity across all lines.
* **Line count** - number of distinct line items.

#### Customer context

* **Customer tags**
* **Order count** (lifetime orders for the customer)
* **Country / province**
* **Locale**

Country, province, and locale are read from the order itself and are available for every checkout. Customer tags and order count come from the Shopify customer record - they populate as soon as the checkout is linked to a customer (which Shopify does once a recognized email is entered, or when a new customer record is created).

#### Session context

Post-purchase offers don't send a session context automatically - no landing URL, shipping, or store-currency data is included in the payload. **Marketing** and **Location** triggers (see [Building Strategies](/aftersell/strategies_building_in_app)) won't match on post-purchase offers unless you evaluate the Strategy yourself through a [custom integration](/aftersell/implementing_strategies_custom_integration) and supply that context.

***

## What happens when the Strategy returns

The product(s) returned by the Strategy **replace** the placeholder in the offer step - they don't add to it. The shopper sees the offer as if you had hand-picked that product yourself.

A single-product offer uses the first returned product. A multi-product offer fills its slots from the returned products in priority order.

***

## When no product is returned

If no rules match and the Strategy returns no products, the post-purchase upsell is **not shown** to the shopper.

To keep your funnel firing, configure a **Catch all** in the Strategy so there is always a fallback product to return. See the [Building Strategies](/aftersell/strategies_building_in_app) page for how to set up a Catch all.

***

## Tips for post-purchase Strategies

* **Use Catch all as a safety net.** A Strategy without a Catch all will skip the offer step if nothing matches. A simple Catch all keeps the funnel showing *something*.
* **Mix dynamic and static steps.** Not every step has to be Strategy-driven. A common pattern is a Strategy on the first offer (most personalized) and a static fallback offer on the second offer (proven seller).


# Thank you page upsells
Source: https://docs.aftersell.com/aftersell/implementing_strategies_thank_you_page_upsells

Use a Strategy to dynamically choose the products shown in a Thank You Page product recommendation widget.

## Overview

When configuring a Thank You Page **product recommendation** widget, you can fill it in a few ways: hand-pick specific products, return a collection, let AI recommend products, or attach a **Strategy**. Each is a different tool for a different job.

Strategies are for **dynamic merchandising in real time** - pairing the right add-on with what the shopper just bought, surfacing a complementary item, or recommending the next step in a routine. Where the Thank You Page widget decides *where* recommendations appear, a Strategy decides *what products go inside it* - evaluated fresh against each order.

A Strategy on the Thank You Page can also override each card's copy and apply a per-product discount, so different products can carry different messaging and pricing. See [Rule copy and per-product discounts](#rule-copy-and-per-product-discounts).

***

## Attaching a Strategy to a Thank You Page Widget

A Strategy is the product source for a single product recommendation widget. It is **exclusive** - a widget sourced by a Strategy can't also use specific products, a collection, or AI recommendations.

1. Open the Thank You Page funnel and edit the **product recommendation** widget you want to configure.
2. In the **Add upsell products** menu, choose **Strategy**.
3. In the Strategy picker, search for and select the Strategy you want to use.
4. Confirm, then save the widget.

Once attached, the widget shows the Strategy's name in place of specific products. Each time the Thank You Page loads, the Strategy is evaluated and the returned products are rendered in the widget.

<Tip>
  Give your Strategies clear, descriptive names. The Strategy name is what shows up in the widget editor once attached, and it's the easiest way to know at a glance which Strategy is driving which widget.
</Tip>

***

## What the Strategy Sees

When a Thank You Page widget evaluates a Strategy, the following context is sent automatically. You don't need to configure any of it - it's pulled from the completed order and session as the page loads.

#### Product context

The line items from the **just-completed order** are sent as the input products. Product triggers - **product tags**, **product collections**, **product type**, **vendor**, **title**, **handle**, and **product metafields** - all evaluate against these items. Their attributes are resolved automatically, so you only need rules; you don't have to supply product data yourself.

<Note>
  The products the shopper just bought are automatically **excluded** from the results, so a Strategy never re-recommends an item that's already in the order.
</Note>

#### Cart context

* **Subtotal** - the order subtotal (in the store's major currency units, e.g. dollars).
* **Item count** - total quantity across all lines.
* **Line count** - number of distinct line items.

#### Customer context

* **Customer tags**
* **Order count** (lifetime orders for the customer)
* **Country / province** (the order's destination)
* **Locale**

#### Session context

UTM parameters captured when the shopper arrived at the store:

* **UTM source**
* **UTM medium**
* **UTM campaign**
* **UTM content**
* **UTM term**

<Warning>
  **Some triggers won't match on the Thank You Page.** Cart notes and cart attributes, customer total spent and accepts-marketing, the selling-plan trigger, and the shipping/store-currency triggers are not part of the Thank You Page payload. Rules that rely on these triggers will never fire here - build Thank You Page Strategies around product attributes, cart shape, customer tags / order count / location, and UTM parameters.
</Warning>

***

## Rule copy and per-product discounts

A Strategy gives you per-product control over both the **copy** and the **discount** shown on each Thank You Page card.

* **Rule copy** - a matching rule can set a **title**, **subtitle**, and **button (CTA) label** for the products it returns. When present, the rule's title appears above the product title (it doesn't replace it), the subtitle shows as a secondary line, and the CTA overrides the widget's button text. Cards whose products didn't come from a rule with copy render unchanged.
* **Per-product discount** - a matching rule can set a discount (a percentage, or a fixed amount) that applies to the products it returns. This **overrides** the widget's configured discount, per product - so different rules can show different discounts on different cards. The discount shown on the card is the discount actually charged when the shopper accepts.

The widget's own discount setting becomes the **default**: it applies to any returned product that the Strategy doesn't set a discount for.

<Warning>
  A **fixed-amount** discount in a currency other than the order's currency can't be applied, so the card falls back to the widget's configured discount instead. **Percentage** discounts always apply regardless of currency.
</Warning>

***

## What Happens When the Strategy Returns

The widget renders the products the Strategy returns, in priority order, up to the widget's **maximum products to show**. Only products that are available for purchase are shown.

The Strategy's products **replace** the widget's placeholder - the shopper sees the widget as if you had hand-picked those products yourself.

***

## When No Product Is Returned

If the Strategy returns no products, the widget renders **nothing** - it's hidden from the Thank You Page. The page never breaks: if a Strategy can't be evaluated for any reason, the widget simply doesn't show.

To keep the widget firing, configure a **Catch all** in the Strategy so there is always a fallback product to return. See the [Building Strategies](/aftersell/strategies_building_in_app) page for how to set up a Catch all. (Catch-all fallback products are shown without rule copy or a per-product discount.)

***

## Evaluation Timing

A Strategy on a Thank You Page widget is evaluated **once, when the Thank You Page loads**. The order is already placed, so there's nothing to re-evaluate against - the products chosen at load are the products shown.

***

## How Shoppers Accept

How an accepted upsell is processed depends on the funnel's order-handling setting:

* **New order** - the shopper completes a separate, discounted checkout for the upsell product.
* **Modify original order** - the upsell is merged into the order the shopper just placed.

Either way, the product, variant, and discount are re-validated against what the Strategy returned before the order is created or edited - so the price charged always matches the price shown.

***

## Tips for Thank You Page Strategies

* **Design around the order.** Product attributes (tags, collections, type, vendor, metafields), cart shape (subtotal, item/line count), customer tags / order count / location, and UTM parameters are the signals available here.
* **Lean on copy and per-product discounts.** Use rule copy to tailor the pitch per product, and per-product discounts to vary pricing by rule - with the widget discount as a safe default.
* **Use Catch all as a safety net.** Without one, the widget shows nothing whenever no rule matches.


# Upcart upsells
Source: https://docs.aftersell.com/aftersell/implementing_strategies_upcart_upsells

Use a Strategy to dynamically choose the products shown in Upcart's upsells module.

## Overview

Upcart is a separate app from Aftersell, so Strategies aren't baked into the Upsells module the way they are in Aftersell's post-purchase and checkout flows. Instead, you bridge the two apps with a small script that calls the Strategies API directly and feeds the result into Upcart's existing Upsells module via Upcart's public API.

The script is **drop-in** - paste it once into Upcart's custom HTML, replace two values (your Strategy API key and the Strategy ID), and the Upsells module will start surfacing whatever products the Strategy returns.

***

## What You'll Need

1. **Your Strategy API key.** In Aftersell, go to **Settings → Product Strategy** and, in the **Security Token** card, copy your token (this is your Strategy API key).
2. **The Strategy ID.** Open the Strategy you want to run in the Aftersell Strategy editor and copy its ID.
3. **The Upsells module enabled in Upcart.** The script overrides the list of products shown in the existing upsell block, so the module needs to be turned on for anything to render.

***

## Adding the Script

In Upcart, go to **Settings → Custom HTML → Scripts (before load)** and paste the script below. Replace `STRATEGY_ID` and `STRATEGY_API_KEY` with the values from Aftersell, then save.

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  const STRATEGY_ID = "YOUR_STRATEGY_ID";
  const STRATEGY_API_KEY = "YOUR_STRATEGY_API_KEY";
  const STRATEGY_BACKEND_URL = "https://start.aftersell.app";

  let cartToken = null;
  const fetchCartToken = async () => {
    const res = await fetch("/cart.js");
    const c = await res.json();
    cartToken = c.token;
  };

  const mapCartItemToContext = (cartItem) => ({
    productId: "gid://shopify/Product/" + cartItem.productId.toString(),
    variantId: "gid://shopify/ProductVariant/" + cartItem.variantId.toString(),
    tags: [],
    title: cartItem.title,
    vendor: cartItem.vendor,
    productType: cartItem.productType,
    handle: cartItem.handle,
    quantity: cartItem.quantity,
    price: cartItem.originalPrice / 100,
  });

  // --- StrategyProduct -> Upcart Product conversion -----------------------

  const gidToNumericId = (gid) => Number(String(gid).split("/").pop());
  const priceStringToCents = (price) =>
    price == null ? null : Math.round(parseFloat(price) * 100);

  const strategyMetafieldsToProductMetafields = (metafields = []) => {
    const grouped = {};
    for (const { namespace, key, value } of metafields) {
      grouped[namespace] = grouped[namespace] || {};
      grouped[namespace][key] = value;
    }
    return { product: grouped };
  };

  const deriveProductOptions = (variants = []) => {
    const byName = new Map();
    for (const variant of variants) {
      (variant.selectedOptions ?? []).forEach((opt, idx) => {
        if (!byName.has(opt.name)) {
          byName.set(opt.name, { name: opt.name, position: idx + 1, values: [] });
        }
        const entry = byName.get(opt.name);
        if (!entry.values.includes(opt.value)) entry.values.push(opt.value);
      });
    }
    return [...byName.values()];
  };

  const mapStrategyVariantToProductVariant = (variant) => {
    const selected = variant.selectedOptions ?? [];
    const optionValues = selected.map((o) => o.value);
    return {
      id: gidToNumericId(variant.variantId),
      title: variant.title,
      option1: optionValues[0] ?? null,
      option2: optionValues[1] ?? null,
      option3: optionValues[2] ?? null,
      sku: variant.sku ?? "",
      requires_shipping: true,
      taxable: true,
      featured_image: null,
      available: variant.availableForSale,
      name: variant.title,
      public_title: variant.title,
      options: optionValues,
      price: priceStringToCents(variant.price) ?? 0,
      weight: 0,
      compare_at_price: priceStringToCents(variant.compareAtPrice),
      inventory_management: "",
      barcode: null,
      requires_selling_plan: false,
      selling_plan_allocations: [],
    };
  };

  const mapStrategyProductToProduct = (product) => {
    const variants = (product.variants ?? []).map(mapStrategyVariantToProductVariant);
    const variantPrices = variants.map((v) => v.price);
    const priceMin = variantPrices.length ? Math.min(...variantPrices) : (priceStringToCents(product.price) ?? 0);
    const priceMax = variantPrices.length ? Math.max(...variantPrices) : (priceStringToCents(product.price) ?? 0);

    const variantCompareAtPrices = variants
      .map((v) => v.compare_at_price)
      .filter((p) => p != null);
    const compareAtMin = variantCompareAtPrices.length ? Math.min(...variantCompareAtPrices) : 0;
    const compareAtMax = variantCompareAtPrices.length ? Math.max(...variantCompareAtPrices) : 0;

    const images = (product.images ?? [])
      .slice()
      .sort((a, b) => a.position - b.position)
      .map((img) => img.src);

    return {
      id: gidToNumericId(product.productId),
      title: product.title,
      handle: product.handle,
      description: product.description ?? "",
      published_at: "",
      created_at: "",
      vendor: product.vendor ?? "",
      type: product.productType ?? "",
      tags: [...(product.tags ?? [])],
      price: priceStringToCents(product.price) ?? 0,
      price_min: priceMin,
      price_max: priceMax,
      available: product.availableForSale,
      price_varies: priceMin !== priceMax,
      compare_at_price: priceStringToCents(product.compareAtPrice),
      compare_at_price_min: compareAtMin,
      compare_at_price_max: compareAtMax,
      compare_at_price_varies: compareAtMin !== compareAtMax,
      variants,
      images,
      featured_image: images[0] ?? "",
      options: deriveProductOptions(product.variants),
      url: product.url ?? "",
      media: [],
      requires_selling_plan: false,
      selling_plan_groups: [],
      metafields: strategyMetafieldsToProductMetafields(product.metafields),
    };
  };

  // -----------------------------------------------------------------------

  let replacedUpsells = null;
  let lastFetchedCartSignature = null;

  const cartSignature = (cart) =>
    JSON.stringify(cart.items.map((i) => [i.variantId, i.quantity]));

  const runStrategyEvaluation = async () => {
    if (!STRATEGY_ID || !STRATEGY_API_KEY) return;

    await fetchCartToken();
    if (!cartToken) return;

    const cart = window.upcartGetCart();
    if (!cart) return;

    const signature = cartSignature(cart);
    if (signature === lastFetchedCartSignature) return;
    lastFetchedCartSignature = signature;

    const cartContext = {
      subtotal: cart.total_price / 100,
      itemCount: cart.items.reduce((acc, item) => acc + item.quantity, 0),
      lineCount: cart.items.length,
    };

    const products = cart.items.map(mapCartItemToContext);

    const res = await fetch(STRATEGY_BACKEND_URL + "/api/public/strategy/evaluate", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Strategy-Api-Key": STRATEGY_API_KEY,
      },
      body: JSON.stringify({
        shopDomain: window.Shopify.shop,
        strategyId: STRATEGY_ID,
        context: {
          products,
          cartToken,
          cart: cartContext.itemCount > 0 ? cartContext : undefined,
          session: { currencyCode: window.Shopify.currency.active },
        },
      }),
    });
    replacedUpsells = await res.json();

    if (typeof window.upcartRefreshCart === "function") {
      window.upcartRefreshCart();
    }
  };

  window.upcartSubscribeCartUpdated(runStrategyEvaluation);

  const waitForUpcartCart = (timeoutMs = 10000) =>
    new Promise((resolve) => {
      const start = Date.now();
      const check = () => {
        if (window.upcartGetCart()) return resolve(true);
        if (Date.now() - start > timeoutMs) return resolve(false);
        setTimeout(check, 100);
      };
      check();
    });

  waitForUpcartCart().then((ready) => {
    if (ready) runStrategyEvaluation();
  });

  window.upcartModifyListOfUpsells = () => {
    if (!replacedUpsells || !Array.isArray(replacedUpsells.products)) return;
    try {
      return replacedUpsells.products.map(mapStrategyProductToProduct);
    } catch (err) {
      console.error("upcartModifyListOfUpsells mapping failed", err);
      return;
    }
  };
</script>
```

<Warning>
  Your Strategy API key authorizes calls against your shop's Strategies. The script above places it in client-side code, which is the only practical way to invoke the API from the cart drawer. Treat the key as you would any other public storefront credential and rotate it from Aftersell **Settings → Product Strategy** if it's ever exposed in a way you didn't intend.
</Warning>

***

## What the Strategy Sees

Because this runs from the storefront cart, the context is a slim subset of what's available on Aftersell's native surfaces:

#### Product context

The line items currently in the Upcart cart are sent as the input products. Triggers like **product type**, **vendor**, **product handle**, **product title**, and any **product ID / variant ID** triggers all evaluate against these items.

#### Cart context

* **Subtotal** - cart subtotal in the store's major currency units (e.g. dollars). Upcart's `total_price` is in minor units (cents), so the script divides by 100 to match the units the rest of the Strategies API uses - and the units your `cart_subtotal` rules are authored in.
* **Item count** - total quantity across all lines.
* **Line count** - number of distinct line items.

#### Session context

* **Currency code** - taken from `window.Shopify.currency.active`.

<Warning>
  **Customer triggers and UTM triggers won't match.** The default script doesn't send customer tags, order count, location, or UTM parameters - so any rule using those triggers will never fire. Use product, cart, and currency triggers, or a Catch all, to make sure something always returns.
</Warning>

***

## What Happens When the Strategy Returns

The products returned by the Strategy fully **replace** the list Upcart would otherwise show in the Upsells module. The merchant-defined upsell list is overridden for the duration of that cart - it's not merged in.

Each Strategy product is mapped to Upcart's expected product shape (variants, images, options, metafields, etc.) so it renders inside the upsell block exactly like any other product.

***

## When No Product Is Returned

If the Strategy returns no products, the Upsells module renders **empty** - no upsells are shown.

To avoid this, configure a **Catch all** in the Strategy so there is always a fallback product to return. See the [Building Strategies](/aftersell/strategies_building_in_app) page for how to set up a Catch all.

***

## Re-Evaluation on Cart Changes

Unlike checkout upsells, the Upcart implementation **re-evaluates the Strategy every time the cart changes** - items added, removed, or quantity-updated. The script subscribes to Upcart's `cartUpdated` event, sends the new cart to the Strategies API, and refreshes the cart drawer with the new upsell list.

A cart-signature check skips redundant calls if the line items and quantities haven't actually changed, so back-to-back cart events that don't materially change the cart won't re-hit the API.

***

## Tips for Upcart Strategies

* **Design around the cart.** Cart-shape and product triggers are the strongest signals you have here. Customer history and UTM-based targeting aren't sent by the default script.
* **Use Catch all as a safety net.** Without one, the Upsells module will show nothing whenever no rule matches.
* **Cache-friendly by default.** The cart-signature guard prevents re-firing the API if the cart hasn't materially changed - good for shoppers who toggle the cart open and closed without editing it.


# Aftersell & Judge.me reviews integration
Source: https://docs.aftersell.com/aftersell/judgeme_reviews_integration

This article explains how to set up the Aftersell and Judge.me Reviews integration for the testimonials widget.

Judge.me reviews work automatically with Aftersell for displaying review stars on upsell offers. To use Judge.me reviews in the testimonials widget, you need to provide your API key.

## Setting up Judge.me integration

1. Install the [Judge.me app](https://apps.shopify.com/judgeme) from the Shopify app store
2. In your Judge.me app, go to `Settings > Integrations > API token`
3. Copy your **Private API token**
4. Open the Aftersell app, then go to `Settings > Product Reviews`
5. Select **Judge.me** from the review integrations list
6. Paste your Private API token in the **Judge.me API key** field
7. Click **Save changes**

The integration is complete. You can now use Judge.me reviews in your Testimonials widget.

## Syncing reviews

Aftersell imports reviews from Judge.me and stores them so they can be displayed in the testimonials widget.

<Warning>
  **Saving your credentials doesn't start an import on its own.** The weekly automatic sync only picks up stores that have a **live Testimonials widget** whose selection mode is **Dynamic** and whose provider is Judge.me — on Checkout, on the Thank You Page, or in a post-purchase offer. Until such a widget exists, use **Sync now** below to import manually.
</Warning>

Once you do have a qualifying widget, Aftersell re-imports that store's reviews about once a week.

To import reviews immediately:

1. Go to `Settings > Product Reviews`
2. Find the **Judge.me reviews** section
3. Click **Sync now**

The sync status shows when reviews were last imported and when the next sync is available.


# Aftersell & Klaviyo reviews integration
Source: https://docs.aftersell.com/aftersell/klaviyo_reviews_integration

This article explains how to set up the Aftersell and Klaviyo Reviews integration for the testimonials widget.

To use Klaviyo reviews in the Aftersell testimonials widget, you need to provide your Klaviyo private API key.

## Setting up Klaviyo integration

1. In Klaviyo, navigate to your account settings
2. Go to `Integrations > Developers > Manage API keys`
3. Click **Create Private API Key**
   * You can name it "Aftersell API key"
   * Select **read-only** permissions
4. Copy the generated API key
5. Open the Aftersell app, then go to `Settings > Product Reviews`
6. Select **Klaviyo** from the review integrations list
7. Paste your private API key in the **Klaviyo private API key** field
8. Click **Save changes**

The integration is complete. You can now use Klaviyo reviews in your Testimonials widget.

## Syncing reviews

Aftersell imports reviews from Klaviyo and stores them so they can be displayed in the testimonials widget.

<Warning>
  **Saving your credentials doesn't start an import on its own.** The weekly automatic sync only picks up stores that have a **live Testimonials widget** whose selection mode is **Dynamic** and whose provider is Klaviyo — on Checkout, on the Thank You Page, or in a post-purchase offer. Until such a widget exists, use **Sync now** below to import manually.
</Warning>

Once you do have a qualifying widget, Aftersell re-imports that store's reviews about once a week.

To import reviews immediately:

1. Go to `Settings > Product Reviews`
2. Find the **Klaviyo reviews** section
3. Click **Sync now**

The sync status shows when reviews were last imported and when the next sync is available.


# Managing checkout discounts
Source: https://docs.aftersell.com/aftersell/managing_checkout_discounts

Learn how to view, edit, and delete discounts created for checkout upsells in Aftersell

The discount library in Aftersell allows you to manage all discounts created for your checkout upsells. You can view which upsells use each discount, edit discount details, and delete unused discounts.

## Accessing the discount library

To access your discount library:

1. Open the **Aftersell** app in your Shopify Admin
2. Navigate to **Checkout** > **Discounts**

The discount library displays all discounts you've created through Aftersell. These discounts also appear under "Aftersell Discounts" on your Shopify Discounts page.

## Understanding discount status

The Checkout discounts page shows one status badge in the top right, reflecting whether your Aftersell checkout discount code is active on Shopify. It is a page-level status, not a per-discount one:

* **Active on Shopify** - The discount is active and working correctly
* **Inactive on Shopify** - The discount may be missing or deactivated on your Shopify Discounts page

If a discount shows as inactive, check your Shopify Admin > Discounts page to verify the discount exists and is active.

## Editing a discount

To edit an existing discount:

1. Click on the discount you want to edit from the list
2. The discount details appear in the right panel
3. Modify the **title**, **discount type** (percentage or fixed amount), or **amount**
4. Click **Update** to apply your changes

⚠️ Changes apply to all upsells using this discount. The "Used in" section shows which widgets and products currently use the discount.

## Deleting a single discount

To delete a discount:

1. Click on the discount you want to delete
2. Click the **Delete** button in the right panel
3. Confirm the deletion in the modal

The discount is removed from all upsells that use it. This action cannot be undone.

## Bulk deleting unused discounts

If you have discounts that aren't currently used in any upsells, you can delete them all at once:

1. In the discount library, look for the **Delete X unused discount(s)** button
2. Click the button to see a list of all unused discounts
3. Review the list in the confirmation modal
4. Click **Delete X discount(s)** to confirm

This feature only appears when you have unused discounts. The system automatically identifies which discounts aren't applied to any upsell offers.

## Searching discounts

Use the search bar at the top of the discount library to find discounts by name. The search matches the displayed rule name, which is the title plus the savings amount — for example "Summer add-on (15% off)". Checkout discount rules do not have discount codes of their own, so you cannot search by code.

## Creating new discounts

Discounts are created when you add them to upsell offers in the Checkout editor. You cannot create standalone discounts in the discount library.

To create a new discount:

1. Go to **Checkout** > **Editor**
2. Edit or create an upsell widget
3. Click **Add discount** when configuring an offer
4. Choose **Create new** and set the title and amount

The new discount appears in your discount library and can be reused in other upsells by selecting **Pick existing** when adding discounts.

## Related articles

* [Checkout widget types](/aftersell/checkout_widget_types) - Learn about adding discounts to upsell widgets
* [Creating your first checkout widget](/aftersell/creating_your_first_checkout_widget) - Step-by-step guide to creating checkout widgets


# Connect your AI client with Aftersell MCP
Source: https://docs.aftersell.com/aftersell/mcp-connect-self

Connect an AI client like Claude Desktop to your store's Aftersell analytics using the Aftersell MCP server (Model Context Protocol).

MCP (Model Context Protocol) is an open standard that lets an AI client read data from outside tools. Aftersell hosts an MCP server that gives your AI client read-only access to your store's Aftersell analytics.

The self-serve connect page lets you link an AI client — such as Claude Desktop — to your store's Aftersell analytics. Once connected, you can ask your AI client questions about your store's upsell performance, funnel results, and more, directly in natural language.

The connection is read-only: your AI client can read your Aftersell analytics data but cannot place orders or change any settings. Personally identifiable customer fields are blocked.

## What you can ask

Once connected, you can ask your AI client questions like:

* How much extra revenue did my upsells make last week?
* How do I stack up against similar stores on post-purchase performance?
* How are my funnels performing this week?
* Break down my offer responses - how many were accepted, declined, or timed out?
* Why aren't my post-purchase offers showing to more shoppers?
* Which upsell products drove the most revenue last month?
* Which of my active funnels is underperforming on conversions?
* How many orders did my store get each day this month, and what was my average order value?
* Compare my primary offer step vs the second offer vs the downsell - which converts best?
* Is my upsell conversion rate trending up or down lately?
* How many people saw my post-purchase offers each day over the last two weeks?
* How does my revenue per visitor compare to similar stores?
* Trace order #1234 - did the shopper see an offer?

## Connecting your AI client

The connect page opens with **Choose your AI client**, a picker offering **Claude Desktop**, **Claude Code**, **Codex App**, and **Codex CLI**. The steps below it change to match your choice: Claude Desktop and Codex App give you a connector URL to paste into the client's own settings, while Claude Code and Codex CLI give you a single terminal command to copy instead.

The walkthrough below is for Claude Desktop.

1. On the connect page, choose **Claude Desktop**. A single-use connect code is minted for you automatically and shown under step 3, **Enter the connect code** — you do not have to click anything to get one. It expires **6 hours** after it is generated; **Regenerate** gives you a fresh one, and **Generate** appears instead if no code is currently shown.
2. Copy the **Remote MCP server URL** from step 2, **Add the connector to Claude Desktop**. It is shown whether or not a code has been generated.
3. In Claude Desktop, open **Settings**, then **Connectors**.
4. Choose **Add custom connector** and paste in the URL.
5. Click **Connect**. Claude will ask for a connect code.
6. Enter the connect code from step 1.
7. A verification number appears in both Claude and your Aftersell admin. Select the matching number in your admin to approve the connection.

Once approved, your status changes to **Connected** and you can start asking questions.

## Connecting a second store

Your MCP connection is tied to your email address, not a single store. Once you have a connection set up, you can link additional stores without going through the full setup again.

To link another store:

1. Open the connect page from that store's Aftersell admin.
2. The page shows a **Store data access** section with a **Link store** button.
3. Click **Link store**. The store is linked immediately — no connect code or approval needed.

Once linked, your AI client can read that store's Aftersell data through the same connection. If you have more than one store linked, tell your AI client which store you're asking about.

## The two sections on the connect page

The connect page has two independent sections:

* **MCP connection** — the status of your AI client's connection to Aftersell MCP. This is email-global: one connection reaches every store you've linked.
* **Store data access** — whether this specific store's data is accessible through your connection.

The store data access section only appears once your MCP connection is active.

## Connection statuses

### MCP connection

| Status                     | Meaning                                                                                                              |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Not connected**          | No active MCP connection. Follow the setup steps to connect.                                                         |
| **Awaiting your approval** | You've entered the connect code in your AI client. Select the matching verification number in your admin to approve. |
| **Connecting…**            | Your approval was submitted. The AI client is finishing the connection. This usually takes a few seconds.            |
| **Connected**              | Your AI client is connected and can read your Aftersell analytics.                                                   |

If your connect code or a pending approval lapses before the connection completes, the status stays **Not connected** — there is no separate expired status. Generate a new code and run through the steps again.

### Store data access

Unlike the MCP connection section above, this section shows a status badge in one case only — **Expired**. The other states are shown in different ways:

| State              | What appears                                                        | Meaning                                                                                   |
| ------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Linked**         | A **Linked** button with a checkmark — no badge                     | This store's data is accessible through your MCP connection.                              |
| **Expired**        | An **Expired** badge and a **Link store** button                    | This store's access lapsed after 30 days without use. Click **Link store** to restore it. |
| **Not yet linked** | No badge — just the section description and a **Link store** button | Your connection exists but this store hasn't been linked yet.                             |
| **Access removed** | No badge — a warning banner                                         | A store owner or staff member removed this store's access. Ask them to restore it.        |

## Disconnecting

To disconnect your AI client from Aftersell MCP, click **Disconnect** on the connect page and confirm. This disconnects your AI client from all stores immediately. Your store access records are kept, so you can reconnect anytime by following the setup steps again.

## Who can connect

Store owners, staff members, and collaborators can all self-connect. Collaborators connect and link stores for their own email address, scoped to the store they have a session for.

Managing other people's MCP access — granting, approving, or revoking access for others — is limited to store owners and staff members.

Access management is also rolled out separately from self-connecting, so the management screen may not be available on your store yet even though you can connect your own AI client. Contact the customer support team if you need it.

## Frequently asked questions

**What is an MCP?** MCP (Model Context Protocol) is an open standard that lets an AI client connect to outside tools and data. This connector uses it to give your AI client read-only access to your store's Aftersell analytics.

**What can the AI access?** Only your store's Aftersell analytics. Aftersell doesn't hold a full copy of your store's data, so the AI can't see everything in Shopify — just the analytics Aftersell has, scoped to this shop. It's read-only and personally identifiable customer fields are blocked.

**My AI is asking me to approve tool calls. What does that mean?** AI clients ask for your approval before they run a tool, so you stay in control of what they do. When your AI wants to read your Aftersell data, it asks to call this connector's tools. Approve them to let it answer. It's read-only, so approving only lets the AI read your analytics; it can't place orders or change anything in your store.

**Is my data safe?** Yes. The connector is read-only and scoped to your store's Aftersell analytics only. The verification number step during setup ensures only you can approve a connection.

**How do I connect another store?** Open the connect page from each store's Aftersell admin and click **Link store** to give your connection access. Your MCP connection reaches every store you've linked, so when you have more than one, tell your AI client which store you're asking about.

**My connect code expired. What do I do?** Generate a new code on this page and use that one. Each new code replaces the previous unused one.

**How do I stop the AI's access?** Click **Disconnect** on this page to disconnect your AI client from Aftersell MCP right away. You can connect again anytime by following the setup steps.

**Can I have multiple AI clients connected?** Each connect code is single-use. To connect a second device or client, generate a new connect code and repeat the setup steps.


# Aftersell & Okendo reviews integration
Source: https://docs.aftersell.com/aftersell/okendo_reviews_integration

This article explains how to set up the Aftersell and Okendo Reviews integration for the testimonials widget.

Okendo reviews work automatically with Aftersell for displaying review stars on upsell offers. To use Okendo reviews in the testimonials widget, you need to provide your User ID.

## Setting up Okendo integration

1. Install the [Okendo app](https://apps.shopify.com/okendo-reviews) from the Shopify app store
2. In your Shopify admin, open the Okendo platform
3. Go to `Settings > Integrations > Credentials`
4. Copy your **User ID**
5. Open the Aftersell app, then go to `Settings > Product Reviews`
6. Select **Okendo** from the review integrations list
7. Paste your User ID in the **Okendo User ID** field
8. Click **Save changes**

The integration is complete. You can now use Okendo reviews in your Testimonials widget.

## Syncing reviews

Aftersell imports reviews from Okendo and stores them so they can be displayed in the testimonials widget.

<Warning>
  **Saving your credentials doesn't start an import on its own.** The weekly automatic sync only picks up stores that have a **live Testimonials widget** whose selection mode is **Dynamic** and whose provider is Okendo — on Checkout, on the Thank You Page, or in a post-purchase offer. Until such a widget exists, use **Sync now** below to import manually.
</Warning>

Once you do have a qualifying widget, Aftersell re-imports that store's reviews about once a week.

To import reviews immediately:

1. Go to `Settings > Product Reviews`
2. Find the **Okendo reviews** section
3. Click **Sync now**

The sync status shows when reviews were last imported and when the next sync is available.


# Order browser troubleshooting
Source: https://docs.aftersell.com/aftersell/order-browser-troubleshooting

Fix common issues with offer statuses, funnel gaps, and ineligible orders in the Order Browser.

Use this guide to investigate unexpected statuses or gaps you're seeing in the [Order Browser](/aftersell/order_browser_overview).

If your offer isn't showing up at all before you even get to the Order Browser, start with [Why isn't my post-purchase offer displaying?](/aftersell/why_isnt_my_1_click_offer_displaying) or [Widget Not Displaying on the Thank You Page](/aftersell/widget_not_displaying_on_the_thank_you_page).

<Note>
  For a complete overview of all Order Browser statuses, see the [Order Browser Overview.](/aftersell/order_browser_overview) Use this guide when you're investigating a specific status or unexpected gap.
</Note>

## Why are so many orders showing as Ineligible?

Ineligible orders are controlled entirely by Shopify, not Aftersell. The most common causes are unsupported payment methods (digital wallets, BNPL, full gift card), orders under \$0.50, multi-currency, and duties or landed costs.

To investigate: use the **Ineligibility reason filter** in the order table to group orders by the specific reason. Then click into an individual order to confirm the payment method or order details behind it.

For a full breakdown of every ineligibility reason and what to do about each one, see the [Order Browser Overview](/aftersell/order_browser_overview). For supported and unsupported payment methods specifically, see [Payment Methods](/aftersell/payment_methods).

> **Tip:** If a large share of your orders are ineligible due to payment method, setting up [Thank You Page upsells](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell) is the best way to recover that traffic since TYP is not subject to Shopify's post-purchase restrictions.

***

## What does "Not configured" mean?

Not configured means a funnel has an offer slot (e.g., Offer 2) that exists but has no offer set up in it yet.

<img alt="Order Browser rows showing Not configured status badges on empty offer slots" />

To fix it: click the **PPU Funnel** link in the order table to go directly to that funnel, then add an offer to the empty slot.

***

## What does "Products excluded" mean and how do I fix it?

Products excluded on a PPU offer slot means every product in your offer was excluded at the time of that order. Click into the order and open the PPU tab, the timeline will show a Products excluded warning with the specific reason listed below.

* **Product already in order:** the offer product was already in the customer's cart. Turn off "Hide offer if already purchased" in your offer settings, or add different products to the offer.
* **Product OOS:** the offer product was out of stock. Add more products so there's always something available to show.
* **Product Inactive:** the offer product was unpublished or deactivated in Shopify. Republish the product or swap it for an active one.
* **All products filtered:** every product was excluded by a combination of rules. Review your offer's filter settings and expand the eligible product pool.

> **Tip:** To reduce this over time, add more products to each offer as fallbacks and periodically check that your offer products are in stock and published.

***

## A lot of orders are showing No interaction. What can I do?

No interaction means the offer was shown but the customer left without clicking Accept or Decline. Some of this is normal behavior, but a consistently high rate can point to offer design issues.

A few things that help:

* **Fewer products per offer.** More than four items in a single offer can cause decision paralysis. Keep it focused and relevant to what the customer just bought.
* **Enable Require Confirmation Click to Accept** in your offer settings. This makes the Accept/Decline action more intentional and typically drives cleaner conversion data.
* **Check offer relevance.** If the offer doesn't feel connected to the original purchase, customers are more likely to ignore it.

**Note on fulfillment holds:** When an order shows 'No interaction', a fulfillment hold is placed for up to 60 minutes. The hold lifts when the customer accepts, declines, or the session closes. See the [Fulfillment](/aftersell/fulfillment) doc for more detail.

***

## Orders are showing Customer skipped. Is something broken?

Not necessarily. Customer skipped means the customer closed their browser or left before the post-purchase page had a chance to load. Common causes:

* The customer navigated away immediately after checkout
* The browser was closed before the post-purchase redirect completed
* The checkout completed through an accelerated flow that bypassed the post-purchase step

If you're seeing an unusually high volume of skips, check whether there have been any recent changes to your checkout configuration, or whether a specific sales channel is generating more skips than others.

***

## PPU Funnel is showing "No funnel triggered." How do I fix it?

No funnel triggered means the order was eligible but no funnel matched its trigger conditions. Common causes:

* No funnel has a trigger set to "All orders" as a catch-all fallback
* Funnel trigger conditions (product tags, customer tags, order value) no longer match the incoming orders
* Multiple funnels are competing and the expected one lost priority

To fix this long-term: make sure you have at least one low-priority funnel with a trigger set to all orders so there's always a fallback. Click the **PPU Funnel** link in the order table (or the **Funnel triggered** event in the order timeline) to review and update your trigger logic directly.

<img alt="Order detail Post Purchase section showing a No funnel triggered warning" />

***

## The Improvement Opportunities panel is flagging gaps. What should I do?

**Funnel & Offer opportunities** means one or more of your funnels has an unconfigured or missing offer slot. Use the Offer opportunities filter in the order table to find the specific orders, then click through to the funnel to set up the missing offer.

**Product opportunities** means an offer is configured but its products are frequently being filtered out or are unavailable. Use the Product opportunities filter to surface those orders, review which products are causing the gap, and either replace them or loosen the filter settings.

***

## I'm seeing "Timer expired" on PPU offers

Timer expired means the post-purchase session clock ran out while the offer was on screen. Shopify's post-purchase page has a time limit, and if the customer was on the page too long without interacting, the session expires.

This is expected for a small percentage of orders. If you're seeing it frequently, check whether your offer has an unusually large number of products or steps that might be slowing down load or review time.

***

## My test order's PPU timeline is empty or incomplete

If you placed a test order and the PPU tab shows no events or partial data, it's likely because the order ID wasn't available when the earliest events fired. This resolves automatically as the order completes - give it a few minutes and refresh.

***

## The PPU timeline is showing "Technical issue"

Technical issue means the post-purchase experience failed to load for this order. This is different from Ineligible (where Shopify blocked it) — the session started but something prevented the page from rendering.

<Note>
  "Not loaded" is a **Rokt Thanks** status only. It never appears on the PPU timeline, where the same underlying condition is reported as Technical issue.
</Note>

Common causes include browser issues on the customer's side, a network interruption mid-redirect, or a transient Shopify platform error. It is not typically caused by your Aftersell configuration.

If you're seeing Not loaded on a small number of orders, no action is needed. If you're seeing it consistently across many orders, contact support and share the order numbers so the team can investigate whether there's a platform-level issue.

***

## I'm seeing "Shopify skipped" - what does that mean?

Shopify skipped means Shopify bypassed the post-purchase page for this order at a platform level. When you click into the order and open the PPU tab, you'll see:

> Shopify skipped can occur in a wider range of situations than just extreme platform load - including on development stores. If you're testing on a dev store and seeing this status, that is expected behavior. If you're seeing it at high volume on a live store with no clear cause, raise it with Shopify directly as it may indicate a Shopify platform issue.

<img alt="Order detail showing an ineligible post-purchase offer skipped by Shopify restrictions" />

Before reaching out to Shopify, use the **Ineligibility reason** filter in the Order Browser and select **Skipped by Shopify** to isolate only those orders. Many ineligible orders have a clear reason (payment method, duties, minimum order value, etc.) that can be resolved without involving Shopify at all. Only orders specifically tagged Shopify skipped are ones where Aftersell has no visibility and Shopify needs to be contacted.

Once you've confirmed the orders are genuinely Shopify skipped, use the **See Shopify docs** button in the order detail view or contact Shopify support directly for further context.

***

## I'm seeing "Pending conversion" on TYP widget

Pending conversion means the Thank You Page offer was displayed but a final decision hasn't been recorded yet. The most common cause is that the page is still open in the customer's browser. It typically resolves to Accepted or No interaction once the session closes.

<Note>
  If you're seeing a persistent volume that never resolves, reach out to support.
</Note>

***

## I'm seeing "No products found" on TYP widget

No products found means the Thank You Page experience couldn't load any products to display. This is different from Products filtered out (where products exist but were excluded by a rule), Out of stock / unavailable (where variants were returned but all are unavailable), and Selected variant unavailable (where a configured variant no longer resolves from Shopify). No products found usually points to a configuration issue with the TYP offer itself, such as all products being unpublished or unavailable.

To fix it: review your TYP offer product selection and make sure at least one product is published and in stock.

***

## I'm seeing "Technical issue" on TYP widget

Technical issue means there was a problem loading the Thank You Page experience for that order. This appears as a badge in the TYP tab of the order detail view.

Like Not loaded on PPU, this is usually caused by a transient rendering or platform error rather than a configuration issue. If it's affecting a small number of orders, no action is needed. If you're seeing it consistently, reach out to support with the affected order numbers.

***

## Order Browser shows "no products recommended" for a Smart Funnel order

If an order that ran through [Smart Funnel](/aftersell/smart_funnel) is showing no products in the Order Browser, the AI had no eligible candidates to display at the time the offer fired. Smart Funnel does not have its own product catalog — it pulls candidates from the recommendation source you have configured under **Settings → Automatic Upsells**, then applies Shopify eligibility and your exclusion rules on top.

Common causes:

* **All candidate products were filtered out.** Any SKUs you have excluded under **Settings → Automatic Upsells** are removed from the pool. If your exclusion list is broad, the remaining pool may be empty for some orders.
* **Candidate products were out of stock or unpublished.** Products that are OOS, inactive, or not published to the Online Store sales channel are dropped before the offer renders. If your highlighted product is unavailable, Smart Funnel tries to substitute — but if no fallbacks are eligible either, nothing displays.
* **Non-English checkout locale.** Smart Funnel only runs when the *shopper's* checkout locale is English — it reads the locale Shopify sends with the order, not your store's primary language. An English store still skips Smart Funnel for a shopper who checked out in another language, and those orders fall through to your regular funnels instead.
* **0% max discount.** A max discount of 0 does not stop Smart Funnel from running — the field accepts 0–99 and the value only scales the offer's *percentage* discount. Set to 0, the product is still offered, just at full price, which usually converts poorly. Raise the max discount if Smart Funnel offers are being shown but rarely accepted.
* **Order was ineligible at the Shopify level.** Confirm the order isn't tagged with a Shopify ineligibility reason (payment wallet, multi-currency, gift card, BNPL, etc.) — if it is, the post-purchase page never had a chance to load. See the ineligibility reasons in the [Order Browser Overview](/aftersell/order_browser_overview).

To investigate: open the individual order in the Order Browser and check the PPU timeline for a **Products excluded** warning — it names the specific reason (e.g., Product OOS, Product Inactive, All products filtered). Then narrow the recommendation exclusion list, republish or restock the affected products, or add more fallbacks to broaden the pool.

For details on how Smart Funnel selects and substitutes products, see [Smart Funnel](/aftersell/smart_funnel).

***

## I'm seeing "Out of stock / unavailable" on TYP widget

Out of stock / unavailable means the Thank You Page product recommendation widget found variants for the offer product, but every variant came back unavailable for that buyer. This is usually genuine out-of-stock, but it can also be caused by region, market, or sales-channel availability restrictions.

To fix it: check that the offer product is in stock and published to the sales channel your store uses. If the product is available in your Shopify admin but still showing this status, it may be restricted to a specific market or sales channel that doesn't match the buyer's context.

***

## I'm seeing "Selected variant unavailable" on TYP widget

Selected variant unavailable means the specific variant configured in your offer no longer resolves from Shopify — it was likely deleted or replaced after the offer was set up.

To fix it: open the offer in Aftersell, go to the product selection for that offer, re-select the product and variant you want to show, and save. This refreshes the offer's product configuration and clears the stale reference.

***

## I'm seeing "Products filtered out" on TYP widget

Products filtered out on the TYP widget means the Thank You Page offer had products configured but all of them were excluded before the widget could display anything.

This is distinct from No products found (where no products could be loaded at all). Products filtered out specifically means the products exist but your offer settings excluded them all.

To fix it: review your TYP offer's filter settings - check for "hide if already purchased," out-of-stock exclusions, or tag-based filters that may be eliminating all available products. Add more fallback products to the offer so there's always something eligible to show.

<img alt="Thank You Page order detail showing Products filtered out and offer product issues" />

***

Still stuck? Reach out via chat or email us at [support@aftersell.app](mailto:support@aftersell.app).


# Order browser overview
Source: https://docs.aftersell.com/aftersell/order_browser_overview



The Order Browser gives you a centralized, order-level view of Aftersell performance. Use it to see which orders were eligible for a post-purchase offer, whether an offer was shown, how customers interacted with each offer slot, and where there are gaps in your setup.

<Info>
  The Order Browser covers Post-Purchase (PPU), Thank You Page (TYP), and Rokt Thanks experiences. **Coming soon:** Checkout timeline data will be added in a future update.
</Info>

## Accessing the Order Browser

To access it, navigate to: **Apps → Aftersell → Order Browser** in your Shopify admin.

<img alt="Aftersell app navigation menu in Shopify admin with Order Browser selected" />

You can also jump directly to a specific order's detail page from Shopify. When viewing any order in your Shopify admin, open the **More actions** menu and select **Open order browser**. This takes you straight to that order's Aftersell detail page without needing to search for it.

***

## Summary Bar

At the top of the Order Browser, three metrics give you a quick pulse on performance for your selected date range.

| Metric                 | What it means                                                                  |
| ---------------------- | ------------------------------------------------------------------------------ |
| **Total orders**       | Every order received in the selected period — eligible and ineligible combined |
| **Total offers shown** | How many of those orders actually had an offer displayed                       |
| **Upsell Revenue**     | Total revenue generated from accepted offers                                   |

<img alt="Order Browser summary bar showing total eligible orders, offers shown, and upsell revenue" />

The Order Browser defaults to the Last 30 days. Use the date picker in the top-right corner to adjust the range. Data is available from **February 25, 2026 onward** — the picker will not let you select an earlier start date. Every summary metric, Total orders included, reflects only the range you have selected.

Use the **Export button** (also top-right) to download the current view as a CSV. The export respects any filters you have active, so filter first if you only want a subset of orders. The CSV includes the following columns, in this order: Order, Date, Eligibility, Sales channel, Total, Currency, PPU Funnels, PPU status, PPU offer 1, PPU offer 2, PPU offer 3, TYP Funnels, TYP status, Rokt Thanks status, Payment Gateway, and Payment Wallet. There is no column picker, so every export contains all sixteen. The Rokt Thanks status column shows the same values as the on-screen badge (`Accepted`, `Shown, not accepted`, `No offer shown`, `Not loaded`). If your store does not have Rokt Thanks enabled, the column is included but the cells are empty.

<Note>
  Order data updates every few minutes, so a very recent order may take a short while to appear. Reload the page if you are waiting on one.
</Note>

***

## Performance Panels

Below the summary bar, three panels break down your performance in more detail. Together they help you quickly spot eligibility issues, configuration gaps, and opportunities to improve coverage.

#### Eligible Post-Purchase Orders

Shows the total count of eligible orders with a donut chart breaking them down by Shown vs Not shown. A high "Not shown" proportion usually points to funnel configuration gaps, product filtering, or Shopify eligibility issues. See the Order Browser Troubleshooting guide for next steps.

#### Improvement Opportunities

This panel highlights eligible orders where at least one offer didn't render because of funnel, offer, or product configuration gaps. Some of these orders may have shown other offers — fixing these gaps widens overall coverage. The panel is split into two categories: Funnel & Offer opportunities and Product opportunities. For each reason, the panel shows how many eligible orders were affected.

**Funnel & Offer opportunities**

<AccordionGroup>
  <Accordion title="No funnel triggered">
    **What it means:** An eligible order came through but no funnel matched its trigger conditions.

    **What to do:** Create a catch-all funnel using the **Show for All Customers** trigger and set it to the lowest priority so it fires whenever no other funnel matches.
  </Accordion>

  <Accordion title="Offer not set up">
    **What it means:** A funnel ran but one or more offer slots had no offer set up.

    **What to do:** Go to the funnel and add an offer to the empty slot.
  </Accordion>

  <Accordion title="Funnel not set up">
    **What it means:** A funnel matched the order but has no offers configured, so nothing could be shown.

    **What to do:** Open the funnel and add an offer to at least one slot.
  </Accordion>

  <Accordion title="No active funnels">
    **What it means:** Your store had no active funnel available to serve this order at all.

    **What to do:** Create a funnel and enable it.
  </Accordion>

  <Accordion title="All offers filtered out">
    **What it means:** A funnel was configured and matched the order, but every product across all offer slots was filtered out by your targeting or filter rules before anything could display.

    **What to do:** Review your funnel's product filters and targeting rules. Broaden the filter criteria or add fallback products to ensure at least one offer has something eligible to show.
  </Accordion>

  <Accordion title="All products filtered">
    **What it means:** An individual offer slot ran but every product in it was filtered out before the offer could display.

    **What to do:** Review the offer's filter settings and add more fallback products so there is always something eligible to show.
  </Accordion>

  <Accordion title="No product set">
    **What it means:** An offer slot exists but no product has been chosen for it.

    **What to do:** Open the funnel and pick a product for that slot.
  </Accordion>

  <Accordion title="No template set">
    **What it means:** An offer slot exists but no offer template has been chosen for it.

    **What to do:** Open the funnel and choose a template for that slot.
  </Accordion>

  <Accordion title="No recommendations">
    **What it means:** The offer uses automatic recommendations and the recommendation provider returned nothing for this order.

    **What to do:** Add a manually-selected fallback product to the offer so it always has something to show.
  </Accordion>

  <Accordion title="All out of stock">
    **What it means:** Every recommended product for the slot was out of stock at the time of the order.

    **What to do:** Restock, or add fallback products that are reliably in stock.
  </Accordion>

  <Accordion title="All rejected by location filter">
    **What it means:** Every candidate product was out of stock at the locations required by the offer's per-location inventory filter.

    **What to do:** Restock at those locations, or relax the inventory filter on the offer.
  </Accordion>

  <Accordion title="All in exclusion list">
    **What it means:** Every recommended product for the slot sits on your store's automatic-recommendation exclusion list.

    **What to do:** This list is not editable from the dashboard — contact support to have it reviewed.
  </Accordion>
</AccordionGroup>

<Note>
  Opportunities are tagged based on the customer's actual journey, not the funnel's configuration. For example, if a funnel has no offer set up in slot 3 but the customer declined slot 2 and never reached slot 3, it will not be flagged. The flag only appears if the customer's journey would have reached that step.

  You can click on any opportunity category to filter the order table to orders affected by that specific gap.
</Note>

**Product opportunities**

<AccordionGroup>
  <Accordion title="Replacement failsafe triggered">
    **What it means:** The replacement upsell failsafe was triggered because the shop hit its replacement-failure threshold within the past 7 days. Replacement upsells are paused shop-wide until the rolling 7-day error count drops below the threshold or you reset the failsafe. Orders attributed to this reason never attempted a replacement.

    **What to do:** Go to **Settings → Replacement Upsells** to see the failsafe status card and your current rolling error count. Once you've resolved the underlying issue, click **Reset failsafe** to resume. If errors have stopped, the failsafe also clears automatically once the 7-day window passes. If you're unsure of the root cause, contact support before resetting.
  </Accordion>

  <Accordion title="No matching line item">
    **What it means:** No line item in the order matched the replacement target's variant ID, so the replacement was skipped.

    **What to do:** Review the replacement upsell configuration and confirm the target variant is present in the orders you expect it to match.
  </Accordion>

  <Accordion title="Multi-match line items">
    **What it means:** More than one line item matched the replacement target, so Aftersell could not tell which one to replace.

    **What to do:** Narrow the replacement target to a variant that appears at most once per order.
  </Accordion>

  <Accordion title="Line item discounted">
    **What it means:** The line item the replacement would have targeted already had a discount applied, and the offer's **Allow replacement if product has discount applied** toggle is off.

    **What to do:** Nothing, if you meant to protect discounted lines. If you do want these orders to convert, turn that toggle on in the offer's settings.
  </Accordion>

  <Accordion title="Subscription only">
    **What it means:** A recommended product is sold as a subscription only, but the customer's checkout already included a subscription, so it couldn't be added as a post-purchase upsell.

    **What to do:** Consider replacing subscription-only products in this offer with non-subscription alternatives, or move subscription offers to the Thank You Page where this restriction doesn't apply.
  </Accordion>

  <Accordion title="Out of stock">
    **What it means:** The offer product was out of stock when the order came through.

    **What to do:** Restock it, or add fallback products to the offer.
  </Accordion>

  <Accordion title="Product inactive">
    **What it means:** The offer product was unpublished or set to inactive in Shopify.

    **What to do:** Republish the product, or swap it for an active one.
  </Accordion>

  <Accordion title="Rejected by location filter">
    **What it means:** The product was out of stock at the locations required by the offer's per-location inventory filter.

    **What to do:** Restock at those locations, or relax the inventory filter on the offer.
  </Accordion>

  <Accordion title="Excluded by tag filter, metafield filter, product filter, or collection filter">
    **What it means:** The product was removed by one of the offer's exclusion filters — by product tag, by metafield, by product, or by collection.

    **What to do:** Open the offer's filter settings and check whether the rule is broader than you intended.
  </Accordion>

  <Accordion title="Excluded by collection / Most/least expensive excluded">
    **What it means:** The candidate product was removed by your store-level collection exclusion rules — the first when an automatic recommendation was excluded, the second when the most/least expensive placeholder picked an excluded product.

    **What to do:** These come from **Settings → Automatic upsells**, not from the funnel. Review the excluded collections there if the pool is coming out empty.
  </Accordion>
</AccordionGroup>

These aren't errors. They're flags that something can be fixed to improve coverage.

### Ineligible Post-Purchase Orders

Shows orders that couldn't receive a post-purchase offer, broken down by the specific reason. The panel surfaces exact counts per reason so you can see where the biggest eligibility gaps are.

<Note>
  Shopify does not tell Aftersell exactly why an order was skipped for post-purchase. The system identifies likely reasons based on Shopify's documented limitations. Because a single order can match multiple reasons, the individual reason counts do not add up to the total ineligible number. No percentages are shown for this section for that reason.

  You can click on any ineligibility reason to filter the order table to just those orders.
</Note>

<AccordionGroup>
  <Accordion title="Below minimum order price">
    **What it means:** Order value was under \$0.50 (e.g., fully discounted orders).

    **What to do:** Shopify restriction — no fix. Set up Thank You Page upsells to capture these orders.
  </Accordion>

  <Accordion title="Duties">
    **What it means:** Order included duties or landed costs.

    **What to do:** Shopify restriction — no fix. TYP upsells are not affected.
  </Accordion>

  <Accordion title="Gift card payment">
    **What it means:** Order was paid entirely with a gift card.

    **What to do:** Shopify restriction — no fix. TYP upsells are not affected.
  </Accordion>

  <Accordion title="Installment payment">
    **What it means:** Order used a BNPL method (Klarna, Afterpay, Shop Pay Installments).

    **What to do:** Shopify restriction — no fix. TYP upsells are not affected.
  </Accordion>

  <Accordion title="Local delivery">
    **What it means:** Order used a local delivery method not supported for post-purchase.

    **What to do:** Shopify restriction — no fix. TYP upsells are not affected.
  </Accordion>

  <Accordion title="Multiple currencies">
    **What it means:** Order was placed in a currency other than the store's default.

    **What to do:** Shopify restriction — no fix. TYP upsells support multi-currency and will show to these customers.
  </Accordion>

  <Accordion title="No destination country code">
    **What it means:** Shipping address was missing a country code.

    **What to do:** Typically a data issue on the order. No fix available for past orders.
  </Accordion>

  <Accordion title="Non credit card payment">
    **What it means:** Order used a non-credit-card payment method not supported by Shopify.

    **What to do:** Shopify restriction — no fix. TYP upsells are not affected.
  </Accordion>

  <Accordion title="Payment gateway">
    **What it means:** Order used a third-party payment gateway that doesn't support post-purchase.

    **What to do:** Check if your gateway supports Shopify's post-purchase API. See Payment Methods for the full supported gateway list.
  </Accordion>

  <Accordion title="Payment wallet">
    **What it means:** Order used a digital wallet (Apple Pay, Google Pay, PayPal).

    **What to do:** Shopify restriction — no fix. Set up Thank You Page upsells to capture wallet orders — TYP is not affected.
  </Accordion>

  <Accordion title="Shopify skipped">
    **What it means:** Shopify bypassed post-purchase for this order. Aftersell has no visibility into why — the error code shown in the order detail is `no_activity`.

    **What to do:** Contact Shopify support directly. Aftersell cannot investigate or resolve this — it is entirely within Shopify's platform.
  </Accordion>

  <Accordion title="Unsupported sales channel">
    **What it means:** Order came through a channel that doesn't support post-purchase (e.g., POS or a third-party marketplace). Post-purchase offers are supported on orders placed through the Online Store, a supported headless or custom sales channel, or a draft-order payment link.

    **What to do:** No fix available. These orders bypass Shopify's standard checkout entirely, so neither post-purchase nor Thank You Page upsells can reach them.
  </Accordion>
</AccordionGroup>

<img alt="Order Browser panels with a shown-versus-not-shown donut chart and ineligibility reason breakdown" />

Payment wallet and Unsupported sales channel tend to be the largest contributors for most stores. For payment method restrictions, [Thank You Page upsells](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell) are the best way to recover that traffic since TYP is not subject to Shopify's post-purchase restrictions.

For a full breakdown of supported and unsupported payment methods, see [Payment Methods](/aftersell/payment_methods)

***

## The Order Table

Below the performance panels is a detailed, order-level table. Each row is a single order. This is where you can search, filter, and drill into exactly what happened for any order.

### Columns

| Column                  | What it shows                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| **Order**               | Shopify order number. Click to open the order detail view.                                      |
| **Date**                | When the order was placed                                                                       |
| **Eligibility**         | Whether the order was eligible or ineligible for a post-purchase offer                          |
| **Sales channel**       | e.g. Online Store                                                                               |
| **Country**             | The shipping country for the order, displayed as an ISO country code (e.g. US, GB, AU)          |
| **Total**               | Order value                                                                                     |
| **PPU Funnel**          | Which post-purchase upsell funnel was shown. Click to open the funnel editor.                   |
| **PPU offer 1 / 2 / 3** | The interaction status for each post-purchase offer slot                                        |
| **TYP Funnel**          | Which Thank You Page funnel was shown                                                           |
| **TYP widget**          | The widget status on the Thank You Page                                                         |
| **Rokt Thanks**         | The Rokt Thanks offer status for the order (only visible if your store has Rokt Thanks enabled) |

<Info>
  PPU stands for Post-Purchase Upsell. TYP stands for Thank You Page. Each post-purchase funnel can have up to three offer slots (PPU offer 1, 2, and 3), each shown or resolved independently.
</Info>

### Offer Status Definitions

**PPU offer statuses** (columns PPU offer 1, 2, 3)

| Status                           | What it means                                                                                                                                                                                                                                     |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Accepted**                     | The customer accepted the offer. The item was added to their order.                                                                                                                                                                               |
| **Declined**                     | The customer actively declined the offer by clicking the decline button.                                                                                                                                                                          |
| **No interaction**               | The offer was shown, but the customer closed the tab or navigated away without clicking Accept or Decline. The offer was seen, just not acted on.                                                                                                 |
| **Customer skipped**             | The customer skipped the post-purchase page entirely, or closed their browser before the offer loaded. The offer never had a chance to display.                                                                                                   |
| **Timer expired**                | The post-purchase session timer ran out before the customer interacted with the offer.                                                                                                                                                            |
| **No funnel triggered**          | No funnel's trigger conditions matched this order, so no offer was selected for this slot.                                                                                                                                                        |
| **No active funnels**            | There were no active (enabled) funnels available to serve an offer for this order.                                                                                                                                                                |
| **Not configured**               | An offer slot exists in the funnel but no offer has been set up in that slot yet.                                                                                                                                                                 |
| **All offers filtered out**      | A funnel was configured and matched the order, but every product across all offer slots was filtered out by your targeting or filter rules before anything could display.                                                                         |
| **Offer type not supported**     | The offer slot's configured offer type isn't supported for this order or context.                                                                                                                                                                 |
| **Unsupported shipping country** | The order's shipping country is not on your store's allowed post-purchase countries list. This is a store-level setting, not funnel targeting.                                                                                                    |
| **Products excluded**            | The offer has products configured, but all of them are being excluded by your offer settings (e.g., hide if already purchased, out of stock, unpublished). Nothing was available to show.                                                         |
| **Products unavailable**         | None of the funnel's configured products were available to recommend for this order.                                                                                                                                                              |
| **No products recommended**      | The offer's recommendation strategy returned no eligible products to show.                                                                                                                                                                        |
| **Recommendations out of stock** | Every product returned by the offer's recommendation strategy was out of stock.                                                                                                                                                                   |
| **No stock at location**         | Every candidate product for this offer was out of stock at the locations required by the offer's per-location inventory filter. Restock at those locations, or adjust the inventory filter on the offer strategy.                                 |
| **Technical issue**              | An unexpected error prevented the offer from loading correctly (for example, a funnel or customer data lookup failed).                                                                                                                            |
| **Ineligible**                   | Shopify skipped the post-purchase page for this order due to a platform-level eligibility rule. This is a Shopify restriction, not an Aftersell configuration issue.                                                                              |
| **Subscription upgrade issue**   | The customer accepted the offer and the item was added to their order, but the downstream subscription upgrade at your subscription provider (Recharge, Loop, or Skio) failed. Open the order to see the specific cause and what to do to fix it. |

**TYP widget statuses** (TYP widget column)

The interaction outcome for the offer shown on the Thank You Page. The Post Purchase funnel and Thank You Page funnel for an order can be the **same or different.**

| Status                      | What it means                                                                                                                                                                                                                                                                                                                                                                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Accepted**                | The customer accepted the offer on the Thank You Page.                                                                                                                                                                                                                                                                                                                                                                                    |
| **Declined**                | The customer declined the offer.                                                                                                                                                                                                                                                                                                                                                                                                          |
| **No interaction**          | The offer was shown but the customer didn't interact with it, and the timer (if one exists) didn't trigger.                                                                                                                                                                                                                                                                                                                               |
| **Timer expired**           | The offer timer expired before the customer interacted.                                                                                                                                                                                                                                                                                                                                                                                   |
| **Pending conversion**      | The customer accepted the offer but the conversion is still being processed.                                                                                                                                                                                                                                                                                                                                                              |
| **No activity**             | The customer did not visit the Thank You Page.                                                                                                                                                                                                                                                                                                                                                                                            |
| **No products found**       | No products matched the offer's placement configuration, so nothing could be shown.                                                                                                                                                                                                                                                                                                                                                       |
| **Products filtered out**   | The offer's configuration filtered out all of its products, so nothing was displayed.                                                                                                                                                                                                                                                                                                                                                     |
| **Already in order**        | The widget is in "Modify original order" mode and every configured variant is already in the customer's order. Shopify does not allow duplicate variants in an order edit, so the upsell was hidden. Switch order handling to **Create new draft order** in the widget's [order handling settings](/aftersell/thank_you_page_extensions_overview#order-handling) to re-offer products regardless of what's already in the original order. |
| **Order can't be modified** | The widget is in "Modify original order" mode and this order could not be edited — for example it was archived, partially paid, past the window during which Shopify allows an order edit, or its shipping cannot accept the offered products. Switch order handling to **Create new draft order** to keep offering products on these orders.                                                                                             |
| **Wrong page**              | The offer is configured to show on a different page.                                                                                                                                                                                                                                                                                                                                                                                      |
| **Already shown**           | The offer had already been shown to this customer.                                                                                                                                                                                                                                                                                                                                                                                        |
| **Technical issue**         | A technical error occurred while loading the offer, often due to server or fetch errors outside Aftersell's control. If this happens frequently, contact support.                                                                                                                                                                                                                                                                         |

**Rokt Thanks statuses** (Rokt Thanks column)

This column is only visible if your store has Rokt Thanks enabled.

| Status                  | What it means                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| **Accepted**            | The customer engaged with the Rokt Thanks offer (positive engagement recorded).                  |
| **Shown, not accepted** | The Rokt Thanks placement loaded and was shown to the customer, but they did not engage with it. |
| **No offer shown**      | No Rokt Thanks offer was served for this order.                                                  |
| **Not loaded**          | The Rokt Thanks placement did not load for this order.                                           |

**Funnel column statuses** (PPU Funnel, TYP Funnel columns)

| Status                           | What it means                                                                                                                                                                                                                                       |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No funnel triggered**          | No funnel matched this order's trigger conditions. The order was eligible but no funnel fired.                                                                                                                                                      |
| **Funnel**                       | A funnel matched the order but showed no offer — either no offers were configured, every configured offer was skipped, or the order had no line items with product IDs. Open the funnel and add an offer to at least one slot.                      |
| **All offers filtered out**      | A funnel was configured and matched the order, but all products across every offer slot were filtered out by your targeting or filter rules. Review your funnel's product filters and targeting to ensure at least one offer has eligible products. |
| **No active funnels**            | Your store had no active funnel available to serve this order.                                                                                                                                                                                      |
| **Ineligible**                   | Shopify skipped the post-purchase page for this order under a platform-level eligibility rule.                                                                                                                                                      |
| **Unsupported shipping country** | The order's shipping country is not on your store's allowed post-purchase countries list — a store-level setting, not funnel targeting.                                                                                                             |
| **Technical issue**              | An error prevented the funnel from being resolved for this order.                                                                                                                                                                                   |

<Note>
  The badge in the Funnel column reads simply **Funnel**. The longer wording — *Funnel not set up* — is what the same underlying reason is called in the Improvement Opportunities panel.
</Note>

<Tip>
  Statuses that are frequently confused:

  * **Customer skipped** = the offer never loaded (the customer left before the page could show)
  * **No interaction** = the offer loaded and was visible, but the customer didn't click anything
  * **Timer expired** = the session timed out while the offer was on screen
  * **Ineligible** = Shopify blocked post-purchase from running at all for this order
  * **No funnel triggered** = the order was eligible but no funnel matched its trigger rules
  * **Funnel** (Funnel column) / **Funnel not set up** (Improvement Opportunities) = a funnel matched but showed no offer
  * **All offers filtered out** = a funnel matched and had offers configured, but every product was filtered out by targeting or filter rules
  * **Subscription upgrade issue** = the offer was accepted and the item added to the order, but the subscription upgrade at your provider failed — open the order for the specific cause and fix
</Tip>

***

## Searching and Filtering Orders

### Search

Use the search bar at the top to find a specific order by name.

### Filters

Click **Add filter +** to filter the order table. Multiple filters can be combined to narrow down results. Click **Clear all** to remove active filters.

| Filter                        | What it does                                                                                                                                                                                                                                                                 |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Post-purchase status          | Filter by the overall post-purchase outcome, grouped into four buckets: **Not eligible**, **No offer shown**, **Shown, not accepted**, and **Accepted**. Use this as a quick top-level filter to find all orders where a customer accepted, declined, or never saw an offer. |
| Post-purchase eligibility     | Filter by whether an order was eligible or ineligible                                                                                                                                                                                                                        |
| PPU Funnel                    | Filter by which post-purchase upsell funnel was shown                                                                                                                                                                                                                        |
| Post-purchase offer 1 / 2 / 3 | Filter by the status of each offer slot                                                                                                                                                                                                                                      |
| TYP Funnel                    | Filter by which Thank You Page funnel was shown                                                                                                                                                                                                                              |
| Thank You page status         | Filter by the outcome on the Thank You Page                                                                                                                                                                                                                                  |
| Payment status                | Filter by payment method or status                                                                                                                                                                                                                                           |
| Post-purchase shown           | Filter by whether the post-purchase page was shown                                                                                                                                                                                                                           |
| Thank You page shown          | Filter by whether the Thank You Page was shown                                                                                                                                                                                                                               |
| Funnel opportunities          | Filter by orders with funnel-level improvement opportunities                                                                                                                                                                                                                 |
| Product opportunities         | Filter by orders with product-level improvement opportunities                                                                                                                                                                                                                |
| Offer opportunities           | Filter by orders with offer-level improvement opportunities                                                                                                                                                                                                                  |
| Ineligibility reason          | Filter by the specific reason an order was ineligible                                                                                                                                                                                                                        |

***

## Viewing an Individual Order

### Viewing an Individual Order

Click any order number to open the order detail view, or use the **More actions → Open order browser** shortcut from the order page in your Shopify admin. This is a complete record of Aftersell activity for that order. Use **View in Shopify** in the top right to open the order directly in Shopify.

<Note>
  The detailed timeline view is only available for orders placed after the Order Browser launch. Orders placed before that date will show limited timeline data.
</Note>

If an order has no Aftersell activity recorded, the detail page shows an informational banner instead of a timeline. This typically means one of the following:

* The order was placed very recently and new orders can take a little while to appear.
* The order predates your Aftersell install, so there was no activity to record.
* The order came from a channel Aftersell does not track, such as POS or subscriptions.

The detail view has up to four collapsible sections in the main column: **Order Summary**, **Post Purchase**, **Thank You Page**, and **Rokt Thanks** — the last shown only when the order has Rokt Thanks activity. Order Summary is expanded by default and the rest start collapsed; click a section header (the chevron on the left) to expand or collapse it. Each section displays a status badge at a glance, for example **1 Accepted** or **No interaction**, so you can understand the outcome without expanding it. The right sidebar holds the section navigation plus separate Customer, Payment method, Order tags, and Discounts codes cards.

<img alt="Individual order detail view with Post Purchase and Thank You Page event timelines" />

### Order Summary

A collapsible section in the main column, open by default. It lists every product in the order — including any accepted upsells — with quantities and pricing, then the order subtotal and total, and finally the name of any Thank You Page funnel whose offer was accepted.

The right sidebar holds four separate cards: **Customer** (shipping address, email, customer tags), **Payment method**, **Order tags**, and **Discounts codes**. All of it pulls from Shopify directly and requires no additional configuration.

### Post Purchase (PPU tab)

A step-by-step milestone timeline of the post-purchase experience for this order.

| Milestone                       | What it means                                                                                                                                                                                                                                                  |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Funnel triggered**            | The funnel fired for this order. Shows the funnel name (click to edit triggers) and the trigger rule that selected it.                                                                                                                                         |
| **Offer shown**                 | An offer was displayed. Shows the products that were presented, with thumbnails.                                                                                                                                                                               |
| **Offer accepted**              | The customer accepted the offer, including revenue amount. If the offer included a subscription upgrade and the upgrade failed at your subscription provider, a red banner appears beneath this milestone showing the specific cause and what to do to fix it. |
| **Offer declined**              | The customer declined the offer.                                                                                                                                                                                                                               |
| **Ineligible**                  | Shopify blocked the post-purchase page for this order. Shows the specific Shopify eligibility reason.                                                                                                                                                          |
| **Technical issue**             | The post-purchase experience failed to load — usually a server or fetch error outside Aftersell's control. (PPU never shows a *Not loaded* status; that label belongs to Rokt Thanks.)                                                                         |
| **Subscription upgrade failed** | The subscription upgrade at your provider failed after the offer was accepted. This row shows the specific failure cause and remediation steps.                                                                                                                |

If products were excluded from an offer, you'll see a **Products excluded** warning beneath the milestone with the specific reason. Possible reasons include:

<AccordionGroup>
  <Accordion title="Ineligible">
    **What caused it:** Shopify blocked the order at a platform level.
  </Accordion>

  <Accordion title="No funnel triggered">
    **What caused it:** No funnel matched this order's trigger conditions.
  </Accordion>

  <Accordion title="All products filtered">
    **What caused it:** Every product in the offer was filtered out by your settings.
  </Accordion>

  <Accordion title="Placement not configured">
    **What caused it:** The offer slot exists but no offer has been set up.
  </Accordion>

  <Accordion title="Product already in order">
    **What caused it:** The offer product was already in the customer's original order.
  </Accordion>

  <Accordion title="Product OOS">
    **What caused it:** The offer product was out of stock at the time of the order.
  </Accordion>

  <Accordion title="Product Inactive">
    **What caused it:** The offer product was unpublished or inactive in Shopify.
  </Accordion>

  <Accordion title="Out of stock at required locations">
    **What caused it:** The offer product was out of stock at the locations required by the offer's per-location inventory filter. Restock at those locations, or adjust the filter on the offer strategy.
  </Accordion>

  <Accordion title="Excluded by tag filter">
    **What caused it:** The offer product was excluded by a product-tag filter on the offer strategy. Review the filter or widen the product pool in your offer strategy.
  </Accordion>

  <Accordion title="Excluded by metafield filter">
    **What caused it:** The offer product was excluded by a product-metafield filter on the offer strategy. Review the filter or widen the product pool in your offer strategy.
  </Accordion>

  <Accordion title="Excluded by product filter">
    **What caused it:** The offer product was excluded by a product filter on the offer strategy. Review the filter or widen the product pool in your offer strategy.
  </Accordion>

  <Accordion title="Timer expired">
    **What caused it:** The post-purchase session timer ran out before the offer had a chance to load.
  </Accordion>
</AccordionGroup>

<Note>
  If you placed a test order and the PPU timeline shows no events or incomplete data, it may be because the order ID wasn't available when the earliest events fired. This resolves automatically as the order completes.
</Note>

### Thank You Page (TYP tab)

Shows the same milestone structure as the PPU tab, filtered to Thank You Page events. A **Technical issue** badge means there was a problem loading the TYP experience for this order.

***

Something not looking right? See the [Order Browser Troubleshooting](/aftersell/order-browser-troubleshooting) guide, or reach out via chat or email us at [support@aftersell.app](mailto:support@aftersell.app).


# Pages vs standalone widgets
Source: https://docs.aftersell.com/aftersell/pages-vs-standalone-widgets



In Checkout , there are two ways to add widgets to your Checkout: **Pages** and **Standalone widgets**. This article explains how each works, when to use them, and how to get them placed in your Shopify Checkout.

### **Which should I use?**

|                     | **Pages**                                | **Standalone widgets**       |
| :------------------ | :--------------------------------------- | :--------------------------- |
| **Best for**        | Displaying multiple widgets together     | Displaying a single widget   |
| **Triggers**        | Shared across all widgets in the page    | Set individually per variant |
| **Block limit**     | Max 5 blocks per widget type             | Max 3 blocks per widget type |
| **Block placement** | One app block per widget inside the page | One app block per widget     |

***

## **Pages**

A Page is a group of widgets that share a single group of triggers. When the trigger conditions are met, all widgets within the page are displayed together. Pages are ideal when you want to show multiple widgets to the same audience at the same time.

### Creating a Page

When creating a page, you have two options: **Guided setup** or **Start from scratch**.

**Guided setup**

The Guided setup walks you through a recommended configuration based on a goal you choose. The setup follows four steps: **Goal, Triggers, Widgets, and Placement.**

**Step 1: Goal**

Choose the goal that best fits what you want to achieve. Each goal comes with a recommended set of widgets pre-configured for you.

| **Goal**                                               | **Recommended widgets**                                         |
| :----------------------------------------------------- | :-------------------------------------------------------------- |
| Increase Average Order Value (AOV) and conversion rate | Upsells, Trust Badges, Testimonials                             |
| Build customer trust and reduce abandonment            | Trust Badges, Cart Controls, Text                               |
| Promote add-ons and accessories                        | Checkbox Upsells, Images, Testimonials                          |
| Encourage customers to reach free shipping threshold   | Upsells (with Rewards), Text                                    |
| Custom configuration                                   | None — start from scratch and build your own widget combination |

**Important:** Your goal cannot be changed after saving. If you need a different goal, you will need to delete the page and create a new one. However, widgets can be added to or removed from a page at any time. Take a moment to choose the goal that best fits your strategy before proceeding.

Once you’ve selected your goal, click **Save and next** to continue.

<img alt="Checkout guided setup Goal step listing recommended goals to choose from" />

**Step 2: Triggers**

Set the conditions under which your page will be shown, or choose to show the page to all customers with no conditions. For a full list of available triggers, see[ <u>Checkout Triggers</u>](/aftersell/checkout_triggers).

**Step 3: Widgets**

Review the widgets that have been recommended for your goal. You can add or remove widgets at this stage, and access advanced settings for each widget. For a full list of available widget types and their settings, see[ <u>Checkout Widget Types</u>](/aftersell/checkout_widget_types).

<img alt="Guided setup Widgets step reviewing recommended checkout widgets with a live preview" />

**Step 4: Placement**

Each widget in your page needs to be placed individually in your Shopify Checkout editor. Each widget is assigned a **BlockID** (e.g., page-upsell-001, page-upsell-002) which is used to identify it when adding the app block in Shopify.

Location recommendations are provided to help you decide where to place each widget on the Checkout Page to place a widget:

1. Note the **BlockID** assigned to your widget in the Aftersell dashboard.
2. Open the **Shopify Checkout editor**.
3. Add the **Aftersell app block**.
4. From the dropdown, select the BlockID that matches your widget (e.g., page-upsell-003).

**Note:** Each widget within a page **has its own BlockID and must be added as a separate app block in the Shopify Checkout editor.** A widget will not display until it has been placed.

<img alt="Shopify Checkout editor adding the Aftersell app block and selecting its BlockID placement" />

***

**Start from scratch**

Start from scratch follows the same process as Guided setup, but skips the Goal step. You configure your triggers, add your widgets manually, and then place them in your Shopify Checkout editor using their BlockIDs.

**Editing a Page**

You can edit a page at any time after creation, including adding or removing widgets and updating triggers. The only thing that cannot be changed is the goal. If you need to change the goal, delete the page and create a new one.

**Duplicating a Page**

To create a copy of an existing page, click the **Duplicate** icon on the page row in the dashboard. The duplicated page is created in an inactive state with the name prefixed by "(Duplicated)" and includes all the same widgets and trigger configuration as the original. You can rename and activate it when ready.

***

## **Standalone widgets**

Standalone widgets are individual widgets, each with their own triggers and priority and are best suited for when you only need to display a single widget all the time or to a targeted group of customers.

### Creating a Standalone widget

Click **Create widget** from the dashboard. You will be prompted to select two things:

* **Widget type**: The type of widget you want to create (Upsells, Rewards, Trust Badges, Testimonials, Cart Controls, Notes, Text, or Images). For a full breakdown of each widget type and its settings, see [Checkout Widget Types](/aftersell/checkout_widget_types).
* **Block**: Which block to add the widget to. There are three blocks available, and the naming follows the widget type you selected. For example:
  * Upsells: Default upsell, Additional upsell 1, Additional upsell 2
  * Trust Badges: Default trust badge, Additional trust badge 1, Additional trust badge 2
  * And so on for each widget type

Each block can hold multiple variants, The block counter in the top-right of the selector shows how many of the 3 available blocks you have created (e.g., 2/3 means 2 blocks created, 1 remaining).

### Block limit

A maximum of **3 blocks** can be used for Standalone widgets. Once all 3 blocks are in use, the **Add new block** option will be unavailable and no additional widgets of the same type can be created until an existing block is removed.

### Placement

Each Standalone widget must be placed in your Shopify Checkout editor as its own app block. When adding an app block in Shopify, you will see BlockID options for your standalone widgets listed as:

* Default placement
* Additional placement 1
* Additional placement 2

The placement value is a routing key, not a position: it tells the app block which stored widget configuration to load. Where a widget actually appears in checkout is decided by where you add its app block in the Shopify Checkout editor — with one exception. **Cart controls** is not freely positionable: it renders after each cart line item wherever the cart is shown. Every other widget type can be added as a block in any location the Checkout editor offers.

To place a widget:

1. Open the **Shopify Checkout editor**.
2. Add the **Aftersell app block** in your desired location.
3. From the dropdown, select the BlockID that corresponds to your widget.

***

## **Analytics**

Analytics are available for both Pages and Standalone widgets. You can view performance data for any individual page or widget by clicking the **bar chart icon** next to it on the dashboard, from within the editor itself or from the Analytics tab in the side navigation


# Post-purchase insights
Source: https://docs.aftersell.com/aftersell/ppu_insights

Understand how your post-purchase funnel performance compares to similar stores using the peer benchmarks feature in Aftersell.

The post-purchase insights page gives you a benchmark view of your revenue per visit (RPV) compared to stores with a similar average order value (AOV) and, where available, a similar industry. This helps you understand how your post-purchase funnel is performing relative to your peers.

This feature is available to all merchants on a post-purchase plan.

***

## Accessing post-purchase insights

You reach post-purchase insights from the home page: a **Peer benchmarks (PPU)** widget appears there, and **View full report** opens the full insights page.

That widget is the only entry point — the report has no sidebar item of its own, and it does not live under the sidebar's **Reports** section (that is the dashboards and Explorer area, which is a different feature).

***

## Peer benchmarks widget

The peer benchmarks widget on your home page gives you a quick snapshot of how your RPV compares to similar stores over the last 30 days.

The widget shows:

* **Your RPV** — Your revenue per visit for post-purchase offers over the last 30 days.
* **Peer comparison** — How your RPV ranks against stores that share your AOV (and industry, if available). The sub-heading describes the comparison being made, for example "Compared to stores that share your AOV and industry · Last 30 days" or "Compared to stores that share your AOV · Last 30 days".
* **Percentile ranking** — Where you fall within your peer group (for example, Top 25%, Average, or Below average).

If your store is new to post-purchase or does not yet have enough data, the widget displays a message explaining that your benchmarks will appear as your store earns with the app.

***

## Full post-purchase insights report

The full report, reached from the home-page widget, includes additional detail across several sections.

### Performance summary

The section, headed **Peer benchmarks** in the app, shows three metric cards — **Revenue per visit**, **Acceptance rate**, and **PPU revenue (30d)**. Each one gives your value, your peer group's median, and a gauge spanning the peer 25th–75th percentile band, plus a tier badge. This lets you see at a glance where you sit against similar stores on each measure.

The peer group is determined by:

* **AOV bucket** — Stores are grouped by average order value range (for example, \$80–100 AOV).
* **Industry** — When your store's industry is available, the peer group combines AOV and industry for a more relevant comparison. If there are not enough peers in the combined cohort, the comparison falls back to AOV only.

The sub-heading on the performance summary describes which comparison is being used.

### Daily RPV trend

The daily RPV trend chart shows your revenue per visit for each day over the last 30 days, plotted alongside the peer group median. This helps you identify patterns, seasonal dips, or improvements in your funnel performance over time.

If there is not enough daily data yet, the chart displays a message to check back after a few days of activity.

### Per-funnel breakdown

The per-funnel breakdown table lists each of your active post-purchase funnels alongside their individual performance metrics, including:

* **Impressions** — How many times the funnel was shown.
* **Acceptance rate** — The percentage of impressions that resulted in an accepted offer.
* **Health status** — One of four labels — **Strong**, **Steady**, **Needs work**, or **No revenue** — based on how your funnel's acceptance rate compares to the peer group median.

You can click **Edit** on any funnel row to go directly to that funnel's trigger settings.

### Recommendations

The recommendations section highlights specific funnels or settings that may help improve your performance, based on your benchmark data.

***

## How the peer group is determined

Aftersell matches your store to a peer group using two dimensions:

| Dimension      | Description                                                         |
| -------------- | ------------------------------------------------------------------- |
| **AOV bucket** | Your store's average order value range (for example, \$80–100 AOV). |
| **Industry**   | Your store's product category or industry, when available.          |

When both dimensions are available, the peer group uses a combined AOV + industry cohort. If that cohort does not have enough stores to produce a reliable benchmark, the comparison falls back to AOV only. The label on the performance summary and widget always reflects which comparison is being used.

***

## Notes

* Benchmark data is updated on a rolling basis and reflects the last 30 days of activity.
* RPV values are shown in your store's currency, converted from USD using the current exchange rate.
* Stores without post-purchase access do not see the widget or the insights page.


# Product Recommendation widget
Source: https://docs.aftersell.com/aftersell/product-recommendation-widget-thank-you-page

Configure the Thank You Page Product Recommendation widget in Aftersell: choose products, design the offer, apply discounts, and set order handling.

The Product Recommendation widget displays upsell products on the Thank You page after checkout. Use it to promote specific products, drive automatic recommendations based on cart contents, or feature a collection. This page covers every setting on the widget. For the full funnel setup and Shopify editor steps, see [How to configure thank-you page widgets](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell).

Add the widget from the **Thank You Page** section of your funnel by clicking **Add Widget** and selecting **Product Recommendation**.

Unlike post-purchase upsells, Thank You page product recommendations are compatible with **all payment gateways** and **multi-currency stores**. Customers re-enter their payment details to complete the upsell purchase, but Aftersell automatically applies their saved shipping information to keep the checkout experience seamless.

<img alt="Aftersell Thank You Page editor with the Product Recommendation widget active and a product selected" />

## Product selection

1. Choose your product selection method:
   * **Specific Products** - Manually select products to display
   * **Automatic Upsells** - Let Aftersell recommend products based on cart contents
   * **Collections** - Display products from a specific collection
   * **Strategy** - Fill the widget from an Aftersell [Strategies](/aftersell/strategies_overview) ruleset. This option appears only when Strategies targeting is active for your store and you have not already picked products by another method.
2. Set the **maximum number of products** to display. There is no fixed maximum, but keeping the count focused (for example, 4-10 products) keeps the offer easy to scan.
3. Enable **Hide product if purchased** so customers are not shown a product they already bought in the same order.
4. Enable **Hide out of stock variants** to filter out unavailable variants so customers only see items they can actually purchase.

When browsing the **Products** tab in the product picker, you can check **Active products only** to hide Draft and Archived products. This filter is off by default and only applies to the Products tab, Collections are not affected.

### Editing specific products

To choose specific products, click **Add upsell products** in the widget editor. Once you have products selected, the button label changes to **Edit upsell products**.

Opening the picker when products are already selected shows your current selection pre-checked. From there you can:

* **Add** new products by checking them.
* **Remove** existing products by unchecking them.
* **Clear** the entire selection by unchecking all products.

Saving the picker reconciles the widget to whatever you leave selected: added products are included, unchecked products are removed, and re-saving an unchanged selection makes no changes. Collection, AI, and Strategy upsell rows are not affected when you edit specific products.

## Display on

The **Display on** setting controls where the widget appears after a customer completes their purchase:

* **On every impression** - Shows the widget on both the Thank You page and the Order Status page.
* **Only on thank you page** - Shows the widget on the Thank You page only.
* **Only on order status page** - Shows the widget on the Order Status page only.
* **Only once on order status page** - Shows the widget on the Order Status page a single time, rather than on every visit.

<img alt="Product recommendation Display on dropdown, Max products field, and hide-product toggles" />

## Offer design

The **Offer design** settings control how product recommendations are presented to customers.

* Choose whether products are displayed in a **horizontal** or **vertical** layout, and adjust visual elements such as borders, button styles, and spacing to match your checkout.
* Add **banner text** above the offer to introduce the recommendation, highlight an incentive, or provide context for the products shown.
* Configure **compare-at price** display and the color used for sale prices.
* Enable a **quantity selector**, customize the quantity label, and set **minimum or maximum quantity limits**.

Compare, Discount, and Sale prices offer two color families:

* **Checkout branding colors** - Accent, Decorative, Info, Subdued
* **Preset colors** - Success (green), Warning (yellow), Critical (red)

<Frame>
  <img alt="The compare-at price color options from both the theme and our presets." />
</Frame>

Some of these settings can also be modified through your Shopify checkout editor or by other apps that offer this functionality.

Two toggles complement the Automatic Discount feature:

* **Show compare at price** - Display the "Compare at" price with a strikethrough.
* **Show discount** - Display the discount on the upsell.

## Discounts and order handling

### Discounts

Apply a discount directly to the upsell by setting a **percentage** or **fixed amount**. The discount is applied automatically when the customer accepts the offer.

Customize how the discount appears with the **discount text** and **discount price color**. Discount colors can use your checkout branding colors (Accent, Decorative, Info, Subdued) or a preset (Success, Warning, Critical). If enabled, the discount display can include the **compare-at price**, shown with a strikethrough to highlight the savings.

<img alt="Thank You page upsell offer for a Hat showing 43 percent off with a strikethrough compare-at price" />

Discounts follow Shopify's standard checkout discount rules. Only one line-item discount can apply to a product at a time, and discounts only combine if marked as **combinable** in Shopify Admin. In some cases, discounts may not apply if another app modifies the checkout. We recommend testing your checkout after enabling discounts.

### Order handling

Order handling controls how an accepted upsell is added to the customer's order. There are two options, each with different trade-offs.

* **Modify original order** - Adds the upsell directly to the existing order. Free shipping is automatically applied. You can optionally email the customer when their order is modified.
* **Create new draft order** - Keeps the original order untouched and creates a separate order for the upsell.

<Frame>
  <img alt="Order handling options to either modify the original order, or to create a new draft order" />
</Frame>

#### When to choose each option

| Use **Modify original order** when...                            | Use **Create new draft order** when...                                                                              |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| You want a single fulfillment for everything the customer bought | You want to re-offer a product the customer just purchased (for example, the same item at a post-purchase discount) |
| Your upsell catalog is distinct from your best-sellers           | Your top-sellers are also your primary upsell candidates                                                            |
| Free shipping on the upsell is the priority                      | You need a separate order for fulfillment or reporting reasons                                                      |
| Your upsell products are not bundle products                     | Your upsell products include bundle products                                                                        |

<Warning>
  **"Modify original order" has limitations.** When this mode is selected, a **Limitations** banner appears in the widget editor listing the following:

  * **Same-variant upsells are hidden.** Shopify's order-edit API does not allow duplicate variants in an order. If the customer already has the upsell variant in their original order, the upsell is hidden from the Thank You page. If an upsell is hidden for this reason, the Order Browser flags the affected order with an "Upsell hidden due to order merging" banner.
  * **Bundle products cannot be added to an existing order.** Shopify's order-edit API rejects bundle products. When a selected upsell variant is a bundle, the outcome follows your **When the order can't be modified** setting:
    * With **Hide the offer and block late acceptances**: the bundle upsell is hidden and customers cannot buy it through this offer.
    * With **Hide the offer, but allow late acceptances as a new order** or **Keep showing the offer and sell it as a new order**: the bundle upsell is fulfilled as a separate draft order instead of being merged into the original order.

  Switch to **Create new draft order** if you want bundle products or same-variant upsells to always be available to customers.
</Warning>

#### When the order can't be modified

When **Modify original order** is selected, some orders can't be edited at the time a customer accepts the upsell. There are exactly three cases: the order has been **archived**, it is **partially paid**, or it is older than the **expiry window** you set below. The **When the order can't be modified** setting controls what happens in those cases.

A **fulfilled** order is not one of them, it can still be edited, but only upsell products that don't require shipping can be merged into it (see the note further down).

| Option                                                        | What it does                                                                                                                                                                                                                          |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hide the offer and block late acceptances**                 | The offer is hidden once the order can no longer be edited. Any acceptance that arrives after the order becomes ineligible is blocked.                                                                                                |
| **Hide the offer, but allow late acceptances as a new order** | The offer is hidden once the order can no longer be edited. If a customer accepts just before the offer hides (a race-window accept), the upsell is fulfilled as a separate draft order instead. This is the default for new widgets. |
| **Keep showing the offer and sell it as a new order**         | The offer stays visible regardless of whether the order can be edited. If the order can't be modified, the accepted upsell is fulfilled as a separate draft order.                                                                    |

The two fallback options create a separate draft order for the upsell when the original order can't be modified. The customer receives a payment link to complete the purchase as a new order.

#### Setting an expiry window

You can set a time limit on how long an order remains eligible for merging. Use the **Consider the order uneditable after** field (located under the behavior selector in **Order handling**) to enter a number of minutes. Once that many minutes have passed since the order was placed, the order is treated as ineligible and the **When the order can't be modified** behavior applies.

Leave the field blank or set it to **0** to never expire, the offer remains eligible for as long as the order itself is editable.

This is useful when your fulfillment workflow processes orders quickly and you want to avoid attempting to merge into an order that is likely already in progress.

#### Other things to know about "Modify original order"

* Free shipping is automatically applied and cannot be disabled.
* The original order is marked as **partially paid** until the customer completes payment for the added upsell. Once payment is captured, Shopify updates the order automatically.
* If the order is already fulfilled, has no shipping line, or contains only items that don't require shipping, only upsell products that **don't require shipping** can be merged into it. Products that do require shipping are dropped from the offer on those orders.

### Free shipping

You can offer **free shipping** on accepted upsell products to help increase conversion. When enabled, customers are not charged shipping for the upsell, while your existing Shopify shipping settings continue to apply to the original order.

How the Free shipping toggle behaves depends on your **Order handling** setting:

* **Modify original order** - Free shipping is automatically applied to the accepted upsell and the toggle can't be disabled.
* **Create new draft order** - The Free shipping toggle applies to the separate draft order created for the upsell. When enabled, the draft order is created without shipping charges on the upsell line item. Leave the toggle off if you want Shopify's normal shipping rates to apply to that new order.

The same behavior applies when a fallback creates a separate draft order under **Modify original order** (for example, a same-variant or bundle upsell, or an acceptance after the order becomes uneditable): the Free shipping toggle controls whether the draft order is created without shipping charges on the upsell.

You can also display a **"Free Shipping" badge** on the offer and customize the badge text to highlight the benefit.


# Product page upsells
Source: https://docs.aftersell.com/aftersell/product_page_upsells

This article outlines how to setup product page upsells.

The Product Page Upsells (PDP Upsells) feature in Aftersell allows you to create compelling upsell offers directly on your product pages. This guide will walk you through how to set up and optimize this feature to boost customer engagement and increase sales.

***

# Introduction to Product Page Upsells

The Product Page Upsells feature enables you to display relevant, complementary, or related product offers directly on the product page of your store. This functionality helps boost conversions by encouraging customers to purchase additional items.

* Customers do not need to make a purchase before seeing Product Page Upsells. These appear based on triggers you set, such as specific products or page conditions.

This feature mimics the popular **"Buy It Together"** experience found in many leading ecommerce platforms by offering a seamless and effective upselling opportunity without interrupting the customer's journey.

***

# Setting Up Product Page Upsells

## Step 1: Create an Upsell Offer

1. Open the Aftersell Product Page Upsells dashboard and click Create New Upsell.
2. Choose which product(s) or collection(s) will trigger the upsell.
3. Select up to five products to display as upsell offers.
4. *(Optional)* Add a discount to make your offer more enticing. When a discount is applied, a value tag is shown to customers on the upsell widget, in parentheses — for example, **(\$100 OFF)** or **(CA\$130 OFF)** for fixed-amount discounts, and **(22% OFF)** for percentage discounts. The label uses the customer's presentment currency, so it always matches the actual discount applied at checkout. The wording comes from the **Discount Text** field under **Design → Pricing**, which defaults to `{{DISCOUNT_AMOUNT}} OFF` — edit it there to change the label.
5. Save your setup when complete.

<img alt="Aftersell New Product Page Upsell editor Configure tab with triggers, products, and discount options" />

## Step 2: Add the app block to the product page

To display upsells on your product pages:

1. Open the Shopify Theme Editor from your Aftersell dashboard.
2. Select **Add block**, then the **Apps** tab, then **PDP Upsell**. The block is not added for you — the link opens the product template so you can place it yourself.
3. Drag it to your preferred position on the page.
4. Save your setup when complete.

<img alt="Shopify Theme Editor with the Aftersell PDP Upsell app block placed showing a product page preview" />

**Note:** You can't move app blocks between sections, but you can reorder them within the same section.

## Translating Product Page Upsells

Only two sections within the Product Page Upsell widget require translation.

### 1. Header Text

The "You may also like" text displayed above the upsell products can be updated.

To edit this:

Go to **Design → Header → Heading Text**

Replace the text with your preferred language.

### 2. Add to Cart Button

The "Add to cart" button text can also be translated.

To edit this:

Go to **Design → Button → Text**

Update the button text to match your store's language.

# **Individual Products vs Bundles**

* **Individual Products:** Customers can add upsell items separately
* **Bundles:** Customers can add multiple products at once with a single discount or a Buy X, Get Y Free offer.

***

# Compatibility with Shopify Themes

Product Page Upsells requires a Shopify theme that supports adding app blocks.\
Most modern themes (2021 and later) are compatible. If you're using an older "vintage" theme, please upgrade to a newer Shopify theme to enable app blocks and unlock this feature.
Most modern themes (2021 and later) are compatible. If you're using an older "vintage" theme, please upgrade to a newer Shopify theme to enable app blocks and unlock this feature.

***

# Discounts and strategy pricing

When you configure a discount on a product page upsell widget, the discount applies to all products the widget returns. If you also assign a strategy to the widget, and that strategy includes per-rule price adjustments, the two discount sources work together on a per-product basis:

* **Products targeted by a strategy rule discount** — the strategy's rule discount applies to those products.
* **Products returned by the strategy but not targeted by a rule discount** — the widget's configured discount applies as a fallback.
* The two sources never stack. Each product receives exactly one discount — either the strategy rule's adjustment or the widget discount, never both.

When the selected strategy carries a rule discount, the widget editor shows an informational banner:

> *"This strategy applies its own discount to the products it targets. The discount below is the fallback for products it doesn't discount."*

The discount section remains fully editable. You can configure the widget discount as the baseline for any products the strategy returns but doesn't specifically discount.

> **Note:** Strategy price adjustments apply to Product Page Upsells V2, a newer version of this feature that is not yet generally available — V1 upsells have no strategy field at all. Stores are moved to V2 by the Aftersell team, and only stores already using Strategies are eligible.

***

# **Limitations**

* Subscription-only products can't be used as upsells.
* Bundles won't appear if an included product is out of stock, this ensures accurate pricing and protects margins.

***

# Translating product page upsells

Only two sections within the Product Page Upsell widget require translation.

### 1. Header Text

The "You may also like" text displayed above the upsell products can be updated.

To edit this:

Go to **Design → Header → Heading Text**

Replace the text with your preferred language.

### 2. Add to Cart Button

The "Add to cart" button text can also be translated.

To edit this:

Go to **Design → Button → Text**

Update the button text to match your store's language.

***

# **Final Steps**

Once you've added the app block and created your offer, activate your upsell to start increasing conversions.

<img alt="Aftersell Your Upsells table with the status toggle highlighted to activate the upsell" />

***

By following these instructions, you can implement the Product Page Upsells feature to enhance your store's sales potential.

For help setting up or troubleshooting, please contact the **Aftersell Support Team** directly from the app.


# Product targeting API security tokens
Source: https://docs.aftersell.com/aftersell/product_targeting_api_security_tokens

Generate and manage security tokens to authenticate API requests for product targeting strategies

Security tokens allow you to authenticate API requests when accessing your product targeting strategies programmatically. You can generate, view, and regenerate tokens directly in the Aftersell admin.

## Generating a security token

To generate your first security token:

1. Navigate to **Settings → Product Strategy** in the Aftersell admin
2. Locate the **Security Token** card at the top of the page
3. Click **Generate Token**
4. Your new token will be displayed - click **Copy** to copy it to your clipboard

⚠️ **Important:** Make sure to copy your token immediately after generation. You won't be able to see it again after you leave the page.

## Viewing your token

After generating a token, you can:

* **Show/hide the token:** Click the eye icon to toggle visibility
* **Copy the token:** Click the **Copy** button to copy it to your clipboard

The token is masked by default for security. Once you navigate away from the page, the token will be permanently hidden and can only be regenerated (which invalidates the previous token).

## Regenerating a token

If you need to create a new token (for example, if your current token was compromised):

1. Navigate to **Settings → Product Strategy** in the Aftersell admin
2. In the **Security Token** card, click **Regenerate**
3. Your new token will be displayed - click **Copy** to save it

⚠️ **Warning:** Regenerating a token will immediately invalidate your previous token. Any API requests using the old token will fail. Make sure to update all systems using the old token before regenerating.

## Using your security token

Send your security token in the `X-Strategy-Api-Key` header on every Strategy API request. Keep your token private and secure - treat it like a password.

<Warning>
  Only one token can be active per store at a time. Generating a new token immediately invalidates the previous one, so a single token has to be shared by every environment that calls the API - you cannot issue separate development, staging, and production tokens.
</Warning>

💡 **Best practices:**

* Store tokens securely (never commit them to version control)
* Regenerate tokens if you suspect they've been compromised
* Update every system that uses the token before you regenerate it, since the old token stops working immediately
* Keep a record of when tokens were generated and where they're being used


# Manage reports
Source: https://docs.aftersell.com/aftersell/reports_dashboards

Create and manage custom analytics reports in Aftersell's Reports section.

The Reports section lets you build custom reports from saved queries, giving you a flexible view of your store's analytics beyond the standard Analytics tabs.

***

## Navigating your reports

When you open the Reports section, you land on the **Reports** table. This table lists every report available to your store, including default reports (provided by Aftersell) and any reports you have created.

Each row in the table shows:

* **Name** — the report name
* **Type** — either **Default** (a report provided by Aftersell) or **Custom** (a report you created)
* **Last updated** — the date and time the report was last modified
* **Delete** — available on your own (Custom) reports only; Default reports cannot be deleted

Click any row to open that report.

***

## Creating a report

To create a new report, click **Create report** in the top-right corner of the Reports table. This immediately creates a new blank report named `Untitled report N` and opens it in view mode. Click **Add widget** to start filling it.

If you have no reports yet, the same **Create report** button appears in the empty state.

***

## Report controls

Three controls apply to every widget on the report at once, so all cards stay in sync. By default, each control is set to **Chart Default**, which inherits the date range, comparison, and timezone of widgets added to the report.

* **Date Range** — set the period you want to see.
* **Comparisons** — compare the selected period against another. The options are **Chart default**, **No comparison**, and **Previous period**; year-on-year is not offered, because reporting data does not yet go back a full year.
* **Time Zone** — set the timezone used for dates and time-based grouping.

***

## Renaming a report

You can rename any report you created (Custom reports only — Default reports cannot be renamed).

1. Open the report by clicking its row in the Reports table.
2. Click **Edit report**. A **pencil icon** appears next to the report title in the header.
3. Click the pencil icon, type the new name, and press **Enter**, or click away to save.

***

## Editing a report

To add or rearrange widgets on a report you own:

1. Open the report.
2. Click **Edit report** in the header.
3. In edit mode, a **Widgets** panel appears on the left. Drag a saved query from the panel onto the grid to add it as a widget.
4. You can also click **Add widget** to build a new query in the Explorer and add it to the report.
5. When you are done, click **Save** to keep your changes, or **Cancel** to discard them.

<Note>
  Default reports (Type: Default) are read-only and cannot be edited.
</Note>

***

## Widgets

Each item on a report is a **widget** — a saved query rendered as a visualization. For adding, configuring, and arranging widgets, see [Manage widgets](/aftersell/reports_widgets).

***

## Sharing a report

When viewing a report, click the **Share** button in the header to generate a shareable link. The recipient opens the report in fullscreen view. The link can only be opened by users authenticated to your Shopify store.

***

**Need help?** Contact the Aftersell support team through your report.


# Explorer
Source: https://docs.aftersell.com/aftersell/reports_explorer

Build custom analytics queries and reports using the Explorer in Aftersell.

The Explorer lets you build custom analytics queries using a flexible query builder (AftersellQL). You can select metrics, group results by dimensions, apply filters, and visualize data in charts or tables. Saved queries can be added to reports as widgets for ongoing monitoring.

<Tip>
  You build queries visually with menus — no syntax required. If you prefer to type queries directly, the Explorer also exposes the underlying AftersellQL text. See [Writing AQL queries](#writing-aql-queries) below for the syntax reference.
</Tip>

***

## Available metrics

These are the metrics you can pick in the Explorer, grouped the same way the metric picker groups them.

### Revenue & profit

| Metric                       | Description                                                                                                                                                                                                                                                                                          |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Revenue**                  | Upsell revenue in your store's native currency.                                                                                                                                                                                                                                                      |
| **Revenue (USD)**            | Upsell revenue normalized to USD for cross-currency comparisons.                                                                                                                                                                                                                                     |
| **Revenue Per Visit**        | Upsell revenue per impression session. Cannot be broken down by product, placement, funnel, or device.                                                                                                                                                                                               |
| **Avg. Conversion Value**    | Revenue per accepted offer. Also referred to as Average Upsell Value.                                                                                                                                                                                                                                |
| **Upsell Revenue Per Order** | Upsell revenue (USD) divided by total orders. Store-level only.                                                                                                                                                                                                                                      |
| **Product Profit**           | Revenue minus cost of goods sold (COGS) for upsold products. Relies on merchant-configured COGS, so treat it as an estimate: products without a tracked cost report revenue as profit, and cost coverage varies by store. Product-grain only; cannot be broken down by funnel, placement, or device. |

### Conversions

| Metric           | Description                                                                                                                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Conversions**  | The number of accepted-offer events. One accepted offer is one conversion, so a session that accepts two offers counts twice.                                                                   |
| **Accept Rate**  | Session-based: the share of sessions that saw an offer and accepted at least one. It is computed independently of Conversions, from a different rollup, so it is not Conversions ÷ Impressions. |
| **Units Sold**   | Total units sold through upsell offers.                                                                                                                                                         |
| **Decline Rate** | Percent of post-purchase offers explicitly declined. Post-purchase only.                                                                                                                        |

### Engagement

| Metric          | Description                                          |
| --------------- | ---------------------------------------------------- |
| **Impressions** | Unique sessions that saw an offer.                   |
| **Show Rate**   | Percent of decisions that resulted in an impression. |

### Store performance

| Metric                        | Description                                                                                                          |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Total Store Revenue**       | Total Shopify-paid order revenue. Store-level only — cannot be broken down by surface, funnel, placement, or device. |
| **Orders**                    | Total Shopify-paid orders. Store-level only.                                                                         |
| **Average Total Order Value** | Store revenue divided by orders. Store-level average order value.                                                    |

### Rokt network

| Metric                         | Description                                                                                          |
| ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| **Rokt Revenue**               | Rokt-network revenue attributed to your store.                                                       |
| **Rokt Transactions**          | Rokt-network transaction count for your store.                                                       |
| **Rokt Revenue / Transaction** | Rokt revenue divided by transactions per time bucket.                                                |
| **Rokt Impressions**           | Total Rokt-network impressions across your store's placements. Distinct from upsell **Impressions**. |
| **Rokt Referrals**             | Rokt-network referrals — positive engagements that sent the shopper to a Rokt partner.               |

***

## Dimensions

Dimensions let you break down metrics by a specific attribute. Not all dimensions are compatible with every metric.

<Note>
  Some dimension and metric combinations are incompatible. For example, **Decline rate** and **Show rate** cannot be broken down by **Currency**. The Explorer automatically prevents incompatible combinations.
</Note>

### Available dimensions

| Dimension     | Description                                                                                                                                        |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Date**      | Groups results by day, week, or month.                                                                                                             |
| **Surface**   | The upsell surface. One of PPU (post-purchase), Checkout, Thank You Page, or Cart.                                                                 |
| **Funnel**    | The specific funnel the offer belongs to.                                                                                                          |
| **Product**   | The upselled product.                                                                                                                              |
| **Placement** | The placement within a funnel.                                                                                                                     |
| **Device**    | The device type: Mobile, Desktop, or Unknown. There is no separate tablet value.                                                                   |
| **Currency**  | The ISO currency code (for example, USD, EUR, GBP). Useful for multi-currency stores. Compatible with store-level metrics and most upsell metrics. |

### Unavailable dimensions

The following dimensions are a work in progress. They appear in the picker but are not yet available as a breakdown. Instead, they show as 'Not compatible' for every metric. **This document will be updated when these dimensions are fully implemented.**

| Dimension         | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| **Flow type**     | The type of upsell flow.                                       |
| **Experiment**    | The A/B test or experiment variant.                            |
| **Outcome**       | The decision outcome (for example, eligible, out of stock).    |
| **Reason code**   | The reason for a decision outcome.                             |
| **Scope**         | The decision scope (Flow, Experience, Placement, or ItemSlot). |
| **Response type** | The offer response (Accepted, Declined, or Timeout).           |

***

## Writing AQL queries

Every query you build in the Explorer is an **AftersellQL (AQL)** statement. Most of the time you build queries visually — picking metrics, dimensions, filters, and a date range from menus — and never need to write AQL by hand.

For power users, the Explorer also exposes the underlying query as editable text. This section is the reference for that text form: what the clauses mean, what values they accept, and a few ready-to-use examples.

### How an AQL statement reads

An AQL statement is a single question made of clauses. Only `SELECT` and a time range (`SINCE`) are required; everything else is optional. When you include optional clauses, they must appear in the order shown below.

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT    <metrics>                    -- what to measure (required)
WHERE     <filters>                    -- narrow the data
GROUP BY  <dimensions>                 -- break the numbers down
SINCE     <time range>                 -- the period to cover (required)
GRAIN     <time grain>                 -- bucket size for time series
COMPARE   <comparison>                 -- compare against another period
CHART     <visualization>              -- how to display the result
TIMEZONE  "<timezone>"                 -- timezone for date buckets
ORDER BY  <field> <direction>          -- sort the results
LIMIT     <number>                     -- cap the number of rows
```

A minimal example — daily upsell revenue and accept rate for the last 30 days:

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT revenue, accept_rate
GROUP BY date
SINCE last_30d
GRAIN day
```

<Note>
  Keywords are not case-sensitive (`SELECT` and `select` both work) and statements do not end with a semicolon. String values are wrapped in double quotes; numbers and lists are not.
</Note>

### Picking what to measure and how to slice it

* **`SELECT`** lists the metrics to measure, separated by commas — for example `SELECT revenue, impressions, accept_rate`.
* **`GROUP BY`** breaks those metrics down by one or more dimensions, such as `date`, `device`, `surface`, or `funnel`. Without `GROUP BY`, you get a single total for the whole period.

For the full list of available metrics and dimensions — and which combinations are allowed — see [Available metrics](#available-metrics) and [Available dimensions](#available-dimensions) above. The Explorer prevents incompatible metric and dimension combinations automatically.

#### Filtering with `WHERE`

`WHERE` narrows the data before it is measured. Combine conditions with `AND`.

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT revenue
WHERE device = "mobile"
GROUP BY date
SINCE last_month
GRAIN day
```

<Warning>
  `impressions`, `accept_rate`, and `rpv` **cannot** be filtered or grouped by device, funnel, placement, or product — their source rollup has no such column. Adding `WHERE device = "mobile"` to a query selecting any of them is rejected with `metric "impressions" cannot be filtered by "device"`.
</Warning>

Supported comparisons are `=`, `!=`, `IN`, `NOT IN`, `>`, `<`, `>=`, and `<=`. Use a list with `IN` to match several values:

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
WHERE surface IN ["PPU", "Checkout"]
```

`experiment` is **not** a filterable field — it has no rollup source, so `WHERE experiment IN [...]` is rejected with `filters on "experiment" are not supported.` (It is listed under **Unavailable dimensions** below for the same reason.)

#### Filtering by multiple funnels

The **funnel** filter supports multi-select operators so you can scope a query to a subset of your funnels:

* **is one of** — includes only the selected funnels (`IN`).
* **is not one of** — excludes the selected funnels (`NOT IN`).

When you choose **is one of** or **is not one of**, the value input changes to a scrollable checkbox list showing all your funnel names. Select as many funnels as you need.

When you group results by **Funnel** and apply an **is one of** filter, the line chart shows one line per selected funnel — even if you select more than the default number of series. No selected funnel is collapsed into an "Other" category.

### Time ranges and comparisons

Every query needs a time range, set with `SINCE`. Use a preset or a custom window.

| Form          | Example                             | Meaning                                                                                                                                                                              |
| ------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Preset        | `SINCE last_30d`                    | A rolling window ending **yesterday** (UTC). The in-flight current day is deliberately excluded, so `last_1d` means yesterday only, and `this_month` runs from the 1st to yesterday. |
| Custom window | `SINCE 2026-07-02 UNTIL 2026-07-05` | A fixed range, using ISO dates (`YYYY-MM-DD`).                                                                                                                                       |

Available presets: `last_1d`, `last_7d`, `last_30d`, `last_90d`, `this_month`, `last_month`, and `this_year`.

* **`GRAIN`** sets the bucket size for time series — `day`, `week`, or `month`. (`hour` parses but no rollup serves hourly data, so such a query is rejected with `group_by / time_grain combination is not supported.`)
* **`COMPARE`** overlays a second period so you can see change at a glance. Use `previous_period` — the equal-length window immediately before. `previous_year` is deliberately hidden from the Compare picker because the warehouse holds no data from before February 2026; it remains typeable in AQL only so previously saved queries keep parsing.

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- A four-day sale vs the four days immediately before it
SELECT revenue, impressions, accept_rate
GROUP BY date
SINCE 2026-07-02 UNTIL 2026-07-05
GRAIN day
COMPARE previous_period
```

<Note>
  Reporting data starts in **February 2026**, so a window earlier than that returns empty for both periods. That is also why year-on-year comparisons aren't offered yet.
</Note>

### Choosing a chart and timezone

These optional clauses are usually set for you by the Explorer's visual controls, but you can also write them directly:

* **`CHART`** sets how the result is displayed: `scorecard`, `line_chart`, `bar_chart`, `area_chart`, `funnel_chart`, or `table`.
* **`TIMEZONE`** sets the timezone used to bucket dates, as a quoted IANA name — for example `TIMEZONE "America/New_York"`. Defaults to UTC.

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT revenue
GROUP BY date
SINCE last_30d
GRAIN day
CHART line_chart
TIMEZONE "America/New_York"
```

The `funnel_chart` type has specific requirements:

* **Placement mode** — Group by `placement` and select one metric. Stages are ordered by the canonical placement sequence (upsell default → downsell → additional upsells). Only the first metric is plotted; additional selected metrics are noted in a footnote.
* **Metric mode** — Select two or more metrics with no `GROUP BY`. Each metric becomes a funnel stage in query order (for example, `SELECT impressions, conversions` shows an impressions → conversions drop-off). All metrics must share the same unit (for example, you cannot mix currency and percentage metrics).

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Placement funnel: conversion drop-off across placements
SELECT conversions
GROUP BY placement
SINCE last_30d
CHART funnel_chart
```

<Warning>
  Placement mode needs a metric that can actually be broken down by placement. `impressions`, `accept_rate`, and `rpv` cannot — the funnel chart shows "These metrics can't be grouped by placement" for those.
</Warning>

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Metric funnel: impressions to conversions drop-off
SELECT impressions, conversions
SINCE last_30d
CHART funnel_chart
```

### Sorting and limiting

* **`ORDER BY`** sorts results by a metric or dimension, with `ASC` or `DESC`.
* **`LIMIT`** caps the number of rows returned — useful for "top N" style questions.

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Top 20 products by upsell revenue this month
SELECT revenue, conversions, avg_conversion_value
GROUP BY product
SINCE this_month
ORDER BY revenue DESC
LIMIT 20
```

### More examples

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Daily performance vs the previous period
SELECT revenue, impressions, conversions, accept_rate
GROUP BY date
SINCE last_30d
GRAIN day
COMPARE previous_period
```

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Mobile vs desktop revenue over the last 90 days
SELECT revenue
GROUP BY device
SINCE last_90d
ORDER BY revenue DESC
```

<Note>
  `impressions`, `accept_rate`, and `rpv` can't be broken down by device — their rollup is shop × surface × day, with no device column. Use `revenue` (or another conversion-sourced metric) for device comparisons.
</Note>

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Which surface is driving the most revenue?
SELECT revenue, impressions, accept_rate
GROUP BY surface
SINCE last_30d
ORDER BY revenue DESC
```

Once you have a query you like, save it and add it to a report as a widget so it keeps updating — see [Manage widgets](/aftersell/reports_widgets). To remove a widget you no longer need, load it in the Explorer and click **Delete** in the title bar. Deleting a widget removes it from every report it appears on. The **Delete** button is only shown for widgets you own; global template widgets are read-only.

***

## Exporting results

The Explorer shows your query results on screen as a scorecard, chart, or table — it does not download a file directly from the query view.

To get the results as a file, save the query and add it to a report as a [widget](/aftersell/reports_widgets). Each widget has its own **Export to CSV** button that downloads the widget's data as a `.csv` file. For the standard Analytics-page exports (Excel and CSV), see [Exporting your data](/aftersell/analytics_in_aftersell#exporting-your-data).

***

## Timezone support

By default, queries run in UTC. You can override the timezone for any query directly in the Explorer toolbar, so that date-bucketed results (daily, weekly, monthly breakdowns) reflect your local time rather than UTC.

<Note>
  Queries that include **Impressions**, **Accept Rate**, or **Revenue Per Visit** always bucket dates in UTC, regardless of the timezone you select. These metrics are sourced from a daily rollup that's only reported in UTC days. If a query mixes one of these metrics with others, the whole result set falls back to UTC so date buckets stay aligned.
</Note>

### Setting a timezone for a query

1. Open the Explorer in your Aftersell admin.
2. In the toolbar, click the **Timezone** selector (next to **Compare**).
3. Choose one of the available timezones from the list, or select **Account default** to use the timezone configured in your analytics settings.
4. Run your query. Results are bucketed using the selected timezone.

The selected timezone is saved with the query. When you save and reload a query, the timezone is restored automatically.

### Account default timezone

If you have **Lock reporting timezone** enabled in your analytics settings, selecting **Account default** in the toolbar uses that locked timezone for your query. The toolbar label shows the resolved zone, for example **Timezone: Account default (Paris (CET))**.

The analytics settings page accepts the full IANA timezone list, but Reports honours only the ten zones above. If your locked zone is not one of them, **Account default** silently resolves to UTC — so pick a locked zone from this list if you want Reports to follow it.

If **Lock reporting timezone** is not enabled, **Account default** falls back to UTC.

### Specifying a timezone in AQL

You can also specify a timezone directly in your AQL query using the `TIMEZONE` clause, which appears between `CHART` and `ORDER BY`:

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT ...
CHART ...
TIMEZONE "Asia/Tokyo"
ORDER BY ...
```

When present, the clause overrides the toolbar selection for that query. The timezone is preserved when you save and reload the query.

### Available timezones

The timezone picker includes the following options:

| Timezone             | Example location           |
| -------------------- | -------------------------- |
| UTC                  | Universal Coordinated Time |
| America/New\_York    | New York (ET)              |
| America/Chicago      | Chicago (CT)               |
| America/Denver       | Denver (MT)                |
| America/Los\_Angeles | Los Angeles (PT)           |
| Europe/London        | London (GMT/BST)           |
| Europe/Paris         | Paris (CET/CEST)           |
| Asia/Tokyo           | Tokyo (JST)                |
| Asia/Singapore       | Singapore (SGT)            |
| Australia/Sydney     | Sydney (AEST/AEDT)         |

This is a closed set of ten zones. Any other IANA timezone in a `TIMEZONE` clause is rejected as unsupported.

### How timezone affects query results

When a timezone is set, date-bucketing in your query uses local time instead of UTC. For example, an event that occurred at `2026-03-29T01:30:00Z` (UTC) falls on March 28 in New York time (ET) but on March 29 in Paris time (CET). Setting the correct timezone ensures your daily, weekly, and monthly breakdowns match your business reporting expectations.

Queries that do not include a timezone — including previously saved queries — continue to run in UTC, so existing results are not affected.

***

## Need help?

If you have questions about the Explorer or want to enable access, contact the Aftersell support team through the in-app chat.


# Reports overview
Source: https://docs.aftersell.com/aftersell/reports_overview

Explore your store's performance with custom reports and the query Explorer in the Aftersell Reports section.

<Note>
  Reports is in beta and is being rolled out in stages, so it is not yet enabled on every store. Some stores are switched on automatically as the rollout widens; others are enabled individually. If you don't see the Reports section in your dashboard, your store has not been included yet — contact the Aftersell support team through the in-app chat to ask about access.
</Note>

The Reports section is a flexible way to explore your store's performance. It has two parts that work together:

* **Reports** — collections of saved queries shown as widgets, for monitoring the metrics you care about at a glance.
* **The Explorer** — a query builder for asking your own questions: pick metrics, break them down by dimensions, filter, and visualize the result.

***

## Reports

When you open Reports, you land on the **Reports** table listing every report available to your store. See [Manage reports](/aftersell/reports_dashboards) for creating, editing, and sharing them.

***

## Exploring your data

Open the [Explorer](/aftersell/reports_explorer) to build a query from scratch — choose what to measure, how to slice it, and the time range, then view the result as a scorecard, chart, or table. Save a query to reuse it, or add it to a report as a [widget](/aftersell/reports_widgets).

Queries are written in **AftersellQL (AQL)**. You build them visually, but you can also type them directly — see [Writing AQL queries](/aftersell/reports_explorer#writing-aql-queries).

***

## Need help?

Questions about Reports, or want a specific report set up? Reach out to the customer support team.


# Manage widgets
Source: https://docs.aftersell.com/aftersell/reports_widgets

Add, configure, and arrange widgets — the saved-query cards that make up a Report.

A **widget** is a single saved [AftersellQL query](/aftersell/reports_explorer#writing-aql-queries) rendered as a visualization on a report. A report is simply a grid of widgets.

<Note>
  A "widget" here means a widget on a Report. It is not the same as the shopper-facing [checkout widgets](/aftersell/checkout_widget_types) or [post-purchase widgets](/aftersell/post_purchase_widgets), which are upsell offers shown to your customers.
</Note>

***

## Adding a widget

There are two ways to add a widget to a report:

* **Drag an existing widget from the Widgets sidebar.** While editing a report (click **Edit report** — see [Manage reports](/aftersell/reports_dashboards)), drag an already-created widget from the **Widgets** sidebar onto the canvas.
* **Click Add widget from the report.** From the report's main view, click **Add widget** to build a new query in the Explorer and add it to the report. Once saved, your widget will be added directly to the Report canvas.

***

## Visualizations

Depending on the query's shape, a widget renders as one of:

* **Scorecard** — a single headline number, for queries with no breakdown.
* **Line chart** — a trend over time.
* **Area chart** — a trend over time with the area beneath the line filled.
* **Bar chart** — a comparison across a dimension.
* **Funnel chart** — drop-off across placements, or across a sequence of metrics.
* **Table** — rows of values, for detailed or multi-dimension queries.

The Explorer recommends a default visualization for each query, and the widget uses it.

***

## Exporting a widget

Each widget has an **Export to CSV** button that downloads the widget's current data as a `.csv` file. This exports the underlying query result — the same numbers shown in the widget's chart or table — so you can work with them in a spreadsheet.

***

## Arranging widgets

In edit mode you can drag widgets to reorder them and resize them on the grid. When you are done, click **Save** to keep your layout, or **Cancel** to discard your changes.

***

## Deleting a widget

You can permanently delete a saved widget from the Explorer. Deleting a widget also removes it from every report it appears on.

To delete a widget:

1. Open the report the widget is on.
2. Click the widget's card. This opens it in the **Explorer**.
3. Click **Delete** in the Explorer title bar.
4. Confirm the deletion in the dialog that appears.

<Note>
  The Explorer has no list of saved widgets to pick from — a widget is only opened by clicking its card on a report. The rows in the edit-mode **Widgets** sidebar are drag handles for placing widgets, and cannot be clicked to open one.
</Note>

The widget is permanently removed and any report cards that referenced it are automatically cleaned up.

<Note>
  The **Delete** button is only shown for widgets you created. Global template widgets are read-only and cannot be deleted.
</Note>

***

## Need help?

If you have questions about widgets, reach out to the customer support team.


# Rokt Thanks loyalty loop
Source: https://docs.aftersell.com/aftersell/rokt_thanks_loyalty_loop

How Loyalty Loop drives repeat purchases by sending customers a discount code for your store after they sign up for a Rokt Thanks offer

Loyalty Loop is a Rokt Thanks feature that drives repeat purchases on your store. When a customer signs up for a partner offer on your Thank You Page, Rokt automatically sends them a follow-up email containing a unique discount code redeemable on your store - giving them an incentive to come back and buy again.

<Note>
  Loyalty Loop has not been released to merchants yet — the setting is currently visible for internal testing only, so you will not find it in your admin. When it does launch it will require your store to price in USD.
</Note>

***

## How it works

1. A customer completes a purchase on your store and sees the Rokt Thanks placement.
2. They sign up for a partner offer on that placement.
3. Rokt's system processes the sign-up within 24 hours. Aftersell generates a unique discount code directly in your Shopify admin - you'll see it appear in your Shopify **Discounts** section.
4. The customer receives a follow-up email containing their discount code, redeemable on your store.

The discount code is unique to each customer and generated specifically for their session.

***

## Benefits

Loyalty Loop turns the revenue earned from Rokt Thanks into a tool for driving repeat purchases. The placement generates revenue from partner advertisers, which offsets the cost of the discount sent to your customers - creating a cycle that rewards loyalty without eroding your margins.

Customers who sign up for an offer receive a tangible reward: a discount code they can use on their next purchase with you.

***

## Enabling Loyalty Loop

Loyalty Loop can be enabled from **Settings > Rokt Network** in the Aftersell admin.

When setting it up, you'll configure the following:

* **Discount amount** - the value of the discount code sent to customers (minimum \$5)
* **Expiry** - how long the discount code remains valid (minimum 30 days)
* **Terms & Conditions** - a link to your T\&Cs, which will be included with the offer shown to customers. You can link to your existing T\&Cs page if it covers this use case, or create a new one and link it here.

Once enabled, everything else happens automatically behind the scenes. As customers sign up for the offer, discount codes will be generated and will begin appearing in the **Discounts** section of your Shopify admin, where you can manage them.

***

## Deduplication and delivery

To avoid sending duplicate emails, Loyalty Loop deduplicates by sign-up: each sign-up sends at most one follow-up email carrying one discount code, no matter how many times it is processed.

Deduplication happens on the coupon record rather than on the mint, so if a sign-up is reprocessed an extra unused code can appear in your Shopify **Discounts** list. It is never sent to the customer and expires on its own at the end of the normal validity window.

***

## FAQ

**Are the codes discount codes or gift cards?**

Codes generated by Loyalty Loop are one-time use discount codes - not gift cards.

**What does the discount code apply to?**

The code applies to a customer's entire order, not specific items. Once used, it cannot be used again. Codes cannot be combined with other discount codes. Codes cannot be applied to subscriptions.

**Can another customer use my code?**

Each code is unique, but may be used by any customer email upon redemption.

**Will Loyalty Loop be presented on all offers?**

No, it will be presented on a select subsection of eligible offers, when most relevant to customers.

***

## Example Terms & Conditions

The following is a sample snippet you can add to your existing Terms & Conditions page to cover Loyalty Loop discount codes. Adjust the details (discount amount, expiry period, store name) to match your configuration.

***

**Loyalty Reward Discount Codes**

From time to time, customers may receive a unique discount code via email following a purchase on our store. These codes are issued as part of a loyalty reward program and are subject to the following conditions:

* Codes are single-use and expire after \[X] days from the date of issue.
* Codes apply to the total order value.
* Discount codes cannot be applied to subscriptions.
* Codes cannot be combined with other offers or discounts unless otherwise stated.
* We reserve the right to cancel or void codes in cases of suspected misuse or fraud.


# Rokt Thanks payouts
Source: https://docs.aftersell.com/aftersell/rokt_thanks_payouts

This article outlines how earnings from Rokt Thanks are paid out.

Every time a customer opts in to an offer by clicking "Yes", you generate revenue. The amount you generate depends on the number of orders placed by your customers and the number of offers they opt in to. To get started, navigate to the Rokt Thanks tab in Aftersell.

<Note>
  All Rokt Thanks payout amounts are settled in USD, regardless of your store's currency. The amounts shown on the payouts page reflect your actual USD settlement amount. This may differ from the revenue figures shown on the Rokt Thanks analytics tab, which displays estimates in your store's currency.
</Note>

***

## How Do I Get Paid?

Rokt Thanks partner payments are handled through RCIs. You can choose between two payout methods depending on your preference.

<AccordionGroup>
  <Accordion title="PayPal">
    The default payout method for Rokt Thanks is via PayPal. Open the **Rokt Thanks** tab, click **Settings**, and enter your PayPal email address under **Payment method**.

    If you don't have a PayPal account, you can still enter the email address you wish to receive payments through and PayPal will help you create an account once your first payment is processed.

    <Warning>
      Review this email carefully before saving. Once added, you can't edit it yourself in Aftersell - to change it, contact the Rokt Finance team at [ap@rokt.com](mailto:ap@rokt.com). While a requested change is being processed, the field is temporarily locked.
    </Warning>

    <img alt="Rokt Thanks Payment method settings with the PayPal email input field" />
  </Accordion>

  <Accordion title="Direct Deposit (Wire/ACH)">
    If you'd like to receive payouts via Direct Deposit, please contact our Support team, who will submit a Finance request on your behalf. To complete setup, our Finance team will need the following information:

    * Account number
    * Account name
    * Bank name
    * Direct deposit type (checking or savings)

    Please also provide the **best phone number** to reach you, as Finance will call to verify these details before activation.
  </Accordion>
</AccordionGroup>

***

## When Do I Get Paid?

Revenue is paid out approximately 45 days after the end of the month it was generated in. The payment system works in three steps:

* **Month 1:** Revenue generation. Offers are shown to customers on your site and revenue is accrued every time they opt in.
* **Month 2:** Revenue collection. We analyze the offers that customers opted in during Month 1 and charge advertisers for these referrals.
* **Month 3:** Invoice creation and payment. You will be sent an invoice detailing the exact amount of revenue to be paid out during the following month.

The example below outlines how revenue generated in July will be paid out in early October:

| July (Month 1)                                        | August (Month 2)                                             | September (Month 3)                                                                              |
| :---------------------------------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| Offers are shown on your site and revenue is accrued. | Advertisers are charged for the referrals generated in July. | An invoice is sent out detailing the amount you'll be paid during the following month (October). |

***

## Is There a Minimum Payment Threshold?

Yes. Minimum thresholds vary by payment method:

* **PayPal:** \$100.00 minimum (default for most partners)
* **Wire/ACH:** \$300.00 minimum

<Note>
  Your revenue will accrue until the end of a month when it meets the minimum threshold required for payment. If your earnings in one month do not meet the threshold, they will carry over and be combined with the following month's earnings until the threshold is reached.
</Note>

Your first payout will be made once your accrued revenue hits the applicable threshold, provided you have a PayPal email address saved in your Rokt Thanks settings.

***

**Want to go further?**

* [Activating and Configuring Rokt Thanks](/aftersell/activating_and_configuring_rokt_thanks) - get Rokt Thanks set up on your store
* [Rokt Thanks Settings](/aftersell/rokt_thanks_settings) - manage your Rokt Thanks configuration including your payout email


# Rokt Thanks settings
Source: https://docs.aftersell.com/aftersell/rokt_thanks_settings

How to modify Rokt Thanks settings

To configure Rokt Thanks settings, click the *Settings* button while in the *Rokt Thanks* tab.

### Payment method

The default payment method for **Rokt Thanks** payouts is **PayPal**. Simply enter your PayPal email, and you’ll receive payments once your generated revenue reaches the **\$100 payment threshold** for each payout period.

Please note that **PayPal applies a 4% processing fee**, which is deducted from your payout amount.

For more information on payments, see our [documentation](/aftersell/rokt_thanks_payouts).

* If you have previously added a PayPal account email for payouts and would like to change it, please email the Rokt Finance team at [ap@rokt.com](mailto:ap@rokt.com).

***

## Traffic allocation

Use the slider to configure the allocation of traffic that will see Rokt Thanks on your confirmation page.

<img alt="Traffic allocation slider set to 100 percent controlling how many customers see the placement" />

When the traffic allocation is set to 100%, Rokt Thanks will appear for every customer provided there is a relevant offer available. Reasons the placement may not appear include:

* The customer is from an unsupported geography.
* The customer’s browser settings are using an unsupported language.
* There are no relevant offers to be displayed based on the available advertisers and the allowed vertical/sub-vertical categories. To ensure the maximum number of advertisers are available, it is recommended that only the necessary verticals or sub-verticals are blocked.

***

### **Aftersell settings**

Skip storewide popup timer widget if Rokt content is available to be shown.

If Rokt Thanks has content to show and a funnel with a storewide popup has also been triggered, this setting ensures that the Rokt content will be shown instead of the storewide popup. If this is unchecked, then the storewide popup will be favoured instead.

* This is currently available only on the [Thank you page scripts](/aftersell/thank_you_page_scripts_overview) approach.

#### Order tagging

On the [Thank you page scripts](/aftersell/thank_you_page_scripts_overview) integration, Aftersell applies the Shopify order tag **`AfterSell Network Offer`** to any order where the customer **accepted** a Rokt Thanks offer. This lets you segment and filter those orders in Shopify.

* There is no setting for this — tagging is always on for that integration.
* Only accepted offers are tagged. An order where the placement was shown but not engaged with is not tagged.
* Only orders going forward are tagged — existing orders are not backfilled.

***

### Offer control

Our machine learning algorithms ensure that you show the most relevant and engaging offers to each individual. In addition, you have full control over which offer categories to show to your customers.

<img alt="Offer control panel listing industry verticals with checkboxes to allow or block offers" />

By default, all industry verticals and sub-verticals are allowed except for **every sub-vertical inside your store's own vertical**, plus Retail Insurance. This is so that competitors in your vertical are blocked from displaying on your site. Your store's vertical and sub-vertical are shown read-only under **Company information** further down this page — to change them, raise a request with our support team.

#### Managing verticals

The offer control section includes two tabs:

* **Verticals** - Standard industry categories that are available by default
* **Growth verticals** - Categories that may be legally or culturally sensitive (e.g., cryptocurrency, dating, fantasy sports, sports betting, paid cashbacks and rewards programs, charities)

By default, growth verticals are blocked. You can selectively allow specific growth verticals by switching to the **Growth verticals** tab and checking the categories you want to permit. Only the growth verticals that comply with Shopify's Terms of Service are available for selection.

***

## Block advertisers

To block offers from particular advertisers:

1. Enter their domain name(s) in the **Block competitors** field.
2. Select **Block**.

A list of all blocked advertisers will appear underneath the field once you’ve saved your changes.

***

### Offers with confirmation emails

If you allow Rokt to send offer confirmation emails from your brand, customers who opt into an offer may receive a confirmation email from your brand containing a coupon code or a link to claim the advertiser’s offer. Enabling this feature helps **maximize your revenue potential** by improving offer engagement and redemption. [Learn more](https://docs.rokt.com/user-guides/rokt-ecommerce/controls/resources/customer-confirmation-emails/).


# Show checkout widgets in Shop Pay
Source: https://docs.aftersell.com/aftersell/show_checkout_widgets_in_shop_pay

How to display checkout widgets in Shop Pay by enabling the Include app block in Shop Pay option under the Checkout behaviour dropdown.

To have your checkout widgets display in Shop Pay, you must enable the "Include app block in Shop Pay" option under the "Checkout behaviour" dropdown.

If you have not set up checkout widgets yet, you can [follow this guide to learn how to add checkout widgets to your checkout](/aftersell/adding_a_checkout_widget_to_your_shopify_checkout).

<img alt="Shopify checkout editor with the Include block in Shop Pay toggle highlighted" />


# Spend threshold upsells
Source: https://docs.aftersell.com/aftersell/spend_threshold_upsells

Intelligently recommend products to help customers reach reward thresholds like free shipping or discounts

Spend threshold upsells work with your rewards bar to automatically recommend products that help customers reach goals like free shipping, discounts, or other rewards. The system intelligently selects the most relevant product based on how close the customer is to the threshold.

***

## How it works

When you add a spend threshold upsell to your checkout, the system:

1. **Calculates the gap** - Determines how much more the customer needs to spend (or how many more items they need) to reach the reward threshold
2. **Selects the best product** - Chooses from your configured product pool based on the gap:
   * If the customer is **already qualified** for the reward, shows the **most expensive product** to maximize revenue
   * If the reward is based on **item count**, shows the **cheapest product** to reduce friction (any product adds 1 item)
   * If the reward is based on **cart total**, shows the **cheapest product that closes the gap**, or the **most expensive product** if no single product can close the gap
3. **Applies discounts** - If you've configured a discount for the upsell, the system factors that into the product selection

***

## Requirements

To use spend threshold upsells, you need:

* **Rewards bar enabled** - The spend threshold feature requires an active rewards bar in your checkout
* **Reward threshold configured** - Set up your reward goal (cart total or item count) in the rewards bar settings
* **Product pool configured** - Choose which products the system can recommend (all products, specific collection, or specific products)

***

## Setting up spend threshold upsells

### Step 1: Enable the rewards bar

1. Open your **Checkout** editor in Aftersell
2. Open the **Upsell** widget you want to use and turn on **Show rewards bar**. The spend threshold product type is greyed out until you do — it reads "Enable "Show rewards bar" to use this option"
3. Configure your reward threshold in the same widget:
   * Choose **Cart total** or **Item count** as the reward basis
   * Set the minimum amount or item count
   * Customize the reward bar text and appearance

### Step 2: Add a spend threshold upsell

1. In your **Upsell** widget, click **Add product**
2. Select **Spend threshold** from the product type options
3. Configure your product pool:
   * **All products** - System chooses from the first 15 active products in your store
   * **Specific collection** - System chooses from the first 15 products in the selected collection
   * **Specific products** - System chooses from the list of products you select

<Note>
  The **All products** and **Specific collection** pools are capped at 15 candidate products. Out-of-stock products and items already in the cart are excluded. If you need control over exactly which products can be offered, use **Specific products**.
</Note>

### Step 3: Configure discounts (optional)

You can add a discount to your spend threshold upsell just like any other upsell product:

1. Click **Add discount** on the upsell offer
2. Choose to **Pick existing** or **Create new** discount
3. The system will factor the discount into product selection, showing products at their discounted price when calculating which product best closes the gap

***

## Best practices

* **Match your product pool to your reward** - If offering free shipping, consider featuring products that complement common purchases
* **Use collections strategically** - Create a hidden collection of products that work well as threshold-closing items
* **Test different configurations** - Try different product pools to see what drives the best conversion rates
* **Combine with other upsells** - Use spend threshold upsells alongside specific product upsells for a comprehensive strategy
* **Monitor performance** - Check your analytics to see which products are most frequently added through spend threshold upsells

***

## Troubleshooting

### Spend threshold upsells not showing

If your spend threshold upsells aren't appearing:

* **Check rewards bar status** - Ensure the rewards bar is enabled in your checkout
* **Verify product availability** - Make sure products in your pool are in stock and available
* **Review triggers** - Confirm your upsell widget triggers are configured correctly
* **Check product pool** - Ensure your selected collection or products aren't empty

### Wrong products being recommended

If the system is recommending unexpected products:

* **Review your product pool** - Check which products are included in your collection or product list
* **Verify pricing** - Ensure product prices are correct in Shopify
* **Check discount configuration** - If using discounts, verify they're applying correctly
* **Consider cart contents** - The system excludes products already in the cart

***

## Need help?

If you have questions about spend threshold upsells, contact our support team through **live chat** or email at **[support@aftersell.app](mailto:support@aftersell.app)**.


# Evaluate strategy
Source: https://docs.aftersell.com/aftersell/strategies_api_reference_evaluate_strategy

api/strategies.json POST /api/public/strategy/evaluate
Evaluate a strategy against provided context to return the desired experience.



# Building strategies
Source: https://docs.aftersell.com/aftersell/strategies_building_in_app

Create, configure, and manage Strategies from the Aftersell dashboard — no code required.

## Overview

The Aftersell dashboard provides a visual interface for building and managing Strategies. You can create strategies, define targeting rules with triggers, assign products to recommend, and configure catch all behavior - all without writing any code.

This guide walks through the end-to-end process of creating a Strategy in the UI.

***

## Navigating to Strategies

1. Log in to Aftersell.
2. Click **Strategies** in the left sidebar navigation.
3. You'll see a list of your existing Strategies, or an empty state prompting you to create your first one.

***

## Creating a New Strategy

1. Click **Add Strategy**.
2. You'll be taken to the Strategy editor where you can add rules.

<Tip>
  Click the **pencil icon** in the top left of the Strategy editor to give your Strategy a descriptive name. A clear name makes it easier to identify strategies in the dashboard later.
</Tip>

***

## Adding Rules

Each Strategy contains one or more **rules**. A rule consists of:

* **Triggers** - the "when" - criteria that must be met for the rule to match.
* **Actions** - the "then" - the experience returned when the rule matches.

### Defining triggers

Triggers determine when a rule fires. You may combine up to five triggers in a single rule. One **AND** / **OR** toggle applies to the whole condition set: with **AND**, every trigger must match; with **OR**, any one trigger matching is enough. Available trigger types include:

#### Product triggers

Target based on the products in context (the shopper's cart, the just-completed order, or the product being viewed):

* **Specific product(s)** - matches specific Shopify products by ID
* **Collection** - matches products belonging to specific collections
* **Tag(s)** - matches products with specific tags (e.g., "sale", "summer")
* **Title** - matches the product title
* **Vendor** - matches the vendor/brand name
* **Type** - matches the product type field (e.g., "Apparel", "Electronics")
* **Handle** - matches the product URL slug
* **Metafield** - matches on custom metafield namespace/key/value pairs
* **Selling plan** - matches "subscription" or "one-time" products. Only evaluates when the request context supplies a selling plan for the product - Aftersell's checkout and post-purchase upsell surfaces don't send this, so the trigger won't match there unless a custom integration supplies it explicitly

#### Customer triggers

Target based on who the shopper is:

* **Customer tag** - e.g., "VIP", "loyalty-gold"
* **Country code** - billing country
* **Province code** - billing province/state
* **Locale** - customer locale (e.g., "en-US")
* **Accepts marketing** - marketing opt-in status
* **Order count** - number of previous orders
* **Total spent** - lifetime spend

#### Cart triggers

Target based on the overall cart state:

* **Cart subtotal** - e.g., subtotal greater than \$50
* **Item count** - total quantity of items in the cart
* **Line count** - number of distinct line items
* **Cart attribute** - custom cart attributes set via Shopify's cart API
* **Cart note** - the cart note field

#### Location triggers

Target based on where the shopper is shipping, and the store's currency:

* **Shipping country** - shipping destination country
* **Shipping province** - shipping destination province/state
* **Shipping method** - selected shipping method
* **Store currency** - the active store currency code

#### Marketing triggers

Target based on the page URL the shopper arrived on:

* **URL** - matches a substring of the landing URL, so you can target a specific campaign or channel by matching a parameter embedded in the URL (e.g. `utm_source=newsletter`)

#### Time triggers

Target based on when the request is evaluated, in store time:

* **Day of week** - the current day
* **Hour of day** - the current hour

#### Dynamic triggers

* **Always match** - a trigger with no condition that always fires. Use it to make a rule run on every request (this is distinct from the strategy-level [Catch all](#configuring-a-catch-all), which only fires when no other rule matches).

<Note>
  Not every trigger is populated on every surface. Checkout, for example, only sends product and cart context - customer, location, and marketing triggers won't match there. See the [Implementing Strategies](/aftersell/implementing_strategies_post_purchase_upsells) guides for what each surface sends.
</Note>

#### Operators

Each trigger uses an **operator** to define how the value is matched. The operators available depend on the trigger type.

| Operator                     | Description                                                                                                                                  |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Equals**                   | Matches when the field is exactly the value you specify - e.g., vendor equals "Nike".                                                        |
| **Does not equal**           | Matches when the field is anything other than the value you specify - useful for excluding a specific product type or vendor.                |
| **Contains any**             | Matches when a multi-value field includes at least one value from your list - e.g., a product has any one of several collection memberships. |
| **Does not contain any**     | Matches when a multi-value field includes none of the values in your list - e.g., exclude products tagged "final-sale".                      |
| **Contains all**             | Matches when a multi-value field includes every value in your list - e.g., a product must have both the "sale" and "summer" tags.            |
| **Does not contain all**     | Matches when a multi-value field is missing at least one of the values in your list.                                                         |
| **Contains**                 | Matches when a text field includes your value as a substring - e.g., title contains "Gift".                                                  |
| **Does not contain**         | Matches when a text field does not include your value.                                                                                       |
| **Greater than**             | Matches when a numeric field exceeds your value - e.g., cart subtotal is greater than \$75.                                                  |
| **Less than**                | Matches when a numeric field is below your value - e.g., order count is less than 2 (first-time buyers).                                     |
| **Greater than or equal to** | Matches when a numeric field meets or exceeds your value - e.g., total spent is at least \$500.                                              |
| **Less than or equal to**    | Matches when a numeric field is at or below your value - e.g., cart item count is no more than 3.                                            |

Not every operator is available for every trigger:

* **List operators** (**Contains any / all** and their negations) apply to multi-value fields like tags, collections, customer tags, and specific products.
* **Text operators** (**Equals**, **Contains**, and their negations) apply to single-value text fields like title, vendor, handle, locale, country, and URL.
* **Numeric operators** apply to fields like cart subtotal, item count, line count, order count, total spent, and hour of day. Numeric operators have no "does not" variants.
* A few fields support only **Equals** and **Does not equal** - selling plan, day of week, and accepts marketing.

### Defining Actions

Actions create the experience you want to deliver to the customer. This is where you decide what products to surface, how to surface them, and any additional data to pass alongside them. A rule can have multiple actions configured together to build out the full experience.

Per rule, all configured actions contribute to one combined pool. For example, a rule with a specific product action, a collection action, and a tag-based action will return products from all three sources together. If a product matches multiple sources, it is deduplicated.

#### Product actions

The same product attributes available on the trigger side are also available when defining actions. You can return products based on:

* **Specific products** - hand-pick individual products from your Shopify catalog.
* **Collection** - return all products belonging to a specific collection.
* **Product attributes** - return products matching criteria like tags, vendor, product type, or metafields - the same attribute types used in triggers.

#### Dynamic actions

Dynamic actions change what is returned based on real-time signals rather than a fixed product list. Available dynamic action types include:

* **Most popular** - your store's best-performing products by sales volume, either store-wide or scoped to a collection.
* **Recently purchased** - products recently purchased across the store.
* **Inherit from when** - reuse the rule's own triggers (the "when") as the product selector, so the products returned match the same criteria the rule fired on.
* **AI Recommendations** - personalized suggestions generated by Aftersell's recommendation model.

#### Filtering actions

Once the product pool is assembled, you can configure how many products are returned and in what order:

* **Sort** - control which products are selected:
  * **Random** - a random selection.
  * **Price: high → low** - most expensive products are returned first.
  * **Price: low → high** - least expensive products are returned first.
* **Amount/Limit** - set the maximum number of products to return.
* **Type** - narrow the assembled product pool to a single Shopify product type. Choose **Equals** for an exact match or **Contains** for a substring match (both are case-insensitive). Only products whose product type matches the value you enter are kept; the rest are removed before the Amount/Limit is applied.

<Info>
  The **Type** filter trims the product pool assembled by your product actions — it is different from the **Product type** product action, which *returns* products of a given type. Use the filter when you want to restrict what a broader action (such as a collection or dynamic action) can return.
</Info>

<Info>
  Sort is applied first, then Amount/Limit. For example, if your sort is set to **Random**, the full product pool is randomized before the limit is applied - so you always get a random slice, not the same products in a random order.
</Info>

#### Key-value actions

Optionally, attach key-value pairs to a rule. When the rule matches, these are returned in `meta.data` in the API response alongside the product results. Common uses include:

* Promotional banner text
* Campaign labels for analytics

<Note>
  If multiple rules match and emit the same key, the value from the first matching rule wins - later rules cannot override it.
</Note>

***

## Rule Priority and Evaluation Order

Rules within a Strategy are evaluated in hierarchical, sequential steps. Step 1 is evaluated first, and so on. You can reorder rules by dragging and dropping them in the Strategy editor. The evaluation engine:

1. Evaluates each rule's triggers against the provided context.
2. Collects products from all matching rules.
3. Deduplicates and limits the result to the configured maximum (default: 20 products).

***

## Configuring a Catch all

Catch all is a special rule that acts as the final step in every Strategy evaluation. It has no trigger, it fires automatically if no other rule in the Strategy matches the current request.

When enabled, the Catch all ensures your recommendation slot is never empty. Its action can be configured using any of the same action types available to regular rules - specific products, collections, dynamic actions, etc.

* **Enable/disable** - toggle the Catch all rule on or off for the Strategy. When disabled, requests that match no rules will return empty.
* **Configure actions** - define what to return using any combination of available action types, the same as any other rule.

When the Catch all fires, the API response will indicate `resolution.fallbackUsed: true`.

***

## Global Filters

Global filters remove products from selection eligibility across every rule in a Strategy. You can access them via the **filter icon** next to the strategy name at the top left of the Strategy editor.

Available global filters:

* **Exclude out of stock** - automatically exclude any product that is currently unavailable for purchase.
* **Exclude input products** - exclude the product(s) that triggered the rule (e.g., the product a shopper is currently viewing on a PDP), so you never recommend the same product the shopper is already looking at.
* **Exclude by product tag** - exclude products carrying specific tags.
* **Exclude by metafield** - exclude products matching a specific metafield namespace/key/value.
* **Exclude by product ID** - exclude specific products by ID.
* **Require stock at location** - keep only products that have available inventory at a chosen location (requires inventory and location read permissions).

***

## Validation and Error States

A Strategy cannot be saved if any rule is incomplete. Each rule needs at least one condition (or the **Always match** trigger) and at least one action; if either is missing, errors will appear directly on the rule in question highlighting what needs to be resolved.

To clear the error and save the Strategy, either:

* **Complete the rule** - add the missing trigger and/or action.
* **Delete the rule** - remove it entirely if it is no longer needed.

The Strategy editor will not allow saving until all rules are valid.


# Strategies overview
Source: https://docs.aftersell.com/aftersell/strategies_overview

Learn what Strategies are, how they work, and how to get started with intelligent experience creation.

## What are Strategies?

Strategies are Aftersell's rules-based experience and product recommendation engine. An individual Strategy is a collection of targeting rules that evaluate shopper context (products in cart, customer attributes, UTM parameters, and more) and return fully enriched product recommendations in real time.

Unlike static recommendation widgets, Strategies give you full control over *which* products are shown to *which* shoppers and *when*. You can use it to power upsell carousels, cross-sell blocks, post-purchase offers, or any custom experience on a Shopify store.

### How it works

1. **You create a Strategy** - a strategy containing one or more rules, each with triggers (predicates) and a set of products to recommend when those triggers match.
2. **Your storefront sends context** - when a page loads or a cart updates, your storefront sends the current product, cart, customer, and session data to the Strategies API.
3. **The engine evaluates** - Aftersell's rules engine evaluates every rule in the strategy against the provided context and returns fully enriched products with titles, prices, images, variants, and availability.
4. **You render the results** - the API response contains everything you need to display recommendations directly. No additional Shopify API calls are required.

### Key concepts

**Strategy** - A named collection of rules that are evaluated together. Each strategy has a unique ID (a 24-character hex string) that you reference when calling the API.

**Step** - A hierarchical evaluation sequence within a Strategy. Rules are evaluated in step order, so actions in Step 1 take priority over those in Step 2.

**Rule** — A single trigger-action pair within a strategy. A rule defines *when* it should match (e.g., "cart contains a product tagged `summer`") *then* the corresponding experience to render.

**Trigger** — A predicate attached to a rule. Triggers can target product attributes, cart properties, customer data, session/UTM parameters, and product metafields.

**Action** - An outcome attached to a rule. Actions return a selection of enriched products, sorting and filtering options, and metadata.

**Catch all** - A special rule that fires automatically when no other rule in the Strategy matches. It has no triggers and is always the final step of evaluation. When enabled, it ensures the recommendation slot is never empty and can be configured with any action type available to regular rules.

***

## Getting Started

### Prerequisites

* An active Shopify store with the Aftersell app installed.
* Access to the Aftersell dashboard (you'll create your Strategies and generate API keys here).
* Strategies enabled on your store. Strategies is not switched on for every store — if you don't see **Settings → Product Strategy** in the dashboard, contact support or your account manager to have it enabled.

### Step 1: Generate your API key

API keys are scoped to a single shop and are required for all Strategy API requests. In the dashboard, the key is labeled your **Security Token** - it's the value you send in the `X-Strategy-Api-Key` header.

1. Log in to the Aftersell dashboard.
2. Navigate to **Settings** in the left sidebar.
3. Open **Product Strategy**.
4. In the **Security Token** card, click **Generate Token**.
5. Copy the key immediately - it is shown only once and cannot be retrieved later. Only a one-way hash is stored.

<Warning>
  Store your API key securely. The plaintext key is returned **once** at generation time. If you lose it, you'll need to generate a new one. Generating a new key automatically revokes the previous one — only one API key can be active per store at a time. Any integrations using the old key will stop working immediately.
</Warning>

### Step 2: Create your first Strategy

You can build Strategies entirely through the Aftersell UI - no code required. See [Building Strategies In-App](/aftersell/strategies_building_in_app) for a walkthrough.

### Step 3: Integrate with your storefront

Once you have a Strategy and an API key, you can call the Evaluate endpoint from your storefront to fetch recommendations.


# Testimonials widget 
Source: https://docs.aftersell.com/aftersell/testimonials-widget-thank-you-page

Configure the Thank You Page Testimonials widget in Aftersell to display customer reviews from your connected review app after checkout.

The Testimonials widget displays customer reviews on the Thank You page to reinforce purchase confidence and build social proof. This page covers every setting on the widget. For the full funnel setup and Shopify editor steps, see [How to configure thank-you page widgets](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell).

Add the widget from the **Thank You Page** section of your funnel by clicking **Add Widget** and selecting **Testimonials**.

## Connect a review app

Testimonials on the Thank You page use **Flex Testimonials**, which pulls reviews directly from your connected review app. To use this widget, you must first configure your review app credentials in **Settings > Product Reviews**. Supported apps include Judge.me, Klaviyo, Okendo, and Yotpo.

For full details on connecting your review app, see [Checkout widget types - Testimonials](/aftersell/checkout_widget_types#testimonials).

## Selection modes

Flex Testimonials offers two selection modes:

* **Manual selection** - Choose specific reviews to display
* **Dynamic** - Automatically fetch and display reviews based on products in the customer's order

In dynamic mode, reviews are imported from your review app and refreshed weekly. To import reviews immediately, go to **Settings > Product Reviews** and click **Sync now**.

## Display settings

You can configure:

* **Maximum reviews to show** - Control how many reviews appear
* **Display type** - Choose between horizontal carousel or vertical stack layout
* **Minimum rating** - Set the minimum star rating for reviews to display
* **Truncate review text after (optional)** - Set a maximum character length for review text


# Text widget (Thank You Page)
Source: https://docs.aftersell.com/aftersell/text-widget-thank-you-page

Configure the Thank You Page Text widget in Aftersell to share messages, discount codes, or brand stories with customers after checkout.

The Text widget displays custom messaging on the Thank You page, such as a welcome note, discount code, or brand story. This page covers every setting on the widget. For the full funnel setup and Shopify editor steps, see [How to configure thank-you page widgets](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell).

Add the widget from the **Thank You Page** section of your funnel by clicking **Add Widget** and selecting **Text**.

## Configure text content

1. Enter your **heading** (optional).
2. Add your **text content** in the editor.
3. Format text using the toolbar (bold, italic, lists, links).
4. Click **Save**.


# Overview
Source: https://docs.aftersell.com/aftersell/thank_you_page_extensions_overview

Overview of Aftersell Thank You Page and Order Status Page widgets, with links to configuration for each widget type.

Customizing your Aftersell Thank You Page and Order Status Page with widgets enhances customer interaction and engagement after checkout. Each widget type is configured on its own page, and this overview links to those pages along with the placement and testing steps that apply to all of them.

## Widget types

<CardGroup>
  <Card title="Product Recommendation" icon="cart-shopping" href="/aftersell/product-recommendation-widget-thank-you-page">
    Display upsell products on the Thank You page. Compatible with all payment gateways and multi-currency stores.
  </Card>

  <Card title="Testimonials" icon="star" href="/aftersell/testimonials-widget-thank-you-page">
    Show customer reviews from your connected review app to reinforce purchase confidence.
  </Card>

  <Card title="FAQs" icon="circle-question" href="/aftersell/faq-widget-thank-you-page">
    Answer common post-purchase questions to reduce support requests.
  </Card>

  <Card title="Text" icon="pencil" href="/aftersell/text-widget-thank-you-page">
    Share messages, discount codes, or brand stories after checkout.
  </Card>

  <Card title="Image" icon="image" href="/aftersell/image-widget-thank-you-page">
    Display a custom image or banner on the Thank You page.
  </Card>
</CardGroup>

For step-by-step setup and how to place widgets in Shopify, see [How to configure thank-you page widgets](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell).

***

## Things to know

* Branding settings automatically align with your Shopify checkout branding settings and cannot be customized within the Aftersell editor.
* Order handling (merge into the original order or create a separate order) is configured on the [Product Recommendation widget](/aftersell/product-recommendation-widget-thank-you-page#discounts-and-order-handling).
* Shopify's checkout preview may not always display widgets. Place a test order to confirm offers appear correctly on a live order. While testing, set your trigger to show for all customers so widgets appear in the Shopify preview, then reset the trigger afterward.
* If you use **manual payment capture** in Shopify with the **Modify original order** setting enabled, Thank You page upsell revenue may not appear immediately in Aftersell analytics. Upsell visits and acceptances are recorded as usual, but revenue only appears after the order's payment status is manually changed to **Paid** in Shopify.

***

## Troubleshooting

**Widget not displaying:** Ensure the widget is active in Aftersell and that the corresponding app block is placed in the Shopify editor on the Thank You page, Order Status page, or both. See [Thank you page troubleshooting](/aftersell/widget_not_displaying_on_the_thank_you_page) for more.


# Tracking Rokt Thanks performance
Source: https://docs.aftersell.com/aftersell/tracking_rokt_thanks_performance

This article explains how to use Rokt Thanks analytics to track performance.

## Overview

You can monitor your **Rokt Thanks** performance directly from your **Aftersell by Rokt** dashboard by clicking on **Analytics**  in the **Rokt Thanks** tab.

<img alt="Rokt Thanks dashboard section with the Analytics button highlighted" />

Use the **date picker** to view performance metrics for a specific time period.

Each card shows the total for the period you select. Unlike other Aftersell analytics tabs, the Rokt Thanks cards do **not** show a period-over-period comparison or a change indicator — to compare two periods, run the report again with the earlier range.

***

## Performance

The **Rokt Thanks Analytics** dashboard includes several key metrics to help you understand performance trends and overall campaign effectiveness.

Below is a breakdown of what each metric represents:

## **Rokt Transactions**

A Rokt Transaction is a Transaction where we select at least one offer from the Rokt Network (i.e. third-party ad or upsell) for rendering to the customer throughout the Transaction Moment. Like Transactions, Rokt Transactions are unique and de-duplicated on the customer order confirmation reference (e.g. revisited confirmation pages or repeated confirmation numbers).

***

## **Number of Transactions**

A transaction will be recorded for each unique confirmation reference observed on a partner page configured as a confirmation page (Page Type). Where there is no confirmation reference, a transaction will be recorded per unique sessionID.

***

## **Revenue per Transaction (RPT)**

Measures the Revenue generated by Rokt per Transaction completed by a customer. RPT = Revenue / Transactions.

***

## Revenue per Rokt transaction (RPRT)

Client Revenue generated by Rokt per Rokt Transaction

***

## Rokt Thanks Revenue

An estimate of the revenue that has been generated for the specified account(s) through customer engagement with Rokt offers. Excludes any commissions that may accrue.

***

## Vertical Analytics

A new table has been added to the bottom of all Rokt Network analytics pages, showing all verticals that received impressions during the selected period.

The table currently includes **impressions, referrals,** and **referral rate**, with more metrics planned for future updates. This gives you greater visibility into vertical performance and helps you identify and block underperforming verticals if needed.

***

## Impressions

The total number of impressions across all offers displayed. An impression is measured for each offer viewed.

***

## Referrals

The positive outcome of a customer's interaction with an offer — for example, clicking a placement and being directed to a partner site.

***

Need Help?

If your analytics data isn’t updating or you have questions about interpreting metrics, contact the **Aftersell Support Team** through your dashboard.


# What is Rokt Thanks?
Source: https://docs.aftersell.com/aftersell/what_is_rokt_thanks

An overview of Rokt Thanks and how it can help generate additional profit

Rokt Thanks allows you to create a new source of income on your Shopify store at no cost by showing premium offers from brands like Disney+, HelloFresh, and Venmo to your customers on the order confirmation page, order status page, and customer account pages.

You earn revenue each time your customers click “Yes, please!” on these offers.

Our machine learning uses real-time first party data (e.g. name, gender, age, email, address, city, country, language, etc.) to ensure each offer you show is targeted to each individual customer. This data stays private to your business.

<img alt="Rokt Thanks popup offering a free Hulu trial on a Jones Road order confirmation page" />

On average, merchants using Rokt Thanks on their site generate an additional \$0.20 to \$0.30 USD in pure profit per transaction. The amount generated per transaction will vary based on a multitude of factors such as geography, opt-in rate, etc.

<img alt="Order confirmation page showing a Rokt Thanks Hulu offer with Yes please and No thanks buttons" />

***

## What is Rokt?

Rokt is the parent company of Aftersell. As a global leader in eCommerce technology and software solutions, Rokt enhances revenue through personalized experiences. Industry leaders such as Wayfair, Uber, and Ticketmaster rely on Rokt's cutting-edge technology to optimize their customer interactions.

***

## What types of offers are shown?

With Rokt Thanks, you have access to an exclusive, closed marketplace of 100s of reputable and recognized advertisers. You have complete control over what categories are shown.

Each experience is tailored to the individual shopper, with intelligence powered by billions of transactions across hundreds of leading Ecommerce businesses. This ensures that you will delight your customers with offers they’re sure to love.

<img alt="Grid of Rokt Thanks advertiser logos including Verizon, Disney+, Hulu, ESPN+, and Marriott" />

***

## Looking to set up Rokt Thanks?

Here is a step by step guide on how to get set up:

[Learn More](/aftersell/activating_and_configuring_rokt_thanks)


# Why can't I see the checkout tab?
Source: https://docs.aftersell.com/aftersell/why_cant_i_see_the_checkout_tab

This article outlines why you may not have access to the Checkout plan.

The Aftersell checkout tab is made possible by the Checkout Extensibility update by Shopify. This update allows merchants to insert app blocks into their Checkout rather than needing to write custom scripts.

## **Which plans get the Aftersell Checkout tab?**

Checkout Extensibility is a Shopify Plus capability, so the Aftersell Checkout tab appears on stores that have it. Aftersell shows the tab for:

* **Shopify Plus** stores
* Stores on a **Plus Trial**
* **Shopify Partner development** stores

Merchants on other plans, such as Basic or Advanced, do not have access to the Aftersell Checkout tab. This is a limitation put in place by Shopify, and Aftersell does not have a say in it.

If you are interested in upgrading to the Shopify Plus plan to access the Aftersell checkout tab and other exclusive features, please reach out to Shopify's support team for more information and they'd be more than happy to help with that!


# Why is Rokt Thanks not showing on my confirmation page?
Source: https://docs.aftersell.com/aftersell/why_is_rokt_thanks_not_showing_on_my_confirmation_page

Troubleshoot common reasons why Rokt Thanks may not be displaying on your confirmation page, Order Status page, or customer account pages.

# Why is Rokt Thanks not showing on my confirmation page?

Rokt Thanks can fail to appear for a few different reasons. Work through the steps below in order to identify the cause.

<Note>
  If Rokt Thanks is missing from a *specific* page only (e.g., shows on Thank You but not on Order Status), the cause is almost always app block placement — skip directly to ["The app block isn't placed on every required page"](#the-app-block-isnt-placed-on-every-required-page).
</Note>

## Start here

### 1. Check your email

Before troubleshooting anything else, check the email inbox associated with your Rokt Thanks account — including your **junk** and **spam** folders — for any email from **Rokt**. In some cases, our team will reach out directly with information specific to your store. If you find an email from Rokt, reply to it and our team will assist you from there.

### 2. Confirm setup is complete

In the Aftersell admin, navigate to the **Rokt Thanks** tab and check that the setup guide at the top shows every task complete. The guide tracks:

* **Enable Rokt Thanks**
* **Place app block on Thank you page**
* **Place app block on Order status page**
* If your store is eligible for Vaulted Rewards, two further tasks for the customer account Orders page

The badge reads **Complete** only when every task is done, and shows the count as *n of N tasks complete*. There is no industry-vertical or Terms & Conditions item on this tab — your store's vertical is read-only under Settings → Rokt Thanks → Company information, and the Aftersell terms are accepted once during Aftersell onboarding.

### 3. Wait for propagation

After enabling Rokt Thanks (or saving any settings change), allow at least **10 minutes** before testing. The Rokt network needs time to register your store, sync configuration, and become eligible to deliver offers.

### 4. Test from an eligible context

A test order from your own browser may not see offers if your IP is in an unsupported region or no relevant offer is currently available for your customer profile. Test from a customer-style session: different network, fresh browser, real shipping address in a supported region.

***

## What's happening?

* [The Rokt Thanks tab doesn't appear in my Aftersell admin](#the-rokt-thanks-tab-doesnt-appear-in-my-aftersell-admin)
* [I just enabled Rokt Thanks and nothing is showing](#i-just-enabled-rokt-thanks-and-nothing-is-showing)
* [Rokt Thanks shows on Thank You but not on Order Status (or vice versa)](#rokt-thanks-shows-on-one-page-but-not-another)
* [Rokt Thanks shows for some customers but not others](#rokt-thanks-shows-for-some-customers-but-not-others)
* [Rokt Thanks used to show but recently stopped](#rokt-thanks-used-to-show-but-recently-stopped)
* [I see the Rokt Thanks block in the editor but nothing renders at checkout](#the-rokt-thanks-block-shows-in-the-editor-but-nothing-renders-live)

***

## The Rokt Thanks tab doesn't appear in my Aftersell admin

Rokt Thanks is only surfaced in the Aftersell admin for stores that are eligible at the store level. If you don't see the **Rokt Thanks** tab at all, the most common causes are:

### Rokt Thanks hasn't been switched on for your account

The **Rokt Thanks** tab appears once Rokt Thanks has been turned on for your Aftersell account — normally during Aftersell onboarding, or by activating it from the home dashboard — or automatically once your store meets the order-volume threshold for eligibility.

Tab visibility is **not** based on your store's country. Rokt Thanks merchant eligibility is country-agnostic.

If you don't see the tab, check your Aftersell **Home** page. If your store is eligible, an activation banner appears at the top of the **Grow your store** section showing an estimated monthly earnings figure based on your recent order volume. Click **Activate Rokt Thanks** to begin setup. If you don't see the banner or can't find it, contact support and we can enable it for you.

### Your store sells in a sensitive vertical

Stores in certain restricted or sensitive industries are not eligible for Rokt Thanks. If you're unsure whether your vertical is affected, reach out to support and we can confirm.

### Your Aftersell account is on an older version

On rare occasions, older installs need to be upgraded before the Rokt Thanks tab appears. Reach out to support and we can refresh your account.

If you believe your store should be eligible and the tab is still missing, contact [support@aftersell.app](mailto:support@aftersell.app) with your store URL and primary shipping region.

***

## I just enabled Rokt Thanks and nothing is showing

### The app block isn't placed on every required page

Rokt Thanks renders on up to three surfaces:

* **Thank You page** — immediately after checkout completion
* **Order Status page** — the persistent post-purchase page customers can return to
* **Customer Account pages** — Profile and Orders pages, if your store has migrated to Shopify's new customer accounts and Vaulted Rewards is enabled

The **Rokt Thanks** app block must be added in the Shopify Checkout Editor on each of these pages individually. Placing it on only one page means it only renders on that page.

How to verify and fix:

1. Open the Aftersell admin → **Rokt Thanks** tab.
2. Click **Edit Thank You Page** — confirm a Rokt Thanks block is in the layout. **Save**.
3. Click **Edit Order Status Page** — confirm the same. **Save**.

The block can be placed anywhere on the page. We recommend the **Main** section (the central column where the order confirmation banner and line items appear), positioned just below the order confirmation banner so it's visible without scrolling. Avoid placing it in the Order Summary column or the Footer — those sections are smaller and tend to be missed by customers.

### Propagation hasn't completed

After enabling Rokt Thanks or saving a settings change, wait at least 10 minutes before testing.

### Traffic allocation is set to 0%

In Settings → Rokt Thanks, check the **Traffic allocation** slider. If it's at 0%, no customer will see the placement.

***

## Rokt Thanks shows on one page but not another

This is almost always an app block placement issue.

* The app block was added on Thank You page but not Order Status page (or vice versa).
* The app block was placed on a draft checkout profile but not on the published one.

How to verify: Open each page in the Shopify Checkout Editor and confirm the Rokt Thanks block is present and saved.

***

## Rokt Thanks shows for some customers but not others

This is expected behavior in many cases. Rokt Thanks uses real-time first-party data and the Rokt network to determine eligibility per customer, so it's normal for offers to display for some shoppers and not others. The most common reasons:

### No offer was available for that customer

Rokt Thanks is not limited to English-speaking markets — offers can be served in English, German, French, Dutch, Spanish, and Italian. Advertiser coverage still varies a lot by market, though, so shoppers in smaller markets are less likely to be matched with an offer at any given moment, and the placement does not render when nothing matches.

If you sell into non-English-speaking markets, open **Settings → Rokt Thanks → Languages** and enable the languages your customers shop in. English is always included and cannot be turned off.

### Traffic allocation is below 100%

If your Traffic allocation slider is below 100%, some customers will be intentionally excluded. To maximize coverage, set it to 100%.

### No relevant offer is available for this customer

Rokt's machine learning evaluates each customer against the active advertiser pool. If no advertiser has an offer that matches the customer's profile and geography at that moment, the placement will not render.

To improve match rate:

* Unblock unnecessary verticals in **Offer control → Verticals** (the more verticals allowed, the more advertisers can match).
* Consider enabling specific **Growth verticals** allowed in your store's region.
* Remove unnecessary domains from the **Block competitors** list (Settings → Rokt Thanks → Block competitors). It holds competitor domain names — there is no advertiser-level block list.

### Your store's vertical is blocking too many advertisers

By default, advertisers from **every sub-vertical inside your store's own vertical** are blocked to prevent competitor offers — not just your own sub-vertical — and Retail Insurance is blocked as well. Depending on how broad your vertical is, that can exclude a large part of the pool.

Your store's vertical and sub-vertical are shown under **Settings → Rokt Thanks → Company information**, but they are read-only — the edit button opens a note asking you to raise a support request. If you think your store is categorised wrongly, contact support and we can change it for you.

In the meantime you can widen the pool yourself by unblocking individual sub-verticals under **Offer control → Verticals**.

### Growth verticals haven't been enabled

By default, growth verticals are blocked. If your customers convert well in those categories and you're in a market where they're permitted, enabling specific growth verticals will increase fill rate.

Only growth verticals that comply with Shopify's Terms of Service are available for selection.

### Your store sells in a sensitive vertical

If your store sells products in a sensitive industry, Rokt placements may not be available for your account. If you're unsure whether your vertical is affected, reach out to our support team and we'll be able to advise.

***

## Rokt Thanks used to show but recently stopped

### Check your email

This is the most important first step. If Rokt Thanks was working and recently stopped, check the email inbox associated with your Rokt account — including your **junk** and **spam** folders — for any email from **Rokt**. In some cases, our team will reach out about changes that affect your placement. If you find an email, reply to it and our team will assist.

### A new checkout profile was published

If a new Shopify checkout profile was published without the Rokt Thanks block, Rokt Thanks will stop showing. Re-add the app block to the live profile.

### Rokt Thanks was disabled

Confirm the Rokt Thanks tab still shows status **Enabled** — the toggle may have been turned off.

### Traffic allocation was changed

Check whether the Traffic allocation slider was recently lowered.

### Verticals or advertisers were newly blocked

A recent change to Offer control settings can reduce or eliminate fill rate. Review your blocked verticals and advertisers.

### Migrated from Scripts to Extensions

If your store recently migrated from Scripts-based Thank You pages to Checkout Extensibility, the Rokt Thanks block must be added in the new editor. Old Scripts placements do not carry over.

***

## The Rokt Thanks block shows in the editor but nothing renders live

### The block is on a draft profile, not the published one

Shopify Admin → Settings → Checkout → confirm which profile is **Published**. Make sure the block is on that profile.

### The Save step was missed

Adding the block isn't enough — you must click **Save** in the top right of the Shopify Checkout Editor.

### The block is in a section that's hidden by theme

Some Shopify checkout layouts hide sections by default. Confirm the section where you placed the Rokt Thanks block (typically **Main**) is visible.

***

## Still not resolved?

Reach out via chat in the Aftersell admin or email [support@aftersell.app](mailto:support@aftersell.app). Include:

* A specific order number where Rokt Thanks did not appear
* The customer's shipping country (if known)
* A screenshot of the Shopify Checkout Editor showing the Rokt Thanks block on the affected page
* A screenshot of your Aftersell Rokt Thanks tab showing the setup checklist status
* Whether you've received any recent email from Rokt about your account

***

## Related guides

* [What is Rokt Thanks?](/aftersell/what_is_rokt_thanks)
* [Activating and Configuring Rokt Thanks](/aftersell/activating_and_configuring_rokt_thanks)
* [Rokt Thanks Settings](/aftersell/rokt_thanks_settings)
* [Rokt Thanks Payouts](/aftersell/rokt_thanks_payouts)


# Why isn't my post-purchase offer displaying?
Source: https://docs.aftersell.com/aftersell/why_isnt_my_1_click_offer_displaying

A complete breakdown of every reason your post-purchase offer may not be showing.

Post-purchase upsells can fail to display for several different reasons. Work through the steps below in order to identify the cause.

<Tip>
  If an offer doesn't display, the original order is always processed as normal. Nothing is lost on the customer's side.
</Tip>

<Info>
  **Thank You Page upsells are a great workaround, and currently the only workaround, for orders that do not meet Shopify's Post-purchase eligibility requirements.**

  If orders are regularly ineligible due to payment method, currency, sales channel, order value, local delivery, duties, etc., [setting up Thank You Page upsells](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell) ensures those customers still see an offer.

  Note that product-level limitations (such as bundle products as upsell items and subscription-on-subscription conflicts) apply to Thank You Page upsells as well.
</Info>

***

## Where to start

**1. Open the Order Browser and find the order**

Go to **Apps → Aftersell → Order Browser** and locate the specific order. Click the order number to review the Post-purchase section. The ineligibility reason shown there identifies which section below applies. Use that as the starting point rather than reading through everything. [Learn how to use the Order Browser →](/aftersell/order_browser_overview)

**2. Confirm the setup**

* Aftersell is selected as the post-purchase app in Shopify **Settings → Checkout → Post-purchase page**
* The funnel is published and active in the Aftersell admin

**3. Confirm the order meets Shopify's Post-purchase requirements**

Shopify's post-purchase page has specific requirements. If any one of them isn't met, the offer will not display. For the full list, [see the requirements below](#the-payment-method-is-not-supported).

One requirement worth checking specifically: if Shopify Markets is enabled and a customer browsed in a non-default market or currency, the offer will not show even if the underlying payment was processed correctly. See [Does Multi-Currency Checkout Impact Aftersell?](/aftersell/does_multi_currency_checkout_impact_aftersell) for more detail.

**4. Review the offer**

* The upsell product is published and in stock in Shopify
* The upsell product is not a bundle (bundle products cannot be used as upsell items due to a Shopify limitation)
* If the upsell product is a subscription, confirm the original order does not already contain a subscription. Shopify only supports one subscription product per order.
* In the offer editor under the **Product Details** widget, confirm "Skip offer if product is in original order" is not enabled. If it is enabled, the offer will be skipped for any customer who already has that product in their cart
* Confirm the funnel's trigger conditions match the order. When multiple triggers are added to a funnel, ALL of them must be met (AND logic between triggers). Within a single trigger, only one of the selected options needs to match (OR logic within a trigger). The one exception is the Product Quantity trigger, which has a toggle to switch its internal logic from OR to AND. If any trigger is not matched, the funnel will not fire for that order. See [Understanding Conditional Logic for Post-Purchase Triggers](/aftersell/understanding_conditional_logic_for_post_purchase_triggers) for more detail.

***

## More detail on each cause

If the checklist above didn't resolve it, the sections below cover every possible scenario in full.

* [Aftersell is not set as the post-purchase app](#aftersell-is-not-set-as-the-post-purchase-app)
* [The payment method is not supported](#the-payment-method-is-not-supported)
* [Other Shopify order requirements](#the-order-doesnt-meet-shopifys-requirements)
* [There is a product or offer issue](#there-is-a-product-or-offer-issue)
* [Nothing above applies](#nothing-above-applies)
* [How do I resolve this for all customers?](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell)

***

## Aftersell is not set as the post-purchase app

For post-purchase offers to appear, Aftersell must be selected as the active post-purchase page app in Shopify.

To check: go to your Shopify admin, navigate to **Settings → Checkout**, and scroll to the **Post-purchase page** section. Confirm that Aftersell is selected.

<Warning>
  **Only one app can be active as the post-purchase page at a time.** Shopify only allows one app to be selected as the post-purchase extension. If you have multiple apps with post-purchase extensions installed, only the one selected in your Checkout settings will show. Other apps such as Thank You Page tools can still run alongside Aftersell since TYP operates separately from the post-purchase step and does not require this setting.
</Warning>

***

## The payment method is not supported

Shopify's post-purchase API only works with specific payment methods. If a customer pays with an unsupported method, Shopify will not display the post-purchase page. These are Shopify-imposed limitations that apply to every post-purchase app, not just Aftersell.

### Supported and unsupported methods at a glance

<AccordionGroup>
  <Accordion title="✅ Supported payment methods">
    | Payment method                                   | Notes                                                                                                                                                                                                                                                                                                 |
    | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Shopify Payments (credit card)**               | Regional sub-methods (iDEAL, Bancontact, Blik) are not supported. These appear under "Shopify Payments" in checkout but are bank transfers, not credit cards, and are not supported for post-purchase offers. In the Order Browser these orders appear as "Non-credit card" or "Unsupported gateway". |
    | **Shop Pay (saved card, standard checkout)**     | The accelerated button is not supported. Shop Pay as a saved card in standard checkout is supported, the customer goes through checkout normally. The Shop Pay accelerated button ("Buy with Shop Pay") bypasses the standard checkout flow entirely and is not supported.                            |
    | **Authorize.net**                                | Not supported for [replacement upsells](/aftersell/replacement_upsells)                                                                                                                                                                                                                               |
    | **Adyen**                                        | Includes Adyen Payments credit card processing                                                                                                                                                                                                                                                        |
    | **Pin Payments**                                 | Credit card processing                                                                                                                                                                                                                                                                                |
    | **Other embedded direct credit card processors** | Must be fully embedded inline in Shopify's checkout, not a redirect                                                                                                                                                                                                                                   |
  </Accordion>

  <Accordion title="⚠️ Conditionally supported payment methods">
    | Payment method     | Notes                                                                                                                                                                                                                                                                                                                                         |
    | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **PayPal Express** | Requires Automatic Payments (Reference Transactions) to be approved. Shopify submits an approval request automatically when you install Aftersell, but approval can take a few days. Check the status in your PayPal account. Also note: PayPal Express only supports one upsell per checkout, Only the first upsell or downsell will appear. |
    | **Braintree**      | Without CVV verification only                                                                                                                                                                                                                                                                                                                 |
    | **Stripe**         | Older versions only. Newer versions no longer supported by Shopify.                                                                                                                                                                                                                                                                           |
  </Accordion>

  <Accordion title="❌ Not supported payment methods">
    | Payment method                                                                                                | Notes                                                                                                                                                                                  |
    | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **PayPal Payments Pro / Payflow Pro / Eway**                                                                  | Providers that require the customer's CVN/CVV to be retained are not supported by Shopify's Post-Purchase Extensions API. Orders appear as "Unsupported gateway" in the Order Browser. |
    | **BNPL (Klarna, Afterpay, Affirm, Sezzle, Shop Pay Installments, Zip)**                                       | Use Thank You Page upsells instead                                                                                                                                                     |
    | **Digital wallets + accelerated buttons (Apple Pay, Google Pay, Amazon Pay, PayPal button, Shop Pay button)** | Use Thank You Page upsells instead                                                                                                                                                     |
    | **Bank transfers (iDEAL, Bancontact, Blik, Przelewy24)**                                                      | Use Thank You Page upsells instead                                                                                                                                                     |
    | **Gift card / COD / Shopify store credit**                                                                    | **Any** gift card payment on the order disqualifies it, whether the gift card covers the whole total or only part of it                                                                |
  </Accordion>
</AccordionGroup>

***

## The order doesn't meet Shopify's requirements

Beyond payment method, Shopify enforces additional conditions before the post-purchase page will load. All of these are Shopify-imposed limitations that apply to every post-purchase app.

<AccordionGroup>
  <Accordion title="Order value is under $0.50">
    Orders must be worth at least \$0.50. Fully discounted and free orders do not qualify.
  </Accordion>

  <Accordion title="Order is in a non-default currency">
    If your store has multi-currency enabled and the customer checked out in a currency other than your store's default, Shopify will not display the post-purchase page.

    If Shopify Markets is enabled, this applies at the market level too. A customer browsing in a non-default market may be routed to a different currency even if the payment itself is supported. See [Does Multi-Currency Checkout Impact Aftersell](/aftersell/does_multi_currency_checkout_impact_aftersell)? for more detail and steps to address this.
  </Accordion>

  <Accordion title="Order includes duties or landed costs">
    Orders with duties or landed costs do not qualify.
  </Accordion>

  <Accordion title="Order is for local delivery">
    Orders where the customer selected local delivery at checkout will not show the post-purchase page.
  </Accordion>

  <Accordion title="Order has no shipping address">
    If the order was completed without a shipping address (for example, a digital-only purchase or a customer who selected local pickup), post-purchase offers cannot load. Shopify requires a destination country code to be present.

    This is why orders containing only digital products never show post-purchase offers: checkout doesn't collect a shipping address for them. If the order also includes a physical product, checkout collects a shipping address and the order can still qualify. For digital-only orders, use [Thank You page offers](/aftersell/thank_you_page_extensions_overview) instead.
  </Accordion>

  <Accordion title="Order was placed through an unsupported sales channel">
    Post-purchase upsells only work for orders placed through the Online Store sales channel or an eligible headless/custom storefront channel. Orders from POS, TikTok, and subscription contract renewal orders will not show post-purchase offers. Draft orders are eligible and can show post-purchase offers.
  </Accordion>

  <Accordion title="Shopify is under extreme load">
    During flash sales or unusually high platform load, Shopify may briefly delay order creation. In these scenarios the post-purchase page may not appear even if the order meets all other requirements.
  </Accordion>
</AccordionGroup>

***

## There is a product or offer issue

Even when the order qualifies, the offer itself may be blocked from displaying.

<AccordionGroup>
  <Accordion title="The offer product is out of stock">
    If the product's inventory is tracked and the stock level is zero or below, the offer will not show. Add fallback products or ensure your offer product has available inventory.
  </Accordion>

  <Accordion title="The offer product is a bundle">
    Bundle products cannot be used as post-purchase upsell items due to a Shopify limitation.

    If a product you expect to see as an upsell simply doesn't appear (rather than loading and then disappearing), the most likely cause is a bundle product in the upsell offer. Bundle products are filtered out before the offer renders, so they never show up on the offer card in the first place. Remove any bundle products from the offer and replace them with standalone products. A customer buying a bundle in their original order can still trigger a funnel. The restriction only applies to bundle products as the upsell item itself.
  </Accordion>

  <Accordion title="Both the original order and the upsell contain subscription products">
    If the original order includes a subscription product and the upsell product is also a subscription, the offer will be skipped. Shopify only supports one subscription product per order.

    **How to detect this:** Place a test order that includes a subscription product and watch whether the upsell skips immediately to the downsell without showing. If so, there is a subscription in the original order conflicting with the subscription upsell.

    **To fix this:** Add a "Does not include subscription products" trigger to funnels that contain subscription upsells. This ensures the funnel only fires for orders without a subscription, preventing the conflict entirely and showing the offer to the right customers.
  </Accordion>

  <Accordion title="The &#x22;skip if already in order&#x22; setting is enabled">
    In the offer editor under the Product Details widget, there is a setting to skip the offer if the upsell product already exists in the original order. If this is enabled and the customer already has that product in their cart, the offer will be silently skipped. Review this setting in your offer and confirm it matches your intended behaviour.
  </Accordion>

  <Accordion title="All three post-purchase offer slots have already been accepted">
    A customer can accept a maximum of three post-purchase offers per checkout. This is a Shopify platform limit. The Thank You Page is a separate experience and allows for one additional accepted offer, so a customer who accepts all three post-purchase offers can still accept one more on the Thank You Page. See [Post-purchase upsells vs Thank You Page upsells.](/aftersell/one_click_upsells_vs_thank_you_page_upsells)
  </Accordion>
</AccordionGroup>

***

## Nothing above applies

If all of the above has been checked and the offer still isn't showing, confirm the following:

* The funnel's trigger conditions match the order. All conditions use AND logic, meaning every single condition must be met. A single unmatched condition silently blocks the funnel from firing. See [How to Configure Post-Purchase Triggers](/aftersell/how_to_configure_post_purchase_triggers) and [Understanding Conditional Logic for Post-Purchase Triggers](/aftersell/understanding_conditional_logic_for_post_purchase_triggers).
* There is at least one funnel with a **Show this funnel for all customers** catch-all trigger set to the lowest priority. Without this, some orders may not match any funnel at all.
* The funnel is published and active in the Aftersell admin.
* Aftersell is confirmed as the active post-purchase app in Shopify **Settings → Checkout → Post-purchase page**.

Still not resolved? Reach out via chat or email us at [support@aftersell.app](mailto:support@aftersell.app) and include the order number.


# Why isn't my checkout upsell displaying?
Source: https://docs.aftersell.com/aftersell/why_isnt_my_checkout_upsell_displaying

A complete breakdown of every reason your checkout upsell may not be showing, including setup, placement, trigger, and product/offer issues.

Checkout upsells can fail to display for several different reasons. Work through the steps below in order to identify the cause.

<Note>
  Checkout upsells are only available to Shopify Plus merchants, because Shopify's Checkout Extensibility API is Plus-only. If you are not on Shopify Plus, checkout upsells will not appear regardless of your configuration. See [Why can't I see the checkout tab?](/aftersell/why_cant_i_see_the_checkout_tab)
</Note>

<Tip>
  If an upsell doesn't display, the customer's checkout experience is unaffected — nothing breaks on the customer's side.
</Tip>

***

## Where to start

Most display problems come down to one of four things: the widget isn't enabled, the app block isn't added/saved in Shopify, the placement doesn't match, or the trigger conditions aren't met. Confirm the basics first:

* You are on a **Shopify Plus** plan
* The widget is **enabled** in the Aftersell Checkout editor (the **Enable** toggle in the top right of the widget settings is on)
* The app block has been **added and saved** in the Shopify Checkout Editor
* The placement selected in Shopify **matches** the placement set in Aftersell

If those all check out and the upsell still isn't showing, work through the detailed causes below.

* [Widget is not enabled or not added to checkout](#widget-is-not-enabled-or-not-added-to-checkout)
* [Placement mismatch between Aftersell and Shopify](#placement-mismatch-between-aftersell-and-shopify)
* [Trigger conditions are not being met](#trigger-conditions-are-not-being-met)
* [There is a product or offer issue](#there-is-a-product-or-offer-issue)
* [Shop Pay widgets not showing](#shop-pay-widgets-not-showing)
* [Testing in the Shopify preview](#testing-in-the-shopify-preview)
* [Nothing above applies](#nothing-above-applies)

***

## Widget is not enabled or not added to checkout

For a checkout upsell to display, two things must be true at the same time:

1. The widget must be **enabled** in the Aftersell Checkout editor
2. The app block must be **added and saved** in the Shopify Checkout Editor

If either is missing, the widget will not appear.

**To enable the widget in Aftersell:**

1. Go to **Apps → Aftersell → Checkout**
2. Open the upsell widget you want to display
3. Confirm the widget is switched on — the header shows a toggle beside an **Active** / **Inactive** badge. (On the earlier Checkout editor this is an **Enable** / **Disable** button pair in the widget card header.)

**To add the app block in Shopify:**

1. Go to **Settings → Checkout** in your Shopify Admin
2. Click **Customize** next to your checkout profile
3. Click **Add app block** and select the Aftersell upsell widget
4. Position it where you want it to appear
5. Click **Save** — changes are not applied until saved

***

## Placement mismatch between Aftersell and Shopify

A placement mismatch is one of the most common reasons a checkout upsell fails to display.

Aftersell supports multiple placements so you can run more than one widget of the same type on the same checkout page. Each placement corresponds to a **separate app block** in the Shopify Checkout Editor, and the placement selected in Shopify must match the one configured in Aftersell.

The Upsell Widget app block's **Placement** dropdown offers eight values: **Default placement (Upsell Widget 1)**, **Additional placement 1 (Upsell Widget 2)**, **Additional placement 2 (Upsell Widget 3)**, and five page-widget slots **page-upsell-001** through **page-upsell-005**.

If the placements do not match, the widget will not appear or may display in the wrong location.

**To fix a placement mismatch:**

1. In the Aftersell Checkout editor, open the upsell widget and note which placement is selected (for example, **Additional placement 1**)
2. In the Shopify Checkout Editor, remove the existing app block for this widget
3. Click **Add app block**, select the Aftersell upsell widget, and choose the **same placement** as configured in Aftersell
4. Save your changes

[Learn more about matching placements →](/aftersell/how_to_configure_checkout_widgets#matching-placements-in-the-shopify-checkout-editor)

***

## Trigger conditions are not being met

If your upsell widget has triggers configured, it will only display when those conditions are met by the cart. If the cart does not satisfy the trigger conditions, the widget will not appear — this is expected behavior.

Available trigger types include:

* **Specific products / collections:** a chosen product, variant, or collection is (or is not) in the cart
* **Quantity of a specific product:** e.g. 2 or more of a product
* **Product tag / product type / variant name:** any cart item matches a Shopify tag, product type, or variant title (case-insensitive)
* **Product metafield / variant metafield:** a cart product or variant has a metafield value that matches
* **Cart subtotal:** the subtotal meets a threshold (see the note below on how the subtotal is calculated)
* **Cart quantity:** total number of items in the cart
* **Subscription in cart:** whether any cart item is a subscription
* **Cart attribute:** a cart-level attribute key/value matches (useful for data set by other apps)
* **Applied discount / discount value:** a specific discount code is applied, or total discount meets a threshold
* **Shipping country:** the customer's shipping country (and optionally province) matches
* **Customer language:** the checkout's language matches (for example, show French content only to French checkouts)
* **Customer tags:** the logged-in customer has the required tags
* **Device type:** the customer is on the configured device (desktop or mobile)

<Note>
  The **cart subtotal** used for trigger evaluation excludes any line items already added by accepted upsells (those tagged with the `__as_offer_id` cart attribute). So accepting one upsell will not, by itself, push the subtotal over a threshold that gates another widget.
</Note>

**Combining conditions:** when a widget has multiple conditions, they are joined with either **AND** or **OR** (your choice), and conditions can be nested into groups for more complex logic. Under an **AND** join, every condition must be met — a single unmatched condition silently blocks the widget. Under an **OR** join, any one match is enough. Review each condition individually against your test cart.

**To troubleshoot triggers:**

1. Open the widget in the Aftersell Checkout editor and review its trigger conditions
2. Temporarily set the trigger to **Show for all customers** to confirm the widget itself is working, then re-enable your specific triggers
3. Make sure at least one widget uses a **Show for all customers** trigger at the lowest priority as a catch-all, so some offer always displays even when no targeted widget matches

[Learn more about checkout triggers →](/aftersell/checkout_triggers)

***

## There is a product or offer issue

Even when the widget is enabled, correctly placed, and its triggers match, the offer itself may be filtered out before it displays.

<AccordionGroup>
  <Accordion title="The upsell product is out of stock">
    If the product's inventory is tracked and no variant is available for sale, the offer will not display. Make sure at least one variant of the upsell product has available inventory, or use a product that doesn't track inventory.
  </Accordion>

  <Accordion title="The upsell product is in Draft or Archived status">
    The upsell product must be a live, sellable product. Products in **Draft** or **Archived** status in Shopify are filtered out and will not appear as offers. Open the product in Shopify Admin and confirm its status is **Active**.
  </Accordion>

  <Accordion title="The upsell product is already in the cart and 'hide if already in cart' is enabled">
    The **Hide offer if product already in cart** setting hides the offer when that product is already in the customer's cart. It is on by default for standard product offers. If you want the upsell to show regardless, disable this setting in the offer configuration.
  </Accordion>

  <Accordion title="The upsell product is a subscription but has no selling plans">
    If **Subscription purchase option** is set to **Subscription** but the product has no selling plans configured in Shopify, the offer is filtered out. Confirm the product has at least one active selling plan, or change **Subscription purchase option** to **One-time product** (the other choices are **Subscription** and **Subscription and a one-time product**).
  </Accordion>

  <Accordion title="The replacement upsell target product is not in the cart">
    If the offer is configured as a replacement upsell, it only displays when the product it is meant to replace is present in the cart. Confirm the correct target product is selected in the replacement upsell configuration.

    A replacement offer is also skipped when the target line **already has a discount applied** — unless you tick **Allow replacement if product has discount applied** — or when the target line's **quantity is above one**, unless you tick **Allow replacement if product quantity greater than 1**.
  </Accordion>

  <Accordion title="The maximum number of accepted offers has been reached">
    If **Max number of accepted offers** is set on the widget, the upsell stops displaying once the customer has accepted that many offers from the widget in the current checkout. This is intentional — once the limit is reached, the widget hides itself. The field applies to Single product and Multi product upsells only; Checkmark upsells have no such limit.
  </Accordion>

  <Accordion title="The offer was already added to the cart by this widget">
    For **single** and **multi-product** upsells, once the customer adds the offer product to their cart, the offer is hidden (the product is already in the cart). **Checkmark** upsells behave differently — they stay visible with the checkbox checked after being accepted.
  </Accordion>
</AccordionGroup>

***

## Shop Pay widgets not showing

Checkout widgets do not display in Shop Pay by default. To show your upsell in Shop Pay, you must explicitly enable it:

1. Open the Aftersell upsell app block in the Shopify Checkout Editor
2. In the block settings, find the **Checkout behaviour** section
3. Check the **Include app block in Shop Pay** option
4. Save your changes

[Learn more about Shop Pay widgets →](/aftersell/show_checkout_widgets_in_shop_pay)

***

## Testing in the Shopify preview

The Shopify Checkout Editor preview does not reliably render widgets. A widget can be configured correctly and still not appear in the editor preview, because the preview can't simulate page tagging and trigger conditions. Don't rely on the editor preview to confirm whether a widget is working.

**To test your upsell accurately:**

1. Temporarily set the widget trigger to **Show for all customers**
2. Place a real test order using Shopify's test payment gateway (or a discount code that makes the order free)
3. Confirm the widget appears during the actual checkout flow
4. Reset your triggers after testing

***

## Nothing above applies

If you've worked through everything above and the upsell still isn't displaying, confirm the following:

* The widget is **enabled** in Aftersell and the app block is **added and saved** in the Shopify Checkout Editor
* The **placement** in Aftersell matches the placement selected in Shopify
* The trigger conditions match your test cart — remember that under an **AND** join, every condition must be met
* There is at least one widget with a **Show for all customers** trigger at the lowest priority as a catch-all
* The upsell product is **Active**, in stock, and (for subscription offers) has active selling plans
* You are testing with a **real checkout flow**, not the Shopify editor preview
* Try clearing your browser cache or testing in an incognito window — changes can take a few minutes to propagate

Still not resolved? Reach out via chat or email us at [support@aftersell.app](mailto:support@aftersell.app) and include a description of your widget setup and the test order details.


# Thank you page troubleshooting
Source: https://docs.aftersell.com/aftersell/widget_not_displaying_on_the_thank_you_page

This article covers common reasons why a widget may not appear on the TYP and provides troubleshooting steps to help resolve the issue.

If something isn't working on your Thank You Page, start here. This guide covers the most common issues and how to fix them.

## What are you experiencing?

* [**My Thank You Page widget is not showing**](#widget-not-displaying)
* [**My Thank You Page analytics have dropped to zero**](#analytics-dropping-to-zero)
* [**My post-purchase offer is not appearing on the Thank You Page**](#post-purchase-offers-not-appearing)

***

## Widget Not Displaying

If your Thank You Page widget is not showing, work through the following checks in order.

### 1. Check the Display Sequence

Understanding the upsell display flow can help identify where issues might occur. The sequence follows this order:

Customer completes checkout → 1-Click Upsell Offers are presented (if eligible) → Customer proceeds to the Thank You Page where additional upsells and widgets may display

1-Click Upsell Offers appear in a layer between checkout and the Thank You Page. If a 1-Click offer fails to load or is misconfigured — for example, if the product is unavailable or the funnel has no active offers — the customer may be sent directly to the Thank You Page without seeing the upsell, which can make it appear as though Thank You Page widgets are also missing when they are not.

### 2. Check Funnel Priority

Another funnel might be displaying instead of the one you're trying to test due to having a higher priority.

1. View the priority of your funnel on the left side of the funnel table.
2. To adjust priority levels, use the **Manage Priority** button at the top right of the funnel table.

<img alt="Aftersell post-purchase funnels table highlighting the Priority column and Manage priority button" />

The funnel with priority level 1 is checked first, followed by priority level 2, and so on.

### 3. Check Funnel Triggers

The order you're placing may not be meeting the trigger requirements set for your funnel. Review your triggers carefully to ensure they are configured correctly.

For example, if your trigger is set to show the widget for orders less than \$50.01, an order with a \$50 item may not qualify once shipping is added, pushing the total above that threshold. Adjusting the trigger value to better reflect real order totals including shipping should resolve this.

### 4. Check Product Availability

The product you're trying to upsell may not be available for purchase. For Thank You Page offers to display correctly:

* Ensure the product is included in the **Online Store** sales channel and set to **Active** status
* Verify the product is in stock - out-of-stock items will not be shown
* Check that the product variants you want to offer are properly configured

### 5. Re-Select Upsell Products

Aftersell may lose connection to a product if significant changes are made in Shopify, such as a handle change or the removal of variants. To restore the connection, simply reselect the product in the offer settings. This prompts Aftersell to update with the new product information.

### 6. Check Thank You Page Extensibility

If you have upgraded to Shopify's Thank You Page extensibility, make sure you are using the Extensions version of the widgets, not the Scripts version.

* **Scripts widgets** only work with the Legacy version of the Thank You Page
* **Extensions widgets** are required for stores that have upgraded to Thank You Page extensibility

Once you have designed your widgets in Aftersell, you need to manually add the app block to your Thank You page in the **Shopify Checkout Editor**.

<Note>
  1-click upsell offers are automatically integrated and do not need to be manually added to the Thank You Page. Only Thank You Page widgets require manual app block setup.
</Note>

Click the button in Aftersell to open the Shopify Checkout Editor:

<img alt="Aftersell Thank You Page Editor with the Open Shopify editor button highlighted" />

Then add the corresponding app block:

<img alt="Shopify Checkout Editor Thank you page block picker listing Aftersell app blocks" />

<Tip>
  Place your widget toward the top of the Thank You page for best visibility. Widgets positioned lower on the page may not be seen on all devices, particularly on mobile where customers are less likely to scroll.
</Tip>

***

## Analytics Dropping to Zero

If your Thank You Page analytics have suddenly dropped to zero or are showing no impressions, work through the following checks.

### 1. Check the App Block is Still Active

The most common cause of analytics dropping to zero is the Thank You Page app block being removed or disabled in the Shopify Checkout Editor.

1. Go to your Shopify Admin and open the Checkout Editor
2. Navigate to the Thank You page
3. Confirm the app block for each widget you use is present and enabled — every widget type is a separate block (**TY Product Recommendation Widget**, **TY Testimonials Widget**, **TY FAQs Widget**, **TY Text Widget**, **TY Image Widget**, or **TY Gift with Purchase**)
4. If it is missing, re-add it and save

### 2. Check Funnel Status

Confirm your funnel is still set to **Active** in the Aftersell dashboard. If it was accidentally paused or disabled, no widgets will display and no impressions will be tracked.

### 3. Check Trigger Conditions

If your funnel triggers have been updated recently, they may no longer be matching orders. Review your trigger conditions and place a test order that should qualify to confirm whether the widget appears.

### 4. Check the Date Range

Make sure the date range in your analytics dashboard is set correctly. If the range was accidentally changed, it may appear as though analytics have dropped when they are actually being filtered out.

### 5. Check for Shopify Updates

If Shopify was recently updated or your checkout settings were changed, one or more app blocks may have been removed as part of the update. Each widget type is a separate block, so check every one you use (**TY Product Recommendation Widget**, **TY Testimonials Widget**, **TY FAQs Widget**, **TY Text Widget**, **TY Image Widget**, or **TY Gift with Purchase**), re-add any that are missing to the Thank You page in the Shopify Checkout Editor, and save.

***

## Post-Purchase Offers Not Appearing

A **post-purchase offer** is any upsell or cross-sell that a customer sees after they have completed payment. In Aftersell, there are two types:

* **1-Click Upsell offers** — appear between the checkout confirmation and the Thank You Page. These use Shopify's native post-purchase extensibility.
* **Thank You Page widgets** — appear on the Thank You Page itself, after the customer has already arrived there.

If your offer is not appearing, first confirm which type you have set up, then work through the relevant checks below.

### 1. Confirm the Offer Type

Make sure you have the correct offer type configured for what you're trying to achieve. If you are expecting a Thank You Page widget but have only set up a 1-Click offer, it will not appear on the Thank You Page.

### 2. Check the Smart Funnel

The Smart Funnel does not support Thank You Page upsells. If you are relying on the Smart Funnel to show Thank You Page offers, they will not appear. You need a manual funnel with Thank You Page widgets configured.

See [How to Configure Thank You Page Widgets](/aftersell/how_can_i_set_up_and_customize_thank_you_page_upsells_in_aftersell) for setup instructions.

### 3. Check Payment Method Compatibility

Unlike 1-Click offers, Thank You Page widgets are not subject to Shopify's payment method restrictions. If your offer is not appearing and you suspect a payment method issue, confirm you have set it up as a Thank You Page widget rather than a 1-Click offer.

### 4. Check Funnel Triggers and Priority

Follow the same trigger and priority checks outlined in the [Widget Not Displaying](#widget-not-displaying) section above.

***

**Need help?**

If you have worked through all the steps above and the issue persists, reach out to our support team via the live chat in the bottom right corner of the app.


# An introduction to cart drawer modules
Source: https://docs.aftersell.com/upcart/an_introduction_to_cart_drawer_modules

This article explains how to use the cart module menu in Upcart.

# Overview

You can view a list of available modules by opening the Cart Editor tab in your Upcart dashboard.

The cart drawer in Upcart is built from several modules. Each module offers unique functionality and has its own customizable settings.

If a module is disabled, a crossed-out eye icon will appear next to it.<img alt="Crossed-out eye icon indicating a disabled module" />

To access all available modules, go to the Cart Editor tab in your Upcart dashboard.

<img alt="Upcart Cart Editor module menu listing General, Body, and Footer modules" />

For a quick and easy introduction to Upcart modules, check out our **[Quickstart Guide to Upcart](/upcart/quickstart_guide_to_upcart)**

***

Need help getting started with Upcart or navigating the app? Contact our 24/7 support team anytime.


# Best practices to increase Upcart conversions
Source: https://docs.aftersell.com/upcart/best_practices_to_increase_upcart_conversions

This article outlines best practices to optimize your cart and boost your average order value (AOV).

# Overview

This guide walks you through proven ways to increase conversions and maximize AOV with **Upcart**. You'll learn how to design your cart for trust, use rewards strategically, configure upsells and add-ons, and make the most of your empty cart space.

***

## Match Your Branding for Trust and Consistency

Your customers are far more likely to complete checkout when your cart feels like a natural extension of your brand.

You can customize your cart's look and feel in the **Design Module** to match your store's identity perfectly.

Here's how to align your cart design for best results:

* **Inherit your fonts** to create a consistent shopping experience.
* **Match button, background, and text colors** with your brand palette.
* **Use contrast** on key actions like *Checkout* to draw attention.
* **Simplify your layout** by removing clutter and unnecessary elements.

## 💡 **Tip:**

If your store uses visuals like trust badges, icons, or illustrations, you can add them easily using Custom HTML or the Trust Badges Module in your Upcart editor.

***

## Use Rewards to Motivate Higher Spend

Upcart's **Rewards Bar** gives your customers a clear path to unlock perks like free shipping, discounts, or gifts and also encourages them to add more to their cart.

## Recommended Three-tier Structure

**Tier 1: Free Shipping**\
Start just above your current AOV to motivate that extra purchase.

* *Example: If your AOV is \$50, set the threshold around \$55–\$60.*

**Tier 2: Percentage Discount**

Offer a small discount at a slightly higher threshold.

* Example: *10–15% off once a customer spends above Tier 1.*

**Tier 3: Free gift**\
End with an exclusive, tangible reward such as a sample, best-seller, or branded item.

* Keep costs low but perceived value high.

### **Tips for rewards setup**

* Avoid large jumps between tiers
* Clearly highlight the reward value in the bar text
* Keep goals achievable but exciting

## ⚠️ Note:

Tiered Rewards is a visual progress bar and does not create the actual discount on its own. To activate the discount when a customer reaches a tier, create a matching rule using one of the following: the Discounts module inside Upcart (the simplest option and recommended for most merchants), a Shopify automatic discount, or a discount management app like Abra Promotions. Review [Shopify's discount stacking limitations](https://help.shopify.com/en/manual/discounts/combining-discounts/discount-combinations) before combining multiple discount types.

***

## Go Further with Discounts

Discounts let you create **rule-based promotions** that apply automatically when certain conditions are met. This could be adding a product, hitting a cart total, or logging in as a subscriber.

Examples:

* "Get a free gift card when you add any subscription"
* "Spend \$100 and add Product X → get 20% off"
* "Free shipping for logged-in customers"

**Supported triggers**

* Cart total threshold
* Cart item quantity
* Specific products or variants
* Collections
* Subscription products
* Customer login status

**Supported rewards**

* Fixed or percentage discounts
* Free gift (specific product or variant)
* Free shipping

## 💡 **Tip:**

Each Discount supports up to **two trigger conditions** (using AND logic).

You can learn more about Discounts in the <a href="/upcart/discounts">Discounts</a> page.

***

## Offer Relevant Upsells

Upsells increase cart value *and* help customers discover complementary products they'll love. When done right, they feel like friendly recommendations, and not pushy add-ons.

### **What makes a good upsell**

* Directly relates to current cart contents
* Has a low price point or acts as an accessory (less friction)
* Enhances or completes the main purchase
* Presented clearly with a benefit or urgency

Examples:

* "Add this matching case for 15% off"
* "Bundle with a charger and save \$10"

## 🧠 **Note:**

You can only use **one upsell method** at a time - either **AI** (best for large catalogs) or **Manual** (best for curated stores).

Show **1–3 upsells** per cart for best performance. More than that can feel overwhelming.

[See the Upsells documentation](/upcart/upsells_module).

***

## Use Add-Ons to Boost AOV with Minimal Friction

Add-ons appear in the cart footer as toggles for extras like **shipping protection** or **gift wrapping**.

## Best Practices

* Clearly explain what the add-on includes.\
  *Example: "Protect your order against loss or theft for up to \$100."*
* Price it fairly in relation to cart value.
* Offer just **one add-on** to reduce decision fatigue.

## 💡 **Tip:**

Upcart's built-in **Shipping Protection Add-on** can be dynamically priced using tiers.

You can also add your own product as a **custom Add-On**, and choose whether it counts toward rewards totals.

***

## Turn empty carts into product discovery

Not every customer adds something right away and that's okay.

Upcart's **Empty Cart Recommendations** turn an empty cart into a curated browsing experience.

## Ideas for Empty Cart Design

* Feature seasonal items, best-sellers, or low-cost intro products.
* Link the "Shop Now" button to your **highest-converting collection**.
* Use a **block layout** for up to 5 products, or a **carousel** to show more.

**Example:**\
During a holiday sale, link your "Shop Now" button to your **Gift Guide** or **Holiday Collection** to inspire purchase intent.

***

## Final Tip: Test and refine

The key to higher conversions? **Consistent testing.**

Use **Upcart's Sandbox Mode** to experiment with:

* Different reward thresholds and logic
* Upsell combinations
* Add-on pricing
* Cart design changes

Then track how each change affects:

* **Average Order Value (AOV)**
* **Conversion rate**
* **Cart abandonment rate**

**If you're unsure where to start, we recommend:**

* One reward bar with 2–3 tiers
* One to two relevant upsells
* One clear add-on
* Empty cart recommendations enabled

***

## 📚 Next Steps

Ready to put these best practices into action?\
Check out our detailed setup guides for:

* [Rewards](#)
* [Upsells](#)
* [Add-ons](#)


# Design module
Source: https://docs.aftersell.com/upcart/design_module

This article explains how to customize your Upcart design settings.

The Design module allows you to customize the appearance of your cart, including layout, brand colours, and button styles.

# General

## Inherit Fonts from Theme

This setting allows Upcart to use the fonts defined in your Shopify theme settings. To view your current font choices, open the [Shopify Theme Editor](https://help.shopify.com/en/manual/online-store/themes/customizing-themes#access-the-theme-editor) and navigate to the Typography section.

## **🚧 Cart Preview 🚧**

Fonts inherited from your theme will not appear in the Upcart preview window, but they will display correctly on your live storefront.

## Show Strikethrough Prices

Enable this setting to show a strikethrough (also known as the [Compare At Price](https://help.shopify.com/en/manual/discounts/sales#set-a-compare-at-price-for-a-product)) price beside each item in the cart. This reflects discounted pricing, similar to your product pages.

<img alt="Cart item showing a strikethrough original price beside the discounted price and savings" />

## Enable Subtotal Line

Adds a subtotal line to the cart. Turning this on also reveals a **Subtotal text color** field under **Colors**, so the subtotal can be styled separately from the rest of the cart text. With the setting off, that colour field is hidden.

## Cart Width

Controls how wide the drawer is, set separately for each viewport:

* **Desktop** - **Default** or **Wide**
* **Mobile** - **Full** (edge to edge) or **Nearly full** (a small gap at the edge)

***

# Colors

## Background Color

Sets the main background color of the cart, excluding the footer and upsell cards.

## Cart Accent Color

Controls the background color of the cart footer and upsell item cards.

<img alt="Upcart Colors settings with the cart accent color applied to pink upsell cards" />

## Cart Text Color

Defines the color for all cart text, except for button text and savings text, which are controlled separately.

## Savings Text Color

Sets the color of the savings text shown beneath the product price.

<img alt="Cart item with the savings amount text highlighted in magenta" />

## Subtotal Text Color

Sets the colour of the subtotal line. This field only appears when **Enable subtotal line** is turned on under **General**.

## 🚧 **Cart Preview** 🚧

The preview editor may not reflect final styling precisely. Your store's theme may include custom CSS that affects text size or color. Always verify changes on your live storefront.

***

# Button Settings

Upcart offers advanced button styling options, including specific customization for the checkout button. This includes methods for CSS adjustments and integrating Shopify's branding tools.

## Corner Radius

Adjusts the roundness of button corners, from **0 px to 40 px**. `0` gives sharp, square corners; `40` is the roundest the slider goes. The value applies to the checkout button, upsell button, discount button, and upgrade button together.

<Note>
  The slider stops at 40 px. For a fully pill-shaped button you need [Custom CSS](/upcart/custom_css) — see [Advanced CSS customization](#advanced-css-customization-for-checkout-buttons) below.
</Note>

<img alt="Corner radius slider set to 16 pixels rounding the checkout button" />

## Button Color

Sets the background color for all buttons in the cart, including:

* Checkout button
* Upsell "Add to Cart" button
* Discount "Apply" button
* Subscription upgrade button You can customize these buttons' color through the Cart Editor. For further advanced customizations like CSS modifications, refer to the advanced customization section.

## Button Text Color

Specifies the text color used in all cart buttons.

## Button Text Hover Color

Controls the color of button text when a customer hovers over it with their mouse. For example, if set to green, the text will turn green on hover.

## Show Continue Shopping Button

Adds a **Continue shopping** button to the cart, letting customers dismiss the drawer and return to browsing without using the close icon.

# Advanced CSS Customization for Checkout Buttons

For significant design changes, you can use Custom CSS code to modify the checkout button:

1. In the Cart Editor, open **Settings** and select the **Custom CSS** tab.
2. Utilize the relevant CSS selector, such as `.checkout`. Example CSS snippets: To create a pill-shaped button:
   ```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
   .checkout {    border-radius: 9999px !important;}
   ```
   To add a black border:
   ```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
   .checkout {    border: 2px solid black !important;}
   ```
   Replace `.checkout` with the actual CSS class for your button. Additional styling includes hover effects, padding, text colors, or fonts.

# Integrating Shopify Branding for Button Customization

If you're using Shopify, you can update your checkout button design via Shopify's admin:

1. Log in to your Shopify Admin.
2. Navigate to `Settings > Checkout > Customize`.
3. Utilize branding options to modify the font, roundness, or colour for a seamless design.

<Frame>
  <img alt="Upcart cart drawer preview with an upsell Add button and checkout button" />
</Frame>


# Header module
Source: https://docs.aftersell.com/upcart/header_module

Learn how to update the header in your Upcart drawer, including logo, title styles, close button, and layout.

# Overview

The Header Module allows you to customize the top section of your Upcart drawer with your brand’s logo, title text, layout, background color, and close button. Visual controls make it easy to style your header without needing to define exact pixel sizes.

# **Header Module Settings**

## **General**

**Height** switches between **Slim** and **Tall** to control the vertical space. **Bottom border** is either **None** or **Thin**. **Background color** takes a hex code or the built-in colour picker, and supports transparency.

<img alt="Upcart Header module General settings with height and background color controls beside a cart preview" />

# **Title**

There are **three ways** to define your cart drawer header title: inherit your theme’s default title styling, display your store’s logo, or create fully custom text styles. Each method offers flexibility depending on your design needs.

<img alt="Upcart Header module title options: inherit theme titles, brand logo, or custom text styles" />

## Inherit from Theme Titles

This option uses your theme’s default heading styles, helping you keep the design visually consistent with the rest of your site. You can add your own title using the Text field and dynamically include the number of cart items using `{{cart_quantity}}`. Text alignment can be set to Side or Center, and you can select the appropriate heading level H2, H3, or H4, based on your store’s content structure.

## Brand Logo

If you prefer to use a brand logo in place of text, you can upload your store’s logo directly in this section. Choose to align the logo to the Side or Center, and scale it with the **Logo size** slider, which runs from 14 px to 48 px. There is no enforced limit on the file you upload, but using a PNG file is recommended for clean transparency and sharp edges. JPEGs are also supported but may include background noise or degrade logo detail. For performance, aim to keep file sizes optimized.

* We recommend using a **PNG** file for best quality and support for transparent backgrounds.
* JPEGs work too, but may not look as clean, especially if your logo has a background or fine details.

## Define Text Styles

Selecting the Text option gives you full control over styling the title independently from your store’s theme. You can enter any custom title and include `{{cart_quantity}}` for dynamic updates. Text alignment can be set to Side or Center, with options to change the font weight to Normal, Semibold, or Bold. Font size is adjustable from 14px to 48px using a visual slider, and you can optionally apply a text color override.

# Close Button

The close button is customizable to match your store’s design. **Location** puts it on the Left or Right side of the drawer. **Background**, **Icon**, and **Border** each take a colour plus a separate hover colour. **Icon size** is Small, Medium, or Large, and **Icon thickness** is Normal or Thick. **Border** is None, Thin, Normal, or Thick.

<Note>
  The border colour and border hover colour fields are disabled while **Border** is set to **None**. Pick a border width first, then set its colours.
</Note>

<img alt="Upcart Header module close button settings for location, colors, icon size, and border" />

# Custom template

On version 2.0 of the Header module, a **Custom template** code editor appears below the settings, with a single **Full** template covering the whole module. It uses React-based JSX, and you must first tick **Access custom templates** under **Settings > Cart settings > Advanced Settings** in the Cart Editor. See [Setting up a custom template](/upcart/setting_up_a_custom_template_in_upcart).

# Tips

* **Want precise spacing or sizing?** Use [Custom CSS](/upcart/custom_css) for full control beyond sliders, great for exact margins, padding, or logo scaling.
* **Test on desktop and mobile.** Header elements like text, logo, and buttons can display differently on various screen sizes
* **Use proper heading levels.** Choosing the right heading (H2, H3, H4) helps with accessibility and SEO. Match the structure of your store's content.

For more ways to personalize your cart, explore our [Upcart Help Docs](/). If you need custom changes, we recommend reaching out to a [Shopify Expert](https://www.shopify.com/ca/partners/directory).


# Quickstart guide to Upcart
Source: https://docs.aftersell.com/upcart/quickstart_guide_to_upcart

Learn how to activate Upcart, enable core features, and publish your cart drawer live.

This guide walks you through setting up Upcart with its main modules, from visual customization to activation on your storefront.

Upcart replaces your theme cart drawer visually, but it **does not integrate with your theme's cart drawer or cart page**. The Shopify cart page will still be accessible.

# **Managing Modules**

Each Upcart module can be **easily enabled or disabled**. Simply click on the **Enable/Disable** button in the top-right corner to turn a module on or off at any time. Your changes take effect immediately once saved.

<img alt="Announcements module row marked Disabled with an arrow pointing to the Enable button" />

# Cart design

When you first open Upcart's Cart Editor, you'll land in the [Design module](/upcart/design_module). Here you can customize the base colors of the drawer to match your store branding.

<img alt="Upcart Cart Editor Design module with colour settings beside a live cart drawer preview" />

# Announcements

To display a cart message or countdown timer, go to **Body > [Announcements](/upcart/announcements_module)**.

In the top right corner, click **Enable**. The badge beside the module name changes from **Disabled** to **Active**.

Enter your message into the **Announcement Text** field and configure the timer if needed.

<img alt="Announcement settings with timer, announcement text field, and colour options" />

Make sure to use the `{TIMER}` variable for countdowns within your announcement text to ensure proper functionality (e.g., "This offer is only available for .") Avoid copying formatted text directly from third-party tools.

Once you're done, make sure to click **Save** in the top-right corner.

#### Theme-Level Issues

* **CSS or App Conflicts:** Ensure that CSS properties like `display: none;` are not hiding the announcement bar. Also, check that third-party apps are not overriding these settings.
* **Text Visibility:** Confirm the announcement bar text color contrasts with the background and adjust it in your theme settings if necessary.

#### Advanced Debugging Steps

For persistent issues, review browser console errors for script problems affecting the announcement bar and disable third-party apps temporarily to pinpoint conflicts.

# Rewards

To display a progress bar that encourages customers to spend more, enable the Rewards Module.

### **General settings**

Set your branding colors and the message shown after the final reward tier is reached.

Choose a reward basis in the **Rewards calculation** card below General settings:

* **Cart total (\$)**: Tracks total cart value
* **Cart quantity (#)**: Tracks quantity of items

<img alt="Rewards module General settings with bar colours and completion message fields" />

### **Tier settings**

Choose your reward type:

* [**Shipping**](https://help.shopify.com/en/manual/fulfillment/setup/shipping-rates/flat-shipping-rates): Unlocks free shipping at the tier
* [**Discount**](https://help.shopify.com/en/manual/discounts/discount-types): Unlocks a discount at the tier
* [**Product**](/upcart/set_up_a_free_product_reward_tier_in_upcart): Adds a product to the cart

Whether tier progress is measured before or after discounts is set once for the whole bar, with the **Use pre-discounted prices for cart total** checkbox in **Rewards calculation** — it is not a property of the reward type.

Set a minimum threshold to trigger the reward and customize the **Title before achieving tier** field. You can create up to **four reward tiers**.

<img alt="Tier settings with the reward type select, minimum amount, and tier title fields" />

<Note>
  This screenshot predates the current labels: it shows the section as "Rewards settings" and the field as "Text before achieving". The controls are the same ones — they now read **Tier settings** and **Title before achieving tier**.
</Note>

# Upsells

Enable **Use AI Recommended Upsells**, select the **Related** algorithm, and turn on **Smart Variant Matching** to preselect matching product variants based on the cart contents.

<img alt="Upsells settings with AI recommended upsells, Related algorithm, and smart variant matching enabled" />

Customize your section title and the **Add** button label.

<img alt="Upsell fields for maximum upsells to display and the section title text" />

# Add-ons

To show a toggle-based add-on in the footer, you can enable either of these options:

### **Shipping protection**

Select **Shipping Protection** and configure dynamic pricing tiers based on cart value.\
This creates a real product in your Shopify catalog.

<img alt="Shipping Protection add-on settings with title, description, and pricing tiers" />

### **Product add-on**

Switch to the **Product Add-On** tab and select an existing product to offer as an upsell.

<img alt="Product add-on tab with a selected Energy Drink product and Change Product button" />

# Activating Upcart on your store

### Step one: Make your cart live

Once everything is configured, go to **Manage All Carts** > select the cart you want to make active > click **Publish**.

Once published, the cart moves to the live section of the carts table. It shows a warning **"App embed off"** badge until you enable the Upcart app embed in your theme, which is the next step. With the embed on, the badge becomes a green **"Live"** badge confirming the cart is showing on your storefront.

<Note>
  The app embed controls whether the Upcart cart drawer displays on your storefront. If you have Discounts configured, those rules remain active through Shopify's discount system even when the app embed is disabled.
</Note>

<img alt="Publishing a cart in Upcart with the Publish confirmation dialog open" />

### **Step two: Enable Theme App Embed**

To activate Upcart on your theme, go to **Shopify Admin → Online Store → Themes → Customize → App embeds**, enable the **Upcart** app embed, and click **Save**.

<img alt="Enabling the Upcart Cart Drawer toggle in the Shopify theme App embeds panel" />

If you encounter any issues or experience compatibility problems, feel free to contact our **Support Chat** for assistance.


# Upsells module
Source: https://docs.aftersell.com/upcart/upsells_module

This guide shows how to configure the Upsells module in Upcart

The Upsells module enables customers to add related or complementary products to their cart with a single click.

<img alt="Cart drawer showing a You'll love these upsell section with Add buttons" />

# Product Selection

## AI Recommended Upsells

Enable this setting to use [Shopify's Product Recommendation Algorithm](https://shopify.dev/docs/themes/product-merchandising/recommendations) to suggest upsells automatically.

### Recommendation Algorithm

This option appears only if AI recommendations are enabled. Choose your desired **Recommendation Intent**: [Recommendation Intent](https://shopify.dev/docs/themes/product-merchandising/recommendations#recommendation-intents).

The intent changes *which* products Shopify returns; it does not change the section heading. However you set it, upsells render under your **Upsell title** (default "You'll love these").

#### **Related products**

Shows similar or substitutable products.

* **Important:** Products must share a collection to be considered "related."

#### **Complementary products**

Shows add-ons or accessories.

* **Note:** Complementary intent must be manually configured in the [Shopify Search & Discovery app](https://apps.shopify.com/search-and-discovery). The algorithm only auto-generates for “Related” products.\
  Learn more in [Shopify's documentation](https://help.shopify.com/en/manual/online-store/search-and-discovery/product-recommendations).

## Smart Variant Matching

<Note>
  This checkbox only appears when **Use AI recommended upsells** is on **and** the Recommendation Algorithm is set to **Related**. It isn't available for manual upsells or for the Complementary intent.
</Note>

When enabled, Upcart pre-selects a variant on an upsell product that matches what the customer already has in their cart, rather than defaulting to the first variant in the list.

For example, if a customer adds a black shirt to their cart, the upsell will automatically pre-select the black variant on a paired pants product. If they added a blue shirt instead, the blue variant would be pre-selected instead.

Smart variant matching works even when option names aren't identical across products. If no matching variant is found, the customer can still select one manually.

## Manual Upsells Configuration

Manual upsells can be set up only when **AI Recommended Upsells** is disabled.

Click **Configure Manual Upsells**.

<img alt="Upsells module with the Configure Manual Upsells button highlighted" />

Click **Add New Upsell** to add a row with:

1. **Trigger**\
   **Specific Trigger:** choose at least one product that must be in the cart.\
   **Collection:** the trigger fires when any cart item belongs to the chosen collection — pick it from the **Collection** tab of the selection modal.\
   **All Products:** display the upsell when *any* product is in the cart.
2. **Upsell**\
   Select the product(s) to show when the trigger matches — or a **collection**, which pulls its products in.

<img alt="Configure Manual Upsells dialog with trigger product and upsell product columns" />

## Order of Upsell Appearance

Upsells are evaluated from top to bottom. To arrange the priority of rows, drag and drop them in the Cart Editor under the **Configure Manual Upsells** section. The system displays upsells based on their top-to-bottom arrangement in the Cart Editor.

<img alt="Manual upsell rows pairing trigger and upsell products with drag handles for ordering" />

If Products A and C are in the cart, and you’ve set upsells for each, both B and D will be shown.

When selecting multiple upsell products in a single upsell row, the order of product selection will determine the order of their appearance in the cart, top to bottom.

***

## Displaying Reviews

Upcart can display product reviews on **upsells and product recommendations** to help customers make informed purchase decisions. Reviews are not shown on standard cart line items.

Upcart uses the **[Shopify Storefront API](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields)** to read review data stored in product metafields. Because of this, reviews will only appear if your review app exposes product review data in a format the Storefront API can access.

<img alt="Upsell product card displaying a star rating and review count" />

### Supported review apps

At this time, Upcart supports reviews from the following apps:

1. **Shopify Product Reviews**\
   [https://apps.shopify.com/product-reviews](https://apps.shopify.com/product-reviews)
2. **Junip**\
   [https://apps.shopify.com/junip](https://apps.shopify.com/junip)
3. **Okendo**\
   [https://apps.shopify.com/okendo-reviews](https://apps.shopify.com/okendo-reviews)
4. **Growave**\
   [https://apps.shopify.com/growave](https://apps.shopify.com/growave)
5. **Fera**\
   [https://apps.shopify.com/fera](https://apps.shopify.com/fera)
6. **Yotpo**
7. **Stamped**
8. **Loox**
9. **REVIEWS.io**
10. **Automizely**
11. **Judge.me**
12. **Ali Reviews**
13. **Trustoo**
14. **Rivo**
15. **Rivyo**
16. **Vitals**

If reviews aren’t appearing, make sure you’re using one of the supported apps and that the products shown in upsells or recommendations have reviews available.

***

## Troubleshooting

If your upsell isn’t displaying, check out the [“Why Isn’t My Upsell Showing?”](/upcart/why_isnt_my_upsell_showing) article in our [FAQ](/upcart/adding_code_to_your_shopify_theme_for_accelerated_checkout_buttons) for common fixes.

#### **Next Steps**

To fine-tune how upsells behave in the cart drawer, continue to the next guide:

[**Upsell Module: Settings**](https://aftersell.mintlify.app/upcart/upsells_module_settings#upsells-module-settings)


# Upsells module: settings
Source: https://docs.aftersell.com/upcart/upsells_module_settings

This article outlines how to fine-tune in-cart upsell behaviour

# Overview

After you have selected your upsell products on Upcart upsells section, it's time to make sure that it is displayed in the way that you intended. This document describes functionality of each feature under **Cart Editor > Upsells > Upsell Settings**, and is a second part of the previous [**Upsell Module**](/upcart/upsells_module) document.

<img alt="Upcart Upsell Settings panel with checkboxes, upsell title, position, and direction options" />

## Show Upsell Offer If Item Already In Cart

If this setting is enabled, upsell offers will still display if the upsell product is already in the cart.

<img alt="Energy Drink upsell still offered even though the same item is already in the cart" />

## Limit the number of upsells in the cart

Allows you to set a limit to how many upsells can be shown at a time. Ticking it reveals a **Maximum number of upsells to display** number field (minimum 1):

<img alt="Limit the number of upsells checkbox enabled with maximum display set to 3" />

## Upsell Title

This is the text that displays **above the upsells module**.

You can style the text by highlighting the text you want to style, then using the buttons above the text field to apply **bolding, italics, underlines,** and **color:**

<img alt="Editing the Upsell title with bold, italic, and color formatting applied to the text" />

## Button text

You can customize the text displayed on the upsell add-to-cart button to your preferred phrasing or language.

## Upsell Position

This dropdown allows you to choose whether you want the upsells to be located at the top of your cart, or at the bottom.

If you're using the [Block](#block) upsell direction, we generally recommend choosing Bottom to maximize visibility of your customer's products.

## Upsell Direction

This dropdown allows you to change the **style of the upsells module**.

There are two possible options at this time:

## Carousel

Carousel will display all of the upsell products in a left to right slider.

This slider has arrows on the left and right side so that your customer can swap between products.

<img alt="Carousel upsell layout showing one product with left and right navigation arrows" />

## Block

Block will display all of the upsell products stacked vertically:

<img alt="Block upsell layout with three products stacked vertically in the cart" />

This style takes up more space, but the benefit is that your customers will see all the upsells without needing to interact with the module first.


# Welcome to Upcart
Source: https://docs.aftersell.com/upcart/welcome_to_upcart

An introduction to Upcart

At Upcart, we help Shopify brands create seamless, high-converting cart experiences that increase Average Order Value (AOV) and reduce cart abandonment.

Our fully customizable cart drawer solution empowers you to transform your cart into a powerful revenue-generating tool. With features like AI-powered upsells, tiered rewards, shipping protection, and extensive customization options, Upcart gives you complete control over your cart experience.

***

## **What you'll find here**

Explore detailed guides and best practices for getting the most out of Upcart:

* **[Cart drawer modules](/upcart/an_introduction_to_cart_drawer_modules)**: Learn about the modular building blocks that power your cart, including [Design](/upcart/design_module), [Header](/upcart/header_module), [Upsells](/upcart/upsells_module), [Rewards](/upcart/tiered_rewards_module_general_settings), and more.
* **[Upsells and recommendations](/upcart/upsells_module)**: Discover how to display targeted product recommendations using AI or manual configuration to boost cart value.
* **[Tiered rewards](/upcart/tiered_rewards_module_general_settings)**: Create progress bars that encourage customers to spend more by tracking progress toward rewards like free shipping, discounts, or free products.
* **Discounts**: Create rule-based promotions that automatically apply discounts, free gifts, or free shipping when specific cart conditions are met.
* **[Customization options](/upcart/getting_started_with_upcart_customizations)**: Use Custom HTML, Custom CSS, and JavaScript to make Upcart truly yours, or explore our [Public API](/upcart/introduction_to_upcarts_public_api) for advanced integrations.
* **[Add-ons](/upcart/add_ons_module)**: Offer shipping protection or product add-ons with simple toggle-based options in your cart footer.
* **[Frequently asked questions](/upcart/adding_code_to_your_shopify_theme_for_accelerated_checkout_buttons)**: Find quick answers and troubleshooting tips.

***

## **Key features**

### 🎨 Fully customizable design

Upcart gives you complete control over your cart's appearance and behavior. Customize colors, fonts, layouts, and spacing through the visual editor, or dive deeper with Custom HTML, Custom CSS, and JavaScript. You can even use our [Public API](https://rokt.notion.site/upcart-public-api) to build custom functionality.

### 🤖 AI-powered upsells

Leverage Shopify's Product Recommendation Algorithm to automatically suggest related or complementary products. Enable Smart Variant Matching to pre-select variants that match what's already in the cart, creating a seamless upselling experience.

### 🎁 Tiered rewards system

Display a visual progress bar that encourages customers to spend more by tracking their progress toward rewards like free shipping, discounts, or free gift items. Create up to four reward tiers based on cart total or item count.

### 💸 Discounts

Build flexible reward rules that automatically apply discounts, gifts, or free shipping when specific cart conditions are met. Discounts run through Shopify's native discount system and apply at checkout, even when the Upcart cart drawer is not visible.

### 🛡️ Shipping protection

Offer dynamic shipping protection with pricing tiers based on cart value. Upcart automatically creates a product in your Shopify catalog and handles the logic for you.

### 📱 Mobile-optimized

Upcart is built mobile-first, ensuring your cart looks great and performs flawlessly on all devices. Customize mobile and desktop views independently for the perfect experience.

### 🔧 Modular architecture

Mix and match modules to create the perfect cart for your store. Enable or disable features like announcements, discount codes, express payments, trust badges, additional notes, and more with a single click.

### 🌍 Multi-language support

Easily translate your cart into any language using Upcart's built-in translation settings or Shopify's native translation tools.

### 💬 24/7 support

Our highly-rated support team is available around the clock to help you with setup, customization, and troubleshooting. Check out our [reviews on the Shopify App Store](https://apps.shopify.com/upcart-cart-builder/reviews?sort_by=newest) to see what merchants are saying.

***

## **Getting started**

Ready to set up your cart? Start with our **[Quickstart guide to Upcart](/upcart/quickstart_guide_to_upcart)**, which walks you through:

1. Enabling and configuring core modules
2. Customizing your cart's design and branding
3. Setting up upsells and rewards
4. Activating Upcart on your storefront

Whether you're new to Upcart or looking to optimize your cart strategy, this site is your go-to resource for **increasing sales and creating exceptional cart experiences**.

***

## **Where can I find it?**

Upcart can be installed from the Shopify App Store:

[Install Upcart](https://apps.shopify.com/upcart-cart-builder)


# What is Aftersell?
Source: https://docs.aftersell.com/upcart/what_is_aftersell

Aftersell is our powerful upselling solution, this article explores how it works in detail.

# What's Upselling?

Upselling is the strategy of encouraging customers to purchase additional or higher-value items to increase their order total.\
By suggesting relevant upgrades or complementary products, you can boost profits without acquiring new customers, all while delivering a better shopping experience.

***

# Why Does Upselling Matter?

Upselling isn’t just about bigger profits, it’s about creating better experiences.

When it's done right, upselling adds value for both your business and your customers. You’re not just selling more, you’re helping customers find products that meet their needs, solve problems, or enhance their purchase. This personalized experience builds trust, strengthens customer loyalty, and drives repeat business.

Essentially, upselling empowers you to raise your AOV, build lasting customer relationships, and drive additional revenue beyond your existing sales.

***

# What Types of Upsells Does Aftersell Offer?

Aftersell offers four distinct upsell types. Providing a complete upselling ecosystem that strategically covers every stage of the customer's journey. This ensures you never miss an opportunity to maximize your store’s potential

### 1. Checkout Upsells

NOTE: This is currently only available to Shopify Plus merchants due to [Shopify's eligibility requirements](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations/checkout-extensibility#eligibility).

Checkout Upsells are offers presented directly during the checkout process & are seamlessly integrated into the customer flow. You can place these offers in strategic locations on the checkout page to encourage impulse add-ons without disrupting the experience.

<img alt="Checkout upsell offering a discounted T-Shirt with an Add button in the order summary" />

### 2. One-Click Upsells

One-Click Upsells, also known as Post-Purchase Upsells, appear immediately after checkout but before the customer reaches the Thank You Page. They carry zero risk of order churn since the initial transaction is already complete.

What makes these the powerhouse of Aftersell is that customers can accept these offers with a single click, no need to re-enter payment details, hence the name “1-Click Upsells.” Once accepted, the additional items are instantly added to the original order and paid for automatically, creating a seamless, frictionless path to more revenue

<img alt="Post-purchase upsell page offering a discounted Hat with Pay Now and decline options" />

### 3. Thank You Page Upsells

Thank You Page upsells are shown on the final page of a customer's order journey (aka the confirmation page). Similar to 1-Click Upsells, these offers carry no risk of order churn since the customer has already completed their purchase. You can use this space to introduce related items, future offers, or loyalty incentives.

<img alt="Thank you page with a discounted Hat upsell offer and Add button beside the order confirmation" />

### 4. Product Page Upsells

Product Page Upsells appear on the product page itself, before the customer has added anything to their cart. Added to your theme through an app block, they show complementary or related products in a "Buy It Together"-style widget, with an optional discount to make the offer more enticing. See [Product page upsells](/aftersell/product_page_upsells) for setup.

***

# What Makes Aftersell Stand Out?

### 1. Trusted by Leading Brands

Top brands like True Classic, Good American, Jones Road, and KitchenAid rely on Aftersell to boost conversions and AOV.

You can explore more **success** stories in our published [Case Studies](https://www.aftersell.com/case-studies).

### 2. Rokt Thanks (Formerly Network Offers)

*Unlock a New Revenue Stream, at No Cost*

You can turn your order confirmation page into a monetization opportunity by showcasing exclusive offers from brands like Disney+, HelloFresh, and Venmo. You effortlessly earn revenue every time a customer clicks “Yes, please!” on these exclusive offers.

Rokt Thanks provides access to a closed marketplace, ensuring customers receive tailored promotions they’ll love. Additionally, you have full control over which brands and categories appear. And, by leveraging intelligence from billions of transactions with industry leaders such as Ticketmaster, Spirit Airlines, and Staples, you're able to deliver highly relevant, personalized experiences that drive engagement and revenue.

### 3. Exceptional Customer Support

Our top tier Customer Support team is consistently praised in [reviews](https://apps.shopify.com/aftersell/reviews?sort_by=newest) for their responsiveness and dedication. Our goal is to ensure that every Aftersell user the proper guidance and peace of mind knowing they have reliable support whenever they need it.

Questions, suggestions, concerns? We’ve got you covered!

### 4. Pricing Built For You

Aftersell offers a 30-day free trial and a usage-based pricing model that scales with your store’s order volume.

That means that smaller stores benefit from affordability as they grow and high-volume merchants can unlock Aftersell’s full potential with pricing that aligns with their scale and success.

***

# Get Started with Aftersell

Ready to increase your AOV and elevate your customer experience?

Click the link below to install Aftersell directly from the Shopify App Store and start turning every order into an opportunity for growth.

[Install Aftersell](https://apps.shopify.com/aftersell)


# Add a mandatory terms and conditions checkbox to your cart
Source: https://docs.aftersell.com/upcart/add_a_mandatory_terms_and_conditions_checkbox_to_your_cart

Require customers to agree to your terms before proceeding with checkout.

# Overview

This tutorial shows you how to add a checkbox beneath the checkout button that requires customers to agree to your store’s terms and conditions. When unchecked, the checkout and express payment buttons are disabled.

This is a great way to ensure legal compliance, set clear expectations, and add professionalism to your cart experience.

***

## What this customization does

* Adds a terms and conditions checkbox under the checkout button
* Prevents customers from checking out until they agree
* Blocks the standard checkout button. On **Version 1** of the express payments module it also greys out the express buttons — see the note below if you're on Version 2
* Supports fully customizable text and link

This customization requires basic HTML, JavaScript, and CSS. It is best for store owners or developers with beginner coding knowledge.

<Warning>
  **The express-button half is Version 1 only.** The script looks for `#upcart-additional-checkout-buttons` and the CSS styles `.upcart-express-pay-button` — both belong to the Version 1 express payments module. Version 2 renders `#upcart-express-payments` and clones Shopify's own buttons, which carry neither selector, so express checkout stays clickable even when the box is unticked. The standard checkout button is blocked on both versions.
</Warning>

***

## Step 1: Add custom HTML

1. Go to **Upcart > Cart Editor > Settings > Custom HTML**
2. Paste the following in **Above announcements/rewards**:

```
<script>  
  function TermsCheckboxUpdate() {  
    var checkbox =  
      window.upcartDocumentOrShadowRoot.querySelector("#agree");  
    var termsWarning =  
      window.upcartDocumentOrShadowRoot.querySelector(".upcartTermsWarning");  
    var checkoutButton =  
      window.upcartDocumentOrShadowRoot.querySelector(".upcart-checkout-button");  
    var cartElement =  
      window.upcartDocumentOrShadowRoot.querySelector(".upcart-cart");  
    var expressButtons =  
      window.upcartDocumentOrShadowRoot.querySelector(  
        "#upcart-additional-checkout-buttons"  
      );  
  
    if (checkbox.checked) {  
      termsWarning.style.display = "none";  
  
      if (checkoutButton) {  
        checkoutButton.classList.remove("upcartDisableCheckoutButton");  
      }  
  
      if (cartElement) {  
        cartElement.classList.remove("style_upcartDisableExpressButton");  
      }  
  
      if (expressButtons) {  
        expressButtons.classList.remove("upcartDisableExpressButton");  
      }  
    } else {  
      termsWarning.style.display = "block";  
  
      if (checkoutButton) {  
        checkoutButton.classList.add("upcartDisableCheckoutButton");  
      }  
  
      if (cartElement) {  
        cartElement.classList.add("style_upcartDisableExpressButton");  
      }  
  
      if (expressButtons) {  
        expressButtons.classList.add("upcartDisableExpressButton");  
      }  
    }  
  }  
  
  window.upcartSubscribeCartLoaded(() => {  
    var checkbox =  
      window.upcartDocumentOrShadowRoot.querySelector("#agree");  
  
    if (checkbox) {  
      checkbox.setAttribute("onclick", "TermsCheckboxUpdate()");  
    }  
  
    TermsCheckboxUpdate();  
  });  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnCartLoaded` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeCartLoaded` for all new scripts.
</Note>

1. Paste the following in **Below checkout button**. Update the link and text to match your store’s terms:

```
<div class="upcartTermsWrapper">  
  <div class="upcartTermsCheckboxWrapper">  
    <input id="agree" type="checkbox" />  
    I accept the  
    <a  
      class="upcartTermsAnchor"  
      href="https://yourstore.com/terms"  
      target="_blank"  
    >  
      Terms & Conditions  
    </a>.  
  </div>  
  
  <div class="upcartTermsWarning">  
    Please accept the Terms & Conditions above before continuing.  
  </div>  
</div>
```

***

## Step 2: Add custom CSS

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**
2. Paste the following to control styling:

```
.upcartDisableCheckoutButton {  
  pointer-events: none !important;  
  background-color: grey !important;  
  opacity: 0.5 !important;  
}  
  
.upcartDisableExpressButton {  
  pointer-events: none !important;  
}  
  
.upcartTermsWarning {  
  text-align: center;  
  width: 100%;  
  color: red;  
  font-size: 14px;  
  font-weight: bold;  
}  
  
.upcartTermsAnchor {  
  text-decoration: underline !important;  
  color: #0000EE;  
  font-weight: bold;  
  font-size: 14px !important;  
  padding: 0 !important;  
}  
  
.upcartTermsWrapper {  
  width: 100%;  
}  
  
.upcartTermsCheckboxWrapper {  
  font-size: 14px;  
  text-align: center;  
  display: flex;  
  justify-content: center;  
  align-items: center;  
  gap: 5px;  
}  
  
.upcart-cart.style_upcartDisableExpressButton  
  .upcart-express-pay-button {  
  background-color: grey !important;  
  opacity: 0.5 !important;  
}
```

You can change the colors to match your branding by updating `color`, `background-color`, and `opacity` values.

***

## Final result

When customers open the cart:

* Checkout and express buttons are disabled until the checkbox is ticked
* A red warning message appears if they try to proceed without agreeing
* Once the box is checked, all buttons become active

***

## Need help?

For advanced implementations or more complex requirements, we recommend working with a **Shopify Expert**. Upcart’s support team does not assist with writing or troubleshooting custom code.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Add an end total line above the checkout button
Source: https://docs.aftersell.com/upcart/add_an_end_total_line_above_the_checkout_button

Display subtotal, fixed shipping, and total in one summary section above the checkout button.

# Overview

This customization adds a clear cost breakdown above the checkout button, showing subtotal, shipping, and total based on a fixed shipping rate.

It helps customers understand their final amount before checkout, improving trust and reducing hesitation.

**Important:** This method only works with fixed shipping rates. If your store uses dynamic shipping, results may be inaccurate.

***

## If you are on Upcart V1.0

#### Step 1: Add custom HTML

1. Go to **Upcart > Cart Editor > Settings > Custom HTML**
2. From the **Select HTML Location** dropdown, choose **Above checkout button**
3. Paste the following code and update the variables to reflect your store’s shipping cost and threshold:

```
<hr>  
  
<div class="cartSummarySection">  
  <div class="cartSummarySubtotal alignLeft">  
    Subtotal:  
    <span class="alignRight subtotalprice">{{UPCART_SUBTOTAL}}</span>  
  </div>  
  
  <div class="cartSummaryShipping alignLeft">  
    Shipping:  
    <span class="alignRight upcartShipping"></span>  
  </div>  
  
  <div class="cartSummaryEndTotal alignLeft">  
    Total:  
    <span class="alignRight upcartEndTotal"></span>  
  </div>  
  
  <div style="clear: both; display: flex;"></div>  
</div>  
  
<script>  
  var shippingThreshold = 15000; // In cents  
  var shippingCostWhenUnderThreshold = 290; // In cents  
  var textWhenUnderShippingThreshold = "$2.90";  
  var textWhenOverShippingThreshold = "FREE";  
  var currencySymbolToAddInfrontOfEndPrice = "$";  
  var shouldCurrencySymbolBeOnLeftSide = true;  
  
  window.upcartSubscribeCartLoaded((event) => {  
    var shippingText = window.upcartDocumentOrShadowRoot.querySelector(".upcartShipping");  
    var endTotal = window.upcartDocumentOrShadowRoot.querySelector(".upcartEndTotal");  
  
    if (event.cart.total < shippingThreshold) {  
      shippingText.innerText = textWhenUnderShippingThreshold;  
  
      if (shouldCurrencySymbolBeOnLeftSide) {  
        endTotal.innerText =  
          currencySymbolToAddInfrontOfEndPrice +  
          ((event.cart.total + shippingCostWhenUnderThreshold) / 100).toFixed(2);  
      } else {  
        endTotal.innerText =  
          ((event.cart.total + shippingCostWhenUnderThreshold) / 100).toFixed(2) +  
          currencySymbolToAddInfrontOfEndPrice;  
      }  
  
    } else {  
      shippingText.innerText = textWhenOverShippingThreshold;  
  
      if (shouldCurrencySymbolBeOnLeftSide) {  
        endTotal.innerText =  
          currencySymbolToAddInfrontOfEndPrice +  
          (event.cart.total / 100).toFixed(2);  
      } else {  
        endTotal.innerText =  
          (event.cart.total / 100).toFixed(2) +  
          currencySymbolToAddInfrontOfEndPrice;  
      }  
    }  
  });  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnCartLoaded` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeCartLoaded` for all new scripts.
</Note>

#### Step 2: Add custom CSS

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**
2. Paste the following CSS and adjust `background-color` or other styles to match your cart footer:

```
.upcart-footer {  
  padding-top: 0px !important;  
}  
  
.cartSummarySection {  
  background-color: #f6f4ef !important;  
  padding: 10px 23px;  
}  
  
.cartSummarySubtotal,  
.cartSummaryShipping,  
.cartSummaryEndTotal {  
  color: black;  
  width: 100%;  
  text-align: left;  
  font-weight: normal;  
  font-size: 16px;  
  padding: 0;  
}  
  
#CartPopup hr {  
  margin: 0px !important;  
}  
  
.alignLeft {  
  float: left;  
}  
  
.alignRight {  
  float: right;  
}
```

## Final result

Once applied:

* A cost breakdown appears above the checkout button
* Customers see subtotal, shipping (fixed or FREE), and total
* The shipping cost dynamically adjusts based on your threshold

This increases cost transparency, improves trust, and can reduce checkout abandonment.

***

## If you are on Upcart V2.0

#### Step 1: Go to cart summary module

1. Enable custom templates first: in **Upcart > Cart Editor > Settings > Cart settings**, expand **Advanced Settings** and tick **Access custom templates**. It's off by default, and until it's on the Cart summary tab shows only a "Custom templates aren't enabled" message with no editor.
2. Go to **Upcart > Cart Editor > Cart summary > Custom template**
3. Paste the following code:

   1. The custom code for the section is from Line 52 to Line 73

      ```
      <div>  
        <div className="upcart-internal-cart-summary upcart-public-cart-summary">  
          <div className="upcart-internal-cart-summary__discount-codes upcart-public-cart-summary__discount-codes">  
            <span className="upcart-internal-cart-summary__discount-label upcart-public-cart-summary__discount-label">  
              {props.totalSavingsText}  
            </span>  
        
            <div className="upcart-internal-cart-summary__slide-codes upcart-public-cart-summary__slide-codes">  
              {props.discountApplications.map((discountApplication) => (  
                <span  
                  key={discountApplication.key}  
                  className="upcart-internal-component-tag upcart-public-component-tag"  
                >  
                  <span className="upcart-internal-component-tag__icon upcart-public-component-tag__icon">  
                    <svg  
                      xmlns="http://www.w3.org/2000/svg"  
                      viewBox="0 0 20 20"  
                      focusable="false"  
                    >  
                      <title>Discount tag icon</title>  
                      <path  
                        fillRule="evenodd"  
                        d="M8.575 4.649a3.75 3.75 0 0 1 2.7-1.149h1.975a3.25 3.25 0 0 1 3.25 3.25v2.187a3.25 3.25 0 0 1-.996 2.34l-4.747 4.572a2.5 2.5 0 0 1-3.502-.033l-2.898-2.898a2.75 2.75 0 0 1-.036-3.852l4.254-4.417Zm4.425 3.351a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z"  
                      />  
                    </svg>  
                  </span>  
        
                  <span className="upcart-internal-component-tag__text upcart-public-component-tag__text">  
                    {discountApplication.title}  
                  </span>  
        
                  {discountApplication.type === "discount_code" && (  
                    <button  
                      type="button"  
                      className="upcart-internal-component-tag__remove-button upcart-public-component-tag__remove-button"  
                      onClick={props.handleRemoveDiscount}  
                      aria-label="Remove tag"  
                    >  
                      {props.isRemovingDiscount ? (  
                        <div className="upcart-internal-component-loader upcart-public-component-loader" />  
                      ) : (  
                        <svg  
                          xmlns="http://www.w3.org/2000/svg"  
                          viewBox="0 0 20 20"  
                        >  
                          <path d="M12.72 13.78a.75.75 0 1 0 1.06-1.06l-2.72-2.72 2.72-2.72a.75.75 0 0 0-1.06-1.06l-2.72 2.72-2.72-2.72a.75.75 0 0 0-1.06 1.06l2.72 2.72-2.72 2.72a.75.75 0 1 0 1.06 1.06l2.72-2.72 2.72 2.72Z" />  
                        </svg>  
                      )}  
                    </button>  
                  )}  
                </span>  
              ))}  
            </div>  
          </div>  
        
          <div>  
            {props.showCartTotalDiscount && (  
              <span  
                className="upcart-internal-cart-summary__total-discount upcart-public-cart-summary__total-discount"  
                dangerouslySetInnerHTML={{  
                  __html: props.formattedCartTotalDiscount,  
                }}  
              />  
            )}  
          </div>  
        </div>  
        
        {/* Custom code for summary section */}  
        <hr />  
        
        <div className="upcart-custom-cart-summary__container">  
          <div className="upcart-custom-cart-summary__row upcart-custom-cart-summary__subtotal">  
            Subtotal:  
            <span className="upcart-custom-cart-summary__subtotal-value">  
              ${(props.totalAfterAllDiscounts / 100).toFixed(2)}  
            </span>  
          </div>  
        
          <div className="upcart-custom-cart-summary__row upcart-custom-cart-summary__shipping">  
            Shipping:  
            <span className="upcart-custom-cart-summary__shipping-value">  
              $2.99  
            </span>  
          </div>  
        
          <div className="upcart-custom-cart-summary__row upcart-custom-cart-summary__cart-total">  
            Total:  
            <span className="upcart-custom-cart-summary__cart-total-value">  
              {/* totalAfterAllDiscounts excludes shipping — add the same 299 cents shown above. */}  
              ${((props.totalAfterAllDiscounts + 299) / 100).toFixed(2)}  
            </span>  
          </div>  
        </div>  
      </div>
      ```

      b. The relevant part is this section from line 52 - 73, use [this doc](/upcart/setting_up_a_custom_template_in_upcart#available-props-full-template) to decide what value you are planning to display on the screen

      ```
        <hr />  
        
        <div className="upcart-custom-cart-summary__container">  
          <div className="upcart-custom-cart-summary__row upcart-custom-cart-summary__subtotal">  
            Subtotal:  
            <span className="upcart-custom-cart-summary__subtotal-value">  
              ${(props.totalAfterAllDiscounts / 100).toFixed(2)}  
            </span>  
          </div>  
        
          <div className="upcart-custom-cart-summary__row upcart-custom-cart-summary__shipping">  
            Shipping:  
            <span className="upcart-custom-cart-summary__shipping-value">  
              $2.99  
            </span>  
          </div>  
        
          <div className="upcart-custom-cart-summary__row upcart-custom-cart-summary__cart-total">  
            Total:  
            <span className="upcart-custom-cart-summary__cart-total-value">  
              {/* totalAfterAllDiscounts excludes shipping — add the same 299 cents shown above. */}  
              ${((props.totalAfterAllDiscounts + 299) / 100).toFixed(2)}  
            </span>  
          </div>  
        </div>
      ```

      c. Go to **Upcart > Cart Editor > Settings > Custom CSS,** add this:

      ```
      .upcart-custom-cart-summary__row {  
        display: flex;  
        flex-direction: row;  
        justify-content: space-between;  
      }
      ```

***

## Need help?

If you want to adapt this for multiple shipping thresholds or advanced logic, we recommend working with a **Shopify Expert**. Upcart’s support team does not provide assistance with implementing or debugging custom code.


# Add-ons module
Source: https://docs.aftersell.com/upcart/add_ons_module

This article explains how to create an add-on product or offer in your Upcart footer.

The add-ons module will display a product at the bottom of the cart with an On/Off toggle.

<img alt="Upcart add-ons module showing a Shipping Protection product with an on-off toggle above the checkout button" />

This module has two different modes, [Shipping Protection](#shipping-protection) and [Product Add On](#product-add-on)

You can learn how each of them works in this document.

***

# Shipping Protection

## 🚧 **Important to Know**

Upcart itself does not offer Shipping Protection services, it only creates a product for you to use in the add-ons module.

If you plan to use the Shipping Protection mode, please make sure you're aware that **you will be providing the service.** If one of your customers gets a lost or damaged package, they'll need to contact you directly to process a claim.

## Add-on Title

This is the title of the product, you can change it to whatever you'd like!

For example, some people prefer using the term "Package Insurance".

## Description

This is the description of the product, you can change it to whatever you'd like!

We recommend making sure the product description matches your brand's tone of voice.

## Price

How much will you charge your customers for Shipping Protection services?

Let us know by filling out this field, and we'll set up the price for it!

On the right side of the field you'll see your store's default currency code. It's a label, not a picker — prices are entered in that currency only.

**However** if you have [Shopify Markets setup](https://help.shopify.com/en/manual/markets/managing-markets#add-a-market) on your storefront, this price will still be converted to your customer's local currency by Shopify!

## Include Add-ons in Cart Item Count

<img alt="Upcart editor Add-ons advanced settings with the Include addons in cart item count checkbox" />

This setting can be found in both modes.

**When checked, the add-on item will add to the cart's item count.**

For example, in the image below the item count at the top of the cart says "2", because the cart contains two products. The Ocean Blue Shirt and the Shipping Protection add-on!

<img alt="Upcart cart drawer with item count of 2 including the enabled Shipping Protection add-on" />

**If unchecked, then it will be excluded from it instead!**

For example, in the image below the item count at the top of the cart says "1", even though the cart contains two products. The Ocean Blue Shirt and the Shipping Protection add-on!

<img alt="Upcart cart drawer showing item count of 1 while the Shipping Protection add-on is excluded" />

This setting controls whether the add-on is *counted* as an item — it never adds the add-on to the cart or accepts it for the customer. As well as the number shown on the cart, the count feeds the Tiered Rewards module when its rewards calculation is set to **Cart quantity (#)**, so turning it on can move a customer over a reward threshold.

<Note>
  Add-ons are always opt-in: the customer has to switch the add-on toggle on themselves. The **Accept offer by default** setting that pre-accepted add-ons has been removed, and appears in the editor only as a disabled, deprecated field.
</Note>

***

# Product Add On

## Select Product/Change Product

Depending on whether this is your first time using this mode or not, you'll see either a "Select" or a "Change" button.

In both scenarios, clicking on the button will **open the product selection window**.

This allows you to choose which product you want offered in the add-ons module. After selecting a product, you can expand it to pick a specific variant. The chosen variant's price and image are used in the cart preview and on the live storefront.

* Since the add-ons module only has an on/off toggle, only one variant can be offered at a time.

## Include Add-ons in Cart Item Count

**When checked, the add-on item will add to the cart's item count.**

If checked, it will be included in the item count at the top of the cart.

**If unchecked, it will be excluded from the item count**

***

## **Addon not showing?**

1. Is the product Out of Stock? If so, then this is why it's not displaying.

2. Is the product a subscription or a bundle? If so, it's not displaying due to limitations on the types of products allowed for add-ons.

3. Is the product in "Draft" status? If so, then it needs to be in "Active" status to display in the add-ons module.

4. Is the product part of the "Online Store" sales channel? Only products in the Online Store sales channel can be displayed in the Add-ons Module.

For more details, you may also check out our [Why Can't I See My Add-On on the Storefront](/upcart/why_cant_i_see_my_add_on_on_the_storefront) documentation.


# Add-ons: product add-on
Source: https://docs.aftersell.com/upcart/add_ons_product_add_on

Offer any product as an add-on in the cart footer with a single toggle.

# Overview

The Product Add-on feature allows you to upsell one of your existing Shopify products directly from the cart drawer, helping increase average order value without disrupting the cart experience.

<img alt="Upcart cart drawer showing an Energy Drink product add-on toggle above the checkout button" />

# General Settings

To begin, click **Select Product** and choose the item you'd like to offer as an add-on. After selecting a product, you can expand it to choose a specific variant — the selected variant's price and image are shown in the cart preview and on the live storefront.

<img alt="Upcart Add-ons module with Product add-on selected showing the chosen Energy Drink product" />

Once selected:

* The product will display in the cart preview with its title, image, and pricing.
* The card's subtitle is the product's description, and the price shown is its first variant's price — the variant you picked isn't named on the card.
* Ensure the selected product is published on your **Online Store** sales channel.

📘 If your add-on isn’t showing up, see [Why Can’t I See My Add-On on the Storefront?](/upcart/why_cant_i_see_my_add_on_on_the_storefront)

# Advanced Settings

## **Include addon tracking on orders**

On by default. Adds add-on details to packing slips and receipts for analytics and tracking.

## **Include Add-On in Cart Item Count**

By default, add-ons are **not** included in the cart’s item count.\
Enable this setting if you want the add-on to increase the cart total item number (for example, if rewards are based on item count).

### **Deprecated: Accept Offer by Default**

As of **February 17, 2025**, this feature has been removed in compliance with [Shopify's App Store requirements (Section 1.19)](https://shopify.dev/docs/store/customize/cart/add-products?utm_source=chatgpt.com#automatic-add-to-cart).\
Apps are no longer permitted to **automatically add paid items** to a customer’s cart without explicit consent.

Customers must manually opt in by toggling the add-on product.

⚠️ This change supports a more transparent and trustworthy checkout experience for buyers.

This policy aligns with Shopify's broader commitment to creating a customer-first experience that prevents forced or misleading practices. For instance, attempts to simulate the default activation of add-ons, such as synthetic toggles or DOM modifications, are explicitly prohibited and may trigger resets or flags within Shopify. By understanding these guidelines, merchants can cultivate transparency and trust, aligning their practices with industry standards.


# Add-ons: shipping protection
Source: https://docs.aftersell.com/upcart/add_ons_shipping_protection

Offer customers peace of mind by letting them add shipping protection at checkout.

The Shipping Protection add-on is a digital product that appears at the bottom of the cart, allowing customers to protect their order against loss, theft, or damage with a simple toggle.

<img alt="Upcart cart drawer showing the Shipping Protection add-on toggle above the checkout button" />

<Warning>
  Upcart does not provide shipping protection services. You are responsible for fulfilling the protection if an issue arises. Customers must contact your support team to resolve claims.
</Warning>

For Product Add-ons, see the [Product Add-on guide](/upcart/add_ons_product_add_on).

***

## General Settings

Neither add-on type is selected when you first open the Add-ons module — the editor shows the two options and no settings until you pick one. Choose **Shipping protection**, then click **Add Shipping Protection** to generate and customize the protection product for your store.

<img alt="Upcart Add-ons module with Shipping protection selected and a disclaimer banner" />

Once added, you'll be able to configure the following fields:

<img alt="Shipping Protection settings with add-on title, description, and cart-value pricing tiers" />

### Add-on Title

This is the name displayed on the add-on in the cart drawer (e.g., "Shipping Protection").

### Description

Displayed below the title, this should explain what the add-on offers (e.g., "Protect your order from damage, loss, or theft during shipping").

### Price

A single flat price, in your store's currency, charged whenever the customer switches shipping protection on. This is the default — every store starts here.

### Shipping Protection Pricing Tiers

Tiered pricing is opt-in: below the **Price** field, click **Enable dynamic shipping protection pricing**. Once tiers exist, they replace the flat price.

Set tiered pricing based on the cart's total value. Each row defines:

* **Total cart value range** - the upper bound is inclusive
* **Protection price** for that range, in your store's currency

You can create up to **15 tiers**, allowing you to charge different protection fees depending on cart size.

<Note>
  The first tier covers orders up to your set threshold (for example \$0-\$50). Any cart value above that threshold automatically falls into the next tier. You do not need to manually define the lower bound of each subsequent tier.
</Note>

***

## Advanced Settings

These optional settings let you fine-tune how shipping protection behaves in the cart.

<img alt="Shipping Protection advanced settings toggles including the deprecated Accept offer by default option" />

### Include addon tracking on orders

On by default. Adds add-on details to packing slips and receipts for analytics and tracking.

### Include Add-on in Cart Item Count

When enabled, the shipping protection product will increase the cart's item count. This is useful if your rewards or discounts are based on item count.

### Auto-Fulfill Shipping Protection

When enabled, the shipping protection product will be automatically fulfilled when the rest of the order is marked as fulfilled.

<Note>
  This respects Shopify's fulfillment settings under Shopify Admin > Settings > Checkout > Order Processing.
</Note>

### Use Pre-Discounted Cart Total

Enable this setting if you want shipping protection tiers to be based on the cart subtotal before discounts are applied.

### Deprecated Feature: Accept Offer by Default

<Warning>
  As of February 17, 2025, this feature has been removed to comply with [Shopify's App Requirements - Section 1.19](https://shopify.dev/docs/store/customize/cart/add-products#automatic-add-to-cart). Apps can no longer automatically add paid items to the cart. Customers must now opt in manually by toggling the add-on. We are unable to implement any customizations or workarounds to re-enable this behaviour, as doing so would violate Shopify's guidelines.
</Warning>

***

## FAQ

<AccordionGroup>
  <Accordion title="How do I change the Shipping Protection image?">
    Edit the product in your **Shopify Admin > Products** and upload a new image just like any other product. See [Shopify's Product Media Guide](https://help.shopify.com/en/manual/products/product-media/add-media) for instructions.
  </Accordion>

  <Accordion title="Can I remove the grey background behind the image?">
    Yes. Add this custom CSS on the **Custom CSS** tab in **Cart Editor > Settings**:

    ```css theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
        .upcart-addons-image-wrapper {
          background-color: transparent;
        }
    ```
  </Accordion>

  <Accordion title="How can I make tiered pricing market-specific?">
    Since tiered pricing is based on **product variants**, you can configure market-specific prices using Shopify's [Markets features](https://help.shopify.com/en/manual/markets/pricing/set-price-adjustments).
  </Accordion>

  <Accordion title="My add-on is not showing on my live store">
    If your shipping protection add-on is not displaying or functioning as expected, work through the following steps:

    * **Check Sales Channel Inclusion** - Ensure the shipping protection product is added to your "Online Store" sales channel. Without this, the add-on will not display.
    * **Verify Product Activation** - Make sure the product is not in "Draft" mode and is set to "Active." Only active products can appear in your cart.
    * **Inventory Settings** - If the product has "Track quantity" enabled, ensure there is sufficient inventory. Alternatively, enable "Continue selling when out of stock."
    * **Browser Cache** - Clear your browser cache and refresh the page to rule out syncing issues.
    * **Review Product Type** - Ensure the product is not a subscription and is not a bundle. These configurations can interfere with visibility. (Multiple variants are fine — tiered pricing relies on them, with one variant created per tier.)

    For more detail, see [Why Can't I See My Add-On on the Storefront?](/upcart/why_cant_i_see_my_add_on_on_the_storefront).
  </Accordion>
</AccordionGroup>

***

**Want to go further?**

* [Add-ons Module](/upcart/add_ons_module) - overview of all available add-on types
* [Add-ons: Product Add-on](/upcart/add_ons_product_add_on) - set up a custom product add-on
* [Why Can't I See My Add-On on the Storefront?](/upcart/why_cant_i_see_my_add_on_on_the_storefront) - troubleshoot add-on visibility issues


# Add to cart button selector
Source: https://docs.aftersell.com/upcart/add_to_cart_button_selector

This article outlines how to configure your Add to Cart button to open Upcart

## How to Use the "Add to Cart Button Selector" in Upcart

If Upcart is not detecting your store’s "Add to Cart" buttons, you can manually tell Upcart which buttons to monitor. No coding is required.

***

This setting tells Upcart which buttons on your store are responsible for adding items to the cart. If your theme or another app uses a custom "Add to Cart" button, you can use this setting to ensure that Upcart detects it.

1. Open the **Upcart Editor**
2. Go to **Settings**
3. On the **Cart settings** tab, scroll down and expand **Advanced Settings**
4. Find **"Add to Cart Button Selector"**

<img alt="Upcart Add to cart button selector setting with Options dropdown set to Use default selector" />

You’ll see a menu with three available selections:

|                         |                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Option**              | **What It Means**                                                                                                         |
| Use Default Selector    | Upcart automatically tries to detect your "Add to Cart" buttons. Choose this option if the buttons are working correctly. |
| Add Additional Selector | Use this when your store includes multiple "Add to Cart" buttons. Add the other button in this field.                     |
| Use Custom Selector     | Choose this if your "Add to Cart" button is not working with Upcart. You will enter the button’s selector directly.       |

## How to Use the "Custom Selector" Option (No Coding Needed)

If you need to use the **Custom Selector** option, follow these simple steps:

1. **Go to your store’s product page.**
2. **Right-click on the "Add to Cart" button.** This is the button customers use to add products to their cart.
3. **Click "Inspect."** A panel with code will appear. You will not need to change anything.
4. In the panel, **look for a word starting with a dot (.) or a hash (#)** in the button’s code. For example: `.product-form__add-button` or `#add-to-cart`.
5. **Copy that part.** For example: `.product-form__add-button`.
6. **Go back to the Upcart Editor,** select **"Use Custom Selector,"** and **paste what you copied into the input box.**

**Tips**

* Try the **Default Selector** first. Only use a custom selector if Upcart is not detecting your "Add to Cart" buttons.
* If your store has multiple "Add to Cart" buttons, such as on product pages and collection pages, use **Add Additional Selector** and repeat the steps above for each button.
* You do not need to write any code. Just copy and paste the selector.
* Some buttons added by custom features, such as bundle apps and upsell apps, may not work even when using this feature.
* You can use any AI tools you prefer to check your work.

***

**Need Help?**

If you need help, you can ask your theme developer to find the correct selector. You do not need to write any code. Just copy and paste the selector as explained above.


# Adding a subtotal line to Upcart
Source: https://docs.aftersell.com/upcart/adding_a_subtotal_line_to_upcart

For those that prefer to have a subtotal line also be displayed above the checkout button

## Introduction

If the subtotal setting *(pictured below)* isn't working for you, here's a document going over how to insert a subtotal line manually.

## Enabling Subtotal Line

You can easily enable the Subtotal line in the cart Design settings.

Here is where to find the setting:

**Cart Editor > Design > General > Enable subtotal line**

<img alt="Cart Editor Design settings with the Enable Subtotal Line checkbox highlighted" />

# Inserting Subtotal via Code

## Accessing Custom CSS and HTML Settings

To begin customizing the CSS for your Upcart, follow these steps:

1. Open the Upcart App within your dashboard.
2. Navigate to the Cart Editor.
3. Open **Settings**. It is a row of tabs — pick **Custom HTML** or **Custom CSS** (they sit behind **More settings** if the row overflows).

## HTML

Make sure to select an HTML location to target the changes you would like to see in Upcart. In our case, we would want the subtotal line to be "above the checkout button". Feel free to change the "Subtotal" text below to match your preferred language.

```
<div   
  class="cart-subtotal-section"   
  style="display: flex; justify-content: space-between;"  
>  
  <span class="cart-subtotal-title">Subtotal</span>  
  <span class="cart-subtotal-value">{{UPCART_SUBTOTAL}}</span>  
</div>
```

This is how your custom HTML settings should look like in Upcart:

<img alt="Custom HTML settings set to Above checkout button with the subtotal line code" />

## CSS

In **Settings =>Custom CSS**, Change the font size and colors in custom CSS as needed. Don't forget to hit "Save" when you're done!

```
.cart-subtotal-section {  
  margin-bottom: 4px;  
}  
  
.cart-subtotal-title {  
  font-size: 24px;  
  color: red;  
}  
  
.cart-subtotal-value {  
  font-size: 18px;  
  color: green  
}
```

<img alt="Custom CSS settings showing the cart subtotal styling rules" />

***

## 🚧 Support for Customizations

Upcart's support team cannot assist with implementing custom CSS or HTML solutions in your cart.

If you need help designing or styling something custom, we recommend [consulting a Shopify Expert](https://www.shopify.com/partners/directory) or chatting with an LLM [using our AI Prompt Guidelines](https://docs.aftersell.com/upcart/ai_prompt_suggestions_for_adding_custom_code_to_your_upcart_settings#ai-prompt-suggestions-for-adding-custom-code-to-your-upcart-settings).


# Adding code to your Shopify theme for accelerated checkout buttons
Source: https://docs.aftersell.com/upcart/adding_code_to_your_shopify_theme_for_accelerated_checkout_buttons

This article explains how to place the required code so express checkout buttons display in the Upcart footer.

## Overview

This guide will walk you through the steps to modify your Shopify theme's code to ensure that Accelerated Checkout buttons work seamlessly in Upcart's updated Express Payment Module.

Before proceeding, we recommend familiarizing yourself with [Shopify's official documentation](https://help.shopify.com/en/manual/online-store/themes/theme-structure/extend/edit-theme-code) on how to edit your theme code. This will help you navigate the code editor smoothly. In addition, the documentation will highlight some of the risks of editing theme code.

***

## Step 1: Access Your Theme Code

1. **Open the Shopify Admin Dashboard**\
   From your Shopify dashboard, go to **Online Store** > **Themes**.

   <img alt="Shopify admin dashboard with Online Store in the left sidebar navigation" />

2. **Open the Code Editor**\
   Next, click on **Actions** for your current theme, then select **Edit Code**.

   <img alt="Shopify Themes page with the theme actions menu open and Edit code highlighted" />

## Step 2: Open the Layout Folder

1. In the code editor, locate the **layout** folder on the left sidebar.
2. Find and open a file called **theme.liquid**.

   <img alt="Theme code editor sidebar with the layout folder open showing theme.liquid" />

## Step 3: Locate the `<body>` Tag

1. In the **theme.liquid** file, search for the line that contains `<body`.\
   This is typically near the middle of the file. An easy way to find it is to search using (Command or Ctrl) + F and look for `<body`.

   <img alt="theme.liquid code editor with the opening body tag highlighted" />

## Step 4: Add the Code

1. Directly below the line with `<body>`, add the following code:

   ```
   {% if additional_checkout_buttons %}  
   <div style="display: none !important">  
       {{ content_for_additional_checkout_buttons }}  
   </div>  
   {% endif %}
   ```

   <img alt="theme.liquid with the additional checkout buttons snippet added below the body tag" />
2. Save the changes.

***

## Step 5: Test Your Changes

Go to your storefront and check the functionality of the Accelerated Checkout buttons. Ensure that everything displays and works as expected while the module is updated and enabled.


# Adding or updating a lock icon to your Upcart checkout button
Source: https://docs.aftersell.com/upcart/adding_or_updating_a_lock_icon_to_your_upcart_checkout_button



# Introduction

Adding a lock icon to your checkout button is a simple yet effective way to boost customer confidence by showing that their payment information is secure. This familiar symbol reassures customers about their data protection, making them more comfortable during the checkout process. In this tutorial, I'll guide you on how to add a lock icon to your checkout button using CSS, which will enhance security and improve the overall user experience.

These steps are perfect for store owners or developers with a basic understanding of CSS. By adding this small but impactful visual cue, you can align the Upcart checkout button with your site's design, helping to build trust and encourage customers to complete their purchases.

Let’s get started!

## Getting Started: Choose a Lock Icon

First, you'll need to choose a lock icon to add to your store. We have some available below for you to use, but you're welcome to use your own. To use your own, upload it to your Shopify store's Files section under **Settings > Files** and copy its URL.

There is no icon field in Upcart for the checkout button. Instead, you paste an HTML image tag into the **Checkout button text** field, which renders HTML — take one of the snippets below and swap its `src` for your own URL.

### Here are Lock Icons we have available for you to select:

HTML to add:

<img alt="White solid padlock icon beside Checkout text on a dark button" />

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<img class="upcart-custom-lock-icon" src="https://cdn.shopify.com/s/files/1/0591/9670/2877/files/WhiteLock2.png?v=1683833338">
```

HTML to add:

<img alt="White outline padlock icon beside Checkout text on a dark button" />

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<img class="upcart-custom-lock-icon" src="https://cdn.shopify.com/s/files/1/0591/9670/2877/files/Lock_White_4.png?v=1688577328">
```

HTML to add:

<img alt="White outlined padlock with keyhole beside Checkout on a dark button" />

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<img class="upcart-custom-lock-icon" src="https://cdn.shopify.com/s/files/1/0591/9670/2877/files/lock_icon_635ba3ed-7ec3-437e-8dce-cf53291aceb1.png?v=1681161869">
```

HTML to add:

<img alt="Black solid padlock icon beside Checkout text on a light blue button" />

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<img class="upcart-custom-lock-icon" src="https://cdn.shopify.com/s/files/1/0591/9670/2877/files/image_4.png?v=1694188629">
```

HTML to add:

<img alt="Black padlock with keyhole beside Checkout on a light blue button" />

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<img class="upcart-custom-lock-icon" src="https://cdn.shopify.com/s/files/1/0591/9670/2877/files/lock_icon_Black.png?v=1681162020">
```

## Placing the Lock Icon:

After choosing the lock icon, go to Manage All Carts > Edit > Settings > Edit copy and find the **Checkout button text** field. You can paste it either before the word "Checkout" or after. Additionally, this is where you can change the word "Checkout" to something else, such as "Secure Checkout" or similar.

<img alt="Editing the checkout button copy in Upcart to place the lock icon" />

## **Accessing Custom CSS Settings**

To begin customizing the CSS for your Upcart, follow these steps:

1. Open the **Upcart App** within your dashboard.
2. Navigate to the **Cart Editor**.
3. Open **Settings** and select the **Custom CSS** tab. Settings is a row of tabs rather than one long page — if you don't see Custom CSS, it's behind **More settings**.

### **Applying Custom CSS to show the lock icon:**

Once you are in the Custom CSS section, copy and paste the code below to show and place your lock icon. Please note that the bigger the padding number, the smaller the icon will be.

1. Locate the CSS input area.
2. Copy and paste the following code into the CSS input area:
3. Adjust `height` under `.upcart-custom-lock-icon` for a different size of the icon. Recommend `16px` or `20px` for a bigger lock icon

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.upcart-custom-lock-icon {  
  height: 12px;   
  margin-right: 6px;   
}   
  
.upcart-checkout-button {   
  display: flex !important;  
  align-items: center;   
  justify-content: center;   
}
```

## **Conclusion**

By following these steps, you've successfully added a lock icon to your checkout button, making your customers feel more secure and confident during their purchase. This small change can make a big difference in how your store is perceived, helping to build trust and improve the overall shopping experience.

## Still Need Help?

If you need any assistance with customizations, we recommend consulting with a Shopify Expert about adding HTML, CSS, and even JavaScript to your cart drawer.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Additional notes module
Source: https://docs.aftersell.com/upcart/additional_notes_module

Let customers leave special instructions with their order directly in the cart drawer.

# Overview

The Additional Notes module displays a collapsible notes section that allows customers to leave a message before proceeding to checkout. These notes appear in your Shopify admin under the order details.

<img alt="Cart drawer notes field with Add special instructions and Enter your note here input" />

💬 Notes can be viewed from the Orders page or the individual Order Details page in your Shopify admin.\
Learn more: [Shopify – Managing Order Details](https://help.shopify.com/en/manual/fulfillment/managing-orders/managing-order-details#notes-comments)

# Customizing Additional Notes

<img alt="Additional notes module editor with notes title, placeholder, and placement settings" />

# **Notes Title**

The title is the text that prompts customers to leave a note. It is clickable and can be customized with formatting options such as bold, italic, underline, and color. When applying a color, you can use the color picker swatch or type or paste a hex code (for example `#DDDDDD`) into the text field below the picker.

⚠️ If the title text is set to white, it may become invisible depending on your background. Highlight the entire field to check if it's readable.

## How it works

The notes section is collapsed by default. When a customer clicks on either the title or the chevron next to it, the notes input box expands. After a customer types a note, it saves automatically.
A status icon appears beside the title to show the save state:

* **Spinner** — the note is being saved
* **Checkmark** — the note was saved successfully

<img alt="Notes title editor formatting Add special instructions with bold, underline, and italic" />

# **Notes Placeholder**

This is the placeholder text that appears inside the input field before the customer types anything. For example, "Special instructions for your order."

As soon as the customer starts typing, their message will replace the placeholder. The submitted note is passed to Shopify and included in the order.

# **Notes Placement**

You can choose where the notes field appears in the cart layout:

#### **Below Cart Items**

* The notes section is placed below all items in the cart.
* Customers may need to scroll to find it, especially if the cart contains many items.
* Upsells and add-ons may be displayed below the notes field.

#### **Top of Footer**

* The notes field appears at the top of Upcart’s sticky footer.
* It remains visible at all times unless the sticky footer is disabled.
* In this layout:

  * Upsells are placed above the notes section
  * Add-ons are placed below the notes section

The 'Below Cart Items' placement is stored internally as bottomOfCart in metafields.


# Adjust the sticky cart button size
Source: https://docs.aftersell.com/upcart/adjust_the_sticky_cart_button_size

Customize the size and position of Upcart’s sticky cart button using CSS.

# Overview

Upcart’s sticky cart button can be resized and repositioned with custom CSS. This allows you to better match your store’s branding or user experience preferences across desktop and mobile devices.

There are two approaches available depending on how much control you want.

***

## Option 1: Scaled resizing (simple setup)

This method uses a single scale factor to shrink or enlarge the button and icon proportionally. It’s the easiest way to adjust button size with minimal code.

## Where to add this

Go to **Upcart > Sticky Cart > Custom CSS**, and paste the code below.

```
/* Set your desired scale factor here */  
/* Recommended range: 1 (default) to 0.65 (smaller) */  
.upcart-sticky-widget {  
  transform: scale(0.55);  
}  
  
/* Scale up your quatity icon */  
/* Recommended range: 1 (default) to 1.25 (bigger) */  
.upcart-sticky-cart-quantity-icon {  
  transform: scale(calc(1.5));  
}
```

## How to customize

* Change `transform` to resize the button (e.g. `0.8`, `0.6`, `1.25` etc.)

## Option 2: Pixel-specific resizing (advanced control)

This method allows you to control each element’s dimensions individually using `px` values. Use it when you want precise adjustments that don’t rely on scale.

```
:root {  
  --widgetMainSize: 40px;  
  --widgetCartIconSize: 30px;  
  --widgetQuantityIconSize: 20px;  
}  
  
.upcart-sticky-widget {  
  height: var(--widgetMainSize) !important;  
  width: var(--widgetMainSize) !important;  
}  
  
[class*="styles_CartIcon"] {  
  left: -2px !important;  
  top: 4px !important;  
}  
  
.upcart-sticky-cart-quantity-icon {  
  height: var(--widgetQuantityIconSize) !important;  
  width: var(--widgetQuantityIconSize) !important;  
  top: -5px !important;  
  left: 25px !important;  
  z-index: 100 !important;  
}  
  
.upcart-sticky-widget svg {  
  display: block !important;  
  height: var(--widgetCartIconSize);  
}
```

## How to customize

* Adjust the variables in `:root` to increase or decrease each element’s size
* Tweak the `left` and `top` values inside the selectors to visually center the icon and badge

## Need help?

If you’re unsure which method is right for you or need help writing custom CSS, we recommend reaching out to a Shopify Expert. Upcart support does not assist with CSS implementation directly.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# AI prompt suggestions for adding custom code to your Upcart settings
Source: https://docs.aftersell.com/upcart/ai_prompt_suggestions_for_adding_custom_code_to_your_upcart_settings

How to use AI tools like ChatGPT etc. to implement custom code.

**Customize your cart drawer in Upcart using HTML and CSS via Settings > Custom HTML & CSS.**

* **While Upcart offers help from our AI assistant Fin, you can also use third-party AI tools to create custom content.**

# Best Practices

* Use only **inline HTML** — no `<html>`, `<head>`, or `<body>` tags.
* Keep all **CSS** in the **Custom CSS** section.
* Use the **HTML location dropdown** to choose exactly where your snippet will appear.
* If you're using JavaScript, it should either be:

  * A small inline `<script>` (like a countdown timer)
  * Or placed in the **“Scripts (Before Load)”** section
* Send the AI a link to Upcart's V2 CSS Selector Library and HTML Location Library so it generates code using the correct class names for your cart version.

# Things to Avoid

* Don’t paste full webpages (`<html>`, `<head>`, `<body>` ) from AI tools or code generators, they will break the Upcart layout.
* Avoid putting styles in `<style>` tags inside the HTML box.
* Don’t use external fonts or heavy libraries unless absolutely necessary.

# Use ChatGPT or Similar AI for Extra Support

Use this copy-paste prompt to get clean code that works with Upcart:

```
I'm using a cart drawer app, Upcart, on my Shopify storefront. Please help me make design changes to the cart. Ensure to provide only the HTML to embed within the existing cart, rather than full HTML documents.   
  
**Do not include:**  
- `<html>`, `<head>`, or `<body>` tags  
- `<style>` tags (I will place CSS in a separate field)  
- Scripts unless they are very small and inline (or intended for the "Scripts (Before Load)" section)  
  
Here's a documentation page that lists all of Upcart's current CSS selectors: https://docs.aftersell.com/upcart/upcart_css_selector_library_v2
(If your cart is still on V1, use the V1 library instead: https://docs.aftersell.com/upcart/upcart_css_selector_library_v1)
  
Here's a documentation page that lists all of Upcart's current HTML locations: https://docs.aftersell.com/upcart/upcart_html_location_library  
  
Here’s what I want to build:  
[Insert what you want. e.g. A free shipping progress bar, a trust badge row, a message for international customers, etc.]  
  
Please return only the HTML snippet for the Custom HTML box and the corresponding CSS (if any) that I can paste into the Custom CSS box.
```


# Analytics in Upcart
Source: https://docs.aftersell.com/upcart/analytics_in_upcart

Understanding your Upcart analytics dashboard and performance metrics

## Per-cart analytics in the home dashboard

The Upcart home dashboard includes a table of your live carts and a table of your draft carts. Each row shows analytics for that individual cart over the selected date range:

* **Impressions** - The number of times customers viewed that cart
* **Cart conversion rate (%)** - The percentage of cart views that resulted in a completed order
* **Added revenue** - The revenue added through that cart's Upcart offers

The analytics columns use the same date range as the summary cards at the top of the home dashboard. Use the date picker to change the range — both the cards and the table update together.

While an A/B test is running, the live cart rows taking part in that test show figures for the **test window** instead of the selected date range, so the test's carts stay comparable with each other. Hover a column heading to see which period applies.

> **Note:** A cart must have been published to Shopify at least once before analytics data appears for it. Draft carts that have never been published show a dash (—) in the analytics columns.

## What you see on the Analytics page

The Analytics page has a selector panel on the left with two tabs:

* **Cart** — lists **All carts** (selected by default), then your **Live carts** and **Draft carts**
* **Test** — lists your A/B tests

The panel on the right shows the detail for whatever you select. With **All carts** selected you get your shop-wide data, in this order from top to bottom. Selecting an individual cart instead shows just Revenue and Impressions for that cart.

### 1. Revenue

A chart showing the total revenue generated by Upcart. Revenue comes from products your customers added through Upcart offers (upsells, add-ons, subscriptions). You can filter the chart by Add-ons, Upsells, or Subscriptions to see which types perform best.

### 2. Cart impressions

A card showing how many times customers viewed your cart. An impression is a unique time a customer has seen the cart - each visit counts once.

### 3. Checkouts completed

A card showing how many orders were completed after someone viewed the cart.

### 4. Conversion rate

A chart with two lines:

* **Checkout** - What percentage of cart viewers went to the checkout page
* **Order** - What percentage of cart viewers completed their purchase

If there's a big gap between these two lines, customers are likely dropping off during checkout. A small gap means your checkout is working well.

### 5. Top performing products

A table of products that sold the most through Upcart offers. The columns are:

* **Product** - The product that was added to the cart via an Upcart offer
* **Quantity sold** - The total number of units sold for this product through Upcart offers
* **Revenue** - The total revenue from sales of this product through Upcart offers
* **Module** - The Upcart offer type that drove the sale (e.g. Add-ons, Upsells, Subscriptions)

## Summary numbers

The big number at the top of the Revenue chart and of the Cart impressions and Checkouts completed cards is the **total** for the selected date range — the daily values added up.

Conversion rate works differently: rather than averaging the daily percentages, it adds up the impressions and the conversions across the whole range and divides once. Busier days therefore carry more weight, which is what you want — a single quiet day with one impression and one conversion can't drag the figure to 100%.

## Where the data comes from

There is nothing to switch on. The storefront records analytics events whenever the Upcart cart drawer renders, so data starts accumulating as soon as your cart is live on your theme.

Analytics therefore depends on two things being true: a cart is **published**, and the **Upcart app embed is enabled** on your theme. If either is missing, the cart never renders and no events are recorded.

## Using the dashboard

* **Date range** - Use the date picker at the top to choose your time period
* **Compare periods** - Use "Compare: Previous" to see how you're doing vs. the previous period
* **Filter by module** - Use the filter checkboxes on the Revenue chart to show or hide Add-ons, Upsells, or Subscriptions

💡 **Tip:** For useful insights, look at at least 7-14 days of data.

## Troubleshooting

### No data showing?

Check that your cart is published and that the Upcart app embed is enabled on your theme — the cart has to actually render for events to be recorded. A cart that has never been published shows a dash (—) rather than zeroes.

### Numbers seem wrong?

Confirm the app embed is on, that you're looking at a date range with enough data (at least 24–48 hours), and — if an A/B test is running — that you're reading a row scoped to the date range rather than the test window.

### Revenue doesn't match Shopify?

Upcart only counts revenue from products added through Upcart offers. Orders from direct checkout links, draft orders, or POS won't appear in Upcart analytics because the cart wasn't part of that purchase.

## Need help?

Contact the Upcart support team through the in-app chat or email [support@upcart.app](mailto:support@upcart.app)


# Announcements module
Source: https://docs.aftersell.com/upcart/announcements_module

Learn how to customize the announcement bar in your Upcart drawer, including height, position, countdown timer, text formatting, and colors.

# Height

The Height setting controls how thick the announcement bar appears. It offers three options: **Slim**, **Normal**, and **Thick**. Slim keeps the drawer more compact, making room for cart content—especially helpful on smaller screens. Normal sits between the two. Thick provides greater visual emphasis, helping your message stand out to customers.

# Position

Use the Position setting to choose whether the announcement bar appears **Before products** or **After products** inside the cart drawer.

* **Before products** puts the bar at the top of the cart body, directly beneath the header.
* **After products** puts it at the bottom of the cart body, just above the footer — below the notes and upsells modules if those are also placed there.

<img alt="Two Upcart carts comparing the announcement bar positioned above and below the products" />

## Timer duration

If you'd like the announcement to expire after a set time, set a countdown in the **Timer duration** field. It takes `MM:SS` — `05:00` for five minutes, `00:30` for thirty seconds. Seconds must be `00`–`59`; the field rejects anything higher.

The countdown only runs if your announcement text contains the timer variable. Once it runs out, the entire announcement bar is automatically removed from the cart.

<Note>
  The built-in countdown timer is session-based and counts down from a set number of minutes. It does not support recurring or daily countdowns that reset at a specific time (for example, counting down to 2:00 PM every day). This functionality is not currently available in Upcart.
</Note>

## Announcement Text

This section lets you enter and format the message displayed in the announcement banner. You can style specific portions of the text using the formatting bar above the input field, which includes options for bold, italics, underline, and color. When applying a color, you can use the color picker swatch or type or paste a hex code (for example `#DDDDDD`) into the text field below the picker.

<img alt="Color picker open for styling text in the announcement text editor" />

<Note>
  The Announcement Text field does not support hyperlinks—there is no link or URL button in the formatting toolbar, and pasted `<a>` tags or Markdown links are stripped on save. To make the announcement clickable or include a link, use the **Custom HTML** module instead (see below).
</Note>

### Adding a link or URL to the announcement

Because the built-in Announcement Text field does not render hyperlinks, you can either replace or supplement the announcement bar by injecting a link with Custom HTML:

1. Go to **Upcart > Cart Editor > Settings > Custom HTML**.

2. Set **HTML Location** to **Above announcements/rewards** (to appear above the announcement bar) or **Below header/announcements/rewards** (to appear directly under it).

3. Paste a snippet with your link, for example:

   ```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
   <div style="text-align: center; padding: 8px;">
     <a href="https://yourstore.com/sale" style="color: #ffffff; text-decoration: underline;">
       Shop the sale →
     </a>
   </div>
   ```

4. Click **Save**, then test in your live cart.

For more on Custom HTML locations and styling, see [Custom HTML](/upcart/custom_html) and [Custom CSS](/upcart/custom_css). Upcart's support team does not write or debug custom code—reach out to a Shopify Expert if you need help building it.

If you're using the countdown feature, insert the timer variable directly into your message. Use `{{timer}}` for V2 carts or `{TIMER}` for V1 carts.

<img alt="Announcement text field with the timer countdown variable added to the message" />

## Important

Make sure to manually type the timer variable (`{{timer}}` for V2, `{TIMER}` for V1) rather than copy-pasting it. This avoids hidden formatting issues that could prevent the timer from displaying correctly in your live cart.

# Font size

You can control the size of the announcement text using the slider, with options ranging from 10px to 24px. This helps ensure readability across both mobile and desktop experiences.

# Colors

Background Color allows you to define the overall fill color of the announcement bar. Border Color lets you adjust the horizontal lines above and below the banner for a styled container look.

# Advanced Timer Configuration

For additional functionality, JavaScript can be used to customize the countdown timer. Add your script in the **"Scripts (Before Load)"** section rather than the Custom HTML module. This is a load-timing requirement, not a security restriction—Custom HTML does execute scripts, but they run too late to hook into the cart's load event reliably. The "Scripts (Before Load)" section runs your code before the cart loads, so callbacks like `upcartSubscribeCartLoaded` fire correctly. Example code:

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeCartLoaded(function(event) {
    // Your countdown timer code here
    // event.cart contains the cart object with .items[], .total, .currency
  });
</script>
```

Legacy note: window\.upcartOnCartLoaded still works but is deprecated and logs a console warning. Use upcartSubscribeCartLoaded for all new scripts.

Be sure to test the placement and syntax of your code carefully. Some platform restrictions may still affect how scripts are processed.


# App billing cycles
Source: https://docs.aftersell.com/upcart/app_billing_cycles

This article explains how Shopify App Billing Cycles work

When using apps through Shopify, including Upcart, it's important to understand how **app billing cycles** work so you can manage your charges and subscriptions effectively.

This guide will walk you through how Shopify handles billing for third-party apps, what to expect on your invoice, and how billing cycles relate to your Shopify subscription.

***

## What is an App Billing Cycle?

An **app billing cycle** is the interval at which you are charged for using a third-party app on your Shopify store. Shopify manages billing for most apps (including Upcart), so your app charges are added directly to your Shopify invoice. App subscriptions renew automatically on their set renewal date, and a new charge is applied unless the app is uninstalled prior to this renewal date. To avoid unnecessary charges, it is crucial to uninstall apps before the renewal date if they are no longer needed.

## Key Points:

* App billing cycles **do not necessarily match** your Shopify subscription billing cycle.
* Each app you install may have its own **billing cycle**, which usually starts on the day you approve the app charge.
* Charges are typically **recurring monthly**, but apps can also use **usage-based** or **one-time** charges.

***

## Types of App Charges

There are three main types of charges you may see from an app:

1. **Recurring Application Charges** (most common)

* A flat monthly fee, for example, **\$29.99/month for Upcart**.
* Billed every 30 days starting from the approval date.
* Automatically renews unless canceled.

1. **Usage Charges**

* Based on how much you use the app (e.g., based on orders, views, or other metrics).
* These are **added to your invoice** within your Shopify billing cycle.
* Usage charges are applied based on specific criteria like your store’s total monthly order volume. They are accrued as long as specific conditions are met, regardless of whether key features of the app are actively utilized. This ensures that usage aligns with your store's activity, even if certain app features are not live.

1. **One-Time Charges**

* A single charge, typically for a special feature, upgrade, or add-on.
* Billed once and not repeated unless explicitly triggered again.

1. Combination of Subscription and Usage Charges

* Some apps may combine a subscription fee with usage-based charges under the same pricing tier, which can result in multiple charges presented separately in your Shopify invoice. This practice is consistent with Shopify's billing processes.

***

## Billing Timeline Example

Let’s say you install an app on April 10 and approve a \$29.99/month recurring charge:

* Your first app billing cycle is **April 10 – May 10**.
* You’ll be charged \$29.99 on your **next Shopify invoice**, even if your main Shopify subscription renews on a different date.
* On May 10, the next \$29.99 will be billed, starting a new 30-day app billing cycle.

Usage-based charges (if applicable) may also appear on the same invoice, based on your usage during the Shopify billing period.

**Please note:** App billing cycles and your Shopify billing cycle **may not always align**. This means charges can occasionally appear larger than expected, especially if **Shopify combines multiple app billing periods** (e.g., two months of charges) into a single invoice. Additionally, because Shopify’s billing cycle and app-specific billing cycles operate independently, charges for these respective cycles may seem to appear on unusually proximate dates. Despite this, these charges correspond to separate periods, ensuring no duplication occurs in the invoice.

***

## Where to See App Charges

You can review all app charges directly in your **Shopify Admin**: This includes charges for all apps like Aftersell. Follow the steps below to locate these details.

1. Login to your **Shopify Admin**.
2. Navigate to **Settings** in the lower-left corner of your admin dashboard.
3. Select **Billing**.
4. Under the **Recent bills** section, you'll see all invoices related to your Shopify account, including app charges. App names, such as Aftersell or Upcart, are displayed next to their respective charges.

For more detailed information, Shopify provides an official breakdown here: [Shopify Help Center – App Charges](https://help.shopify.com/en/manual/your-account/manage-billing/billing-charges/types-of-charges/third-party-charges/app-charges). If you need to review refunded charges or charge history, filter for **Refunded** invoices on the Billing page. This allows you to select and review specific bills, including detailed information on refunds and charge adjustments.

# Confirming Free or Promotional Plans and Checking Pending Charges

* To confirm that a free or promotional plan has been applied correctly:

  * For **Aftersell**, log into the app and verify pricing details when prompted to ensure successful application.
  * For **Upcart**, it depends on which kind of plan you were given. A **free** plan carries no Shopify charge, so there is nothing to approve — open **Plan & billing** and check that it is the plan shown as current. A **discounted promotional** plan does still have to be accepted by you: open the promo link the team sent you, choose the plan, and approve the Shopify charge. The discount only applies to the plan the promo code was issued for.
* To check for any pending charges or app-related expenses:

  * Navigate to the "App charges" section in your Shopify invoice.
  * Pending charges are itemized and can be cross-referenced with app usage.

***

## **Need help?**

Feel free to reach out to our support team via **chat in the app** or by emailing us at **[support@upcart.app](mailto:support@upcart.app)**. we’ll be happy to help clarify any billing questions or concerns you may have!


# App compatibility with Upcart
Source: https://docs.aftersell.com/upcart/app_compatibility_with_upcart



This article outlines how to troubleshoot app compatibility issues with Upcart and provides best practices for optimal performance.

## **Overview**

Upcart is designed to integrate smoothly with most Shopify apps. However, certain third-party apps may cause functionality issues depending on how they modify Shopify’s cart, checkout, pricing, or currency logic.\
​

Upcart operates as a cart drawer overlay, enhancing the shopping cart experience without completely replacing Shopify’s native cart or checkout.\
​

Apps that override Shopify’s cart behavior, intercept Add to Cart actions, or replace Shopify’s native pricing or currency system may conflict with Upcart.

We recommend using Shopify’s native functionality wherever possible (such as Shopify Markets for currency conversion). **Our team has limited scope of support for third-party apps that significantly alter Shopify’s default cart structure.**

Even if an app is available in the Shopify App Store, it may still be categorized as a third-party app and may have certain limitations when used with Upcart.

## **Incompatible Apps**

The following apps have been found to consistently cause issues with Upcart and are not supported:

**BUCKS (Currency Converter App)**\
Upcart is not compatible with third-party currency conversion apps. Upcart uses Shopify’s native currency conversion through Shopify Markets. Currency converter apps like BUCKS only change prices visually on the storefront and do not modify the actual cart currency. Because of this, they will not affect currency display inside Upcart and may cause inconsistencies.

If you require multi-currency functionality, we recommend using **Shopify Markets.**

**CloudFox Checkout**\
Third-party checkout replacement apps are not compatible with Upcart.

**CartPanda**\
Third-party checkout systems are not supported.

***

## **Apps That May Cause Issues**

The following apps have been reported to cause conflicts or may not work fully as intended with Upcart:

* **qikify Quick View Popups**
* **Vitals**
* **Bundle Bear**

While these apps may work in some cases, certain elements or features of Upcart may not display or function as expected.

If you experience issues while using any of these apps, we recommend enabling the compatibility setting outlined below.\
​

Developers can also utilize the [<u>Upcart Public AP</u>](https://rokt.notion.site/upcart-public-api)I to work toward a resolution.

***

## **Enhanced AJAX API Compatibility**

If you are experiencing conflicts with another app, we recommend enabling:

**Enhanced AJAX API Compatibility**

To enable this setting:

Go to **Upcart → Cart editor → Settings → Cart settings → Advanced Settings → Enhanced Ajax API compatibility**. There is no top-level Settings destination in the Upcart admin — the setting lives inside the cart editor, behind the collapsed **Advanced Settings** disclosure.

This setting tells Upcart to stop intercepting Add to Cart calls.

It also does a second thing the name doesn't suggest: it makes Upcart queue calls to Shopify's Ajax cart API (`/cart/add`, `/cart/add.js`, `/cart/update.js`, `/cart/change.js`) so they run one at a time, preventing simultaneous updates from different scripts from overwriting each other. Because that queueing patches all cart network requests on the page, turn the setting on only when you need it, and test the storefront afterwards.

This allows other apps, such as bundle apps, page builders, customization apps, and product option apps, to function without interference.

### **Important:**

This setting does come with a tradeoff.

Since Upcart will no longer intercept Add to Cart calls, it cannot prevent other apps from redirecting customers to the native cart page.

If customers are redirected away from the cart drawer after enabling this setting:

1. Check the conflicting app’s settings.
2. Look for options such as:
   * Disable redirect to cart
   * Stay on page after add to cart
   * Enable AJAX add to cart
3. Adjust those settings to prevent forced cart page redirects.

Testing after enabling this setting is strongly recommended.

The apps listed above are examples of those that have shown compatibility issues with Upcart. There may be additional apps not yet identified. This list will be updated as new cases are reported.

### If Upcart Is Not Opening or Is Redirecting

If Upcart is not opening properly or is redirecting to the cart page instead, please refer to our troubleshooting guide:

[Troubleshooting Upcart Not Opening or Redirecting to Cart Page](/upcart/troubleshooting_upcart_not_opening_or_redirecting)

This guide walks through common causes and step-by-step solutions, including:

* Conflicts with theme or custom code
* Issues with AJAX cart settings
* App compatibility checks
* Browser and cache troubleshooting steps

If the issue persists after following the guide, please contact support with your store URL and a brief description of the issue.

***

## **Testing Recommendation**

Before making any changes live, we recommend testing Upcart on a duplicate version of your theme.

To do this:

* In Shopify admin, go to **Online Store > Themes**
* Click **Actions** next to your live theme, then select **Duplicate**
* Open the duplicate theme and click **Preview**
* Test cart interactions, bundles, discounts, currency display, and upsells
* Once confirmed, publish the updated theme

Testing in advance helps prevent display or performance issues before they impact customers.

***


# Cart position
Source: https://docs.aftersell.com/upcart/cart_position

Choose which side of the screen the Upcart drawer appears from.

# Overview

The cart position setting allows you to control whether Upcart slides in from the **right** or **left** side of the screen. This is especially useful for stores that use **right-to-left languages**, or that want to match specific visual layouts.

## **How to Set the Cart Position**

In the **Cart Editor → Settings → Cart settings** tab, you'll find a dropdown labeled **Cart position**. You can choose:

* **Slide from right** *(default)*
* **Slide from left**

# **Slide From Right**

This is the default setting for most stores. The cart drawer slides out from the right-hand side of the screen on both desktop and mobile.

## Desktop Example:

<img alt="Upcart cart drawer sliding in from the right on desktop" />

## Mobile Example

<img alt="Upcart cart drawer sliding in from the right on mobile" />

# Slide From Left

If your store layout or customer base benefits from a left-aligned cart, you can switch the position. The cart will then slide in from the left side of the screen.

## Desktop Example

<img alt="Upcart cart drawer sliding in from the left on desktop" />

## Mobile Example

<img alt="Upcart cart drawer sliding in from the left on mobile" />


# Cart translations
Source: https://docs.aftersell.com/upcart/cart_translations

Edit or translate individual text labels across the Upcart interface.

# **Overview**

Upcart's Translations feature lets you change the phrasing and language of your cart's interface elements. Whether you want to adjust default wording or serve customers in multiple languages, everything can be managed directly inside Upcart.

If you need to support multiple languages, you'll first need to set them up in your **Shopify admin language settings**. Once that's done, all translation editing happens inside Upcart.

***

## How the customer's language is chosen

Upcart follows the **active Shopify storefront locale** for the current session. That's the same locale Shopify uses to render the rest of the storefront, and it's set by whichever of these Shopify determines for the shopper:

* The language chosen from your storefront's language switcher (if you've added one to your theme).
* The locale-prefixed URL the shopper is on (for example, `/fr` or `/de`).
* Your Shopify Markets language and country routing rules for the shopper's market.
* Your store's **Default language** in **Settings > Languages**, used as the fallback.

When Upcart renders, it looks up the translations you've saved for the matching language and uses them. If no translation exists for a field in the active language, Upcart falls back to the default text.

Because language selection is driven by Shopify, you can't override it from inside Upcart. Add or adjust languages in your Shopify admin and, if needed, add a language switcher to your theme so shoppers can change languages.

***

## Step 1 - Add Languages in Shopify Admin

Before a language can be used in Upcart, it must be added in your **Shopify admin settings**.

1. In Shopify, go to **Settings > Languages**
2. Add each language you want your store and cart to support

Important:

* All languages must be added here first if you want your cart to display in multiple languages
* Once added, they will appear in Upcart's language dropdown

Note: If you only want to edit or rephrase your existing cart text, you can skip this step.

<img alt="Shopify admin Languages settings listing English, French, German, and Spanish with an Add language button" />

## Step 2 - Translate Your Cart in Upcart

1. Go to **Upcart > Manage all carts**
2. Select the cart you want to translate
3. Click the **Translate** button
4. Choose a language from the dropdown
5. Add or update your translations

Click **Save** in the top right when you are done.

<img alt="Upcart Translations editor with the language dropdown open showing German, Spanish, and French" />

***

## How the Translations Editor Works

The editor has two columns:

* **Original**\
  The default text currently used in your cart
* **Translation**\
  Where you enter your translated or customized text

You can edit any field directly.

* Click **Save** to apply changes
* Click the **× icon** to **clear** a field. It empties the box rather than restoring the original, and an empty translation fails validation ("Translation cannot be empty") and blocks Save — so retype something before saving, or reload to discard the change.

***

What You Can Translate

You can customize all customer-facing text in your cart, including:

* Cart title and header text \*
* Checkout button and footer labels \*
* Empty cart messages
* Cart item labels — the show/hide bundle contents links
* Upsell content and buttons
* Upsell review count text \*
* Tiered rewards messaging \*
* Tiered rewards tier descriptions (e.g., "Free Shipping", "20% Off")
* Product recommendations
* Notes and special instructions
* Discount code fields — the input placeholder and the apply button
* Subscription options \*
* Announcement banners \*

Note: the fields with a \* next to them support dynamic variables such as `{{cart_quantity}}`, `{{total_price}}`, `{{amount}}`, and `{{review_count}}`.

<img alt="Upcart Translations fields showing dynamic variables like cart_quantity and total_price" />

***

## Editing Cart Text for a Single Language

If you only want to rename or rephrase specific cart elements without setting up multiple languages, you can do this through the **Edit Copy** panel.

1. Go to **Manage Carts > Edit**
2. Open **Settings** — it's a row of tabs; anything that doesn't fit sits behind **More settings**
3. Choose the **Edit copy** tab

**Body**

* **Automatic discount savings text** (e.g. "Save")
* **Empty cart message** (e.g. "Your cart is empty")
* **Continue shopping button text** (e.g. "Or continue shopping")

**Footer**

* **Total discount savings text** (e.g. "Discounts")
* **Subtotal text** (e.g. "Subtotal")
* **Checkout button text** (e.g. `Checkout • {{total_price}}`)

**Bundles**

* **Show bundle items text**, singular and plural
* **Hide bundle items text**, singular and plural

**Example:** To rename the checkout button to "Secure Checkout", update the **Checkout button text** field to `Secure Checkout • {{total_price}}` and click **Save**.

<img alt="Upcart Edit Copy panel editing body and footer text labels with a live cart preview" />


# Change product quantity selector colors
Source: https://docs.aftersell.com/upcart/change_product_quantity_selector_colors

Customize the look of product and upsell quantity selectors using CSS.

# Overview

This tutorial shows how to adjust the colors of the quantity selector components in the Upcart drawer. You can style the input field, text, and plus/minus icons. Updating these styles helps match your store’s branding and makes the cart experience more visually consistent.

This customization is best suited for store owners or developers with basic CSS knowledge.

***

## Where to find the custom CSS editor

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**
2. Scroll down to the input field and paste your CSS code
3. Click **Save**
4. Refresh your storefront to preview your changes live

***

## Example CSS for quantity selector styling for V1.0

```
/* Change background color of quantity field */  
.upcart-product-quantity-minus,  
.upcart-product-quantity-input,  
.upcart-product-quantity-plus {  
  background-color: yellow;  
}  
  
/* Change text color of quantity number */  
.upcart-product-quantity-input {  
  color: green;  
  -webkit-text-fill-color: green;  
}  
  
/* Change color of the + and - icons */  
.upcart-product-quantity-minus svg,  
.upcart-product-quantity-plus svg {  
  fill: pink;  
}
```

## Example CSS for quantity selector styling for V2.0

```
/* Change background color of the - icons */  
.upcart-public-component-product-tile__quantity-minus,  
.upcart-public-component-product-tile__quantity-plus {  
  background-color: yellow !important;  
}  
  
/* Change background color of quantity field */  
.upcart-public-component-product-tile__quantity-selector input {  
  background-color: yellow;  
}  
  
/* Change text color of quantity field */  
.upcart-public-component-product-tile__quantity-selector input {  
  color: red;  
}  
  
/* Change color of the + and - icons */  
.upcart-public-component-product-tile__quantity-minus svg,  
.upcart-public-component-product-tile__quantity-plus svg {  
  fill: orange;  
}
```

***

## How to customize

You can change the values in `background-color`, `color`, and the rest using any valid color format:

* Named colors (example: `white`, `black`)
* Hex codes (example: `#ff0000`)
* RGB values (example: `rgb(0, 132, 255)`)

**Example for a darker look:**

```
background-color: #1a1a1a;   
color: #ffffff;
```

These updates affect the quantity selectors on cart line items. Upsell and recommendation tiles don't render a quantity selector, so they are unaffected.

***

## Need help?

If you run into issues or need assistance, reach out to our [support team](mailto:support@upcart.app). We’re happy to help.


# Change the toggle colors in the add-on module
Source: https://docs.aftersell.com/upcart/change_the_toggle_colors_in_the_add_on_module

Customize the colors of the add-on toggle to match your store’s branding.

# Overview

This tutorial shows how to change the toggle colors used in Upcart’s add-on module, including shipping protection or any product-based toggle. Custom-colored toggles can help highlight important upsells and create a more cohesive visual experience.

This approach is best for store owners or developers with basic CSS knowledge.

***

## Where to find the custom CSS editor

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**
2. Scroll to the bottom of the page and paste the CSS code into the input field
3. Click **Save**
4. Refresh your storefront to see the changes applied

***

## Sample CSS for toggle customization in V1.0

The CSS below adjusts the toggle background color (on and off states), the toggle handle color, and resets other elements to avoid visual conflicts.

```
.upcart-cart {  
  --toggleColorWhenOn: #0dcd8d;     /* Color when toggle is ON */  
  --toggleColorWhenOff: #c4cdd5;    /* Color when toggle is OFF */  
  --toggleHandleColor: #ffffff;    /* Color of the toggle handle */  
}  
  
/* Toggle background when OFF */  
[class*="styles_ToggleSwitch"] {  
  background-color: var(--toggleColorWhenOff);  
}  
  
/* Toggle background when ON */  
[class*="styles_ToggleSwitch--active__"] {  
  background-color: var(--toggleColorWhenOn) !important;  
}  
  
/* Toggle handle (the circle) */  
[class*="styles_ToggleSwitch__circle__"] {  
  background: var(--toggleHandleColor) !important;  
}  
  
/* Reset internal parts to avoid unwanted overlap */  
[class*="styles_ToggleSwitch__loader__"],  
[class*="styles_ToggleSwitch__loading__"],  
[class*="styles_ToggleSwitch__checkMark__"] {  
  background-color: unset !important;  
}
```

## Sample CSS for toggle customization in V2.0

```
/* Toggle background color when OFF */  
.upcart-public-addons__toggle-slider {  
  background: blue;  
}  
  
/* Toggle background color when ON */  
.upcart-public-addons__toggle-switch input:checked + .upcart-public-addons__toggle-slider {  
  background: pink;  
}  
  
/* Toggle handle color (the circle) */  
.upcart-public-addons__toggle-slider::before {  
  background: orange;  
}
```

***

## How to customize

You can change the values in `background-color`, `color`, and the rest using any valid color format:

* Named colors (example: `white`, `black`)
* Hex codes (example: `#ff0000`)
* RGB values (example: `rgb(0, 132, 255)`)

***

## Still need help?

For additional customizations, we recommend working with a **Shopify Expert**. They can assist with adding HTML, CSS, or JavaScript to your cart drawer.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Change the upsell arrow color
Source: https://docs.aftersell.com/upcart/change_the_upsell_arrow_color

Use custom CSS to adjust the color of the navigation arrows in your upsell carousel.

# Overview

By default, the carousel arrows in Upcart’s upsell section are black. If your upsell background is dark, the arrows may be difficult to see. You can fix this by changing the arrow color with a simple CSS update.

***

## Where to find the custom CSS editor

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**
2. Scroll down to the input field and paste your CSS code
3. Click **Save**
4. Refresh your storefront to preview the changes

***

## Example CSS to change the arrow color in V1.0

```
.styles_PreviewCarousel__ [class~="control-next"]::before,  
.styles_PreviewCarousel__ [class~="control-prev"]::before {  
  border-color: white !important;  
}
```

## Example CSS to change the arrow color in V2.0

```
.upcart-public-component-carousel__button svg {  
  stroke: orange;  
}
```

The V1 rule above sets the arrows to white; the V2 rule sets them to orange. Both apply to the next and previous arrows.

***

## How to customize

You can update `border-color`, `stroke` to match your brand’s palette. Use any valid color format:

* Named colors (example: `black`, `white`, `red`)
* Hex codes (example: `#ffffff`)
* RGB values (example: `rgb(255, 255, 255)`)

**Example:**

```
border-color: #00bcd4 !important;
```

This ensures your upsell navigation arrows remain visible against any background color.


# Change the upsell variant selector colors
Source: https://docs.aftersell.com/upcart/change_the_upsell_variant_selector_colors

Customize the background and text color of variant selectors in the upsell section.

# Overview

Upcart allows you to change the colors used for upsell variant selectors using simple custom CSS. This is a quick way to align your cart’s appearance with your brand and improve the customer experience during product selection.

This customization is ideal for store owners or developers with basic CSS knowledge.

***

## Where to find the custom CSS editor

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**
2. Scroll down to the input area and paste your CSS code
3. Click **Save**
4. Refresh your storefront to preview the changes live

***

## Example CSS for variant selector styling in V1.0

```
.upcart-upsell-item-variant-selector {     
  color: white !important;  
  background-color: #008060 !important;   
}
```

## Example CSS for variant selector styling in V2.0

```
.upcart-public-component-upsell-tile__variant-row select {  
  color: white;     
  background-color: #008060;   
}
```

***

## How to customize

* **color**: Sets the text color
* **background-color**: Sets the background of the variant selector box

You can use different types of values, such as:

* Named colors (example: `black`, `white`, `red`)
* Hex codes (example: `#000000`)
* RGB values (example: `rgb(255, 0, 0)`)

**Example:**

```
.upcart-public-component-upsell-tile__variant-row select {     
  color: #000000 !important;     
  background-color: #f3f4f6 !important;   
}
```

This lets you create a variant selector style that either blends in with your store’s design or stands out to grab attention.

***

## Still need help?

For additional customizations, we recommend working with a **Shopify Expert**. They can assist with adding HTML, CSS, or JavaScript to your cart drawer.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Changing font sizes
Source: https://docs.aftersell.com/upcart/changing_font_sizes

Adjust text size in Upcart using custom CSS.

# Overview

If you want to change the font size of specific text elements in your cart (such as upsell titles or variant options), you can do so using Upcart’s built-in **Custom CSS** editor.

***

## Step 1: Inspect the element

1. Open your storefront and launch the Upcart drawer.
2. Right-click on the element whose font size you want to change.
3. Choose **Inspect** from your browser’s context menu to open the Developer Tools.
4. Locate the element’s **class name** in the HTML panel.\
   Example: `upcart-item-option`

## Step 2: Access the custom CSS editor

1. Go to **Shopify Admin > Apps > Upcart**
2. Open the **Cart Editor**
3. Click on **Settings**
4. Find the **Custom CSS** section

## Step 3: Write your custom CSS

In the CSS input field:

1. Start with a period (`.`) followed by the class name
2. Add `{ font-size: 14px !important; }` (or your desired size)

Example:

```
.upcart-item-option {  
 font-size: 14px !important;  
}
```

💡 **Note:** `.upcart-item-option` is a V1 class. On V2, the equivalent line-item variant text is `.upcart-public-component-product-tile__variant`. See the [V2 CSS selector library](/upcart/upcart_css_selector_library_v2) for the full set.

Use `!important` only if the style is not being overridden after the change.

## Step 4: Save and test

1. Click **Save** in the Cart Editor
2. Refresh your storefront page
3. Open the cart drawer and confirm the font size has updated

If the text hasn't changed, double-check the class name or use the browser’s Inspect tool again to confirm you’re targeting the correct element.


# Common Upcart API uses
Source: https://docs.aftersell.com/upcart/common_upcart_api_uses

Learn how to put Upcart's Public API to work with practical, copy-paste examples.

## How the API Pattern Works

Most Upcart API scripts follow the same simple pattern:

Listen for a cart event → Check a condition → Take an action

For example: "When the cart loads → check if it's empty → hide the sticky button."

💡 **New to APIs?** Start with [What is an API?](/upcart/what_is_an_api) before diving into the examples below.

***

## Where to Add Your Scripts

All scripts below go in:

**Cart Editor → Settings → Custom HTML → Scripts (before load)**

Wrap each snippet in `<script>...</script>` tags and save. To test, open your browser's Dev Tools console (`F12`) and look for any `console.log` messages.

***

## A note on legacy vs. modern callbacks

Upcart has two ways to listen for cart events:

| Style                | Example                          | Status                            |
| -------------------- | -------------------------------- | --------------------------------- |
| Modern (recommended) | `upcartSubscribeAddedToCart(fn)` | Current                           |
| Legacy (deprecated)  | `upcartOnAddToCart = fn`         | Still works, logs console warning |

All examples below use the modern API. Existing scripts using the old style will continue working.

***

## Example 1: Hide the Sticky Cart Button When the Cart is Empty

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeCartLoaded(function(event) {
    var stickyBtn = document.querySelector("#upCartStickyButton");
    if (stickyBtn) {
      var totalQty = event.cart.items.reduce(function(sum, item) {
        return sum + item.quantity;
      }, 0);
      stickyBtn.style.display = totalQty === 0 ? "none" : "block";
    }
  });
</script>
```

**How it works:** `upcartSubscribeCartLoaded` fires every time the cart is loaded. The callback receives an `event` with a `cart` object containing an `items` array. We sum the `quantity` of each item to determine if the cart is empty.

⚠️ **IMPORTANT:** `event.cart` does NOT have an `item_count` property. You must calculate the total by iterating `event.cart.items`.

***

## Example 2: Log When an Item is Added to the Cart

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    console.log("Added to cart:", event.item.title, "| Qty:", event.item.quantityAdded);
  });
</script>
```

**Properties available on `event.item`:**

| Property                   | Description                             |
| -------------------------- | --------------------------------------- |
| `event.item.title`         | Product title                           |
| `event.item.quantityAdded` | Number of units added in this action    |
| `event.item.quantity`      | Total quantity of this item now in cart |
| `event.item.variantId`     | Shopify variant ID                      |
| `event.item.handle`        | Product handle                          |
| `event.item.productId`     | Shopify product ID                      |
| `event.item.finalPrice`    | Final price after discounts             |
| `event.item.image`         | Product image URL                       |

***

## Example 3: Integrate with a Third-Party Analytics App (e.g. TripleWhale)

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.TriplePixel('AddToCart', {
      item: event.item.variantId,
      q: event.item.quantityAdded
    });
  });
</script>
```

> **Note:** Each third-party app is different. Check with your app's support team for the correct event format.

***

## Example 4: Open the Cart Automatically After a Product is Added

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>
```

> **Note:** If "Open cart drawer on add to cart" is already enabled in **Cart Editor → Settings → Cart settings**, you don't need this script.

***

## Quick Reference: Subscribe Functions (Modern API)

| Function                                               | When it fires                   | Callback receives                                                                                      |
| ------------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `upcartSubscribeCartLoaded(fn)`                        | Cart data loads                 | `{ cart }` - cart has `.items[]`, `.total`, `.currency`                                                |
| `upcartSubscribeAddedToCart(fn)`                       | Item added to cart              | `{ item }` - item has `.title`, `.variantId`, `.quantityAdded`, `.quantity`                            |
| `upcartSubscribeCartOpened(fn)`                        | Cart drawer opens               | `{}` (empty object)                                                                                    |
| `upcartSubscribeCartClosed(fn)`                        | Cart drawer closes              | `{}` (empty object)                                                                                    |
| `upcartSubscribeCartUpdated(fn)`                       | Cart contents change            | `{ cart }`                                                                                             |
| `upcartSubscribeItemRemoved(fn)`                       | Item removed                    | `{ item }`                                                                                             |
| `upcartSubscribeCheckoutClicked(fn)`                   | Checkout button clicked         | `{ event }` - browser MouseEvent                                                                       |
| `upcartSubscribeUpsellsAddedToCart(fn)`                | Upsell item added               | `{ variant }` - has `.id` and `.title`                                                                 |
| `upcartSubscribeUpsellsRendered(fn)`                   | Upsells render in cart          | `{ item, element }` - item is the product, element is the DOM node                                     |
| `upcartSubscribeNotesTextChanged(fn)`                  | Cart notes updated              | `{ newNotesText, oldNotesText }` - the new notes string and the previous one                           |
| `upcartSubscribeRewardsMilestonesCompletedChanged(fn)` | Reward milestone status changes | `{ numOfMilestonesCompleted, status }` - `status` is `"promotion"`, `"demotion"`, or `"initial-state"` |

***

## Direct Action Functions

| Function                           | What it does                                                   |
| ---------------------------------- | -------------------------------------------------------------- |
| `window.upcartOpenCart()`          | Opens the cart drawer                                          |
| `window.upcartCloseCart()`         | Closes the cart drawer                                         |
| `window.upcartRefreshCart()`       | Refreshes cart data                                            |
| `window.upcartGetCart()`           | Returns the current cart object                                |
| `window.upcartRegisterAddToCart()` | Registers add-to-cart for page builders (Replo, PageFly, etc.) |
| `window.upcartFormatMoney()`       | Formats a price using your store's money format                |

For the full API documentation, see the [Upcart Public API Documentation](https://rokt.notion.site/upcart-public-api).

***

## Troubleshooting

* **Script not running?** Double-check placement: it should be in *Scripts (before load)*, not after load.
* **Element not found?** Make sure the selector (e.g. `#upCartStickyButton`) matches the actual element ID in your cart.
* **Something broke?** Comment out your script by adding `//` to the start of each line, save, and refresh.
* **Still stuck?** See the [API FAQ](/upcart/upcart_api_frequently_asked_questions) for more troubleshooting steps.


# Creating a cart from templates
Source: https://docs.aftersell.com/upcart/creating_a_cart_from_templates

Use ready-made cart templates to quickly set up a styled cart that matches your brand.

Upcart includes a template-based cart creation flow that lets you start with a pre-designed cart style and select the modules you want to include. This is a faster alternative to building a cart from scratch.

## How to create a cart from templates

You can access the template flow from two places:

* **All Carts page** — Click **Create cart**, then select **Create from templates** from the dropdown menu.
* **Empty state** — If you have no carts yet, click **Start from templates** in the empty carts view.

During onboarding, you are also prompted to design your first cart using templates at the end of the setup flow.

## Step 1: Select a base style

The first step shows a grid of pre-designed cart styles. Each card displays:

* The style's name
* A wireframe preview of the cart layout and color palette
* Color swatches for the template
* The font. The four built-in styles don't set one, so they read **Inherits from theme** — only the live-theme card names an actual font.

Select a style by clicking on it. The live preview panel on the right updates to show how your cart will look with that style applied.

If Upcart can detect your Shopify theme's colors and fonts, a **Your Live Theme** card appears at the top of the grid. Selecting it applies your theme's colors, fonts, and button styling to the cart automatically.

When you are happy with your selection, click **Next**.

## Step 2: Select modules

The second step shows a set of recommended modules you can include in your cart. Each module card displays an image and a short description.

Click a module card to toggle it on or off. You can add or remove modules at any time later in the cart editor.

Available modules include:

* **Upsells** — Present targeted upsell offers to increase order value
* **Rewards** — Incentivize customers to add more to their cart with reward tiers
* **Recommendations** — Show AI-powered product recommendations to boost AOV
* **Add ons** — Let customers add complementary products with a single toggle
* **Announcements** — Display promotional banners and messages at the top of the cart
* **Subscriptions** — Offer subscription upgrades directly in the cart drawer

When you are done, click **Save as draft**. The cart is created as a draft and you are taken to the cart editor to continue customizing and publish when ready.

## After creating your cart

Once the cart is created, it opens in the cart editor where you can:

* Adjust colors, fonts, and layout in the [Design module](/upcart/design_module)
* Configure each module's settings
* Publish the cart to make it live on your store

For more information on managing multiple carts, see [Multicart](/upcart/multicart).


# Custom CSS
Source: https://docs.aftersell.com/upcart/custom_css

Write CSS to customize the design of your cart drawer.

# Overview

This section allows you to change the look and feel of existing cart elements or apply styles to custom HTML added through the editor.

## **Where to Find It**

Go to:\
**Upcart > Cart Editor > Settings > Custom CSS**\
Settings is a row of tabs; Custom CSS is one of them, alongside Custom HTML. If it is not visible, it is behind **More settings**.

## **How It Works**

You can add CSS to:

* Style default cart elements
* Modify the appearance of custom HTML
* Adjust spacing, alignment, typography, and more

As you type, an **auto-complete popup** will suggest valid Upcart selectors to help speed up editing. Selecting a suggestion will auto-complete the rule and help you structure your code. If changes fail to appear as expected, review common troubleshooting suggestions, such as refreshing caches in both the browser and Upcart editor, checking CSS placements, and ensuring proper specificity in your CSS rules.

## **Using Selectors**

Upcart provides a wide range of custom selectors. Click **"Show list"** to view all available options. Avoid using global selectors like `body`, `div`, or `h3` unless scoped with `.upcart-cart` to prevent unintentional changes to your storefront. For situations where styles are not applied correctly, consider increasing CSS specificity or appending `!important` to your CSS rules. Doing so ensures they override any conflicting styles. Example:

```
.upcart-cart .upcart-checkout-button {    border-radius: 20px !important;    background-color: #CFA17E !important;    color: #1A1A1A !important;}
```

Example (safe selector):

```
.upcart-cart h3 { font-size: 20px; }
```

## **Example: Thank You Message Styling**

Suppose you added this custom HTML below the checkout button:

```
<div class="thank-you-message">Thanks for shopping with us!</div>
```

Without CSS, the message will look plain. To style it:

```css theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.thank-you-message { color: green; font-size: 16px; font-weight: bold; text-align: center; margin-top: 5px; }
```

# Common Problems and Solutions

## CSS Not Appearing on Mobile Devices

If your custom text or styles are not visible on mobile:

* Refresh the page in both **Upcart Editor** and your mobile browser to clear cached versions.
* Ensure the latest published cart version is active.
* Confirm that CSS is saved on the **Custom CSS** tab in **Upcart > Cart Editor > Settings**.

## Discrepancies Between Editor and Live Store

Styles showing correctly in the editor but not on the live site may need increased selector specificity or `!important` added to key rules.

```
.upcart-cart .upcart-checkout-button { font-size: 18px !important; background: blue !important; color: white !important; }
```

## Incorrect CSS Selector Usage

Verify that the correct class or ID is being targeted. Always include prefixes like `.upcart-` for Upcart-specific elements to avoid unintended results. If the style does not apply as expected, ensure that the selector `.thank-you-message` is accurately targeting the intended HTML element and check that the CSS code is placed on the correct tab (Upcart > Cart Editor > Settings > Custom CSS).

***

Support for Customizations:

Upcart Support cannot assist with implementing or debugging custom CSS. For advanced styling help, we recommend working with a Shopify Expert. For troubleshooting custom CSS, refer to the common problems section for guidance on resolving issues such as missing styles on mobile devices, discrepancies between editor previews and live storefronts, and selector misplacement.


# Custom HTML
Source: https://docs.aftersell.com/upcart/custom_html

Add custom HTML or JavaScript to your cart using the built-in HTML editor.

The **Custom HTML** section in Upcart allows you to insert custom code into various parts of the cart drawer.\
You can also write JavaScript using `<script>` tags, and interact with the cart using Upcart's [Public API](https://rokt.notion.site/upcart-public-api) (e.g., `upcartOnCartLoaded (deprecated — use upcartSubscribeCartLoaded for new scripts)`).

## **Where to Find It**

Go to: **Cart Editor > Settings > Custom HTML**

## **How It Works**

The **HTML Location** dropdown lets you choose where the code will appear inside the cart layout. Based on your selection, the code will be injected into the corresponding cart area.

You can use this to add:

* Custom messages
* Trust text
* App integrations
* Analytics snippets
* Styling hooks
* Promotional content, such as banners with personalized offers or discounts
* Product guarantees that build customer confidence

## **Dynamic Tokens**

You can use the following token inside any Custom HTML field to inject live cart data:

| Token                 | What it renders                                               |
| --------------------- | ------------------------------------------------------------- |
| `{{UPCART_SUBTOTAL}}` | The current cart subtotal, formatted in your store's currency |

**Example:**

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<p>Your current total: <strong>{{UPCART_SUBTOTAL}}</strong></p>
```

This token works in all HTML location fields except **Scripts (Before Load)**, where you should use the JavaScript API instead. This is the only dynamic token available in Custom HTML fields.

## **Available HTML Locations**

|                                        |                                                                                                                        |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Location                               | Description                                                                                                            |
| **Above announcements/rewards**        | Top of the cart, below the cart header.                                                                                |
| **Below header/announcements/rewards** | Immediately under any announcements or reward bars.                                                                    |
| **Between each line item**             | Injected under every product in the cart.                                                                              |
| **Below cart items**                   | Directly beneath the cart line items, above the bottom modules.                                                        |
| **Above footer/add-ons**               | Below cart items and upsells, above add-ons.                                                                           |
| **Above checkout button**              | Inside the footer, directly above the checkout button and subtotal.                                                    |
| **Below checkout button**              | Inside the footer, directly below the checkout button.                                                                 |
| **Bottom of cart**                     | At the very bottom of the drawer (outside footer).                                                                     |
| **On empty cart screen**               | Displayed beside the “Your cart is empty” text.                                                                        |
| **Scripts (Before Load)**              | Invisible area to run JavaScript **before** the cart loads. Ideal for tracking, conditional logic, or custom behavior. |

## **Custom CSS (Optional)**

You can style your HTML using the **Custom CSS** editor found under:\
**Upcart > Cart Editor > Settings > Custom CSS**

For example, to adjust empty cart alignment:

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
[class*="styles_CartPreview__empty__"] { flex-direction: column; } [class*="styles_CartPreview__empty__"] h3 { margin: unset; }
```


# Customize currency formatting in Upcart
Source: https://docs.aftersell.com/upcart/customize_currency_formatting_in_upcart

Control how currency is displayed in your cart using Shopify Markets and custom script settings.

# Overview

This customization lets you change how currency symbols and codes appear in your Upcart cart drawer. You can control whether to show the currency symbol (for example `$`), the currency code (for example `USD`), where they appear, and how they are spaced.

This setup requires that:

* Your store is using **Shopify Markets**, or
* You are working with a **single market**

***

## Where to add the script

1. Go to **Upcart > Cart Editor > Settings > Custom HTML**
2. From the **Select HTML Location** dropdown, choose **Scripts (Before load)**
3. Paste the script below into the input field
4. Save your changes

***

## Currency formatting script

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<!-- Upcart Currency Formatting Script -->
<script>
// ~~~~~~START OF MERCHANT SETTINGS~~~~~~
let useCurrencySymbol = true;
let useCurrencyCode = true;
let currencySymbolPlacement = 'left';     // 'left' or 'right'
let currencyCodePlacement = 'right';      // 'left' or 'right'
let currencySymbolSpacing = false;
let currencyCodeSpacing = true;
let currencyFormat = "{{amount}}";        // Use Shopify's currency format
// ~~~~~~END OF MERCHANT SETTINGS~~~~~~

formatCurrency();

function formatCurrency() {
  let currencyMap = fillCurrencyMap(new Map());
  let currencyCode = Shopify.currency.active;
  let currencySymbol = currencyMap.get(currencyCode);

  if (currencySymbolPlacement == 'left' && currencyCodePlacement == 'left') {
    window.upcartMoneyFormat =
      (useCurrencyCode ? currencyCode : "") +
      (currencyCodeSpacing && useCurrencyCode ? " " : "") +
      (useCurrencySymbol ? currencySymbol : "") +
      (currencySymbolSpacing && useCurrencySymbol ? " " : "") +
      currencyFormat;

  } else if (currencySymbolPlacement == 'left' && currencyCodePlacement == 'right') {
    window.upcartMoneyFormat =
      (useCurrencySymbol ? currencySymbol : "") +
      (currencySymbolSpacing && useCurrencySymbol ? " " : "") +
      currencyFormat +
      (currencyCodeSpacing && useCurrencyCode ? " " : "") +
      (useCurrencyCode ? currencyCode : "");

  } else if (currencySymbolPlacement == 'right' && currencyCodePlacement == 'right') {
    window.upcartMoneyFormat =
      currencyFormat +
      (currencyCodeSpacing && useCurrencyCode ? " " : "") +
      (useCurrencyCode ? currencyCode : "") +
      (currencySymbolSpacing && useCurrencySymbol ? " " : "") +
      (useCurrencySymbol ? currencySymbol : "");

  } else if (currencySymbolPlacement == 'right' && currencyCodePlacement == 'left') {
    window.upcartMoneyFormat =
      (useCurrencyCode ? currencyCode : "") +
      (currencyCodeSpacing && useCurrencyCode ? " " : "") +
      currencyFormat +
      (currencySymbolSpacing && useCurrencySymbol ? " " : "") +
      (useCurrencySymbol ? currencySymbol : "");

  } else {
    console.warn("Unexpected placement configuration. Falling back to default.");
    window.upcartMoneyFormat =
      (useCurrencySymbol ? currencySymbol : "") +
      (currencySymbolSpacing && useCurrencySymbol ? " " : "") +
      currencyFormat +
      (currencyCodeSpacing && useCurrencyCode ? " " : "") +
      (useCurrencyCode ? currencyCode : "");
  }
}

function fillCurrencyMap(map) {
  map.set('EUR', '€');
  map.set('GBP', '£');
  map.set('JPY', '¥');
  map.set('AUD', '$');
  map.set('CAD', '$');
  map.set('CHF', 'CHF');
  map.set('CNY', '¥');
  map.set('INR', '₹');
  map.set('RUB', '₽');
  map.set('BRL', 'R$');
  map.set('ZAR', 'R');
  map.set('MXN', '$');
  map.set('SGD', '$');
  map.set('NZD', '$');
  map.set('HKD', 'HK$');
  return map;
}
</script>
```

***

## Settings explained

Inside the script, look for this section:

```
// ~~~~~~START OF MERCHANT SETTINGS~~~~~~
```

You can adjust these values to control how currency appears in the cart:

|                             |                                                             |                                                                                    |
| --------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Setting                     | Description                                                 | Options                                                                            |
| **useCurrencySymbol**       | Show or hide the currency symbol (example: `$`)             | `true` / `false`                                                                   |
| **useCurrencyCode**         | Show or hide the currency code (example: `USD`)             | `true` / `false`                                                                   |
| **currencySymbolPlacement** | Where the symbol appears                                    | `'left'` / `'right'`                                                               |
| **currencyCodePlacement**   | Where the code appears                                      | `'left'` / `'right'`                                                               |
| **currencySymbolSpacing**   | Adds a space between symbol and amount (example: `$ 10.00`) | `true` / `false`                                                                   |
| **currencyCodeSpacing**     | Adds a space between code and amount (example: `10 USD`)    | `true` / `false`                                                                   |
| **currencyFormat**          | Controls number formatting                                  | `{{amount}}`, `{{amount_no_decimals}}`, etc. (refer to Shopify's currency options) |

***

## Final result

Once the script is added and saved:

* Currency symbols and codes display exactly as configured
* Works across all parts of the Upcart drawer, including rewards and upsells
* Adapts to **Shopify Markets** automatically if they are enabled

***

## Need help?

For advanced customization, we recommend working with a **Shopify Expert**. Upcart's support team does not assist with writing or troubleshooting custom code.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Customizing the color of product savings text (save XXX) in Upcart
Source: https://docs.aftersell.com/upcart/customizing_the_color_of_product_savings_text_save_xxx_in_upcart

This article outlines how to customize the visibility of your Upcart's savings row by hiding discount elements for a cleaner design.

# **Overview**

This guide is designed for merchants using Upcart who want to change the color of the text that says 'Save \$XXX' beneath the products in the cart. Changing the color allows you to design your cart with your own branding in mind.

<Note>
  **Try the built-in setting first.** The Cart Editor has a **Savings text color** picker under **Design > Colors** that sets exactly this colour, on both module versions, with no code. Only reach for CSS when you need something the picker can't express — a gradient, per-product colours, or overriding the picker on one surface.
</Note>

By using a bit of CSS and some basic coding knowledge, you can easily add this functionality to your store. These customization options are perfect for store owners or developers with a little bit of CSS experience.

## Example

Here is what the cart will look after changing the color of the savings text:

<img alt="Upcart cart drawer with the product Save 2.00 dollar savings text shown in red" />

***

# Accessing Custom CSS Settings

To begin customizing the CSS for your Upcart, follow these steps:

1. Open the **Upcart App**.
2. Click on **Cart Editor**.
3. Open **Settings** and select the **Custom CSS** tab (behind **More settings** if the tab row overflows).

***

# Applying Custom CSS

Once you are in the Custom CSS section, you can change the color of the product savings text by following these steps:

1. Locate the CSS input area.
2. Copy and paste the following code into the CSS input area:

**If you are on Version 1, use this code:**

```
.upcart-product-savings {  
   color: red !important;  
}
```

**If you are on Version 2, use this code:**

```
.upcart-public-component-product-tile__savings {  
   color: red !important;  
}
```

### Choosing a Color format

You can replace `red` with any color of your choice using three different ways.

For example:

* **Named Color**: `green`
* **RGB**: `rgb(0,128,0)`
* **Hex Code**: `#008000`

***

## Still Need Help?

If you need any assistance with customizations, we recommend consulting with a Shopify Expert about adding HTML, CSS, and even JavaScript to your cart drawer.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Disable fixed footer
Source: https://docs.aftersell.com/upcart/disable_fixed_footer

Choose whether the cart footer stays pinned or scrolls with the cart content

# Overview

This setting controls whether the footer, including the checkout button, remains **fixed at the bottom** of the cart drawer or scrolls away with the list of cart items.

You'll find the **Disable fixed footer** checkbox in the Upcart Cart Editor, under **Settings > Cart settings**.

<img alt="Upcart Cart settings with the Disable fixed footer checkbox highlighted and checked" />

# **How It Works**

## Unchecked (Default Behavior, Sticky Footer Enabled)

* The footer **stays pinned** to the bottom of the cart.
* The **checkout button is always visible**, even when scrolling through a long list of items.
* Ideal for improving conversion and reducing friction.

## Checked (Sticky Footer Disabled)

* The footer **scrolls with the cart**.
* If there are many items, the checkout button may move off-screen.
* Useful for stores with very tall or scroll-heavy layouts.

## **Best Practice**

We recommend keeping the sticky footer **enabled** so the checkout button remains easily accessible at all times. However, feel free to test both modes to find what works best for your design.


# Disable quantity selector and product page links for reward / free items
Source: https://docs.aftersell.com/upcart/disable_quantity_selector_and_product_page_links_for_reward_free_items

Disable the quantity selectors and product page links for rewards/free items in Upcart, ensuring users cannot exploit your free rewards.

<Note>
  **Check whether you need this at all.** On **both** module versions, Upcart already hides the quantity selector on its own reward items, and already suppresses the reward's product-page link unless you've turned on **Allow reward product page access from cart** in the Rewards module (it's off by default).

  So reach for the script below only for free items Upcart didn't grant — a gift added by another app or by your own code, which Upcart doesn't recognise as a reward.

  **The script's selectors are Version 1 only.** `.upcart-product-item` and the `.upcart-product-*` CSS below belong to the V1 cart items module. On **Version 2**, target the public product-tile classes instead — `.upcart-public-component-product-tile__quantity-selector`, `__quantity-minus`, `__quantity-plus` and `__product-title` — see the [V2 CSS selector library](/upcart/upcart_css_selector_library_v2).
</Note>

# Overview

This guide is intended for Upcart merchants looking to eliminate quantity selectors and product page links for free and reward items. Making this adjustment protects your reward strategy and helps prevent misuse of your rewards offerings.

## Example

Here is what the cart will look like *after* disabling the quantity selector and product page links:

<img alt="Cart with a free gift snowboard that has no quantity selector beside a paid snowboard" />

***

# Accessing Custom CSS and HTML Settings

To begin customizing the CSS and HTML for your Upcart, follow these steps:

1. Open the **Upcart App**.
2. Click on **Cart Editor**.
3. Click on **Settings** and select the **"Custom HTML"** tab and then the **"Custom CSS"** tab

***

# CSS and HTML Code Changes

## CSS

**Copy and paste the code below into the Custom CSS section. Save and add the HTML below.**

```
.free-item-disable-qty .upcart-product-quantity-input,  
.free-item-disable-qty .upcart-product-quantity-minus,  
.free-item-disable-qty .upcart-product-quantity-plus {  
    pointer-events: none !important;  
    cursor: not-allowed;  
    opacity: 0.5;  
}  
  
.free-item-disable-qty .upcart-product-title,  
.free-item-disable-qty .upcart-product-image-wrapper {   
    pointer-events: none !important;   
}
```

***

## HTML Scripts (Before load)

**Copy and paste the code below into the Custom HTML dropdown for *Scripts (Before load)*. Save.**

```
<script>  
  function upcartDisableQtyOnFreeItems(cart) {  
    const freeItems = cart.items.filter((item) => item.finalLinePrice === 0);  
    for (const item of freeItems) {  
      const cartRow = window.upcartDocumentOrShadowRoot.querySelector(`[id="${item.key}"].upcart-product-item`);  
      cartRow?.classList.add('free-item-disable-qty');  
      console.log("Free item disabled")  
    }  
  }  
  
  window.upcartSubscribeCartLoaded((event) => upcartDisableQtyOnFreeItems(event.cart));  
  window.upcartSubscribeCartUpdated((event) => upcartDisableQtyOnFreeItems(event.cart));  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnCartLoaded` and `window.upcartOnCartUpdated` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeCartLoaded` and `upcartSubscribeCartUpdated` for all new scripts.
</Note>

***

## 🚧 Support for Customizations

Upcart's support team cannot assist with implementing custom CSS or HTML solutions in your cart.

If you need help designing or styling something custom, we recommend consulting a Shopify Expert:

[See Shopify Experts](https://www.shopify.com/partners/directory)

##

##


# Discount codes module
Source: https://docs.aftersell.com/upcart/discount_codes_module

This article outlines how to add an option for customers to manually enter a discount code within Upcart.

The discount codes module adds a discount code entry box to your cart, allowing customers to manually enter a code and apply it to their order.

# Discount Input Placeholder

This is the text that displays in the discount code entry field before your customer types into it. This is generally used to let your customer know what this text field is for.

<img alt="Discount code entry field with placeholder text highlighted beside the Apply button" />

# Discount Apply Button Text

This is the text that shows on the button next to the discount code.

<img alt="Discount code field with the Apply button highlighted" />

***

## **🚧 Discount limitations**

Upcart is not able to support all discount functionality available in checkout.

* **Multiple discount codes are not supported.**\
  Multiple automatic discounts can be used at a time, but there can only be one manual discount code. Customers must go to checkout to apply multiple manual discount codes.
* **Free shipping discounts are not supported.**\
  Customers must go to checkout to apply free shipping discounts.
* **Shopify Plus stores using checkout.liquid are not supported.**\
  Shopify Plus stores using checkout extensibility are supported. The discount codes module will be hidden on the real storefront if your store is using checkout.liquid.

Please make sure to review if these are applicable to your store.

These are the same three limitations shown in the **Discount limitations** banner inside the module, behind **Show more**.

***

# Custom templates

On version 2.0 of the Discount codes module, a **Custom template** code editor appears below the settings with two templates: **Full** (the whole module) and **Skeleton** (what renders while the module is loading). Tick **Access custom templates** under **Settings > Cart settings > Advanced Settings** in the Cart Editor first. See [Setting up a custom template](/upcart/setting_up_a_custom_template_in_upcart).


# Discounts
Source: https://docs.aftersell.com/upcart/discounts



The Discounts feature lets you build flexible reward rules that automatically apply discounts, gifts, or free shipping when specific cart conditions are met. It is designed to help boost conversion and average order value with real-time, personalized rewards.

<Note>
  Discounts are the renamed version of what was previously called Triggered Rewards. All existing Triggered Rewards have been migrated automatically. The functionality is identical, just managed from a new top-level section in the app.
</Note>

Discounts operate through Shopify's native discount system, meaning they apply at checkout regardless of whether the Upcart cart drawer is active or visible on your storefront.

<Warning>
  Discounts are not the same as the Discount Codes module or upsell discounts. These are separate features.
</Warning>

**Discounts vs. Tiered Rewards**

Not sure which to use? Here is the key difference:

* **Tiered Rewards** guide customers toward milestones using a visible progress bar in the cart.
* **Discounts** activate automatically based on specific cart conditions, with no additional visual elements required.

Use Discounts when you want rule-based promotions that fire silently in the background. Use Tiered Rewards when you want customers to see their progress toward a reward.

***

## How to Access Discounts

There are three ways to access the Discounts module:

* **From the Upcart homepage** - The Discounts section is visible on the homepage. Click **Manage all discounts** to open the module.

<img alt="Upcart homepage Discounts section card with the Manage all discounts button" />

* **From the Upcart sidebar** - Go to **Upcart Cart Drawer > Discounts** in the left sidebar.

<img alt="Upcart left sidebar with Discounts highlighted under the Cart Drawer menu" />

* **From the Cart Editor** - Click **Edit Cart**, then find the **Discounts** module in the Body section and click **Manage all discounts**.

<img alt="Upcart Cart Editor Discounts module with Manage all discounts highlighted next to a cart preview" />

From the Discounts page you will see two sections:

* **Live discounts** - rules that are currently active and applying to qualifying carts
* **Draft discounts** - rules that have been created but not yet published

<img alt="Discounts page listing Live discounts and Draft discounts in two tables" />

***

## How Discounts Work

Each discount rule is made up of:

* One or more **trigger conditions** that must all be met for the reward to activate
* A **reward type** that is automatically applied when conditions are met

When your customer's cart meets all the conditions in a rule, the discount is applied through Shopify's discount system and reflected at checkout.

**Example use cases:**

* "Get 10% off when you add a snowboard and spend \$500+"
* "Get a free gift when you subscribe to any product"
* "Free shipping for logged-in customers"

***

## Creating a Discount Rule

Click **Create discount** from the Discounts page. Each rule has three sections to configure.

<img alt="Create a discount page with Overall, Triggers, and Reward sections" />

### Overall

* **Title** - Internal label for the rule (up to 50 characters). This also appears in your custom template if you are using one to display discounts on your storefront.
* **Discount Code** - Required field (up to 25 characters). You cannot **Publish** or **Save draft** without it. This is the title/label of the Shopify automatic app discount that Upcart creates, not a code shoppers type at checkout. Rules always fire from the cart conditions (triggers), never from a customer entering a code.
* **Description** - Customer-facing explanation of the rule (for example, "Spend \$50 or more to unlock free shipping on your order").

### Triggers

Add up to 2 trigger conditions. All conditions use AND logic - both must be true for the reward to activate. See the [Trigger Conditions](#trigger-conditions) section below for a full breakdown of available triggers.

### Reward

Select the reward type to apply when conditions are met. See the [Reward Types](#reward-types) section below for a full breakdown of available rewards.

Once configured, click **Publish & exit** to make the rule live immediately, or **Save draft** to save it without activating.

***

## Trigger Conditions

Each rule can contain up to **2 triggers**. All conditions use **AND logic** - both must be true for the reward to activate.

<AccordionGroup>
  <Accordion title="Specific Products">
    Triggers when any selected product or variant is in the cart.

    * Supports full products or specific variants
    * Multiple selections use OR logic
    * Up to **20 variants** per trigger
    * Set a minimum quantity match (defaults to 1)

    Use this for "Add iPhone 15 Pro" or "Add any featured item" style triggers.
  </Accordion>

  <Accordion title="Specific Collections">
    Triggers when any cart item belongs to a selected collection.

    * Supports multiple collections, up to **20** per trigger
    * OR logic across collections
    * Set a minimum quantity match (defaults to 1)

    Ideal for collection-based promotions like "Buy from Winter Sale."
  </Accordion>

  <Accordion title="Cart total">
    Triggers when the pre-discount cart total meets a set dollar amount. The threshold is calculated before any discounts (including other discount rules) are applied.

    <Note>
      This trigger only supports your store's main currency. It does not perform automatic currency conversion for international markets. Thresholds are always evaluated in your store's base currency regardless of the customer's checkout currency.
    </Note>

    Great for rewards like "Spend \$100, get a free gift."
  </Accordion>

  <Accordion title="Cart quantity">
    Triggers when the total number of items (not unique SKUs) in the cart reaches a set number. For example, 2 of one product and 1 of another equals 3 total items.

    Perfect for promotions like "Buy 4 or more items, get 20% off."
  </Accordion>

  <Accordion title="Subscription">
    Triggers when the cart includes any item with a subscription (checks for a Shopify selling plan ID).

    Useful for rewards like "Free shipping with any subscription" or "Free gift for subscribers."
  </Accordion>

  <Accordion title="Customer is logged in">
    Triggers when the customer is logged in. Supports both email/password and social login.

    Great for member-only rewards or loyalty perks.
  </Accordion>
</AccordionGroup>

***

## Reward Types

Once your trigger conditions are met, one of the following rewards is automatically applied.

<AccordionGroup>
  <Accordion title="Cart Discount">
    Applies a discount to the entire cart. Supports:

    * Percentage discounts (e.g. 20% off)
    * Fixed dollar discounts (e.g. \$5 off)

    Maximum: 100% or \$9,999.99 per rule.
  </Accordion>

  <Accordion title="Free Gift">
    Automatically adds a specific product to the cart at 100% off when conditions are met.

    Requirements:

    * The gift product must be **Active** or **Unlisted** and available through your Online Store (not **Draft** or **Archived**)
    * The product must be in stock
    * The discount applies only to the exact product or variant selected

    <Note>
      If the customer removes the free gift from their cart, the discount is also removed.
    </Note>
  </Accordion>

  <Accordion title="Free Shipping">
    Removes the shipping cost by discounting the cheapest available shipping method to \$0. No additional configuration needed.
  </Accordion>
</AccordionGroup>

***

## Discount Combinations

Discount combinations control how Upcart discounts stack with other discounts at checkout. They are set on the **Discounts** page, below the Live and Draft tables — **not** on an individual rule.

<Warning>
  This is a single, store-wide setting. Upcart creates one Shopify automatic app discount for your store and these checkboxes configure that one discount, so whatever you choose here applies to **every** Upcart discount rule at once. You cannot allow one rule to combine with order discounts and block another from doing so.
</Warning>

All three are **off** by default. The available combination types are:

* **Product discounts** - Applies alongside other product-level discounts for different items. If two discounts target the same product, only the best discount applies.
* **Order discounts** - Applies with order-level discounts. Product discounts are applied first, then order-level discounts on the subtotal.
* **Shipping discounts** - Applies together with free shipping or other shipping-level discounts to get the largest eligible shipping discount.

<img alt="Discount combinations options with Product, Order, and Shipping discounts checked" />

***

## Managing Your Discount Rules

Each rule in the Live and Draft tables has a **Publish** / **Unpublish** button, and draft rules also have a **Delete** button.

<Warning>
  **Discount rules cannot be edited once created** — not after publishing, and not while they are still drafts. There is no edit screen. To change a rule, delete it and create a new one.
</Warning>

<Note>
  **Delete is only available on draft rules.** A live rule has no delete button — click **Unpublish** to move it to Drafts first, then delete it. Unpublishing on its own is the way to pause a rule without losing its configuration; it can be re-published at any time.
</Note>

***

## How Discounts Work with App Embed Status

Discounts are applied through Shopify's discount system, not through the Upcart cart drawer. This means:

* **Discounts remain active even when the Upcart app embed is turned off.** Turning off the app embed only hides the cart drawer from your storefront. It does not disable your discount rules.
* **Discounts apply at checkout.** Your customers will see the discount reflected when they reach checkout, regardless of whether the Upcart cart drawer is visible on the page.

To fully stop a discount from applying, click **Unpublish** on the individual rule to move it to Drafts. If you want it gone entirely, delete it from the Drafts table afterwards — a live rule cannot be deleted directly.

***

## Storefront Display

The Upcart cart drawer dynamically updates as conditions are met. Rewards appear instantly based on real-time evaluation of the cart.

By default, the cart shows active discount rules using a default display template, showing the rule title and description for each active rule. Discounts are also visible at Shopify checkout where the applied discount amount is reflected.

For full control over the layout, the module supports [**custom templates**](/upcart/setting_up_a_custom_template_in_upcart) using React-based code. To use them, first tick **Access custom templates** under **Settings > Cart settings > Advanced Settings** in the Cart Editor — the setting requires version 2.0 of the module. Once enabled, the Custom Template section appears within the Discounts module. The available top-level props are: `rules`, `showSection`, and `onToggleSection`. Each item within `rules` has its own `id`, `title`, and `description` fields.

<Note>
  Custom template development requires React knowledge. Aftersell supports built-in features but does not provide assistance with custom coding.
</Note>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="If I have no live cart but an active discount, does the discount still apply?">
    Yes. Discounts operate through Shopify's discount engine independently of the Upcart cart. As long as the discount rule is published, it will apply to qualifying orders even if there is no Upcart cart published on your storefront.
  </Accordion>

  <Accordion title="Does turning off the Upcart app embed disable my discounts?">
    No. Turning off the app embed only hides the Upcart cart drawer from your storefront. Active discount rules will continue to apply at checkout.
  </Accordion>

  <Accordion title="Can I edit a discount rule after it has been created?">
    No, and this applies to drafts too — there is no edit screen for a discount rule at any point after it is created. To change one, delete it and create a replacement.
  </Accordion>

  <Accordion title="Can I temporarily pause a discount without deleting it?">
    Yes. Click **Unpublish** to move the rule to Drafts. This pauses it without deleting the configuration and it can be re-published at any time.
  </Accordion>

  <Accordion title="Why is there no Delete button on my live discount?">
    Delete is only offered on draft rules. Click **Unpublish** first to move the rule to Drafts, then delete it from there.
  </Accordion>

  <Accordion title="Can I use a promo code with a discount rule?">
    No. Each rule has a required Discount Code field (up to 25 characters), but this is the title/label of the Shopify automatic app discount that gets created, not a code shoppers type at checkout. Rules always fire from the cart conditions (triggers), never from a customer entering a code.
  </Accordion>

  <Accordion title="The Cart Total Threshold trigger is not working for my international customers. Why?">
    The Cart Total Threshold trigger only supports your store's main currency. It does not perform automatic currency conversion for international markets. Thresholds are always evaluated in your store's base currency regardless of the customer's checkout currency.
  </Accordion>

  <Accordion title="My free gift is not appearing. Why?">
    The most common causes are:

    * The gift product is set to **Draft** or **Archived**, or is not available through your Online Store
    * The product is out of stock
    * The trigger conditions are not actually being met

    Check all three before reaching out to support.
  </Accordion>

  <Accordion title="If a customer removes the free gift from their cart, does the discount still apply?">
    No. The free gift discount is tied to the presence of the gift product in the cart. If the customer removes it, the discount is also removed.
  </Accordion>

  <Accordion title="Can discounts be stacked or combined with other discount apps?">
    Discounts go through Shopify's native discount system. Compatibility with third-party discount apps depends on those apps and Shopify's stacking rules. If you notice unexpected discount behavior, check for conflicts with other installed discount apps.
  </Accordion>

  <Accordion title="What is the difference between Discounts and Triggered Rewards?">
    They are the same feature. Discounts is the renamed version of Triggered Rewards, now surfaced as a top-level section in the app for clarity. All existing Triggered Rewards have been migrated automatically and the functionality is identical.
  </Accordion>
</AccordionGroup>

***

## Tips

* **All triggers must be true.** If your rule has two trigger conditions, both must be met before the reward activates.
* **Free gifts must remain in the cart.** If your customer removes the gift product, the discount is removed too.
* **Avoid duplicate rewards.** If you use both Tiered Rewards and Discounts, make sure they offer distinct benefits to avoid confusion or unintended stacking.
* **Get the rule right before you publish.** Rules cannot be edited after creation, so it is worth reading the triggers and reward back once before saving.
* **Consider renaming the checkout button to "Review Order"** if you are using complex discount rules, so customers have a chance to review their cart before completing the purchase.

***

**Need help?**

If you have questions about setting up or managing your discount rules, our support team is here to help. Reach out anytime through the in-app chat.


# Enhanced Ajax API compatibility
Source: https://docs.aftersell.com/upcart/enhanced_ajax_api_compatibility

Allow third-party apps and custom scripts to take control of the Add to Cart process.

# Overview

This setting does two things:

1. **Queues Shopify Ajax cart calls.** When several scripts hit Shopify's Ajax cart API (`/cart/add`, `/cart/add.js`, `/cart/update.js`, `/cart/change.js`) at the same time, Shopify sometimes drops one of the changes. Upcart forces those calls to run one at a time so every update registers. This is the setting's main purpose.
2. **Steps back from Add to Cart.** It also disables Upcart's built-in Add to Cart handling, so an app or theme that needs full control of that flow doesn't conflict with it.

Both behaviours are tied to the one checkbox — you can't enable the request queueing without also giving up Upcart's Add to Cart handling.

## Where to Find It

Open the cart editor, go to **Settings > Cart settings**, and expand **Advanced Settings**.\
Look for **"Enhanced Ajax API compatibility."**

## How It Works

### Disabled (Recommended)

Upcart maintains full control over the Add to Cart process. This ensures consistent behavior and allows Upcart to prevent other apps or scripts from overriding the cart flow.

This is the **recommended setting for most stores**. Keep this disabled unless you are experiencing specific issues where Upcart is not intercepting add-to-cart events from your theme or other apps.

### Enabled

Upcart will no longer manage the Add to Cart process. This allows other apps, custom JavaScript, or your theme to modify the cart without interference.

**Enable this setting ONLY when:**

* Your store uses a non-standard AJAX cart API
* Upcart is not intercepting add-to-cart events from your theme or other apps
* You need third-party apps to have direct control over cart behavior

**Important trade-offs when enabled:**

* Other apps can redirect customers to the Shopify cart page instead of opening the Upcart drawer
* You may experience redirect loops or unexpected cart behavior
* Upcart cannot prevent external apps from altering cart behavior

**If enabling causes redirect loops:**

1. Disable this setting
2. Use the manual Upcart API (`upcartRegisterAddToCart`) instead
3. See integration guides for specific apps (e.g., [Replo](/upcart/upcart_x_replo_landing_page_builder))

## Testing

After changing this setting:

1. Click **Save**
2. Test adding products to your cart
3. Verify the Upcart drawer opens correctly
4. Check that you're not redirected to the Shopify cart page

If you experience issues after enabling, disable the setting and contact support for alternative solutions.


# Exclude a reward tier from a specific market
Source: https://docs.aftersell.com/upcart/exclude_a_reward_tier_from_a_specific_market

Use Shopify’s Translate & Adapt app to hide a reward tier for customers in specific regions.

# Overview

Upcart does not natively support market-specific reward tier visibility. However, you can apply a practical workaround by combining the Translate & Adapt app with Upcart’s reward settings.

The process involves temporarily adjusting your rewards, capturing the version needed for each market, and then saving it through Shopify’s localization system.

***

## Step 1: Set up your default rewards

In your Rewards module, create all tiers as usual. For example:

* **Tier 1**: 20% discount at \$100
* **Tier 2**: Free shipping at \$200

Save and publish the rewards so the default version (e.g. for Canada or global markets) includes all tiers.

## Step 2: Prepare your localized version

Decide which market you want to exclude the tier from. For example, to remove **free shipping for Mexico**:

* Open the **Translate & Adapt** app in Shopify
* Select the market (e.g. Mexico) and the language (e.g. English)
* Search for **store metadata**
* Locate the reward tiers under the metafield `upcartEditorSettings.rewardsTiers`

This will display the raw JSON configuration of your live rewards setup.

## Step 3: Remove the tier in Upcart

1. Temporarily remove the tier you want to exclude from your rewards configuration inside the Upcart Cart Editor.

   * For example, remove **Tier 2 (Free Shipping)** and leave only **Tier 1 (20% off)**.
2. Save your changes. Then return to the Translate & Adapt app and refresh the metadata panel. It should now show the updated version with only one reward tier.
3. Copy the updated JSON code and paste it into the translation field for that market and language.

   * You may need to make a minor edit (such as changing a punctuation mark in the reward text) to allow the translation to save.
4. Save the translation.

## Step 4: Re-add the reward tier globally

Return to Upcart and re-add the previously removed tier (e.g. Free Shipping at \$200). Save your changes again.

* This re-establishes your full global reward configuration while preserving the version without the second tier for the excluded market.

## Step 5: Confirm it’s working

Preview your storefront using Shopify’s market selector or a VPN to view from the excluded market (e.g. Mexico). You should only see the first reward tier.

Switch back to your default market (e.g. Canada) to confirm that both tiers appear.

Repeat this process for other languages within the same market if needed.

***

## Optional: Translate the reward text

In the same Translate & Adapt section, you can localize reward copy for each market and language.

For example:

* English: "You're \$20 away from a 20% discount."
* French (Mexico): "Il vous reste 20 \$ avant de recevoir une réduction de 20 %."

## Notes

* This approach works because Translate & Adapt stores localized versions of metafields based on what was active at the time.
* If you add new tiers later, the localized market will still display the version originally saved, unless you manually update it.
* This makes the method useful for short-term or market-specific promotions, but it should be applied with caution. Always test your changes using Shopify’s market preview tools or by viewing the store in an incognito window.

##


# Exclude certain products from Upcart upsells (AI recommendations & manual)
Source: https://docs.aftersell.com/upcart/exclude_certain_products_from_upcart_upsells_ai_recommendations_manual

Use custom JavaScript to exclude specific products from AI-recommended or manual upsells.

# **Overview**

This guide shows how to prevent specific products (e.g. warranties, shipping protection, low-priority items) from appearing in your upsells by excluding them based on **Product ID**, **Product Handle**, or **Product Tags**.

You can add this code in **Upcart > Editor > Settings > Custom HTML**, in locations such as **Above announcements/rewards**.

## Exclude by product ID

To find a product ID:

* Go to **Shopify Admin > Products**
* Open the product and copy the long numeric ID from the URL (after `/products/`)

Example:

```
<script>  
  window.upcartModifyListOfUpsells = (upsells) => {  
    var productIDsToExclude = [  
      6958755512477,  
      6958755610781  
    ];  
  
    return upsells.filter(item =>   
      !productIDsToExclude.includes(item.id)  
    );  
  };  
</script>
```

## Exclude by product handle

To find a product handle:

* In **Shopify Admin > Products**, open the product
* Scroll to **Search engine listing preview** > **Edit**
* The handle is the last part of the product URL (e.g. `ocean-blue-shirt`)

Place this script in the **Above announcements/rewards** HTML location:

```
<script>  
  window.upcartModifyListOfUpsells = (upsells) => {  
    var productHandlesToExclude = [  
      "ocean-blue-shirt",  
      "yellow-wool-jumper"  
    ];  
  
    return upsells.filter(item =>   
      !productHandlesToExclude.includes(item.handle)  
    );  
  };  
</script>
```

## Exclude by product tags

To add or find tags:

* Go to **Shopify Admin > Products**
* Open a product and scroll to the **Tags** section
* Tags are case-sensitive

Adding collection product tags in bulk:

* Go to **Shopify Admin > Products**
* Click **Search and Filter (F) > Add Filter > Collection**
* Select the collection of the items you want to exclude
* Select all items (top left checkbox)
* Click **more** button **(...)** > **Add Tags**
* Select or type in the tag to apply it to all items in the collection

Example script:

```
<script>  
  window.upcartModifyListOfUpsells = (upsells) => {  
    var productTagsToExclude = [  
      "Exclude From UpCart Upsells"  
    ];  
  
    return upsells.filter(item =>   
      !item.tags.some(tag =>   
        productTagsToExclude.includes(tag)  
      )  
    );  
  };  
</script>
```

## Best practices

* Tags must match exactly, including capitalization
* If you're filtering upsells in multiple locations (e.g. AI and manual), paste the code in both HTML sections
* Always test your implementation using **Sandbox Mode** before going live

## Need help?

For help writing or debugging advanced customizations, we recommend reaching out to a Shopify Expert. Upcart support does not assist with custom JavaScript, HTML, or CSS implementations.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Express payments module
Source: https://docs.aftersell.com/upcart/express_payments_module

Display accelerated checkout buttons below the main checkout button in the Upcart drawer.

# Overview

This feature allows you to show Shopify’s Express Payment options (such as Shop Pay, Apple Pay, or Google Pay) for a faster checkout experience using the buyer’s saved payment methods.

Express or accelerated checkout buttons help returning customers complete purchases faster by skipping manual entry of payment and shipping info. These buttons appear **below the main Checkout button** in the cart and are powered by Shopify.

Upcart supports these buttons visually and structurally, but **Shopify controls their behavior and visibility**.

📘 Learn more in [Shopify's documentation on accelerated checkouts](https://help.shopify.com/en/manual/payments/accelerated-checkouts) and [Shopify's release notes on accelerated checkout buttons](https://shopify.dev/changelog/developer-preview-accelerated-checkout-buttons-on-storefront-now-support-shopify-functions-bundles-and-have-improved-performance).

<img alt="Shop Pay, PayPal, and Google Pay express buttons below the Upcart checkout button" />

# **Getting Express Payments to Show**

To display accelerated checkout buttons inside Upcart, your Shopify theme must already include them on the storefront. You can do this by:

1. **Adding a snippet to your theme code**

   * Go to **Online Store > Themes > Edit Code**
   * Open the **layout/theme.liquid** file
   * Find the opening `<body>` tag (not `</body>`)
   * Below that tag, paste the following code:

     ```
     {% if additional_checkout_buttons %} <div style="display: none !important"> {{ content_for_additional_checkout_buttons }} </div> {% endif %}
     ```
2. Save the file

Here is an example of what it should look like:

<img alt="The additional checkout buttons Liquid snippet added below the body tag in theme.liquid" />

Once this is done, Upcart will be able to detect and render your express payment options.

💡 If you prefer not to edit code, reach out to your developer or a [Shopify Expert](https://experts.shopify.com).

# Payment gateways

The **Payment gateways** card belongs to the **legacy** Express Payments module — you only see it if your store is still on the older version. It lists the express gateways Upcart can show in the cart, and lets you turn each on or off and set the order they appear in. Six gateways are listed:

* Shop Pay
* PayPal
* Apple Pay
* Amazon Pay
* Meta Pay
* Google Pay — listed but marked **Coming Soon** and not selectable

Google Pay is held back deliberately: it doesn't refresh when the cart changes, so it would show a stale price to anyone who edits their cart before clicking it. The other five can be enabled and reordered — enabled gateways sit in an ordered list, use the up and down arrows beside each row to change the order, and disabled ones sit below where clicking adds them back.

<Note>
  Enabling a gateway here does not guarantee it shows. A gateway is hidden in the real cart if it is not enabled on your Shopify store, or if the shopper is not eligible for it — an Apple Pay button, for example, only shows on a supported device and browser. See [Shopify's accelerated checkouts documentation](https://help.shopify.com/en/manual/payments/accelerated-checkouts) for how to enable gateways and the eligibility rules for each.
</Note>

# Accelerated Checkout Buttons Design

Once your buttons are set up, you can customize how they appear inside Upcart.

## **Button Height**

* **Default button height** and **Mobile button height** are set separately, each from **25 px to 55 px**
* Each has a number field and a slider wired to the same value — use whichever is easier

## **Checkout Button Alignment**

* Choose how the express buttons are aligned:

  * **Left**
  * **Right**
  * **Center**
  * **Space Between**

## **Row Gap**

* Set the vertical spacing between stacked buttons, from **0 px to 40 px**

# **Advanced Display Options**

## **Hide Buyer Consent**

When enabled, this hides the buyer consent message usually displayed when a subscription product is in the cart. It can help reduce visual clutter if you already provide related information elsewhere.

## **Render Cart in Shadow DOM**

Enable this to prevent your Shopify theme’s CSS from interfering with Upcart’s styling.\
This ensures consistent design across all browsers and devices.

Enabling this also applies the same setting from **Settings > Cart settings > Advanced Settings**.

## **Theme Compatibility Notes**

* Shopify now enforces **strict styling rules** for Accelerated Checkout Buttons.
* Upcart’s new version fully supports these rules and will follow Shopify’s styling behavior.

⚠️ On the current module, a **Revert To Old Version** banner appears at the top with a **Revert To Legacy Express Payments** button. It is only needed for out-of-date themes — reverting drops you back to the pre-Shopify-styling behaviour, so leave it alone unless your theme genuinely requires it.

If you do revert, uncheck any saved styling options from the previous module so they do not interfere with the new version.


# Force re-render of custom HTML fields
Source: https://docs.aftersell.com/upcart/force_re_render_of_custom_html_fields

Refresh all Custom HTML elements whenever the cart updates.

# Overview

This setting makes Upcart rebuild the HTML you've added through the Custom HTML editor when the **cart total changes**. It's useful when dynamic content (like custom subtotals or counters) doesn't update correctly on its own.

<Note>
  The rebuild is keyed on the cart total, not on every cart change. A cart update that leaves the total the same — swapping to an equally-priced variant, editing the cart note — will not re-render your custom HTML. If your content has to track something other than price, update it from a `cart_updated` handler instead.
</Note>

## Where to Find It

Upcart > Cart Editor > Settings > Cart settings, then expand Advanced Settings\
Look for **"Force re-render of custom HTML fields."**

## How It Works

### Enabled

Upcart will re-render all Custom HTML elements every time the cart updates. This ensures that dynamic content stays in sync, but may slightly affect performance.

### Disabled

Custom HTML elements will only re-render when absolutely necessary. This provides better performance but may cause some elements to lag behind cart changes.


# Geolocation pricing for tiered rewards
Source: https://docs.aftersell.com/upcart/geolocation



## Geolocation Pricing

Set custom reward thresholds per country instead of relying on automatic currency conversion.

**Note:** This feature applies to the **Tiered Rewards** module only. It is not available for Discounts.

Geolocation Pricing lets you define custom reward minimum amounts for specific countries, giving you precise control over reward thresholds across international markets. This is useful when you want customers in different regions to qualify for rewards at locally appropriate amounts rather than relying on exchange rate conversions.

For example, you may want US customers to qualify at **\$75**, while customers in Japan need to reach **8,000 JPY** regardless of exchange rate fluctuations. This feature works best if your store uses Shopify Markets with multiple currencies enabled.

***

### Where to Find It

1. Open **Upcart**
2. Click **Edit cart**
3. Open the **Rewards** module and stay on **General settings**
4. Click **Show advanced settings**
5. Tick **Enable geolocation pricing override**
6. Click **Configure geolocation pricing** to open the setup window

<Warning>
  These controls only appear when the Rewards module's basis is set to **Cart total**. On a **Cart quantity** rewards bar the thresholds are item counts rather than money, so there is nothing to price per country and the geolocation settings are not shown at all.
</Warning>

<img alt="Opening Tiered Rewards advanced settings and the Configure Geolocation Pricing modal in Upcart" />

***

### Geolocation Pricing vs. Auto Currency Conversion

Upcart offers two ways to handle international reward thresholds:

|                  | **Auto Currency Conversion**                                          | **Geolocation Pricing**                                   |
| :--------------- | :-------------------------------------------------------------------- | :-------------------------------------------------------- |
| **How it works** | Converts your base threshold using Shopify's real-time exchange rates | You manually define thresholds per country                |
| **Best for**     | Stores that want a hands-off approach                                 | Stores that want precise, stable control over each market |
| **Tradeoff**     | Thresholds fluctuate as exchange rates change                         | Requires manual updates if pricing changes                |

Picking one is the simplest setup. If you do turn on both, Upcart warns you in the module and the order of operations matters: **geolocation picks the threshold first, then the currency conversion is applied on top of it**. Your geolocation values therefore have to be expressed in your store's base currency, not the local one.

For example, with a base currency of USD, a reward at \$10 USD, and a geolocation rule setting Canada to \$20 USD, a Canadian shopper sees roughly:

> \$20 USD × exchange rate ≈ \$27.50 CAD

If you want the shopper to see exactly the number you typed, enable geolocation pricing on its own.

***

### Configuring Rules

Each rule lets you define a target group of countries and set custom minimum amounts per reward tier.

**Country Targeting**

Each row has a **For** dropdown with two options:

* **Countries Selected** - the rule applies to the countries you pick
* **Countries Not Selected** - the rule applies everywhere *except* the countries you pick

Countries are chosen from the searchable list beside the dropdown, not typed in — start typing a two-letter code (`US`, `JP`, `GB`) and select from the results. Your picks appear as badges above the search box, and a row with **no** countries selected shows an **All Countries** badge, meaning it matches everywhere. The codes come from the [Shopify Country Code reference](https://shopify.dev/docs/api/storefront/latest/enums/CountryCode).

**Setting Thresholds**

Each row has **Tier 1**, **Tier 2**, and **Tier 3 min amount** fields. Only the fields for tiers you have actually created are editable — the rest are greyed out, so fill in as many as you have and leave the others alone.

<Warning>
  Only the first three tiers can be overridden per country. The Rewards module allows four tiers by default, but the geolocation window exposes fields for tiers 1–3 only. A fourth tier always uses its base threshold, converted by Shopify if automatic currency conversion is on.
</Warning>

To target multiple markets, click **Add New Geolocation Pricing** and add a separate row for each (e.g. one row for the US, another for Japan). When you're done, click **Update** to save your changes.

> 📌 **Rule order matters.** Upcart processes rules from top to bottom. Place more specific rules (e.g. "Only US and JP") above broader ones (e.g. "All Countries") to prevent conflicts. If no rule matches a customer's country, the default base threshold applies.

***

### Troubleshooting

**Wrong threshold applying for a country** Check the rule order. A broader rule higher in the list may be overriding a more specific one.

**Thresholds behaving unexpectedly** Confirm that Auto Currency Conversion is not also enabled. Having both active will apply exchange rates on top of your custom values.

**A country isn't being matched** Double-check that you're using the correct two-letter ISO code. Refer to the [Shopify Country Code reference](https://shopify.dev/docs/api/storefront/latest/enums/CountryCode) for the full list.

***

### Related Articles

* [Tiered Rewards module - General settings](/upcart/tiered_rewards_module_general_settings)
* [Tiered Rewards module - Rewards settings](/upcart/tiered_rewards_module_rewards_settings)
* [Tiered Rewards module - Advanced settings](/upcart/tiered_rewards_module_advanced_settings)


# Getting started with Upcart customizations
Source: https://docs.aftersell.com/upcart/getting_started_with_upcart_customizations

Learn how to use HTML, CSS, and JavaScript to build custom features and styling in your cart drawer.

⚠️ **Important notice**

This example customization in this doc only works with V1.0 of the Upcart cart modules. If you recently upgraded your cart to Version 2, these customizations code will not work. You will need to use the new selectors provided for Version 2 in the [migration guide.](/upcart/upcart_v20_migration_guide)

Please review the other customization documentation for V2.0 solutions.

# Overview

Upcart gives you full control to modify the cart’s appearance and behavior using **Custom HTML**, **Custom CSS**, and **JavaScript**. These tools let you add new features, style your cart to match your brand, or introduce logic to improve how your cart works.

This guide covers the basics of each and shows how to get started. Each section includes a quick visual example to help you understand how changes look in practice.

***

Before you start, make sure to review [Upcart’s customization policy](/upcart/upcart_customization_policy) so you know what is and isn’t supported by our team.

## Add content with HTML

HTML is used to add static content like text, banners, or buttons into your cart. You can choose from multiple HTML locations in the **Custom HTML** editor (e.g., above checkout button, bottom of cart, between items).

Common use cases:

* Add custom messages
* Insert legal disclaimers or policy links
* Highlight shipping deadlines or delivery info

**Example:**

```
<div style="text-align: center; font-weight: bold;">  
  Thanks for shopping with us!  
</div
```

<img alt="Upcart Custom HTML editor adding a thank-you message above the checkout button" />

***

## Add logic with JavaScript

JavaScript controls cart behavior and logic. You can use it to show or hide elements, conditionally apply styling, or respond to cart changes in real time.

You’ll wrap your code in a `<script>` tag and place it in **Custom HTML > Scripts (Before Load)** or **Above Announcements**, depending on when it should run.

**Example: [Limit the cart to one upsell at a time](/upcart/limit_the_cart_to_one_upsell_at_a_time):**

```
<script>  
  // Show upsells again when upsells are removed  
  window.upcartSubscribeItemRemoved((event) => {  
    if (event.item?.properties?.__upcartUpsell) {  
      const upsells = window.upcartDocumentOrShadowRoot.querySelector(".upcart-upsells-module");  
      if (upsells) upsells.style.display = "block";  
    }  
  });  
  
  // Hide upsells once one is added  
  window.upcartSubscribeUpsellsAddedToCart(() => {  
    const upsells = window.upcartDocumentOrShadowRoot.querySelector(".upcart-upsells-module");  
    if (upsells) upsells.style.display = "none";  
  });  
  
  // Check for upsell in cart when it loads  
  window.upcartSubscribeCartLoaded((event) => {  
    const upsells = window.upcartDocumentOrShadowRoot.querySelector(".upcart-upsells-module");  
    const items = event.cart.items || [];  
    const hasUpsell = items.some(item => item?.properties?.__upcartUpsell);  
    if (upsells && hasUpsell) {  
      upsells.style.display = "none";  
    }  
  });  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnItemRemoved`, `window.upcartOnAddUpsell`, and `window.upcartOnCartLoaded` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeItemRemoved`, `upcartSubscribeUpsellsAddedToCart`, and `upcartSubscribeCartLoaded` for all new scripts.
</Note>

<img alt="Upcart Custom HTML Scripts Before Load editor with JavaScript hiding the upsells module" />

***

🔧 **Developer note:**\
Upcart provides a full [Public API documentation](https://rokt.notion.site/upcart-public-api) that lists all functions, variables, and best‑practice patterns available for advanced customizations. We recommend reviewing this when building more complex scripts or integrations.

***

## Style your cart with CSS

CSS controls the look and feel of elements in your cart. Use it to adjust spacing, colors, font sizes, or hide unwanted elements. **Custom CSS** is one of the tabs under **Settings** (behind **More settings** if the tab row overflows).

Common use cases:

* Change product title or button colors
* Adjust font size or alignment
* Add spacing between sections

**Example: Change upsell title color in V1.0:**

```
.upcart-upsells-title {  
  color: #C20075 !important;  
  font-size: 25px;  
  font-style: italic;  
  text-align: center;  
}
```

<img alt="Upcart Custom CSS editor styling the upsell title color with a changes saved confirmation" />

***

## Additional resources

Looking to improve your HTML, CSS, or JavaScript skills? Check out these free tools:

* [W3Schools](https://www.w3schools.com/)
* [Codecademy](https://www.codecademy.com/?g_network=g\&g_productchannel=\&g_adid=528849219280\&g_locinterest=\&g_keyword=codecademy\&g_acctid=243-039-7011\&g_adtype=\&g_keywordid=kwd-41065460761\&g_ifcreative=\&g_campaign=account\&g_locphysical=9001394\&g_adgroupid=70492864474\&g_productid=\&g_source=%7Bsourceid%7D\&g_merchantid=\&g_placement=\&g_partition=\&g_campaignid=1726903838\&g_ifproduct=\&utm_id=t_kwd-41065460761:ag_70492864474:cp_1726903838:n_g:d_c\&utm_source=google\&utm_medium=paid-search\&utm_term=codecademy\&utm_campaign=INTL_Brand_Exact\&utm_content=528849219280\&g_adtype=search\&g_acctid=243-039-7011\&gad_source=1\&gad_campaignid=1726903838\&gbraid=0AAAAAon8KZFBIKQJ4KKGpsSVHO3yi2Njl\&gclid=CjwKCAjwx-zHBhBhEiwA7Kjq61-cNVEH2PzXZCcjcqIZS-0mCe8EEyPBJYyj4QRn5bma8OMqd3IJrBoCwjoQAvD_BwE)
* [Mozilla Developer Network (MDN)](https://developer.mozilla.org/en-US/)

## Support for customizations

Upcart’s support team can’t assist with implementing custom code. For more advanced changes, we recommend hiring a [Shopify Expert](https://www.shopify.com/ca/partners/directory).


# Go to cart when pressing checkout button
Source: https://docs.aftersell.com/upcart/go_to_cart_when_pressing_checkout_button

Choose whether the Checkout button opens the cart page or goes directly to Shopify Checkout.

# Overview

This setting allows you to change the behavior of the main call-to-action button at the bottom of the cart drawer.

## **Where to Find It**

Go to:\
**Upcart > Cart Editor > Settings > Cart settings**\
Look for the checkbox labeled **“Go to cart page when pressing checkout button.”**

<img alt="Upcart Cart settings with the Go to cart page when pressing checkout button checkbox enabled" />

## **How It Works**

## ✅ Enabled (Box Checked)

* The Checkout button will take customers to your store’s **default cart page**\
  (e.g. `yourstore.com/cart`)
* This gives customers another opportunity to review their order in full before proceeding to checkout.
* You can customize the button text to say something like **“Review Order”** using the **Checkout button text** field on **Settings > Edit copy**.

## ⬜ Disabled (Box Unchecked)

* The Checkout button will send customers **directly to Shopify Checkout**\
  (e.g. `yourstore.com/checkout`)
* This is the default behavior for a faster checkout experience.


# Hide properties starting with single underscore "_"
Source: https://docs.aftersell.com/upcart/hide_properties_starting_with_single_underscore

Control whether internal or app-generated product attributes are shown in the cart drawer.

# Overview

This setting hides any line item properties that begin with a single underscore (`_`). These are often added by third-party apps or custom scripts to store internal data, such as personalization info or product metadata.

This setting only affects visibility in the **Upcart cart drawer**. Your Shopify theme’s cart page may still display these properties.

## Where to Find It

Upcart > Cart Editor > Settings > Cart settings, then expand Advanced Settings\
Look for **“Hide properties starting with single underscore.”**

## How It Works

### **Enabled**

Any line item properties starting with `_` will be hidden from the cart drawer. This keeps the layout clean and avoids showing technical or irrelevant data to customers.

### **Disabled**

These properties will remain visible. This can be helpful if you want customers to review their personalization choices or see other custom product details.


# Hide specific cart elements using product IDs
Source: https://docs.aftersell.com/upcart/hide_specific_cart_elements_using_product_ids

Use product IDs to conditionally hide the rewards bar or other cart elements based on what’s in the cart.

⚠️ **Important notice**

This customization only works with Version 1 of the Upcart cart modules. If you recently upgraded your cart to Version 2, these customizations may not work. You will need to use the new selectors provided for Version 2 in the [migration guide.](/upcart/upcart_v20_migration_guide)

If your customizations are not working as expected, you can revert the cart to Version 1 yourself: in the Cart Editor, use the **Cart version** dropdown at the top of the left-hand menu and choose **V1.0 (Legacy)**. The dropdown appears once every module in the cart is on V2.

We are currently working on new customization templates for Version 2 of the modules, and they will be available soon.

# Overview

This customization allows you to hide specific parts of the cart, such as the rewards bar, if certain products are present. It is useful when you want to simplify the cart experience for certain SKUs or prevent specific promotions from appearing alongside certain items.

This setup uses product IDs to detect which products are in the cart and hides a chosen element if a match is found. You’ll apply the logic using custom HTML and CSS in the Upcart editor.

***

## When to use this

* Hide the rewards bar when promotional items are in the cart
* Hide custom content blocks, trust badges, or upsell sections based on product type
* Maintain a cleaner or more tailored checkout flow for specific items

This approach requires basic knowledge of HTML and JavaScript.

***

## Step 1: Find the product IDs

1. Go to **Shopify Admin > Products**
2. Click the product you want to target
3. Copy the numeric product ID from the URL after `/products/`

**Example:**

```
/products/1234567890 → 1234567890
```

You’ll use these IDs in the JavaScript array that controls visibility.

***

## Step 2: Add custom HTML

1. Go to **Upcart > Cart Editor > Settings > Custom HTML**
2. Paste the following code into **both** the **Above announcements/rewards** and **On empty cart screen** HTML locations
3. Replace the values in `productIDsToExclude` with your product IDs
4. Update `.YOUR-CLASS-HERE` to target the cart element you want to hide (for example: `.upcart-rewards`, `.custom-message`, `.trust-badge`)

```
<script>  
  window.upcartSubscribeCartLoaded((event) => {  
    const items = event.cart.items;  
    const productIDsToExclude = [  
      6958755512411,  
      6958755610712,  
      7736708759774  
    ];  
  
    let cartContainsExcludedItem = false;  
  
    items.forEach((item) => {  
      productIDsToExclude.forEach((id) => {  
        if (item.productId === id) {  
          cartContainsExcludedItem = true;  
        }  
      });  
    });  
  
    const targetElement = window.upcartDocumentOrShadowRoot.querySelector(".YOUR-CLASS-HERE");  
    if (targetElement) {  
      targetElement.style.display = cartContainsExcludedItem ? "none" : "block";  
    }  
  });  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnCartLoaded` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeCartLoaded` for all new scripts.
</Note>

***

## Step 3: Optional fallback CSS

If you want to ensure the element is hidden before the cart fully loads, add this in the **Custom CSS** section:

```
.YOUR-CLASS-HERE {   display: none; }
```

**Note:** This may temporarily hide the element for all users until JavaScript runs, which can cause flicker. In most cases, it is better to rely on the JavaScript method.

***

## Final result

Once set up:

* The targeted cart element (such as the rewards bar) will be hidden if the cart contains one of the specified products
* The element remains visible otherwise
* You can reuse this logic to hide or show different elements based on product-specific rules

***

## Still need help?

For more complex customizations, we recommend working with a **Shopify Expert**. They can assist with HTML, CSS, and JavaScript inside your cart drawer.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Hide the discount row or specific savings elements
Source: https://docs.aftersell.com/upcart/hide_the_discount_row_or_specific_savings_elements

Hide parts of the discount summary section for a cleaner cart design.

# Overview

Upcart’s savings row displays information about applied discounts, codes, and savings. If you prefer a more minimal layout, you can selectively hide elements using custom CSS.

You can remove the entire row or just specific pieces like the discount amount, code badges, or the word “Discount.”

***

## Where to find the custom CSS editor

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**
2. Paste the code snippets below into the input area
3. Click **Save**
4. Refresh your storefront to see the changes live

***

## CSS examples

**Hide the entire savings row in V1.0**

```
.upcart-savings-row {  
  display: none;  
}
```

#### **Hide the entire savings row in V2.0**

```
.upcart-public-cart-summary {  
  display: none;  
}
```

Removes all discount-related content from the cart drawer.

***

**Hide only the discount amount in V1.0**

```
.upcart-savings-amount {       
  display: none;     
}
```

#### **Hide only the discount amount in V2.0**

```
.upcart-public-cart-summary__total-discount {       
  display: none;     
}
```

Keeps the discount label or code visible but hides the amount saved.

***

**Hide discount code badges in V1.0**

```
.upcart-discount-code-badge {       
  display: none;     
}
```

**Hide discount code badges in V2.0**

```
.upcart-public-cart-summary__slide-codes {       
  display: none;     
}
```

Hides the visual badge displaying the active discount code.

***

**Hide the savings label in V1.0**

The V1 label carries no class of its own, so scope the rule to the savings row:

```
.upcart-savings-row .styles_Footer__savingsCodes__ > span {       
  display: none;     
}
```

<Warning>
  Don't target `.UpcartDesignSettings__cartTextColor` on its own. It is the global cart-text-colour utility class, applied to the header, announcements, the rewards bar, product titles, the recommendations title and more — hiding it blanks most of the cart.
</Warning>

The label text itself is your **Total discount savings text** translation, which defaults to "Discounts" — you can change the wording there instead of hiding it.

#### **Hide the word "Discount" in V2.0**

```
.upcart-public-cart-summary__discount-label {       
  display: none;     
}
```

Hides static text that uses the word “Discount.” You may want to adjust this selector manually for more precise targeting.

## Important note

Hiding elements, especially the discount amount, may reduce visibility of promotions and savings. Consider the customer experience before applying these changes.

## Need help?

For advanced styling or layout changes, we recommend working with a **Shopify Expert**. Upcart’s support team does not assist with custom code implementation.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Hide the quantity selector for specific products
Source: https://docs.aftersell.com/upcart/hide_the_quantity_selector_for_specific_products

Prevent quantity changes for select products by hiding the quantity selector using CSS.

# Overview

This customization hides the quantity input (including the plus and minus buttons) for specific product variants in the cart. This ensures those products can only be purchased in fixed quantities.

This is helpful for free gifts, subscription boxes, or limited-edition items.

This method uses **Shopify variant IDs** (not product IDs), so you can target specific variants directly.

***

## Step 1: Find the variant ID

1. In **Shopify Admin**, go to **Products**
2. Click the product you want to modify
3. In the **Variants** section, select the variant you want to lock
4. Look at the URL in your browser — the variant ID appears after `/variants/`

**Example URL:**

```
https://admin.shopify.com/store/your-store/products/1234567890/variants/36485954240671
```

In this example, the variant ID is: `36485954240671`

***

## Step 2:

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**
2. Paste the following code into the input area, replacing the example variant ID with your own:

#### Add custom CSS in V1.0

```
.upcart-product-item[id*="36485954240671"]  
  [class*="styles_QuantityField__"] {  
  display: none !important;  
}
```

#### Add custom CSS in V2.0

**Per-variant targeting is not possible with CSS in V2.0.** V1 works because each row carries the variant id as a DOM `id`; the V2 row does not expose the variant id as an attribute at all, so there is no selector to match a single variant on.

What you *can* do in V2 is hide the quantity selector on **every** cart item:

```
.upcart-public-component-product-tile__quantity-selector {
  display: none;
}
```

If you need it hidden for specific variants only, use the Cart Items module's custom template instead of CSS. The `productTile` template receives `showQuantitySelector` along with the raw line item, so you can decide per line whether to render the selector. See the [CSS selector library](/upcart/upcart_css_selector_library_v2) and the [customization policy](/upcart/upcart_customization_policy).

***

## Important notes

* Make sure there is exactly **one space** between the selectors:\
  `.upcart-product-item[id*='...']` and `[class*="styles_QuantityField__"]`
* Repeat the rule for each variant you want to target by using its unique ID

**Example for multiple variants in V1.0:**

```
.upcart-product-item[id*="36485954240671"]  
  [class*="styles_QuantityField__"],  
.upcart-product-item[id*="49133203521846"]  
  [class*="styles_QuantityField__"] {  
  display: none !important;  
}
```

In V2.0 there is no multi-variant equivalent — the selector above applies to every cart item, and per-variant control needs the custom template route described earlier.

***

## Result

* Customers still see the product in their cart
* The quantity cannot be adjusted
* The product remains locked to the quantity added initially (for example, 1 unit for a free gift)

**Use this for:**

* Free gifts
* Promotional samples
* One-per-customer product rules

***

## Still need help?

For more complex rules, we recommend working with a **Shopify Expert**. They can help with HTML, CSS, and JavaScript customizations inside your cart drawer.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Hide the rewards bar for specific countries
Source: https://docs.aftersell.com/upcart/hide_the_rewards_bar_for_specific_countries

Use custom HTML and CSS to show or hide your rewards bar based on customer location.

# Overview

If you only offer rewards in certain regions, you can hide the rewards bar from customers in specific countries using a combination of JavaScript and CSS. This helps keep your cart clean and relevant for shoppers based on where they are browsing from.

**Note:**

Even when hidden, the rewards logic still runs in the background. For example, a free gift may still be added to the cart if the conditions are met, even if the bar is not visible.

***

## Step 1: Find your target country codes

You’ll need to define which countries should see the rewards bar. To find codes, refer to Shopify’s list of **ISO 2-letter country codes**.

**Examples:**

* `US` → United States
* `CA` → Canada
* `MX` → Mexico

***

## Step 2: Add custom HTML

1. Go to **Upcart > Cart Editor > Settings > Custom HTML**
2. Paste the following code into **both** of these locations:

   * Above announcements/rewards
   * On empty cart

Replace `"US"` with your desired country code(s).

```
<script>  
  function hideRewards() {  
    let rewardsBar = window.upcartDocumentOrShadowRoot.querySelector(".upcart-rewards");  
    let country = window.Shopify.country;  
  
    if (country.includes("US")) {  
      rewardsBar.classList.remove("hide");  
      return;  
    }  
  
    rewardsBar.classList.add("hide");  
  }  
  
  window.upcartSubscribeCartOpened(() => setTimeout(hideRewards, 300));  
  window.upcartSubscribeCartLoaded(hideRewards);  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnCartOpened` and `window.upcartOnCartLoaded` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeCartOpened` and `upcartSubscribeCartLoaded` for all new scripts.
</Note>

## Alternative Code For Rewards V2.0 version

If you have upgraded your rewards to the V2 version, the code is just slightly different as the rewards selector is replaced with the new `.upcart-public-rewards` selector. Use the below code if you have upgraded your tiered rewards module

```
<script>  
  function hideRewards() {  
    let rewardsBar = window.upcartDocumentOrShadowRoot.querySelector(".upcart-public-rewards");  
    let country = window.Shopify.country;  
  
    if (country.includes("US")) {  
      rewardsBar.classList.remove("hide");  
      return;  
    }  
  
    rewardsBar.classList.add("hide");  
  }  
  
  window.upcartSubscribeCartOpened(() => setTimeout(hideRewards, 300));  
  window.upcartSubscribeCartLoaded(hideRewards);  
</script>
```

To support multiple countries, adjust the condition like this:

```
if (["US", "CA", "GB"].includes(country)) {
```

***

## Step 3: Add custom CSS

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**
2. Paste this code to control visibility:

```
.hide {  
  display: none;   
}
```

***

## Final result

Customers from excluded countries will not see the rewards bar in their cart, even though reward logic still functions in the background.

Use this method if:

* You only offer rewards in select markets
* You want to avoid displaying non-applicable promotions
* You need a short-term workaround before setting up proper region-based logic

***

## Need help?

For advanced regional logic or JavaScript support, we recommend working with a **Shopify Expert**. Upcart support does not assist with writing or troubleshooting custom code.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Hide the sticky cart button on the homepage
Source: https://docs.aftersell.com/upcart/hide_the_sticky_cart_button_on_the_homepage

This article explains how to use JavaScript and CSS to hide the floating cart button on your store’s homepage.

# Overview

If you want a cleaner first impression or your homepage layout conflicts with the sticky cart button, you can hide the button specifically on the homepage using a simple code snippet.

This setup checks the customer’s current page and removes the sticky cart button if they are on the homepage.

***

## When to use this

* To avoid visual clutter on your homepage
* When using a custom hero section or layout that overlaps with the sticky cart
* To keep the cart button focused on product pages or collections

***

## Step 1: Add the script

1. Go to **Upcart > Cart Editor > Settings > Custom HTML**
2. From the **HTML Location** dropdown, select **Scripts (Before Load)**
3. Paste the following JavaScript:

```
<script>  
  var stickyCartButton = document.querySelector("#upCartStickyButton");  
  
  if (  
    stickyCartButton &&  
    (document.location.pathname === "/" + Shopify.locale ||  
     document.location.pathname === "/")  
  ) {  
    stickyCartButton.classList.add("hide-sticky-cart-button");  
  }  
</script>
```

This script checks the current page’s path and applies a class to hide the sticky button if the customer is on the homepage.

***

## Step 2: Add custom CSS

1. Go to **Upcart > Sticky Cart > Custom CSS (note that this is Sticky Cart, not Cart Editor)**
2. Paste the following CSS:

```
.hide-sticky-cart-button {     
  display: none;   
}
```

***

## Final result

* The sticky cart button will be hidden when a customer visits the homepage (`/` or `/[locale]`)
* The button remains visible on all other pages


# A/B testing
Source: https://docs.aftersell.com/upcart/how-to-a-b-test-upcart

Run a head-to-head test between your live cart and a draft cart to see which performs better, then promote the winner to live in one click.

A/B Testing lets you compare your live cart against a draft cart variant with real shopper traffic. Upcart automatically splits incoming traffic between the two variants based on your chosen allocation, tracks per-variant analytics, and lets you declare a winner when you're ready.

***

## How It Works

Each A/B test is made up of:

* **Variant A** - your current live cart (automatically selected, cannot be changed)
* **Variant B** - one draft cart of your choosing
* **Traffic allocation** - a configurable split between the two variants (1-99% each, must sum to 100%)
* **Test name** - up to 255 characters; use something descriptive like "Free Shipping Bar - March Test"

Once the test is published, incoming shoppers are routed to one of the two variants. Each variant collects its own impressions, conversion, and revenue data. When you're ready, you declare a winner and that variant becomes the new live cart.

***

## Setting Up a Test

1. Go to **Upcart > Carts**
2. Make sure you have at least one **live cart** and one **draft cart**. The **Create test** button is always on the page, but it stays disabled until both exist. It gives no hint as to which one is missing, so check your cart list. While a test is already running the button is replaced by **End test**, since declaring a winner is the only test action available then.
3. Click **Create test**
4. Enter a test name
5. Select the draft cart you want to test against your live cart
6. Set your traffic allocation (defaults to 50/50)
7. Click **Publish & start test**

<Note>
  The traffic allocation and cart settings are locked once the test is live. If you need to make changes, end the current test and start a new one.
</Note>

***

## Viewing Test Analytics

Once your test is running, per-variant analytics are available in the **Analytics** tab. The four KPIs reported for each variant are:

| Metric                         | What it measures                                                                                                                   |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Impressions**                | Cart views in the test period where at least one module actually rendered. A cart that opened with no modules shown isn't counted. |
| **Cart Conversion Rate (CCR)** | Checkout completion percentage                                                                                                     |
| **Added Revenue**              | Revenue from upsells, add-ons, and recommendations attributed to that variant                                                      |
| **Average Order Value (AOV)**  | Average order value during the test period                                                                                         |

<Note>
  Analytics are aggregated by a daily job. If you just started a test, you will see dashes instead of numbers for the first \~24 hours. This is expected and not a bug. Numbers will appear within 24 hours of the test starting.
</Note>

A progress bar in the Analytics tab shows how close you are to the recommended number of impressions for statistical significance. Once you reach that threshold, you have enough data to confidently declare a winner.

***

## Ending a Test and Declaring a Winner

1. Go to **Upcart > Carts** and click **End Test**
2. Select the winning variant
3. Click **Confirm**

The winning variant is published as the new live cart with 100% of traffic. The losing variant remains as a draft.

<Warning>
  There is no undo on a winner declaration. If you select the wrong variant, you will need to manually republish the previous cart from your drafts.
</Warning>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I run more than one test at a time?">
    No. Only one active test is allowed per store at a time. You must end the current test before starting a new one.
  </Accordion>

  <Accordion title="Can I test two draft carts against each other?">
    No. A/B Testing always tests your live cart against one draft cart. The live cart is automatically selected and cannot be changed.
  </Accordion>

  <Accordion title="Can I test more than two variants at once?">
    No. A/B Testing supports exactly two variants. Multivariate testing is not currently supported in Upcart.
  </Accordion>

  <Accordion title="Can I change the traffic split after the test starts?">
    No. The traffic allocation is locked once the test is published. To change it, end the current test and start a new one with the desired split.
  </Accordion>

  <Accordion title="Can I edit the cart or test settings while a test is running?">
    No. Both the test configuration and the cart editor settings are locked while a test is live. End the test to make changes.
  </Accordion>

  <Accordion title="Why am I seeing dashes instead of numbers in my analytics?">
    Analytics are aggregated by a daily job. Brand new tests show dashes until the first aggregation run completes, which typically happens within 24 hours of the test starting. This is expected behavior and not a bug.
  </Accordion>

  <Accordion title="Will the same shopper see both variants?">
    No. Each shopper is assigned to one variant and **stays in it across sessions** — the assignment is stored in their browser's local storage, so it survives page loads, new tabs, and returning days later. It's only re-derived if the test's carts change or the test ends.
  </Accordion>

  <Accordion title="Does the test affect shoppers who never open the cart?">
    No. Variant assignment only matters when the cart is shown. Shoppers who never trigger the cart are not counted in impressions.
  </Accordion>

  <Accordion title="Is revenue converted to a single currency for international stores?">
    Yes. Every amount is read in your store's default currency before being totalled, so Added Revenue and AOV are already normalised — a multi-currency store's figures are directly comparable between variants.
  </Accordion>

  <Accordion title="Does Upcart automatically pick a winner?">
    No. Upcart shows per-variant metrics and a progress bar toward statistical significance, but you make the final call. There is no automatic winner selection.
  </Accordion>

  <Accordion title="Can I undo a winner declaration?">
    No. Once a winner is declared, that variant becomes the live cart immediately. To revert, you would need to manually republish the previous cart from your drafts.
  </Accordion>

  <Accordion title="What happens to the losing variant after I declare a winner?">
    The losing variant remains as a draft cart. It is not deleted.
  </Accordion>

  <Accordion title="Can I see past test results?">
    Yes. The Analytics tab shows both your current live test and previous completed tests side by side.
  </Accordion>
</AccordionGroup>

***

**Need help?**

If you have questions about setting up or running an A/B test, reach out to our support team via the in-app chat.


# Setting up tiered rewards
Source: https://docs.aftersell.com/upcart/how-to-set



A step-by-step guide to setting up Tiered Rewards in Upcart, from creating discounts in Shopify to configuring and enabling your reward tiers.

#### Overview

Tiered Rewards display a visual progress bar in the cart drawer, encouraging customers to spend more to unlock rewards like free shipping, discounts, or free products.

Setting up Tiered Rewards involves two parts: configuring your reward tiers in Upcart, then creating a matching discount in Shopify. Upcart tracks and displays progress toward the reward, but Shopify is what applies it at checkout.

***

#### Step 1: Configure Your Reward Tiers in Upcart

1. In the Upcart app, go to **Cart Editor > Tiered rewards**.
2. Select the reward type you want to offer (Shipping, Discount, or Product).
3. Set the **Minimum Amount** that customers need to reach to unlock the reward.
4. Add your customer-facing messaging. Insert the remaining amount with a variable — `{{amount}}` on the Version 2 Rewards module, `{AMOUNT}` on Version 1. The field's help text shows which one applies to your cart.
5. Repeat for additional tiers if needed. You can configure up to four tiers.
6. Save your changes.

For a full breakdown of every available setting at this stage, see [Tiered Rewards Module - Rewards Settings](/upcart/tiered_rewards_module_rewards_settings).

***

#### Step 2: Create the Matching Discount in Shopify

Upcart does not create or apply discounts directly. Once your tiers are configured, you need to create a matching discount in Shopify so the reward is actually applied at checkout.

**Free Shipping**

1. Go to **Shopify Admin > Discounts** and create a new automatic discount.
2. Set it to apply free shipping when the cart reaches your target threshold (e.g. \$70).
3. Save the discount.

**Discount (Percentage or Fixed Amount)**

1. Go to **Shopify Admin > Discounts** and create a new automatic discount.
2. Set the discount value and the minimum cart value required to trigger it.
3. Save the discount.

**Free Product**

1. Duplicate the product in Shopify and set the duplicate's price to \$0.
2. Add "Free" to the duplicate's title to distinguish it.
3. Alternatively, create an automatic 100% discount applied to that specific product.

For more detail on the free product setup, see [Set Up a Free Product Reward Tier in Upcart](/upcart/set_up_a_free_product_reward_tier_in_upcart).

📌 The threshold you set in Shopify must match the minimum amount configured in Upcart. If they are out of sync, the progress bar and the actual reward will not align.

***

#### Step 3: Configure General Settings

With your tiers in place, review the General Settings to control how the rewards bar looks and behaves.

Key things to configure:

* **Bar background and foreground colors** to match your store's branding.
* **Reward Calculation** - choose whether progress tracks by cart total or item count.
* **Show rewards on empty cart** if you want the bar visible before anything is added.
* **Product Filters** to control which items count toward reward progress (e.g. excluding gift cards or sale items).

For a full breakdown of all options, see [Tiered Rewards Module - General Settings](/upcart/tiered_rewards_module_general_settings).

***

#### Step 4: Configure Advanced Settings (Optional)

If your store sells internationally, you have two options for handling reward thresholds across currencies:

* **Auto Currency Conversion** - Upcart automatically converts your threshold using Shopify's real-time exchange rates.
* **Geolocation Pricing Override** - Define custom thresholds per country for precise control.

⚠️ Only enable one of these at a time. Using both simultaneously will apply exchange rates on top of your custom values, leading to unintended thresholds.

For step-by-step instructions, see [Tiered Rewards Module - Advanced Settings](/upcart/tiered_rewards_module_advanced_settings) or the dedicated [Geolocation Pricing for Tiered Rewards](/upcart/geolocation) guide.

***

#### Step 5: Enable Tiered Rewards

1. Go to **Cart Editor > Tiered rewards**.
2. Toggle the Tiered Rewards module on.
3. Save your changes.

The rewards progress bar will now be visible to customers in the cart drawer.

***

#### Related Articles

* [Tiered rewards module - General settings](/upcart/tiered_rewards_module_general_settings)
* [Tiered rewards module - Rewards settings](/upcart/tiered_rewards_module_rewards_settings)
* [Tiered rewards module - Advanced settings](/upcart/tiered_rewards_module_advanced_settings)
* [Set up a free product reward tier in Upcart](/upcart/set_up_a_free_product_reward_tier_in_upcart)
* Geolocation Pricing for Tiered Rewards


# How do I cancel my Upcart subscription?
Source: https://docs.aftersell.com/upcart/how_do_i_cancel_my_upcart_subscription

This article outlines how to cancel/unsubscribe from the Upcart app

If you're running into any issues with how Upcart is working, please reach out to us using the chat in the bottom right corner of the app.\
We're always happy to help troubleshoot and we always appreciate your feedback.

***

## Uninstalling Upcart

If you're set on parting ways with us, all you need to do is uninstall the app.\
Uninstalling the app will automatically cancel your subscription to Upcart.

You can use [this link](http://admin.shopify.com/settings/apps/app_installations/app/upcart-2) to go directly to your **Shopify Admin apps list** and uninstall from there.

***

## Step-by-Step Guide

If you prefer not to use the link above, follow the steps below to uninstall manually:

1. Click on **Settings** in the bottom left corner of your Shopify Admin.
2. Select the **Apps and Sales Channels** tab on the left side of the screen.
3. Find **Upcart** in the list of apps.\
   *Hint: You can sort the list alphabetically (A–Z) to find it faster.*
4. Click on the **Uninstall** button next to Upcart.
5. Optionally, leave a reason for uninstalling, then click the red **Delete** button.

***

## After Uninstalling

Rest assured that Upcart doesn't leave any code behind on your store.\
Because Upcart runs through an app embed, it removes everything automatically when uninstalled.

***

For follow up Billing questions, please refer to our [Billing FAQ](/upcart/upcart_pricing_structure#frequently-asked-questions) or reach out to our support team at [support@upcart.app](mailto:support@upcart.app).


# How to add gradient colors and animation to your rewards bar
Source: https://docs.aftersell.com/upcart/how_to_add_gradient_colors_and_animation_to_your_rewards_bar

Customize your rewards bar with animated gradients for a more dynamic look.

# Overview

This tutorial shows you how to apply a gradient background and animation effect to your Upcart rewards bar using custom CSS. This enhancement helps your reward tiers stand out and adds visual appeal to your cart.

These customizations are simple to apply and are suitable for store owners or developers with basic CSS knowledge.

***

## Where to find the custom CSS editor

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**
2. Scroll to the bottom of the page and paste your code into the input area
3. Click **Save**
4. Refresh your storefront to see the changes live

***

## Example CSS for gradient animation

This code adds a diagonal shimmering gradient effect to your rewards progress bar:

```
.upcart-rewards-bar-foreground {  
  background-image: linear-gradient(  
    45deg,  
    rgba(255, 255, 255, 0.4) 25%,  
    transparent 0,  
    transparent 50%,  
    rgba(255, 255, 255, 0.4) 0,  
    rgba(255, 255, 255, 0.4) 75%,  
    transparent 0,  
    transparent  
  );  
  background-size: 1rem 1rem;  
  animation: slide 4s linear infinite;  
}  
  
@keyframes slide {  
  from {  
    background-position-x: 0;  
  }  
  to {  
    background-position-x: 113px;  
  }  
}
```

## Alternative code for V2.0 Rewards Version

If you have upgraded your rewards to the V2 version, the code is just slightly different as the rewards selector is replaced with a new selector. Use the below code if you have upgraded your tiered rewards module

```
.upcart-public-component-segmented-progress-bar__segment-fill {  
  background-image: linear-gradient(  
    45deg,  
    rgba(255, 255, 255, 0.4) 25%,  
    transparent 0,  
    transparent 50%,  
    rgba(255, 255, 255, 0.4) 0,  
    rgba(255, 255, 255, 0.4) 75%,  
    transparent 0,  
    transparent  
  );  
  background-size: 1rem 1rem;  
  animation: rewards-bar-slide 4s linear infinite;  
}  
  
@keyframes rewards-bar-slide {  
  from {  
    background-position-x: 0;  
  }  
  to {  
    background-position-x: 113px;  
  }  
}
```

## Notes

* To change the shimmer angle, adjust `45deg` to another direction (example: `-45deg`).
* To change the base bar color, use the built-in color settings in the **Rewards module**.

***

## Final result

After applying this CSS, your rewards bar will display a subtle moving texture overlay. This draws attention to your rewards system without overwhelming the rest of your cart design.

***

## Need help?

For advanced customizations, we recommend working with a **Shopify Expert**. They can help implement HTML, CSS, or JavaScript in your cart drawer. Upcart support does not assist with writing or debugging custom code.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# How to customize your mobile cart width
Source: https://docs.aftersell.com/upcart/how_to_customize_your_mobile_cart_width

This article outlines how to customize your mobile cart width using css.

# **Introduction**

Welcome to this tutorial on customizing the mobile cart width to suit your preferences! Adjusting the mobile cart width can greatly enhance your customers' shopping experience by ensuring that your cart is easy to view and interact with on smaller screens. This customization allows you to control the layout, making sure it fits seamlessly with your overall store design and keeps things looking clean and organized.

These steps are designed for store owners or developers with basic CSS knowledge. By tweaking the mobile cart width, you can improve usability and make the checkout process smoother for your customers, potentially increasing conversions and customer satisfaction.

Let’s get started and make your mobile cart look and work exactly how you want it!

## **Accessing Custom CSS Settings**

To begin customizing the CSS for your Upcart, follow these steps:

1. Open the **Upcart App** within your dashboard.
2. Navigate to the **Cart Editor**.
3. Open **Settings** and select the **Custom CSS** tab (behind **More settings** if the tab row overflows).

## **Applying Custom CSS**

Once you are in the Custom CSS section, you can change the mobile cart width by following these steps below. Change the number from 90% to any number you desire, the larger the number, the more space the cart takes up across the screen. (note: this applies to both V1.0 and V2.0 Upcart)

1. Locate the CSS input area.
2. Copy and paste the following code into the CSS input area:

```
.upcart-cart {   
  --widthOfMobileCart: 90%;   
}   
  
/* MOBILE WIDTH STYLING*/   
@media only screen and (max-width: 600px) {              
  [class*="styles_CartPreview__right__"] {   
    right: calc(var(--widthOfMobileCart) * -1);   
  }   
  
  [class*="styles_CartPreview__right__"]  
  [class*="styles_active__"] {   
    right: var(--widthOfMobileCart);   
  }   
  
  [class*="styles_CartPreview__"] {  
    width: var(--widthOfMobileCart);   
  }  
  
  .upcart-backdrop,  
  [class*="styles_CartPreview__empty__"],   
  [class*="styles_CartPreview__card__"],   
  [class*="styles_CartPreview__upsells__"],      
  [class*="styles_CartPreview__bottomModules__"],  
  .upcart-cart-body {   
    width: 100% !important;   
  }  
}
```

# **Conclusion**

By following this tutorial, you’ve successfully customized the mobile cart width, making it more user-friendly and aligned with your store’s design. These small changes can have a big impact on your customers' shopping experience, making it easier for them to browse and buy on mobile devices.

## Still Need Help?

If you need any assistance with customizations, we recommend consulting with a Shopify Expert about adding HTML, CSS, and even JavaScript to your cart drawer.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Introduction to Upcart's public API
Source: https://docs.aftersell.com/upcart/introduction_to_upcarts_public_api

Learn how to get started with Upcart's API, add scripts, test changes, and customize your cart with ease.

The **Upcart Public API** lets you customize your cart, automate workflows, and integrate with third-party apps - whether you're a developer or just getting started.\
This guide will walk you through the basics and help you start building custom functionality inside your cart drawer.

👉 [View Full Upcart Public API Documentation](https://rokt.notion.site/upcart-public-api)

***

## Overview

The Public API is a collection of JavaScript functions and event listeners that let you:

* **React to cart changes** — detect when items are added, removed, or updated.
* **Trigger actions** — such as opening or closing the cart programmatically.
* **Build custom features** — inject your own logic or UI components directly inside the cart drawer.

It’s especially helpful when working in the **Custom HTML** section of the Upcart editor, where you can use these functions to create unique experiences for shoppers.

***

## What You Need to Get Started

Before using Upcart’s API, make sure you have:

* **Access to Upcart in your Shopify store**\
  Ensure Upcart is installed and active in your store.
* **A basic understanding of JavaScript**\
  Many customizations use pre-written snippets, but knowing basic JavaScript helps if you want to go beyond the basics.

***

## Adding Your First Upcart API Script

You can start using the API right from your Upcart editor:

1. Go to **Upcart Editor → Settings → Custom HTML → Scripts (before load)**

2. Paste in your script — for example:

```
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    console.log("You just added " + event.item.title + " to your cart!");
  });
</script>
```

**Note:** Older examples using `window.upcartOnAddToCart` still work but are deprecated and log a console warning. Use `upcartSubscribeAddedToCart` for all new scripts.

3. Save your changes, then test it in your store:

* Open Dev Tools (`F12` or `Ctrl + Shift + J` on Windows, `Cmd + Option + J` on Mac)
* Add a product to your cart
* Check the Console tab for the message:\
  `"You just added [product title] to your cart!"`

🎉 If you see the message, your first API script is working!

***

## Start Customizing Your Cart

Now that you’re set up, you can use the API to do all sorts of cool things — like automatically opening the cart when items are added, updating custom widgets, or sending analytics events.

For full function references and examples, check out the **[Upcart Public API Documentation](https://rokt.notion.site/upcart-public-api)**.

***

## More Resources

* 🧩 **[API FAQ](/upcart/upcart_api_frequently_asked_questions)** — Troubleshooting tips and common questions
* ⚙️ **[Common Uses for Upcart API](/upcart/common_upcart_api_uses)** — Popular code examples and templates
* 💡 **[Customization Docs](/upcart/add_a_mandatory_terms_and_conditions_checkbox_to_your_cart)** — Pre-written scripts to help you get started fast
* 🛍️ **[Shopify’s Cart API Documentation](https://shopify.dev/docs/api/ajax/reference/cart)** — Learn how Shopify handles cart data behind the scenes
* 👩💻 Need advanced customizations? Consider hiring a [Shopify Expert](https://www.shopify.com/ca/partners/directory/services/development-and-troubleshooting/custom-apps-integrations) for more complex integrations.


# Klaviyo add to cart event tracking in Upcart
Source: https://docs.aftersell.com/upcart/klaviyo_add_to_cart_event_tracking_in_upcart

This article explains how to enable accurate Klaviyo event tracking when customers add items to their cart using Upcart.

# Overview

By default, Upcart takes over Shopify's cart functionality, which can prevent third-party apps like **Klaviyo** from detecting cart updates. Fortunately, there are two reliable ways to restore **Add to Cart (ATC)** tracking in Klaviyo while keeping Upcart active.

Before you begin, make sure **Klaviyo Onsite Tracking** is properly configured. You can follow their setup guide here:\
👉 [Klaviyo Onsite Tracking Setup Guide](https://help.klaviyo.com/hc/en-us/articles/4425956184731)

***

## Option 1: Use AJAX Compatibility (Fastest Setup)

Upcart includes a setting that restores compatibility with other apps by exposing Shopify's native cart update behavior. When this is enabled, Klaviyo can once again listen for Add to Cart events.

## How to enable:

1. Go to **Upcart > Cart Editor > Settings > Cart settings**
2. Scroll to **Advanced Settings** and expand it
3. Tick **Enhanced Ajax API compatibility**
4. Click **Save** and test the result

⚠️ **Important: Enhanced AJAX API Compatibility trade-offs**\
This setting is **disabled by default** for most stores. Enable it ONLY if your store uses a non-standard AJAX cart API and Upcart is not intercepting add-to-cart events. When enabled, other apps gain more control over cart behavior, which can cause redirect loops or send customers to the Shopify cart page instead of opening the Upcart drawer. If enabling this setting causes redirects, disable it and switch to **Option 2** instead, using the manual Upcart API (`upcartRegisterAddToCart`).

For complete guidance on this setting, see [Enhanced AJAX API Compatibility](/upcart/enhanced_ajax_api_compatibility).

***

## Option 2 (Recommended): Add a Custom Klaviyo Script

This method gives you the best of both worlds, **Upcart stays in full control**, and **Klaviyo tracking still works**.

## Steps:

1. Open **Upcart > Cart Editor > Settings**
2. Scroll down to the **Custom HTML** section
3. From the dropdown, choose **Scripts (Before Load)**
4. Paste the following script:

Modern API (recommended):

```
<script>
  function TrackATC(){
    var _learnq = window._learnq || [];
    _learnq.push(['track', 'Added to Cart']);
    console.log("Klaviyo ATC");
  }

  window.upcartSubscribeAddedToCart(function(event) { TrackATC(); });
  window.upcartSubscribeUpsellsAddedToCart(function(event) { TrackATC(); });
</script>
```

<Warning>
  Paste the whole block, including the `TrackATC` function. The subscriber calls it, so a snippet with only the two `upcartSubscribe…` lines throws `Uncaught ReferenceError: TrackATC is not defined` on every add to cart and sends nothing to Klaviyo.
</Warning>

Legacy API (still works but deprecated):

```
<script>  
  function TrackATC(){  
    var _learnq = window._learnq || [];  
    fetch(`${window.location.origin}/cart.js`)  
      .then((res) =>  
        res.clone().json().then((data) => {  
          var cart = {  
            total_price: data.total_price / 100,  
            $value: data.total_price / 100,  
            total_discount: data.total_discount,  
            original_total_price: data.original_total_price / 100,  
            items: data.items,  
          };  
          _learnq.push(['track', 'Added to Cart', cart]);  
          console.log("Klaviyo ATC");  
        }).catch((e) => {  
          console.error('Klaviyo add to cart tracking failed', e);  
        })  
      );  
  }  
  
  window.upcartOnAddToCart = () => { TrackATC(); };  
  window.upcartOnAddUpsell = () => { TrackATC(); };  
</script>
```

***

## What this does:

* Sends an "Added to Cart" event to Klaviyo any time a product or upsell is added using Upcart
* Adds a confirmation message (`Klaviyo ATC`) to your browser console so you know it's working

***

## How to Test Your Setup

To confirm your Klaviyo integration is working properly:

* Follow [Klaviyo's guide to testing Add to Cart events](https://help.klaviyo.com/hc/en-us/articles/4425956184731)
* Use your browser's **Console** tab to verify the "Klaviyo ATC" log appears after adding a product
* Check Klaviyo's analytics dashboard for ATC event data

If you still don't see tracking data, confirm that Klaviyo's onsite scripts are installed and enabled. For help, contact [Klaviyo Help Center](https://help.klaviyo.com/hc/en-us).

***

## Summary

|                                          |                                          |                                    |
| ---------------------------------------- | ---------------------------------------- | ---------------------------------- |
| Method                                   | Benefits                                 | When to Use                        |
| **Option 1** – Enable AJAX Compatibility | Fastest setup, no code required          | When other apps don't interfere    |
| **Option 2** – Add Custom Script         | Most reliable, Upcart remains in control | When Option 1 causes cart redirect |

If you're using Klaviyo and Upcart together, this guide should help you track events smoothly while keeping your cart drawer experience intact.

***

Need more help? Reach out to us via in-app support.


# Limit the cart to one upsell at a time
Source: https://docs.aftersell.com/upcart/limit_the_cart_to_one_upsell_at_a_time

Use custom HTML to hide the upsell module after a single upsell is added to the cart.

# Overview

This customization prevents multiple upsells from being added at once by hiding the upsell section as soon as one upsell is accepted. Once the upsell is removed, the module reappears.

This is useful if you want to:

* Simplify the cart experience
* Reduce decision fatigue
* Maintain exclusivity around certain offers

***

## How it works

* When a customer accepts an upsell, the upsell section is hidden
* If the upsell item is removed, the upsell section becomes visible again
* Works with both AI-recommended and manual upsells

***

## Where to add the code

1. Go to **Upcart > Cart Editor > Settings > Custom HTML**

<Warning>
  **The selector below is Version 1 only.** `.upcart-upsells-module` is on the V1 upsells carousel. If your Upsells module is on **Version 2**, swap it for `.upcart-public-upsell` in all three handlers — the rest of the script is unchanged. See the [V2 CSS selector library](/upcart/upcart_css_selector_library_v2).
</Warning>

2. Paste the following code into the **Above announcements/rewards** location

***

## HTML script to copy

```
<script>  
  // Show upsells again when upsells are removed  
  window.upcartSubscribeItemRemoved((event) => {  
    if (event.item?.properties?.__upcartUpsell) {  
      const upsells = window.upcartDocumentOrShadowRoot.querySelector(".upcart-upsells-module");  
      if (upsells) upsells.style.display = "block";  
    }  
  });  
  
  // Hide upsells once one is added  
  window.upcartSubscribeUpsellsAddedToCart(() => {  
    const upsells = window.upcartDocumentOrShadowRoot.querySelector(".upcart-upsells-module");  
    if (upsells) upsells.style.display = "none";  
  });  
  
  // Check for upsell in cart when it loads  
  window.upcartSubscribeCartLoaded((event) => {  
    const upsells = window.upcartDocumentOrShadowRoot.querySelector(".upcart-upsells-module");  
    const items = event.cart.items || [];  
    const hasUpsell = items.some(item => item?.properties?.__upcartUpsell);  
    if (upsells && hasUpsell) {  
      upsells.style.display = "none";  
    }  
  });  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnItemRemoved`, `window.upcartOnAddUpsell`, and `window.upcartOnCartLoaded` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeItemRemoved`, `upcartSubscribeUpsellsAddedToCart`, and `upcartSubscribeCartLoaded` for all new scripts.
</Note>

***

## Result

Once this customization is added:

* Customers only see upsells if they have not already accepted one
* The upsell module is hidden as soon as an upsell is added
* The module reappears automatically if the upsell item is removed
* No need to configure product IDs or tags

This keeps your upsell experience focused, uncluttered, and easy for customers to engage with.

***

## Still need help?

For more advanced customization, we recommend working with a **Shopify Expert**. They can assist with HTML, CSS, and JavaScript inside your cart drawer.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Multicart
Source: https://docs.aftersell.com/upcart/multicart

Create and manage multiple cart configurations in Upcart.

# What is Multicart?

Multicart lets you create and manage multiple separate cart configurations from a single Shopify store. Instead of having just one cart that's always live, you can now:

* Keep draft carts to experiment and iterate before going live
* Publish a cart at any time, switching the live experience for your customers in seconds
* Preview draft carts on your live storefront before publishing

This gives you the flexibility to prepare seasonal or campaign carts in advance, and make changes safely without affecting your live storefront.

## Managing your carts

You can manage your carts in two places:

* **Homepage** - Shows your current live cart with a "Manage all carts" button
* **All Carts page** - Access this via "Manage all carts" to see all your live and draft carts in separate sections, with per-cart analytics and buttons to publish, edit, preview, duplicate, translate, and delete

## Understanding live vs. draft carts

### What does "live" mean?

A **live cart** is the cart configuration currently shown to your customers on your store. Only one cart can be live at any time.

### What does "draft" mean?

A **draft cart** is a saved configuration that isn't visible to customers yet. You can have as many draft carts as you need to experiment, prepare for campaigns, or test new ideas.

### Can I have no live cart?

Yes, you can unpublish your only live cart. When this happens, Upcart is effectively disabled for your customers. The app will warn you before you do this.

⚠️ **Important:** Having no live cart does not stop billing. You must uninstall Upcart to stop billing.

## Working with the cart editor

The cart editor now loads a specific cart's configuration. At the top of the editor, you'll see:

* The cart's name and status (live or draft)
* **Publish** or **Unpublish** buttons
* A dropdown to switch between carts without leaving the editor
* **Show items in cart** vs. **Show empty cart** toggle (top right)

### Key changes from the previous editor

**What's moved:**

* The cart preview toggle is now in the top right corner
* Save and discard now use Shopify's standard save bar

**What's new:**

* **Publish button** - Makes your cart live instantly
* **Cart switcher** - Switch between carts within the editor
* **Rename carts** - Carts are named "Untitled cart #" by default, but you can rename them

### When do changes go live?

* **For draft carts:** Saving only updates the draft configuration. Nothing changes on your live storefront.
* **For the live cart:** Saving updates your storefront immediately (same behavior as before Multicart).

## Publishing and unpublishing carts

### Publishing a cart

When you click **Publish** on a draft cart:

1. The draft cart's configuration becomes your live cart
2. Your previous live cart is automatically moved to draft
3. Changes appear on your storefront immediately

You'll see a confirmation modal before this happens: "Publishing will make this cart live. The current live cart will be moved to draft."

### What happens during publishing?

Publishing a cart:

* Syncs shipping protection product (if configured)
* Syncs discount combinations
* Writes all settings to Shopify metafields
* Marks the cart as LIVE
* Automatically demotes the previous live cart to DRAFT

This process can take a few seconds.

### Understanding the "App embed off" badge

If you see a yellow "App embed off" badge on your live cart, it means:

* The cart is set to LIVE in Upcart
* But the Upcart Bridge (app embed) is disabled in your Shopify theme editor
* Upcart won't appear on your storefront even though the cart is "live"

**To fix this:** Go to Shopify admin → Online Store → Themes → Customize → App embeds, and enable the Upcart Bridge.

⚠️ **Note:** Discounts will still be live even if the app embed is off. To turn them off, you need to disable them in your Shopify discounts separately.

## Previewing draft carts

You can preview any draft cart before publishing:

1. Click **Preview** on a draft cart in the All Carts page
2. Your live storefront opens with the draft cart's settings
3. The URL includes `?upcart-sandbox-mode=1`. The value must be exactly `1` — any other value (including `true`) will not trigger preview mode.

For information about preview limitations and troubleshooting, see [Multicart troubleshooting](/upcart/multicart_troubleshooting).

## Duplicating carts

You can duplicate any cart to create a copy with the same configuration. This is useful when you want to:

* Create variations of an existing cart
* Test changes without affecting the original
* Prepare seasonal versions based on your current setup

When you duplicate a cart, all settings, modules, and translations are copied to the new draft cart.

<Note>
  Upcart does not offer a file-based import or export for cart configurations. To reuse a cart's settings, duplicate the cart inside Upcart or start a new cart from [templates](/upcart/creating_a_cart_from_templates). Cart configurations cannot be transferred between Shopify stores from within Upcart.
</Note>

## Deleting carts

### Can I delete a live cart?

Not directly from the app. The delete option only appears once a cart is a draft, so unpublish the live cart first (moving it to draft), then delete it.

### How to delete a cart

1. Go to **All Carts**
2. If the cart is live, click **Unpublish** first
3. Once it's a draft, the delete option becomes available
4. Click **Delete**

⚠️ **Warning:** If you unpublish your only cart without publishing another, you'll have no live cart and Upcart will be disabled for customers.

## Translations

You can now translate cart-facing text per cart, per Shopify locale. This allows you to have different button labels, headings, and reward messages in each language, all managed within Upcart.

### How to translate your cart

1. From the **All Carts** page, find your cart
2. Click the **Translate** button
3. Enter translations for each locale (e.g., fr, de, es) enabled on your Shopify store

### What text can be translated?

You can translate the following fields per locale:

**Header:**

* Cart title

**Footer:**

* Checkout button
* Continue shopping
* Subtotal label
* Discount label
* Discount savings text

**Empty cart:**

* Empty cart message

**Cart items:**

* Show/hide item labels (singular and plural)

**Upsells:**

* Header
* Add button
* Review count text

**Tiered rewards:**

* Per-tier progress text (up to 6 tiers)
* Per-tier reward description (up to 6 tiers)
* Unlock text

**Recommendations:**

* Section title
* Section header
* "Shop now" button

**Notes:**

* Title
* Placeholder text

**Announcement:**

* Banner text

**Discount code:**

* Placeholder
* Button

**Subscription upgrades:**

* Button
* Options text
* One-time purchase
* Full price
* Subscription plan

### When do translations go live?

When you publish a cart, the translations stored for that cart are synced to Shopify's Translations API. The previous live cart's translations are replaced.

### Are translations copied when duplicating?

Yes. When you duplicate a cart, the translations for all locales are also copied to the new draft cart.

For troubleshooting translations, see [Multicart troubleshooting](/upcart/multicart_troubleshooting).

## Per-cart settings

Each cart has its own independent configuration for:

### Shipping protection

Shipping protection is configured per-cart. Each cart has its own shipping protection product configuration.

When you publish a different cart, the shipping protection product for that cart will be synced. The previous cart's shipping protection product will no longer be active.

### Discounts

Each cart has its own Discounts configuration. You can set up different Discount rules for each cart.

⚠️ **Note:** Discounts depend on live cart events and may not behave as expected in sandbox preview mode. Test Discount rules after publishing to a live environment.

## Cart versioning (V2)

Upcart has two generations of storefront components:

* **Base (V1)** - Older version
* **V2** - Current standard

New carts are created as V2 by default. Only pre-existing carts may still be on V1.

### What is the V2 upgrade banner?

When you open the cart editor for a cart that still has V1 modules, you'll see a banner prompting you to upgrade to V2.0.

Each cart tracks its own version state independently, so dismissing the banner on one cart won't affect other carts.

### What happens if I upgrade to V2?

Your cart's module versions are updated. V2 uses updated storefront components that may render slightly differently.

You can revert the upgrade at any time before publishing.

## Analytics

Per-cart analytics are tracked for each cart configuration. This lets you compare performance across different cart setups.

⚠️ **Note:** Per-cart analytics are only tracked from March 16, 2026 onwards. Analytics from before that date are still available via the analytics page or the chart on the home page.

## How your previous cart translated to Multicart

If you were using Upcart before this update, here's how your previous configurations translated:

* **Live cart** - Your live cart stayed the same, nothing changed
* **Sandbox** - Your saved changes in sandbox are now in a "draft" cart
* **Disabled cart** - Your disabled/not-live cart was converted into a draft cart. If your disabled cart had a sandbox version, you now have 2 draft carts in your Carts page

## Limitations

### How many carts can I have?

There is currently no hard limit on the total number of carts. You can create as many draft carts as you need.

### Currently supported

* **1 live cart at a time** - Only one cart can be live at any given moment

## Troubleshooting

For common issues, solutions, and frequently asked questions about Multicart, see [Multicart troubleshooting](/upcart/multicart_troubleshooting).


# Multicart troubleshooting
Source: https://docs.aftersell.com/upcart/multicart_troubleshooting

Troubleshoot common issues with Multicart configurations.

# Multicart troubleshooting

This guide helps you resolve common issues when working with multiple cart configurations in Upcart.

## Preview limitations

Draft previews may not fully reflect live cart behavior. Features that depend on real cart state, live discount codes, or certain integrations may behave differently.

**Features with known preview limitations:**

* **Discounts** - May not fire correctly in sandbox mode
* **Shipping protection** - Product lookups behave differently in sandbox
* **Express payments** (Shop Pay, Apple Pay, etc.) - Not available in preview

⚠️ **Tip:** For most layout and design changes, the preview is reliable. For testing Discounts, shipping protection, or express payments, you'll need to publish the cart to test properly.

### Preview troubleshooting

If you preview a cart and see an incorrect cart, this can happen due to Shopify limitations. Try refreshing the page or opening and closing the cart to refresh the preview.

## Troubleshooting translations

If translations aren't showing on your storefront:

1. **Check if the translation was saved** - Go to All Carts → Translate on your live cart and verify text has been entered for the locale
2. **Check if the cart with translations is live** - Translations only sync when a cart is published
3. **Check Shopify locale settings** - Go to Shopify Admin → Settings → Languages and verify the locale is enabled
4. **Check that the correct locale is active** - Your storefront needs to be browsed in the target locale for translations to display

## Common issues and solutions

### Upcart has disappeared from my store

**Most common cause:** You have no live cart.

**How to fix:**

1. Open the Upcart app and go to **All Carts**
2. Check whether any cart shows a green "live" badge
3. If no cart is live, click **Publish** on any draft cart you want to make active

**Other causes:**

* The Upcart app embed may be disabled. The live cart would show a yellow "App embed off" badge. Go to Shopify Admin → Online Store → Themes → Customize → App embeds → enable **Upcart**.

### My cart settings changed/reset after I published a different cart

This is expected behavior. Publishing a cart overwrites the live Shopify metafields with the new cart's settings.

**How to fix:**

1. Your previous cart is still saved as a draft
2. Go to **All Carts**, find your old cart in the Drafts section
3. Click **Publish** on it to restore the previous settings

**How to prevent it in future:** Review a draft cart carefully before publishing, since publishing replaces all live settings.

### My shipping protection disappeared after switching carts

Shipping protection is configured per-cart. The newly published cart either has no shipping protection product configured, or has a different one.

**How to fix:**

1. Go to the cart editor for the currently live cart
2. Navigate to the Add-ons module → Shipping Protection section
3. Re-configure the shipping protection product
4. Save (the live cart's settings will update immediately)

**If you want both carts to have the same shipping protection:** Configure the shipping protection product on each cart individually before publishing.

### My Discount rules stopped working after switching carts

Discount rules are **store-wide, not per-cart** — one set for your whole shop, applying regardless of which cart is live. Publishing a different cart never removes or replaces them, so a change in behaviour after a publish isn't a lost rule set.

**How to fix:** Open **Discounts** in the Upcart left-hand navigation and check the rules there. If a rule has stopped firing, look at whether the newly published cart still contains the block that surfaces it — the rules survive the publish, but the cart layout that displays their progress may not.

### I can't delete my cart

You're trying to delete a live cart. Live carts cannot be deleted.

**How to fix:**

1. Go to **All Carts** and identify which cart is live (green badge)
2. Click **Unpublish** on it
3. ⚠️ Warning: This will mean no cart is live until you publish another
4. Once it's a draft, the delete option will become available

**If you have no other cart to publish:** Create a new cart (or duplicate the current one), configure it, and then publish the new one before deleting the old one. This avoids a gap with no live cart.

### The draft preview doesn't look right/doesn't match what I expect

Draft previews use sandbox mode, which has known limitations. Not all features behave the same as in a live environment.

**Known limitations:**

* Discounts may not fire in sandbox mode
* Shipping protection may not render correctly
* Express payment buttons (Shop Pay, Apple Pay, etc.) are not available in preview

**For most layout/design changes:** The sandbox preview is reliable enough.

**For testing Discounts, shipping protection, or express payments:** You'll need to publish the cart to a live environment to test properly.

### My live cart analytics aren't populated

Per-cart analytics only cover activity recorded since carts began being stamped onto analytics events. Earlier activity is still stored and still counted — it just can't be split by cart, so view it on the Analytics page or the home-page chart instead of the per-cart view.

## Frequently asked questions

### What happens to my current live cart when I publish a new one?

The previous live cart is automatically moved back to draft. This happens instantly. You'll see a confirmation modal before this happens.

### Can I preview both sandbox and live carts at once?

When switching between sandbox and live previews, Upcart will refresh the page to load the correct data. If you need to preview both versions at once, use a private/incognito window for one of them to avoid forced refreshes.

### I published a cart by mistake and now my live settings are wrong. What do I do?

No data is lost. Go to **All Carts** and find the cart you actually wanted to be live (it will now be in the Drafts section). Click **Publish** on it to restore it as the live cart.

### I'm getting an error when trying to publish/unpublish/delete. What's wrong?

The server prevents two cart mutations from running at the same time for the same shop. If you clicked quickly twice, or two browser tabs triggered the action simultaneously, the second one will fail.

Wait a few seconds and try again. The error is transient. If it persists, refresh the page and try once more.

### The upgrade to V2 changed how my cart looks. Can I revert it?

**If you haven't published yet:** You can revert the upgrade in the cart editor before publishing.

**If you already published the V2 cart:** You don't need an old draft. Open the cart editor and use the **Cart version** dropdown to switch back to **V1.0 (Legacy)**, then save. The dropdown appears whenever every module in the cart is on V2, whether the cart is live or draft.

### I don't see a "Translate" option on my cart. Where is it?

The Translate action only appears in the **All Carts** table, not on the homepage cart card. It also requires you to have at least one non-English locale enabled in your Shopify store.

To access it:

1. Go to Upcart → All Carts (via "Manage all carts" on the homepage)
2. Find your cart in the table
3. Look for the Translate button in the row actions

If no Translate option appears at all, you may not have additional locales set up in Shopify. Go to Shopify Admin → Settings → Languages to add a locale.


# Open cart button selector
Source: https://docs.aftersell.com/upcart/open_cart_button_selector

This article outlines how to prevent the default cart drawer from overriding Upcart

Upcart now ensures that your store always opens the Upcart cart drawer, even if your theme normally opens its own. This is useful when the cart icon or button in your theme doesn't trigger Upcart by default.

***

**This setting tells Upcart which button or icon on your store should open the Upcart cart drawer. If your theme uses its own cart drawer, you can use this setting to ensure that Upcart opens instead.**

1. Go to the Upcart Editor.
2. Click **Settings**.
3. On the **Cart settings** tab, scroll down and expand **Advanced Settings**.
4. Find **Open Cart Button Selector**:

<img alt="Upcart Open cart button selector dropdown set to Use default selector" />

You’ll see a menu with three available selections:

|                         |                                                                                                                                                      |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Option**              | **What It Means**                                                                                                                                    |
| Use Default Selector    | Upcart automatically detects the cart icon. Use this option if the cart drawer opens correctly.                                                      |
| Add Additional Selector | If your store includes more than one cart icon and only one functions by default, use this setting to add the selector of the one that doesn’t work. |
| Use Custom Selector     | If the cart drawer doesn’t open when the cart icon is clicked, use this option to tell Upcart which button to target.                                |

***

## How to Use the "Custom Selector" Option (No Coding Required)

If you need to use the **Custom Selector** option, follow these steps:

1. **Go to your store’s homepage.**
2. **Right-click on your cart icon.** This is the button or icon customers click to view their cart.
3. **Click "Inspect."** A panel will open showing the page’s code. You do not need to change anything.
4. In the panel, **look for a class or ID next to the highlighted code.** It will usually start with a dot (`.`) for a class or a hash (`#`) for an ID. For example: `.site-header__cart` or `#cart-icon`.
5. **Copy that class or ID.** For example: `.site-header__cart`.
6. **Return to the Upcart Editor.** Select **"Use Custom Selector"** and paste what you copied into the input box.

💡**Tips**

* If you're unsure which option to choose, start with the **Default Selector**.
* Use the **Custom Selector** only if clicking your cart icon does not open the Upcart cart drawer.
* Make sure to test the cart functionality on both mobile and desktop devices.
* You can use any AI tools you prefer to help review or verify your work.

***

**Need More Help?**

If you need help, you can ask your theme developer to find the correct selector. You do not need to write any code. Just copy and paste the selector as explained above.


# Open on add to cart
Source: https://docs.aftersell.com/upcart/open_on_add_to_cart

Control whether the cart drawer opens automatically when a customer adds an item to their cart.

## Overview

The Open on Add to Cart setting controls whether the Upcart drawer opens automatically every time a customer clicks "Add to Cart" on your store.

## Where to find it

Go to: Cart Editor > Settings > Cart settings
Look for the toggle labeled "Open cart drawer on add to cart."

## Default behavior

This setting is enabled by default. When enabled, the cart drawer slides open immediately whenever a customer adds a product to their cart.

## Enabled (Default)

* The cart drawer opens automatically on every "Add to Cart" action.
* Customers immediately see what's in their cart, including any upsells or rewards.
* Recommended for most stores.

## Disabled

* The cart drawer does not open automatically when items are added.
* Customers must manually click the cart icon to open the drawer.
* Use this if your theme already shows an add-to-cart confirmation and you don't want the drawer competing with it.

## Opening the cart programmatically

If you disable this setting but still want the cart to open under specific conditions, you can trigger it when an item is added using the public API:

```javascript theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>
```

Place this in Cart Editor > Settings > Custom HTML > Scripts (Before Load). This example opens the cart when an item is added. You can swap upcartSubscribeAddedToCart for any other subscribe event depending on when you want the cart to open.

## Best practice

Keep this setting enabled for most stores. The cart drawer opening on add to cart is one of the most effective ways to surface upsells, rewards progress, and the checkout button at the moment of highest purchase intent.


# Premade customizations database
Source: https://docs.aftersell.com/upcart/premade_customizations_database

Browse ready-made design and functionality changes to personalize your cart.

This collection of guides is designed to help you customize the look and behavior of your Upcart drawer. Whether you're adjusting the style to better match your store’s theme or modifying how Upcart works, these articles provide step-by-step instructions and code snippets.

All examples include copy-pasteable code and simple setup steps, so you can apply changes quickly without needing a developer.

To get started, choose one of the categories below.

## Styling changes

Refer to the [Styling Recipes](/upcart/changing_font_sizes) collection to change the way something looks.

## Functionality changes

Refer to the [Functionality Recipes](/upcart/add_a_mandatory_terms_and_conditions_checkbox_to_your_cart) collection to change the way something works.


# Prevent upsell-only purchases in the cart
Source: https://docs.aftersell.com/upcart/prevent_upsell_only_purchases_in_the_cart

Require customers to add at least one regular product before checking out.

# **Overview**

This customization uses HTML, CSS, and JavaScript to block checkout when the cart only contains upsell items. It helps ensure that upsells are treated as secondary offers, not standalone purchases, supporting a more controlled and intentional upsell strategy.

This ensures that upsell products function within specific boundaries, emphasizing their role as complementary items to primary products.

When implemented, the **checkout button will be disabled** until at least one non-upsell product is added to the cart.

## How it works

* If the cart contains only upsell items, the checkout button is greyed out
* A warning message appears below the button
* Once a regular product is added, the button becomes active and the warning disappears- Provides clear validation for scenarios ensuring that upsell products are only purchased with associated trigger products, such as displaying targeted warning messages.

This setup is ideal for store owners or developers with basic knowledge of JavaScript and CSS.

## Step 1: Add custom HTML

Go to:\
**Upcart > Cart Editor > Settings > Custom HTML**

## In the **Above announcements/rewards** section, paste:

```
<script>  
  function CartContainsOnlyUpsells(cart) {  
    var cartWithoutUpsells = cart.items.filter(item => item.properties?.__upcartUpsell == null);  
    return cartWithoutUpsells.length === 0;  
  }  
  
  function ToggleCheckoutButton(shouldBeEnabled) {  
    var checkoutButton = window.upcartDocumentOrShadowRoot.querySelector(".upcart-checkout-button");  
    var warning = window.upcartDocumentOrShadowRoot.querySelector(".upcartUpsellOnlyWarning");  
  
    if (checkoutButton && warning) {  
      if (shouldBeEnabled) {  
        checkoutButton.classList.remove("upcart-disable-checkout-button");  
        warning.style.display = "none";  
      } else {  
        checkoutButton.classList.add("upcart-disable-checkout-button");  
        warning.style.display = "block";  
      }  
    }  
  }  
  
  window.upcartSubscribeCartLoaded((event) => {  
    ToggleCheckoutButton(!CartContainsOnlyUpsells(event.cart));  
  });  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnCartLoaded` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeCartLoaded` for all new scripts.
</Note>

## In the **Below checkout button** section, paste:

```
<div class="upcartUpsellOnlyWarning" style="display: none;">  
  Your cart only contains upsell products. <br>  
  Please add a regular product to continue to checkout.  
</div>
```

Feel free to adjust the wording in the warning message to fit your brand tone.

## Step 2: Add custom CSS

Go to:\
**Upcart > Cart Editor > Settings > Custom CSS**

Paste the following code:

```
.upcartUpsellOnlyWarning {  
  width: 100%;  
  text-align: center;  
  margin-top: 10px;  
  color: red;  
  font-weight: bold;  
  font-size: 15px;  
}  
  
.upcart-disable-checkout-button {  
  cursor: none !important;  
  pointer-events: none !important;  
  opacity: 0.4 !important;  
}
```

This styles the warning message and disables the checkout button visually and functionally.

## Final result

Once set up:

* Checkout is blocked unless at least one non-upsell product is in the cart
* A message informs customers why checkout is disabled
* The experience feels smooth and brand-aligned

This is especially helpful for: Coupling effective upsell strategies with these techniques also improves the overall customer shopping experience by eliminating unnecessary conflicts in the purchase process.

* Preventing accidental single-item upsell purchases
* Maintaining upsells as add-on only products
* Ensuring better control over AOV and product bundling

## Still Need Help?

If you need any assistance with customizations, we recommend consulting with a Shopify Expert about adding HTML, CSS, and even JavaScript to your cart drawer.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Protect your upsell strategy with CSS - disable clicks on product titles & images in the cart and upsell
Source: https://docs.aftersell.com/upcart/protect_your_upsell_strategy_with_css_disable_clicks_on_product_titles_images_in_the_cart_and_upsell

Prevent customers from clicking product titles and images in the cart and upsells to reduce distractions and protect upsell-only items.

# Overview

This customization uses CSS to disable links on product titles and images in the cart drawer and upsell section. It helps keep the focus on completing checkout and prevents customers from leaving the cart to view product pages.

This is also useful for stores that offer exclusive upsell items that should not be accessed outside the cart.

***

## Why this is useful

* Reduces friction and keeps customers focused on checkout
* Prevents navigation away from the cart, especially on mobile
* Limits exposure of upsell-only products not meant to be browsed elsewhere

***

## Where to find the custom CSS editor

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**
2. Scroll down to the input field and paste your code
3. Click **Save**
4. Refresh your storefront to preview the change

***

### CSS to disable clickable links in V1.0

```
.upcart-product-title-link,  
.upcart-product-image-wrapper a,  
.upcart-upsell-item-card a {  
  cursor: none;  
  pointer-events: none;   
}
```

### CSS to disable clickable links in V2.0

```
/* Disabled click in Cart items */  
.upcart-public-component-product-tile__image-wrapper,  
.upcart-public-component-product-tile__title-link {  
  cursor: none;  
  pointer-events: none;   
}  
  
/* Disabled click in Upsell items */  
.upcart-public-component-upsell-tile a {  
  cursor: none;  
  pointer-events: none;   
}
```

This CSS will:

* Remove pointer functionality from product titles and images
* Prevent customers from clicking through to product detail pages
* Keep the styling and layout the same (only the interaction is disabled)

***

## Need help?

Upcart’s support team does not provide assistance with custom CSS implementation. For advanced setup or styling, we recommend working with a **Shopify Expert**.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Recommendations module
Source: https://docs.aftersell.com/upcart/recommendations_module

Learn how to show and customize product recommendations in the empty Upcart drawer.

# Overview

The Recommendations Module allows you to showcase suggested products when a customer's cart is empty. This is a valuable opportunity to re-engage shoppers and guide them toward key collections or bestsellers. You can access this feature by going to **Cart Editor > Recommendations** in your Upcart dashboard.

<img alt="Empty Upcart cart drawer with a Shop Now button and a recommended snowboard product" />

# Settings

The module includes several optional elements you can enable to tailor the customer experience and drive more engagement.

<img alt="Recommendations settings panel with header text, Shop Now button, and layout options" />

## **Edit Header Text**

This sets the main heading or intro message that appears above the recommendations area. You can use this to encourage customers to browse your store. For example, a message like “Your cart is empty, check out these top picks” can prompt them to continue shopping.

## **Enable ‘Shop Now’ Button**

When toggled on, this adds a prominent call-to-action button beneath the header text. It offers customers a quick link to start browsing products. Use this if you want to actively guide users toward a specific section of your store.

## **Edit Button Text**

This field controls the label shown on the ‘Shop Now’ button. You might use phrases like “Start Shopping” or “View All Products” depending on your store’s tone.

## **Edit Button URL**

Here you define where the button leads. Most stores link this to a collection page, such as `/collections` or `/collections/bestsellers`. Use a full relative path so the button routes correctly.

## **Product Recommendations Header Text**

This sets the title that appears just above the list of recommended products. Common choices include “You may also like” or “Recommended for you.”

## **Configure Manual Recommendations**

1. Click to open the manual product selection window.
2. Choose the specific products you want to recommend.
3. Save your selections.

Unlike the **[Upsells module](/upcart/upsells_module)**, these manual picks are always visible and don’t depend on trigger products. They will appear any time the cart is empty.

<img alt="Select Products modal on the Collection tab for choosing recommended products" />

## **Maximum Number of Recommendations to Display**

Use this to limit how many products appear. If you select five products but set the display limit to three, only the first three will be shown. This helps you keep the layout focused and clean.

## **Recommendation Direction**

Choose how your recommended products are laid out:

* **Carousel layout** displays products in a horizontal row with left and right arrows for scrolling.
* **Block layout** stacks products vertically in a single column.

Select the layout that best fits your brand’s design and the space available in your cart drawer.

## **Product Reviews**

Tick **Show product reviews on recommendations** to display star ratings on each recommended product. Ratings come from your connected review app's product metafields, so they only appear where valid review data exists.

With it on, a **Review count text** field lets you word the count beside the stars — use the `{{review_count}}` variable to insert the number.


# Render cart in shadow DOM setting
Source: https://docs.aftersell.com/upcart/render_cart_in_shadow_dom_setting

This article explains what the Render Cart in Shadow DOM setting does and how to troubleshoot issues related to styling or integration conflicts between your Shopify theme and Upcart.

## What Shadow DOM Does

When the **Render Cart in Shadow DOM** setting is turned **on**, Upcart creates a self-contained space that keeps its styles and scripts separate from the rest of your store.

This means:

* Your theme’s global CSS can’t override Upcart’s design.
* Upcart’s styling also won’t interfere with your theme.
* The cart stays consistent across different devices and themes.

You can think of Shadow DOM as a “protective bubble” around your cart that helps it look and work the way it’s meant to.

***

## How this happens

Shopify and third party themes often come with global CSS and JavaScript that can unintentionally affect how Upcart looks or behaves.

The **Render Cart in Shadow DOM** setting helps prevent these conflicts by isolating Upcart’s cart drawer inside its own protected environment. When enabled, Shadow DOM keeps your cart design and layout consistent, regardless of theme updates or custom code changes.

However, if your theme or third-party app needs direct access to cart elements, this isolation can sometimes create integration challenges.

***

## Technical Considerations

If you or a developer need to modify elements within Upcart using JavaScript, it’s important to use the right document references:

* Use `upcartDocumentOrShadowRoot` when targeting elements **inside** Upcart.
* Use `document` when targeting elements **outside** of Upcart (for example, your Shopify theme’s header or footer).

Even though the Shadow DOM is isolated, Upcart still provides ways to interact with your theme and other apps through its **Public API** and helper functions.

***

## Troubleshooting and Limitations

In most cases, enabling Shadow DOM will fix CSS and layout conflicts automatically.\
However, there can always be some scenarios where you may still experience issues:

* **Pricing apps:** If another app needs to directly modify prices or checkout behavior inside the cart, Shadow DOM can make that difficult since it hides Upcart’s internal structure from external scripts.
* **Theme-level JavaScript:** Custom scripts that use `document.querySelector()` may not find cart elements while Shadow DOM is enabled.

If you need to test your store's behaviour for these integrations, you can temporarily disable it: open the cart editor, go to **Settings → Cart settings**, expand **Advanced Settings**, and clear **Render cart in shadow DOM**.


# Reposition upsells or add-ons below the product list
Source: https://docs.aftersell.com/upcart/reposition_upsells_or_add_ons_under_the_product_list_with_css

Use CSS to move the bottom modules — upsells, notes and announcements — directly below the cart items.

# Overview

When the Upsells module's position is set to **bottom**, Upcart pushes it — along with the notes and announcement modules, if those are also set to bottom — down to the base of the cart body. This tutorial pulls that group up so it sits immediately after the product list, making it more visible and increasing the likelihood of engagement.

<Note>
  This affects the **bottom modules** container, which holds the upsells, notes and announcement modules. **Add-ons are not in it** — they render in the footer, and this rule doesn't move them.
</Note>

This layout change can improve conversion by displaying complementary offers right after customers review their cart contents.

***

## Where to find the custom CSS editor

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**
2. Scroll to the input field and paste the code below
3. Click **Save**
4. Refresh your storefront to view the changes

***

## CSS to reposition modules

```
[class*="styles_CartPreview__bottomModules__"] {  
  margin-top: 0px;   
}
```

The container ships with `margin-top: auto`, a flex auto-margin that pushes it to the bottom of the cart body. Overriding it to `0` removes that push, so the group sits directly after the product list instead. It is not decorative spacing — if you set some other value, you're positioning the group, not trimming a gap.

***

## Optional enhancements

You can combine this adjustment with:

* Upsell styling (background colors, padding, or borders)
* Add-on highlight styles
* Scroll anchors or animations for smoother appearance

***

## Still need help?

For additional customization, we recommend working with a **Shopify Expert**. They can help with HTML, CSS, or JavaScript in your cart drawer.

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Set mobile cart width to zero until triggered by Upcart with CSS
Source: https://docs.aftersell.com/upcart/set_mobile_cart_width_to_zero_until_triggered_by_upcart_with_css

Learn how to set your mobile cart width to zero unless triggered by Upcart using CSS, for a cleaner, more streamlined shopping experience.

⚠️ **Important notice**

This customization only works with Version 1 of the Upcart cart modules. If you recently upgraded your cart to Version 2, these customizations may not work. You will need to use the new selectors provided for Version 2 in the [migration guide.](/upcart/upcart_v20_migration_guide)

If your customizations are not working as expected, you can revert the cart to Version 1 yourself: in the Cart Editor, use the **Cart version** dropdown at the top of the left-hand menu and choose **V1.0 (Legacy)**. The dropdown appears once every module in the cart is on V2.

We are currently working on new customization templates for Version 2 of the modules, and they will be available soon.

# **Introduction**

Welcome to this CSS tutorial, where we’ll show you how to set your mobile cart width to zero unless it’s triggered by Upcart. This is a handy way to keep your cart hidden and streamline the mobile shopping experience until your customers are ready to view it.

This guide is designed for store owners or developers with basic CSS knowledge. By using this customization, you can keep your cart out of sight and improve page layout, reducing distractions and helping your customers focus on shopping. It’s a small tweak that can make a big difference in your store’s mobile experience.

Let’s get started and make your mobile cart work smarter, not harder!

## **Accessing Custom CSS Settings**

To begin customizing the CSS for your Upcart, follow these steps:

1. Open the **Upcart App** within your dashboard.
2. Navigate to the **Cart Editor**.
3. Open **Settings** and select the **Custom CSS** tab (behind **More settings** if the tab row overflows).
4. Next, copy and paste the code into the CSS input area
5. When you are done “Click Save” and refresh your storefront page to see the results live.

## Here is the CSS Code to Copy and Paste into the CSS Section:

```
@media (max-width: 440px) {  
    .upcartPopupShow [class*="styles_CartPreview__right__"] {  
        width: 100%;  
        max-width: 440px;  
    }  
  
    [class*="styles_CartPreview__right__"] {  
        width: 0px;  
	max-width: 440px;  
    }  
}
```

# **Conclusion**

And that’s it! You’ve now learned how to change your mobile cart width to zero until it’s triggered by Upcart, creating a cleaner and more focused shopping experience.

## 🚧 Support for Customizations

Upcart's support team cannot assist with implementing custom CSS or HTML solutions in your cart.

If you need help designing or styling something custom, we recommend consulting a Shopify Expert:

[See Shopify Experts](https://www.shopify.com/partners/directory)


# Set up a free product reward tier in Upcart
Source: https://docs.aftersell.com/upcart/set_up_a_free_product_reward_tier_in_upcart

This article explains how to automatically add a free gift to the cart when a customer reaches a specific spend threshold.

## Overview

Offering a free product is a great way to drive higher order values and surprise your customers with added value. In Upcart, you can create a **reward tier** that adds a designated product to the cart when the customer reaches a specific threshold.

This guide walks you through setting that up and explains how to make the reward product free using Shopify.

***

## How Product Rewards Work

When a product reward is unlocked, Upcart automatically adds the selected product to the customer's cart. However, Upcart does not change the product's price. You'll need to handle pricing on the Shopify side.

It is important to note that Upcart does not have the functionality to create or apply discounts on its own; all such configurations must be handled via Shopify.

There are two ways to make the reward free:

1. **Create a duplicate version of the product priced at \$0**
2. **Use Shopify's Buy X, Get Y automatic discount** to make the product free at checkout

We'll walk through both methods in detail.

***

## Step 1: Create the Product Reward Tier in Upcart

1. Open **Upcart > Cart Editor**.
2. Go to the **Tiered rewards** tab.
3. In the **Rewards calculation** card, pick the basis for the whole bar: **Cart total (\$)** or **Cart quantity (#)**. This applies to every tier — it isn't set per tier.
4. In the **Tier settings** card, click **+ Add tier**.
5. Set the **Reward type** to **Product**.
6. Enter the **Minimum amount** (or **Minimum quantity**, if you chose Cart quantity) required to unlock the reward.
7. Select the **product** to add once the threshold is met — up to three per tier.

At this point, the product will be added to the cart when the requirement is met, but it will still be full price. Use one of the methods below to make it free.

***

## Method 1 (Recommended): Create a Free Version of the Product

This is the most stable and flexible option.

**Steps:**

1. In **Shopify**, go to **Products**.
2. Duplicate the product you want to offer as a free reward.
3. Set the price of the duplicated product to **\$0.00**.
4. Rename it clearly (for example, **Free Mystery Gift**).
5. Set the product to **Active** or **Unlisted**. Choosing **Unlisted** keeps it working in the cart and at checkout while hiding it from your storefront in one step (see [Optional: Hide the Reward Product from Your Storefront](#optional-hide-the-reward-product-from-your-storefront) below).

This method avoids discount stacking issues and gives you full control over how the reward is presented.

***

## Method 2: Use an Automatic Shopify Discount

If you prefer not to duplicate products, you can use a **Buy X, Get Y** discount to make the reward product free.

**Steps:**

1. Go to **Shopify Admin > Discounts**.
2. Click **Create Discount**.
3. Choose **Buy X, Get Y**.
4. Under **Customer Buys**, set a **Minimum Purchase Amount** (for example, \$200).
5. Under **Customer Gets**, select the reward product and set the quantity to 1.
6. Set the discount to **100% off**.
7. Enable **Automatic discount**.
8. Turn on **Combine with other discounts**, if applicable.

This setup ensures that once the customer hits the minimum spend, the reward product is discounted to \$0 automatically.

Shopify will still show the reward discount on other items in the cart due to how the system tracks purchase conditions. This is expected behavior and cannot be changed by Upcart.

Additionally, Shopify's system may restrict certain types of discount stacking or applications in specific configurations. Double-check whether your reward setup in Shopify aligns with these discount rules to avoid issues.

***

## Method 3: Use the Discounts module

The Discounts module can apply a 100% discount on a specific product when cart conditions are met, without requiring a duplicate product or a Shopify-side discount.

**Steps:**

1. Open the **Discounts** module in Upcart and click **Create Discount**.
2. Add a **Cart total** trigger (or **Cart quantity**) matching the threshold of your Tiered Reward. The field inside is **Cart total minimum amount** or **Minimum item count**.
3. Set the reward type to **Free Gift** and select your reward product.
4. Publish the rule.

When the customer reaches the threshold, Tiered Rewards displays the visual progress, and the Discounts rule applies the 100% discount on the gift product at checkout.

⚠️ **Note:** If you are using the Tiered Rewards product reward to add the product to the cart and also a Discounts rule to apply the discount, ensure both reference the exact same product or variant. Misaligned configurations can cause the product to be added but not discounted, or vice versa.

***

## Additional Configuration Tips

## Update the Reward Bar Messaging

After setting up your product reward, make sure the reward bar displays the correct message.

In the tier settings, edit **Title before achieving tier**. There is no per-tier "after achieving" field — the completion message is **Text after completing full rewards bar**, in the module's **General settings** card, and it covers the whole bar rather than one tier.

**Example:**

* Before: "You're \$20 away from a free mystery gift!"
* After: "You've unlocked your free mystery gift!"

This ensures the messaging is accurate and aligned with the actual reward.

***

## Optional: Hide the Reward Product from Your Storefront

A \$0 reward product can still be discovered by customers through search, collection pages, or product recommendations, even when it is only meant to appear in the cart. The cleanest way to hide it is Shopify's **Unlisted** product status.

### Set the reward product to Unlisted

1. In your Shopify admin, go to **Products** and open your reward product (for example, *Free Mystery Gift*).
2. In the **Status** dropdown near the top of the product page, select **Unlisted**.
3. Click **Save**.

That is the whole process. An **Unlisted** product is hidden from your storefront search, collection pages, predictive search, product recommendations, the Shopify Catalog, your sitemap, and search engines, while staying fully functional in the cart and at checkout so Upcart can still add it as a reward.

<Note>
  Unlisted products behave like Active products in the cart, at checkout, and on orders. Setting the reward to Unlisted does not stop Upcart from adding it, and does not stop Shopify from applying the \$0 price or discount.
</Note>

<Tip>
  Unlisted replaces the older method of hiding a product with a `seo.hidden` metafield and excluding it from collections. You no longer need to create metafields, use the bulk editor, or add collection rules. If a reward was previously hidden with `seo.hidden`, switching its status to **Unlisted** is enough, and you can remove the old metafield.
</Tip>

An **Unlisted** product page can still be opened by anyone who has the direct link. If you also want to prevent customers from manually adding the reward from its product page, see [Preventing Reward Exploits](/upcart/preventing_reward_exploits_and_automatically_open_upcart_on_shopify_cart_page).

***

## Final Result

Once complete:

* Customers will unlock the product reward after reaching the spend threshold.
* The reward product will be added automatically to the cart.
* Shopify ensures the item is free through discount or pricing configuration.
* The reward product is hidden from your storefront.
* Ensure that the reward thresholds defined in Upcart align accurately with the discount rules created in Shopify to avoid discrepancies.


# Setting up a custom template in Upcart
Source: https://docs.aftersell.com/upcart/setting_up_a_custom_template_in_upcart

This article outlines the key props available for customizing Upcart templates, helping you personalize your cart experience while maintaining core functionality.

## ⚠️ **Important Notice**

Custom templates require advanced technical knowledge of HTML, CSS, JavaScript, and React. Please ensure you have sufficient development expertise or access to a qualified Shopify developer before proceeding. **Our support team will not provide assistance with custom template development, debugging, or troubleshooting.** Technical questions should be directed to a Shopify expert or qualified developer.

***

## Code editor features

The custom template code editor includes built-in tools to help you write valid templates more easily.

### TypeScript IntelliSense

The editor understands TypeScript, so you get autocomplete suggestions, type-checking, and inline documentation for all available `props` as you type. The prop type hints are editor-only IntelliSense to help you write templates — they are not something you write into the template, and they never run on your storefront.

### Editable template body

The editor exposes only the editable JSX body of your template — there are no locked lines. The surrounding function wrapper is added automatically at build time and is never shown in the editor.

Use **Reset to default** at any time to restore the original template if your edits break the template structure.

***

## General Section

## Header

The Header module allows you to customize the cart header with your own design while maintaining essential cart functionality like displaying item count and providing a close button.

### **Available Props - Full template**

<img alt="Cart drawer header showing the Cart title, item count, and close button" />

`cartQuantity`

* **Type**: `string`

* **Description**: The current number of items in the cart, formatted as a string

* **Usage**: Display the cart item count in your custom header design

```
<h2>Shopping Cart ({props.cartQuantity})</h2>
```

`closeHandler`

* **Type**: `() => void`

* **Description**: A callback function that closes the cart when triggered

* **Usage**: Attach to buttons, icons, or other interactive elements to close the cart

```
<button  
  onClick={props.closeHandler}  
  aria-label="Close cart"  
>×</button>
```

`titleComponent`

* **Type**: `React.ReactElement | null`

* **Description**: A pre-rendered title component for the cart header that includes proper styling and translations

* **Usage**: Display the cart title based on your cart settings configuration

```
<div>{props.titleComponent}</div>
```

***

## Body Section

## Announcements

The Announcements module allows you to customize announcement displays with your own design while maintaining essential announcement functionality like timer controls and conditional visibility.

### Available Props - **Full template**

<img alt="Cart announcement bar with a countdown timer reserving the customer's products" />

`announcementTemplate`

* **Type**: `string`

* **Description**: The HTML content for the announcement message

* **Usage**: Display the announcement message in your custom implementations

```
<div dangerouslySetInnerHTML={{ __html: props.announcementTemplate }} />
```

`timer`

* **Type**: `string`

* **Description**: The current timer value formatted as a string

* **Usage**: Display countdown timer in custom announcement implementations

```
<div>Time remaining: {props.timer}</div>
```

`shouldUseTimer`

* **Type**: `boolean`

* **Description**: Indicates whether the timer functionality is enabled for this announcement

* **Usage**: Conditionally render timer-related content and controls

```
<div>  
  {props.shouldUseTimer && (  
    <span>{props.timer}</span>   
  )}  
</div>
```

`isTimerExpiredAndShouldHide`

* **Type**: `boolean`

* **Description**: Indicates if the timer has expired and the announcement should be hidden

* **Usage**: Control the visibility of the entire announcement based on timer state

```
<div>  
  {!props.isTimerExpiredAndShouldHide && (  
    <div>{props.timer}</div>  
  )}  
</div>
```

## Tiered Rewards

The Rewards module allows you to customize reward progress displays with your own design while maintaining essential rewards functionality like milestone tracking, progress visualization, and reward messaging.

### Available Props - **Full template**

<img alt="Tiered rewards progress bar with free shipping and product milestone icons" />

`rewardsMessageHtml`

* **Type**: `string`

* **Description**: The HTML content for the rewards message

* **Usage**: Display the rewards message with rich formatting in custom implementations

```
<div dangerouslySetInnerHTML={{ __html: props.rewardsMessageHtml }} />
```

`milestonesCompleted`

* **Type**: `number`

* **Description**: The number of milestones that have been completed

* **Usage**: Display completion count or calculate completion percentage

```
<div>  
  {Math.round((props.milestonesCompleted / props.milestonesData.milestonesToRender.length) * 100)}% Complete  
</div>
```

`milestonesData`

* Type:

  ```
  {  
    milestonesToRender: {  
      id: string;  
      label: string;  
      icon: React.ReactElement;  
      isCompleted: boolean;  
      positionPercent: number;  
    }[];  
    progressPercent: number;  
    showMilestones: boolean;  
    settings: {  
      iconContainerSize: string;  
      iconAlignment: string;  
      labelAlignment: string;  
      hideLabel: boolean;  
    };  
  }
  ```

* **Description**: Complete milestone configuration and progress data for the rewards system

* **Usage**: Access milestone information, progress percentage, and display settings

* **Properties**:

  * `milestonesToRender`: Array of milestone objects with completion status and positioning
  * `progressPercent`: Current progress as a percentage (0-100)
  * `showMilestones`: Whether to display milestone markers
  * `settings`: Visual configuration for milestone display

## Discounts

The Discounts module supports custom templates so you can design your own display while keeping essential functionality like rule management, section visibility, and reward presentation. The internal module type identifier for custom templates is `TRIGGERED_REWARDS` for backward compatibility with existing custom template code.

### **Available Props - Full template**

`rules`

* **Type**:

  ```
  {  
    id: string;  
    title: string;  
    description: string;  
    conditionsMet: boolean;  
  }[]
  ```

* **Description**: Array of Discount rules that are currently enabled

* **Usage**: Display available rewards, their titles, descriptions, and whether each rule's conditions have been met

* **Properties**:

  * `id`: Unique identifier for the reward rule
  * `title`: Title of the Discount rule
  * `description`: Description of the reward rule
  * `conditionsMet`: Whether the rule's conditions are currently satisfied by the cart. Use this to build "you've unlocked X" vs "spend \$Y more to unlock X" UX patterns

```
<div>
  {props.rules.map((rule) => (
    <div key={rule.id}>
      <h3>{rule.title}</h3>
      <p>{rule.conditionsMet ? "Reward unlocked!" : rule.description}</p>
    </div>
  ))}
</div>
```

`showSection`

* **Type**: `boolean`

* **Description**: Indicates whether the Discounts section should be displayed

* **Usage**: Control the visibility of the entire Discounts module

```
<div>  
  {props.showSection && (  
    <div>  
      <h2>Available Rewards...</h2>  
    </div>  
  )}  
</div>
```

`onToggleSection`

* **Type**: `() => void`

* **Description**: A callback function that toggles the visibility state of the Discounts section

* **Usage**: Attach to buttons or interactive elements to allow users to show/hide the rewards section

```
<button type="button" onClick={props.onToggleSection}>  
  {props.showSection ? "Hide Rewards" : "Show Available Rewards"}  
</button>
```

## Recommendations

The Recommendation module allows you to customize upsell product displays with your own design while maintaining essential e-commerce functionality like variant selection, add-to-cart actions, and product information display.

### **Available Props - Recommendation tile template**

<img alt="Recommendation tile showing a snowboard product with price and Add button" />

*The recommendation tile template shares the [same prop interface as the upsell tile template](#available-props-upsell-tile-template) in the Upsells module. All available props, types, and usage examples are documented in the Upsells Module section below.*

## Cart Items

The Cart Items module allows you to customize cart item displays with your own design while maintaining essential e-commerce functionality. This module provides multiple template types, each with their own specific props for different aspects of cart item display.

<Note>
  **Showing a loading indicator during add-to-cart or cart updates:** The standard Cart Items module does not expose a built-in "adding to cart" spinner. If you want to display a loading state while an item is being added or a cart operation is in progress, use the Product tile template and read the `isLoading` and `loadingOperation` props (documented below) to conditionally render a spinner or overlay. Custom templates require developer experience — see the notice at the top of this page.
</Note>

### **Available Props - Product tile template**

**Note:** Enabling the *Product Tile* template will override all other templates in this module, including **Variant template**, **Properties template**, **Bundle template**, and **Price template**.\
If you want to use custom code in any of those templates, you ***must*** *turn off the Product Tile template.*

<img alt="Cart product tile with image, variant, sale price, quantity selector, and subscribe button" />

`title`

* **Type**: `string`

* **Description**: The product title/name

* **Usage**: Display the main product name in cart items

`variant`

* **Type**: `React.ReactNode`

* **Description**: Pre-rendered variant information component

* **Usage**: Display variant details as a React component

`properties`

* **Type**: `React.ReactNode`

* **Description**: Pre-rendered product properties component

* **Usage**: Display product properties and subscription info as a React component

`bundle`

* **Type**: `React.ReactNode`

* **Description**: Pre-rendered bundle details component

* **Usage**: Display bundle information as a React component

`compareAtPrice`

* **Type**: `string | undefined`

* **Description**: Formatted compare-at price (original price)

* **Usage**: Display original price for sale items

`price`

* **Type**: `string`

* **Description**: Formatted current price

* **Usage**: Display the current item price

`savings`

* **Type**: `string | undefined`

* **Description**: Formatted savings amount

* **Usage**: Display how much the customer saves

`imageUrl`

* **Type**: `string | undefined`

* **Description**: Product image URL

* **Usage**: Display product image

`productUrl`

* **Type**: `string | undefined`

* **Description**: Product page URL

* **Usage**: Link to product detail page

`quantity`

* **Type**: `number`

* **Description**: Current item quantity in cart

* **Usage**: Display and manage item quantity

`showQuantitySelector`

* **Type**: `boolean`

* **Description**: Whether to show quantity controls

* **Usage**: Conditionally display quantity selector

`discountCodes`

* **Type**: `string[] | undefined`

* **Description**: Array of applied discount codes for this item

* **Usage**: Display item-specific discounts

`subscription`

* **Type**:

  ```
  {  
    subscriptionUpgradeData: {  
      buttonText: string;  
      defaultSellingPlanId: number;  
    } | null;  
    sellingPlansData: {  
      sellingPlanGroups: {  
        name: string;  
        selling_plans: {  
          id: number;  
          name: string;  
        }[];  
      }[] | null;  
      activeSellingPlanId: string;  
      oneTimePurchaseText: string | null;  
    } | null;  
    upgradeSellingPlan: (item: CartItem, sellingPlanId: number) => void;  
    changeSellingPlan: (item: CartItem, value: string) => void;  
    getSellingPlanGroupText: (groupName: string, planName: string) => string;  
  }
  ```

* **Description**: Complete subscription management object with upgrade data, selling plans, and handler functions

* **Usage**: Manage subscription functionality

* The subscription object contains:

  * **subscriptionUpgradeData**: Upgrade information (null if no upgrade available)

    * `buttonText`: Text for the upgrade button
    * `defaultSellingPlanId`: ID of the default selling plan for upgrades
  * **sellingPlansData**: Available selling plan options (null if no plans)

    * `sellingPlanGroups`: Array of plan groups with their selling plans
    * `activeSellingPlanId`: Currently selected selling plan ID
    * `oneTimePurchaseText`: Text for one-time purchase option (null if not available)
  * **upgradeSellingPlan**: Function to upgrade to a specific selling plan
  * **changeSellingPlan**: Function to change the current selling plan
  * **getSellingPlanGroupText**: Utility function to format selling plan display text

`onIncrease`

* **Type**: `() => void`

* **Description**: Function to increase item quantity

* **Usage**: Handle quantity increase actions

`onDecrease`

* **Type**: `() => void`

* **Description**: Function to decrease item quantity

* **Usage**: Handle quantity decrease actions

`onDeleteProduct`

* **Type**: `() => void`

* **Description**: Function to remove item from cart

* **Usage**: Handle item removal

`onQuantityChange`

* **Type**: `(quantity: string) => void`

* **Description**: Function to handle direct quantity input

* **Usage**: Handle manual quantity changes

`handleInputChange`

* **Type**: `(e: React.ChangeEvent<HTMLInputElement>) => void`

* **Description**: Input change handler for quantity field

* **Usage**: Handle quantity input field changes

`replaceItemWithVariant`

* **Type**: `(variantId: string) => Promise<{ success: boolean }>`

* **Description**: Function to replace item with different variant

* **Usage**: Handle variant switching

`isLoading`

* **Type**: `boolean`

* **Description**: Loading state for cart operations

* **Usage**: Show loading indicators

`loadingOperation`

* **Type**: `'increase' | 'decrease' | 'inputChange' | 'remove' | 'subscription' | undefined`

* **Description**: Specific operation currently loading

* **Usage**: Show operation-specific loading states

`setLoadingOperation`

* **Type**: `(op: "increase" | "decrease" | "inputChange" | "remove" | "subscription" | undefined) => void`

* **Description**: Function to set loading operation state

* **Usage**: Manage loading states for different operations

`rawItem`

* **Type**: `CartItem` (Refer to the `CartItem` [type below](#cartitem-object-properties))

* **Description**: Raw cart item data containing all information

### **Available Props - Variant template**

<img alt="Cart item variant line showing the selected size Medium" />

`item`

* **Type**: `CartItem` (Refer to the `CartItem` [type below](#cartitem-object-properties))

* **Description**: Raw cart item data containing variant information

* **Usage**: Access variant details from the cart item

### **Available Props - Properties template**

<img alt="Cart item property line showing a gift message note" />

`productProperties`

* **Type**: `{ key: string; value: string; isUrl?: boolean; }[]`

* **Description**: Array of product properties (custom fields, line item properties)

`subscriptionLabel`

* **Type**: `string | undefined`

* **Description**: Label for subscription information

### **Available Props - Bundle template**

<img alt="Expanded bundle listing three included component products with variants" />

`getSizedImageUrl`

* **Type**: `getSizedImageUrl: ({ src, width, height }: SizedImageParams) => string`

* **Description**: Utility function to get properly sized image URLs

`item`

* **Type**:

  ```
  {  
    itemComponents: {  
      quantity: number;  
      image: {  
        url: string;  
        height: number | null;  
        width: number | null;  
        alt: string;  
      };  
      product: {  
        title: string;  
        has_only_default_variant: boolean;  
      };  
      variantTitle: string;  
    }[];  
    variantTitle: string | undefined;  
    hasComponents: boolean;  
  }
  ```

* **Description**: Bundle item information including components. `itemComponents` is an array of component objects — map over it to render each bundled component.

`showDetailsText`

* **Type**: `string | undefined`

* **Description**: Text for "show details" action

* **Usage**: Display expand button text

`hideDetailsText`

* **Type**: `string | undefined`

* **Description**: Text for "hide details" action

`isExpanded`

* **Type**: `boolean`

* **Description**: Whether bundle details are expanded

`toggleCollapsible`

* **Type**: `() => void`

* **Description**: Function to toggle bundle details visibility

* **Usage**: Handle expand/collapse actions

`chevronDownIconComponent`

* **Type**: `React.ReactElement`

* **Description**: Pre-rendered chevron icon for expand/collapse

* **Usage**: Display consistent expand/collapse indicator

### **Available Props - Price template**

<img alt="Cart price showing original price struck through with sale price and savings" />

`compareAtPrice`

* **Type**: `string | undefined`

* **Description**: Formatted compare-at price (original price)

* **Usage**: Display original price for sale items

`price`

* **Type**: `string`

* **Description**: Formatted current price

* **Usage**: Display the current item price

`savings`

* **Type**: `string | undefined`

* **Description**: Formatted savings amount

* **Usage**: Display how much the customer saves

### **CartItem Object Properties**

The `CartItem` object contains all the detailed information about a cart line item. This object is available as props.rawItem in the Product Tile template and props.item in the Variant template.

#### **Core Identification**

* `key (string)` - Unique identifier for this cart item.

* `id (number)` - Variant ID (legacy field, use variant\_id instead)

* `variant_id (number)` - The Shopify variant ID for this item

* `product_id (number)` - The Shopify product ID

* `lineIdxFrom1 (number)` - 1-based index of this item in the original cart before modifications

#### **Product Information**

* `title (string)` - The line item title (usually variant title)

* `product_title (string)` - The main product title

* `handle (string)` - Product URL handle (e.g., "camp-stool")

* `vendor (string)` - Product vendor/brand name

* `product_type (string)` - Product category/type for tax purposes

* `sku (string)` - Stock Keeping Unit identifier

* `product_description (string)` - Full product description

* `product_has_only_default_variant (boolean)` - Whether the product has only one variant

#### **Pricing (All prices in cents)**

* `quantity (number)` - Number of this item in the cart

* `price (number)` - Unit price before discounts

* `original_price (number)` - Same as price

* `discounted_price (number)` - Unit price after product-level discounts

* `compare_at_price (number | null)` - Compare-at price (MSRP). Note: This field is added by Upcart, not provided by Shopify's cart API

* `final_line_price (number)` - Total price after product-level discounts (quantity × discounted\_price)

* `original_line_price (number)` - Total price before discounts (quantity × price)

* `line_price (number)` - Total price after all discounts

* `final_price (number)` - **Deprecated** - Unit price after product discounts (doesn't account for quantity)

* `total_discount (number)` - Same as line\_level\_total\_discount

* `line_level_total_discount (number)` - Total discount amount applied to this line item

#### **Media & URLs**

* `image (string)` - Primary product image URL

* `url (string)` - Relative URL path to the product page (e.g., "/products/camp-stool?variant=42789611372803")

* `featured_image (object | null)` - Featured image details:

  * `alt (string)` - Image alt text
  * `aspect_ratio (number)` - Image aspect ratio
  * `height (number)` - Image height in pixels
  * `url (string)` - Image URL
  * `width (number)` - Image width in pixels

#### **Variants & Options**

* `variant_title (string | null)` - Variant title (e.g., "Large / Red")

* `variant_options (string[])` - Array of variant option values

* `options_with_values (Array)` - Detailed option information:

  * `name (string)` - Option name (e.g., "Size")
  * `value (string)` - Option value (e.g., "Large")

* `untranslated_product_title (string | undefined)` - Original product title before translation (cart mutation responses only)

* `untranslated_variant_title (string | undefined)` - Original variant title before translation (cart mutation responses only)

#### **Custom Properties & Metadata**

* `properties (Record<string, any> | null)` - Custom line item properties, or `null` when the line has none — check before reading a key. Properties whose keys start with `__` are always hidden from customers; keys starting with a single `_` are hidden too when the **Hide properties starting with single underscore "\_"** cart setting is on.

* `gift_card (boolean)` - Whether this item is a gift card

* `taxable (boolean)` - Whether this item is subject to tax

* `requires_shipping (boolean)` - Whether this item requires shipping

* `grams (number)` - Item weight in grams

#### **Discounts & Promotions**

* `discounts (Array)` - Simplified discount information:

  * `amount (number)` - Discount amount in cents
  * `title (string)` - Discount title/name

* `line_level_discount_allocations (Array)` - Detailed discount allocation information:

  * `amount (number)` - Discount amount in cents
  * `discount_application (object)` - Full discount application details:

    * `allocation_method (string)` - How discount is allocated
    * `created_at (string)` - When discount was created
    * `description (string | null)` - Discount description
    * `key (string)` - Discount key identifier
    * `target_selection (string)` - What the discount targets
    * `target_type (string)` - Type of target
    * `title (string)` - Discount title
    * `total_allocated_amount (number)` - Total amount allocated
    * `type ('discount_code' | '')` - Discount type (empty string for automatic discounts)
    * `value (string)` - Discount value
    * `value_type (string)` - How value is applied

#### **Bundle Products**

* `has_components (boolean | undefined)` - Whether this item is a bundle containing other products (GET cart responses only)

* `item_components (Array | null | undefined)` - Bundle component details:

  * `quantity (number)` - Quantity of this component
  * `image (object)` - Component image:

    * `url (string)` - Image URL
    * `height (number | null)` - Image height
    * `width (number | null)` - Image width
    * `alt (string)` - Alt text

* `product (object)` - Component product info:

  * `title (string)` - Product title
  * `has_only_default_variant (boolean)` - Whether product has only default variant

* `variantTitle (string)` - Component variant title

#### **Business Rules**

* `quantity_rule (object | undefined)` - Quantity constraints (GET cart responses only):

  * `min (number)` - Minimum allowed quantity
  * `max (number | null)` - Maximum allowed quantity (null = no limit)
  * `increment (number)` - Quantity increment step

#### **Subscription Information**

* `selling_plan_allocation (object | undefined)` - Subscription/selling plan details:

  * `price (number)` - Subscription price in cents
  * `compare_at_price (number | null)` - Subscription compare-at price
  * `per_delivery_price (number)` - Price per delivery
  * `selling_plan (object)` - Selling plan details:

    * `id (number)` - Selling plan ID
    * `name (string)` - Plan name
    * `description (string)` - Plan description
    * `options (Array)` - Plan options:

      * `name (string)` - Option name
      * `position (number)` - Option position
      * `value (string)` - Option value
    * `recurring_deliveries (boolean)` - Whether plan has recurring deliveries

#### **Integration Metadata**

* `__appIntegrated (object | undefined)` - Third-party app integration data:

  * `app ('stay.ai')` - Integrated app identifier
  * `bundleRole ('parent' | 'child')` - Role in bundle structure

## Upsells

The Upsells module allows you to customize upsell product displays with your own design while maintaining essential e-commerce functionality like variant selection, add-to-cart actions, and product information display.

### **Available Props - Upsell tile template**

<img alt="Upsell tile showing a product with sale price, variant dropdown, and Add button" />

`itemUrl`

* **Type**: `string`

* **Description**: The URL of the product page

* **Usage**: Create links to the product detail page for enhanced user navigation

```
<a href={props.itemUrl} className="product-link">  
  <img src={props.imageUrl} alt={props.altText} />  
</a>
```

`imageUrl`

* **Type**: `string | undefined`

* **Description**: The URL of the product image

* **Usage**: Display product images in custom upsell implementations

* **Fallback**: Handle undefined values gracefully with placeholder images

`description`

* **Type**: `string`

* **Description**: The description of product

* **Usage**: Display product description in custom upsell implementations

`altText`

* **Type**: `string`

* **Description**: Alt text for the product image for accessibility

* **Usage**: Provide screen reader support and improve accessibility compliance

```
<img   
  src={props.imageUrl}   
  alt={props.altText}  
  className="product-image"  
/>
```

`productId`

* **Type**: `string`

* **Description**: The unique identifier for the product

* **Usage**: Track products, implement analytics, or use in add-to-cart functionality

`productTitle`

* **Type**: `string`

* **Description**: The title/name of the product

* **Usage**: Display the product name in custom upsell implementations

```
<div>  
  <h3>{props.productTitle}</h3>  
</div>
```

`oldPrice` & `newPrice`

* **Type**: `string | null` (oldPrice), `string` (newPrice)

* **Description**: Formatted compare-at price and current price

* **Usage**: Display pricing information with sale indicators

`isSingleVariant`

* **Type**: `boolean`

* **Description**: Indicates if the product has only one variant

* **Usage**: Conditionally render variant selection UI elements

`productOptions`

* **Type**: `{ name: string; position: 1 | 2 | 3; values: string[]; }[]`

* **Description**: Complete product option configuration including all available choices

* **Usage**: Access detailed product option information for advanced variant selection UI

`variantOptions`

* **Type**: `{ label: string; value: string }[]`

* **Description**: Available variant options for the product

* **Usage**: Create variant selection dropdowns or buttons

* **Structure**: Each option contains a display label and unique value identifier

`selectedVariantId` & `selectedVariantLabel`

* **Type**: string (selectedVariantId), string | undefined (selectedVariantLabel)

* **Description**: Currently selected variant ID and its display label

* **Usage**: Track and display the selected variant information

`onVariantChange`

* **Type**: `(variantId: string) => void`

* **Description**: Function to handle variant selection changes

* **Usage**: Update the selected variant when user makes a selection

`onAddClick`

* **Type**: `(productId: string, variantId?: string) => void`

* **Description**: Function to handle adding the product to cart

* **Usage**: Implement add-to-cart functionality with proper product and variant identification

```
<button   
  onClick={() => props.onAddClick(props.productId, props.selectedVariantId)}  
  disabled={props.addLoading}  
>  
  {props.addLoading ? 'Adding...' : props.addButtonText}  
</button>
```

`rating` & `reviewCount`

* **Type**: `number | undefined` (rating), `string | undefined` (reviewCount)

* **Description**: Product rating and formatted review count text

* **Usage**: Display social proof and product quality indicators

`addLoading` & `addButtonText`

* **Type**: `boolean` (addLoading), `string` (addButtonText)

* **Description**: Loading state for add-to-cart action and button text

* **Usage**: Provide user feedback during cart operations and customize button text

`cartItemsCount`

* **Type**: `number`

* **Description**: The current number of items in the cart

* **Usage**: Display cart status or implement cart-based logic

## Additional Notes

The Notes module allows you to customize cart note functionality with your own design while maintaining essential note-taking capabilities like expandable sections, text input handling, and loading states.

### **Available Props - Full template**

<img alt="Cart notes section with an expandable special instructions text field" />

`cartNote`

* **Type**: `string`

* **Description**: The current cart note content entered by the customer

* **Usage**: Display and manage the cart note text in custom implementations

```
<textarea  
  value={props.cartNote}  
  ...  
/>
```

`notesPlaceholder`

* **Type**: `string`

* **Description**: Placeholder text for the notes input field

* **Usage**: Provide guidance to customers about what to include in their notes

```
<textarea  
  placeholder={props.notesPlaceholder}  
  ...  
/>
```

`notesTitle`

* **Type**: `string`

* **Description**: The title/header text for the notes section

* **Usage**: Display the section title in custom note implementations

```
<h3 className="notes-title" dangerouslySetInnerHTML={{ __html: props.notesTitle }} />
```

`chevronDownIconComponent`

* **Type**: `React.ReactElement`

* **Description**: Pre-rendered chevron icon component for expand/collapse functionality

* **Usage**: Display consistent expand/collapse indicators in custom implementations

`loadingIndicatorComponent`

* **Type**: `React.ReactElement | null`

* **Description**: Pre-rendered loading indicator component for async operations

* **Usage**: Display loading states during note save operations

`handleCartNoteChange`

* **Type**: `(newCartNote: string) => void`

* **Description**: Function to handle cart note content changes

* **Usage**: Update the cart note when user modifies the text

`isExpanded`

* **Type**: `boolean`

* **Description**: Indicates whether the notes section is currently expanded

* **Usage**: Control the visibility of the notes input area

`toggleCollapsible`

* **Type**: `() => void`

* **Description**: Function to toggle the expanded/collapsed state of the notes section

* **Usage**: Attach to buttons or interactive elements to control section visibility

***

## Footer Section

## Add-ons

The Addons module allows you to customize addon product displays with your own design while maintaining essential e-commerce functionality like product information display, pricing, toggle controls, and currency formatting.

### **Available Props - Full template**

<img alt="Add-on product row showing a gift card with price and enable toggle" />

`addonProduct`

* **Type**:

  ```
  {  
    product: {  
      id: number;  
      title: string;  
      description: string;  
    };  
    variant: {  
      id: number;  
      price: number;  
      compare_at_price: number | null;  
    };  
    image: {  
      src: string;  
      alt: string;  
    };  
  }
  ```

* **Description**: Complete addon product information including product details, variant pricing, and image data

* **Usage**: Access all product information needed to display addon products

* **Structure**: Contains nested product, variant, and image objects with comprehensive product data

  * **Product Object Properties** `addonProduct.product`

    * **id**: Unique numeric identifier for the product
    * **title**: Display name of the addon product
    * **description**: HTML description content of the product
  * **Variant Object Properties**

    * **id**: Unique numeric identifier for the variant
    * **price**: Current price in cents
    * **compare\_at\_price**: Original price in cents (null if no comparison price)
  * **Image Object Properties**

    * **src**: URL of the product image
    * **alt**: Alt text for the image (for accessibility)

`toggle`

* **Type**:

  ```
  {  
    state: 'enabled' | 'disabled' | 'loading';  
    handleEnable: () => void;  
    handleDisable: () => void;  
  } | null
  ```

* **Description**: Toggle control state and handlers for enabling/disabling the addon

* **Usage**: Implement interactive toggle functionality for addon selection

* **States**: Three possible states - enabled, disabled, and loading

* **Handlers**: Separate functions for enable and disable actions

`moneyFormat`

* **Type**: `string`

* **Description**: The currency format string used for price formatting

* **Usage**: Pass to the formatMoney function for consistent currency display

`formatMoney`

* **Type**:

  ```
  (options: {  
    cents: string | number;  
    format?: string;  
    shouldRemoveHTML?: boolean;  
  }) => string
  ```

* **Description**: Utility function for formatting currency values

* **Usage**: Format prices consistently with store currency settings

* **Parameters**: Takes cents value, optional format string, and HTML removal option

## Discount Codes

The Discount Code module allows you to customize discount code input functionality with your own design while maintaining essential e-commerce capabilities like code validation, form submission, and user feedback.

### **Available Props - Full template**

<img alt="Discount code input field with an Apply button" />

`indicator`

* **Type**: `'validating' | 'invalid' | 'none'`

* **Description**: Current validation state of the discount code input

* **Usage**: Display appropriate UI feedback based on validation status

* **States**:

  * `validating`: Code is being processed/validated
  * `invalid`: Code validation failed
  * `none`: No validation state (default/idle)

`discountCodeInput`

* **Type**: `string`

* **Description**: Current value of the discount code input field

* **Usage**: Display and manage the discount code text entered by the user

```
<input  
  type="text"  
  value={props.discountCodeInput}  
  onChange={(e) => props.setDiscountCodeInput(e.target.value)}  
  ...  
/>
```

`discountCodePlaceholder`

* **Type**: `string`

* **Description**: Placeholder text for the discount code input field

* **Usage**: Provide guidance to users about what to enter in the input

`discountCodeButtonText`

* **Type**: `string`

* **Description**: Text to display on the apply/submit button

* **Usage**: Customize the button text for discount code submission

`setDiscountCodeInput`

* **Type**: `(value: string | ((prev: string) => string)) => void`

* **Description**: Function to update the discount code input value

* **Usage**: Handle user input changes in the discount code field

`handleSubmit`

* **Type**: `(e: React.FormEvent<HTMLFormElement>) => void`

* **Description**: Function to handle form submission for discount code application

* **Usage**: Process discount code validation and application

* **Event**: Handles form submission events

```
<form onSubmit={props.handleSubmit} >  
  <div className="input-group">  
    <input  
      type="text"  
      value={props.discountCodeInput}  
      onChange={(e) => props.setDiscountCodeInput(e.target.value)}  
      placeholder={props.discountCodePlaceholder}  
    />   
    <button   
      type="submit"  
      disabled={props.indicator === 'validating' || !props.discountCodeInput.trim()}  
    >  
      {props.discountCodeButtonText}  
    </button>  
  </div>  
</form>
```

## Cart Summary

The Cart Summary module allows you to customize cart summary and discount displays with your own design while maintaining essential e-commerce functionality like discount management, savings calculation, and pricing transparency.

### **Available Props - Full template**

<img alt="Cart summary discount row showing an applied discount code and amount" />

`totalSavingsText`

* **Type**: `string`

* **Description**: Text label for the total savings section

* **Usage**: Display the savings label in custom cart summary implementations

`discountApplications`

* **Type**:

  ```
  {  
    key: string;  
    title: string;  
    type: 'discount_code' | '';  
  }[]
  ```

* **Description**: Array of applied discount codes and automatic discounts

* **Usage**: Display all active discounts with their titles and types

* **Structure**: Each discount contains a unique key, display title, and type identifier

`cartTotalDiscount`

* **Type**: `number`

* **Description**: The total discount amount in cents

* **Usage**: Access raw discount value for calculations or custom formatting

`showCartTotalDiscount`

* **Type**: `boolean`

* **Description**: Indicates whether the total discount should be displayed. Marked deprecated in favour of `showTotalSavings`, but see the note below — inside a custom template this is still the prop you have.

* **Usage**: Conditionally render discount information based on settings

`formattedCartTotalDiscount`

* **Type**: `string`

* **Description**: Pre-formatted HTML string of the total discount amount. Marked deprecated in favour of `formattedTotalSavings`, but see the note below.

* **Usage**: Display properly formatted discount amount with currency symbols

<Warning>
  **`showTotalSavings` and `formattedTotalSavings` are not available inside a custom template.** They exist on the module's internal context, but the Cart summary template is handed only `showCartTotalDiscount` and `formattedCartTotalDiscount` — reading the newer pair returns `undefined`. Use the two above, and note that they show the discount total only; they do not follow the **Show compare-at price savings in footer total** setting.
</Warning>

`isRemovingDiscount`

* **Type**: `boolean`

* **Description**: Indicates if a discount removal operation is in progress

* **Usage**: Show loading states during discount removal

`handleRemoveDiscount`

* **Type**: `() => Promise<void>`

* **Description**: Function to handle discount code removal

* **Usage**: Remove applied discount codes from the cart

`totalCompareAtPrice`

* **Type**: `number`

* **Description**: Total compare-at price adds up (all items in the cart)

* **Usage**: Calculate and display savings or original pricing information

`totalAfterAllDiscounts`

* **Type**: `number`

* **Description**: Final cart total in cents after all discounts are applied

* **Usage**: Display the final price customers will pay

`originalTotalPrice`

* **Type**: `number`

* **Description**: Original cart total in cents before any discounts

* **Usage**: Show original pricing for transparency and savings calculation

`cartItemCount`

* **Type**: `number`

* **Description**: Total number of items in the cart

* **Usage**: Display item count information in cart summaries

## Trust Badges

The Trust Badges module allows you to customize trust badge displays with your own design while maintaining essential trust-building functionality like conditional badge visibility and proper image handling.

### **Available Props - Full template**

`showBadge`

* **Type**: `boolean`

* **Description**: Indicates whether the trust badge should be displayed

* **Usage**: Control the visibility of trust badges based on module settings

`badgeUrl`

* **Type**: `string`

* **Description**: The URL of the trust badge image to display

* **Usage**: Source URL for the trust badge image in custom implementations


# Show compare-at price savings in footer total
Source: https://docs.aftersell.com/upcart/show_compare_at_price_savings_in_footer_total

Control how the savings row in your cart footer calculates and displays total savings.

This article explains how savings are calculated and displayed in the cart footer when compare-at prices are enabled.

***

## Overview

Upcart can display total savings in the cart footer by combining:

* Product savings from compare-at prices
* Discount codes applied to the cart

This allows customers to clearly see how much they are saving before checkout.

***

## How to use

1. Open the Upcart editor
2. Go to **Settings > Cart settings**
3. Expand **Advanced Settings** — the checkbox is inside that collapsed section, not on the Cart settings tab itself
4. Enable or disable **Show compare-at price savings in footer total**

<Note>
  This setting applies to the newer cart summary module. Stores that installed Upcart before that module shipped may still be on the earlier one, where the savings row always shows discount-code savings only and the setting has no visible effect. If you enable it and nothing changes, contact support to check which version your cart is on.
</Note>

***

### When enabled

The savings row includes both:

* Compare-at price savings
* Discount code savings

### Example

Product A: Compare-at price \$100, Current price \$80 (20% off)\
Product B: Compare-at price \$50, Current price \$40 (20% off)\
Discount code applied: -\$10

Savings breakdown:

* Product A: \$100 - \$80 = \$20
* Product B: \$50 - \$40 = \$10
* Discount code: \$10

With this setting enabled, the savings row shows:\
**Save \$40** (`(100 - 80) + (50 - 40) + 10`)

***

### When disabled

The savings row only includes discount code savings.

Using the same example:

With this setting disabled, the savings row shows:\
Save \$10 (discount code only)

***

## Why this happens

Compare-at price savings are calculated as the difference between the original price and the current price.

When this setting is enabled, Upcart adds these product-level savings to any discount codes applied to the cart.

When this setting is disabled, only discount codes are included in the savings total shown in the footer.


# Show continue shopping button
Source: https://docs.aftersell.com/upcart/show_continue_shopping_button

Add a “Continue Shopping” link below the Checkout button in the cart drawer.

# Overview

This feature adds a simple text link that closes the cart when clicked. It’s especially helpful for **mobile users**, where tapping the close icon in the top corner may be less accessible.

## **Where to Find It**

Go to:\
**Upcart > Editor > Design** \
Look for the 'buttons' section in the design module, then a checkbox labeled **“Show continue shopping button.”**

<img alt="Upcart button settings with the Show continue shopping button checkbox highlighted" />

## **How It Works**

## ✅ Enabled (Box Checked)

* A **“Continue Shopping”** link appears at the bottom of the cart drawer.
* When clicked, the drawer closes and returns the customer to the storefront.

You can customize the link text with the **Continue shopping button text** field on **Settings > Edit copy**.

<img alt="Cart footer with a Checkout button and an Or continue shopping link below it" />

## ⬜ Disabled (Box Unchecked)

* The link will not appear in the cart.
* Customers will need to manually close the cart using the “X” button.


# Show discounts from base price instead of compare at price
Source: https://docs.aftersell.com/upcart/show_discounts_from_base_price_instead_of_compare_at_price

Choose how product-level savings are calculated and displayed in the cart.

# Overview

This setting controls whether Upcart uses the **original product price** or the **compare-at price** when displaying product savings. It only affects **savings shown on individual line items**, not the total savings above the checkout button.

## **Where to Find It**

Go to:\
**Upcart > Editor > Settings > Cart settings**, then expand **Advanced Settings**\
Look for **“Show discounts from base price instead of from compare at price.”**

## **How It Works**

### Enabled (Box Checked)

**When the line actually has a discount**, savings are calculated from the **original product price**:

```
Original Price - Discounted Price = Savings
```

The strikethrough shown is the product's original price rather than the compare-at price.

**When the line has no discount**, the compare-at price is still used — so enabling this doesn't remove compare-at strikethroughs from undiscounted products.

### Disabled (Box Unchecked)

Savings are calculated using the **compare-at price**.

```
Compare-at Price - Discounted Price = Savings
```

This may overstate the actual discount if the compare-at price is higher than the product’s original base price.


# Show savings below product prices
Source: https://docs.aftersell.com/upcart/show_savings_below_product_prices

Display or hide green savings text beneath product prices in the cart.

# Overview

This setting lets you control whether the text `(Save $___)` appears below discounted product prices inside the cart drawer.

## **Where to Find It**

Go to:\
**Upcart > Editor > Settings > Cart settings**\
Enable or disable the checkbox labeled **“Show savings with product prices.”**

# **How It Works**

## ✅ Enabled (Box Checked)

* Displays a green `(Save $___)` line beneath the product price.
* The amount is the **strikethrough price minus what the line actually costs now**, so any product-level discount already applied — an automatic discount or a discount code that reduced the line — widens it.
* Which price is used as the strikethrough depends on your pricing settings:

  * **Compare at price** (default)
  * **Base price** (if you’ve enabled that in Advanced Settings)

📘 You can learn more about pricing logic here:\
[Show discounts from base price instead of from compare at price?](#)

<img alt="Cart T-Shirt line item showing the discounted price with a Save 5.00 savings line below" />

## ⬜ Disabled (Box Unchecked)

* Hides the savings text entirely.
* Useful if you prefer a cleaner, minimal cart design

<img alt="Cart T-Shirt line item showing the discounted price with the savings line hidden" />


# Sticky cart button
Source: https://docs.aftersell.com/upcart/sticky_cart_button

Add a floating cart icon that remains visible across your storefront and customize its appearance.

# Overview

Upcart’s Sticky Cart Button is a floating cart icon that stays visible as customers scroll, making it easier for them to access their cart at any time. It's especially useful on mobile, where reaching the top-right corner can be difficult.

The button displays the current cart quantity and opens the cart drawer when clicked.

## Where to find it

**Sticky cart** is its own page in Upcart's left-hand navigation — it isn't a tab inside the cart editor.

Here you can activate the button and adjust its styling to match your storefront.

## Cart icon

Select from three icon styles: a bag, a box, or a shopping cart. This icon will appear inside the floating button.

## Background color

This sets the circular background behind the icon. You can choose a color using a hex code or color picker.

## Icon color

This changes the color of the icon symbol itself. For best visibility, use high contrast against the background color.

## Quantity background color

Customize the background color of the cart quantity bubble (the circle that shows the number of items in the cart).

## Quantity text color

Adjust the color of the number inside the quantity bubble. This helps ensure readability, especially with dark or light backgrounds.

## Sticky cart position

Choose where the button appears on the screen. Available positions include:

* Bottom right
* Center right
* Top right
* Bottom left
* Center left
* Top left

This gives you flexibility to avoid overlap with other elements on your store.

## Device settings

Control where the sticky cart appears. Options include:

* Show on all devices
* Show only on desktop
* Show only on mobile

This allows you to tailor the visibility depending on your store’s layout and customer preferences.


# Subscription upgrades module
Source: https://docs.aftersell.com/upcart/subscription_upgrades_module

Let customers switch between one-time purchases and subscriptions directly from the cart using the Subscription Upgrades module.

# Overview

This guide walks you through how to enable and configure these options in Upcart, and includes tips for customizing button text, display labels, and subscription plan formatting. When enabled, the module adds two interactive options to qualifying cart items:

* **Upgrade to a Subscription**
* **Downgrade to a One-Time Purchase (OTP)**

These options appear as dropdowns or buttons next to each eligible product, allowing customers to easily change their purchase type before checking out.

# **Upgrade to a Subscription**

When a product supports subscription plans, customers will see a prompt in the cart to upgrade their purchase. If your product has multiple subscription intervals, the customer can choose between them. They can also revert to a one-time purchase if you allow it.

## Button Text

By default, the upgrade button displays the **Selling Plan Group Name**, which is pulled directly from your subscription app. You can override this by editing the button label and removing the `{{selling_plan_group_name}}` variable if needed.

<img alt="Upcart Button text field set to Upgrade to Subscription beside a cart preview of the upgrade button" />

## Override Subscription Plan Options Text

This setting controls how subscription intervals are shown in the dropdown. The text includes the `{{selling_plan_name}}` variable, which reflects the subscription frequency (e.g. “Delivered every month”). To edit this text, tick **Override subscription plan options text**. This unlocks a field where you can enter your custom label.

<img alt="Upcart override settings for subscription plan options text using selling plan name variables" />

## Subscription Plan Options One-Time Purchase Text

This is the label shown when a customer chooses not to subscribe. The default is “One-time purchase.” To customize this label, tick **Override subscription plan options text**, then use the **Subscription plan options one-time purchase text** field directly beneath it.

The same checkbox unlocks two more fields:

* **Subscription plan full price text** — the dropdown group heading above the one-time option. Defaults to “Full price”.
* **Subscription plans heading text** — the heading above the subscription plan options.

Both the **Selling Plan Group Name** and **Selling Plan Name** are generated by your subscription app, not by Upcart. If you need to localize or translate these names, refer to the settings in your subscription app.

**Note:** Upcart integrates with **[Shopify's Subscription API](https://shopify.dev/docs/api/admin-graphql/2023-10/objects/sellingplan#top)**, meaning it will support all modern subscription applications.

# **Downgrade to a One-Time Purchase**

If a product supports both subscriptions and one-time purchases, customers will also see the option to switch back. This is presented in the same dropdown used to select subscription plans.

<img alt="Upcart cart item with a dropdown to switch between subscribe and save and one-time purchase" />

To restrict customers from switching back to a one-time purchase, enable the **Prevent Downgrades** setting at the bottom of the Subscription Upgrades configuration. When this is checked, the “One-time purchase” option is removed from the dropdown entirely.

Preventing downgrades can help increase subscription conversions, but it may also create friction. If customers aren’t given the flexibility to switch, they might remove the product entirely or abandon their cart. Consider testing this setting before fully enabling it.


# Theme compatibility with Upcart
Source: https://docs.aftersell.com/upcart/theme_compatibility_with_upcart

This article outlines how to troubleshoot theme compatibility issues with Upcart and provides best practices for optimal performance.

## Overview

Upcart is designed to integrate smoothly with most **Shopify-built themes**. However, certain third-party themes may cause functionality issues due to differences in code structure and customization.

Native Shopify themes are developed by Shopify itself, ensuring seamless compatibility, whereas custom or third-party themes may cause issues, even if they are purchased through the Shopify platform.

We recommend using **Shopify’s built-in themes**, such as **Dawn**, which offer the best compatibility and performance with Upcart. Our team has limited scope of support for third-party themes, as variations in how they are developed can lead to conflicts that are outside our control.

For clarification, themes such as FOXECOM, even if bought on Shopify, are categorized as third-party and may have certain limitations in functionality.

***

## Incompatible Themes

The following themes have been found to consistently cause issues with Upcart and are not supported:

* **Trade**

If you are using this theme and experience issues with Upcart, we recommend switching to a more compatible Shopify-built theme to ensure full functionality.

***

## Themes That May Cause Issues

The following themes have been reported to cause conflicts or may not work fully as intended with Upcart:

* **Shrine**
* **Impulse**
* **Impact**
* **Prestige**

While these themes may work in some cases, certain elements or features of Upcart might not display or function as expected. If you experience issues while using any of these themes, we recommend testing with **Dawn** or another Shopify-built theme for the best results.

For themes with compatibility challenges, developers can utilize the [Upcart Public API](https://rokt.notion.site/upcart-public-api) to work towards resolution.

Note

The themes listed are examples of those that have shown potential compatibility issues with Upcart. There may be additional themes not yet identified. This list will be updated as new cases are found or reported.

***

## Partially Supported Themes

Many Shopify themes are compatible with Upcart, and we work to make the app as accessible as possible for merchants using custom or non-default themes.

If you suspect your theme is only partially supported:

This can include engaging a Shopify expert to use the Upcart API, ensuring standard Shopify elements are used, or considering a switch to a native Shopify theme to eliminate compatibility challenges.

1. Review the following articles first:

* [**Change Cart Type in Theme**](/upcart/change_cart_type_in_theme)

- **Malformed Theme Code**

2. If issues persist after following these steps, reach out to **Upcart Support** for further assistance.
3. Provide the theme developer access to the [UpCart Public API](https://rokt.notion.site/upcart-public-api) to resolve theme compatibility issues effectively.

***

## Testing Recommendation

Before making any changes live, we recommend **testing Upcart in a theme preview** or on a **duplicate version** of your theme. This allows you to verify that all cart and upsell features function correctly without affecting your live storefront.

To do this:

1. In your Shopify admin, go to **Online Store > Themes**.
2. Click **Actions** next to your live theme, then select **Duplicate**.
3. Open the duplicate theme and click **Preview**.
4. Test your Upcart setup, including cart interactions, discounts, and upsells.
5. Once confirmed, publish the updated theme.

Testing in advance ensures compatibility and helps prevent any display or performance issues before they impact your customers.

***

## Best Practices

To maintain the best performance and ensure Upcart works smoothly with your theme:

* **Keep your theme up to date.** Shopify and theme developers regularly release updates that improve compatibility and performance.
* **Test after any theme edits.** If you make code or layout changes, test your cart behavior to ensure everything displays correctly.
* **Avoid heavy third-party customizations.** Large design or script modifications can interfere with cart functionality.
* **Use Shopify’s Theme Editor carefully.** Preview changes before publishing to prevent display or checkout issues.

Following these best practices helps maintain a stable setup and ensures your store runs smoothly with Upcart.


# Tiered rewards module - advanced settings
Source: https://docs.aftersell.com/upcart/tiered_rewards_module_advanced_settings

Fine-tune how your rewards bar behaves across international storefronts.

This guide explains optional advanced settings such as reward product linking, automatic currency conversion, and geolocation-based reward thresholds.

📘 *This is the third of three guides on configuring the Rewards Module.*\
See also:\
[General Settings](/upcart/tiered_rewards_module_general_settings) | [Rewards Settings](/upcart/tiered_rewards_module_rewards_settings)

⚠️ *If your store only sells in one currency or market, you may skip this guide.*

## **Accessing advanced settings**

In the Cart Editor, open the **Rewards** module and find the **General settings** card. Below **Text after completing full rewards bar** there is a **Show advanced settings** link — click it to expand the section.

(Pre-discounted cart total is a separate setting, in the **Rewards calculation** card. It isn't on the path to these.)

The advanced section holds up to four settings, and which ones appear depends on your Rewards module version:

* **Remove previous rewards products from cart when reaching higher tier** — give the customer only their most recently earned reward product rather than accumulating all of them. **Version 2 only.**
* **Allow reward product page access from cart**
* **Enable automatic currency conversion**
* **Enable geolocation pricing override**

<img alt="Rewards settings with the Show advanced settings link highlighted below the bar text" />

# **Allow Reward Product Page Access from Cart**

Enable this to let customers **click on reward products** directly from the cart drawer.\
They will be redirected to the product's Shopify page, which is useful when additional information (e.g. sizing, ingredients, or reviews) is available on the product detail page.

## **Enable Automatic Currency Conversion**

Upcart will automatically convert reward thresholds using **Shopify’s real-time exchange rates** based on the customer’s location.

For example, a reward set at **\$100 USD** will appear in the local equivalent, such as **€91 EUR** or **¥14,000 JPY**, depending on the exchange rate at the time.

⚠️ If **Geolocation Pricing Override** is also enabled, Shopify’s exchange rate will apply to any custom values you’ve defined, which may lead to unintended pricing behavior. **We recommend enabling only one** of these settings at a time.

# **Enable Geolocation Pricing Override**

Use this setting to define **custom reward minimums per country** instead of relying on currency conversion.

For example, you may want customers in the US to qualify for a reward at **\$75**, while customers in Japan need to reach **¥1,000**, regardless of exchange rate fluctuations.

This feature works best if your store uses **Shopify Markets** with multiple currencies enabled.

## **What Happens When You Click “Configure Geolocation Pricing”**

<img alt="Configure Geolocation Pricing dialog with US and JP country rules and tier minimum amounts" />

Clicking **“Configure Geolocation Pricing”** opens a setup window where you can create and manage location-specific reward rules.

Each rule lets you define a **target group of countries** and set custom **minimum amounts** for each reward tier. You can choose whether the rule applies **only to the countries selected** or **to all countries except** those listed.

To specify countries, enter the two-letter country codes (e.g., `US` for the United States, `JP` for Japan) into the country selector. Then, enter the desired minimum amounts for **Tier 1**, **Tier 2**, and **Tier 3**. You can fill in any or all of the tiers depending on your reward setup.

**[Shopify List of Country Codes](https://shopify.dev/docs/api/storefront/latest/enums/CountryCode)**

You can add multiple rows to target different markets. For instance, one row might apply a rule to US customers, while another targets Japan.

📌 **Tip on Rule Order:**\
Upcart processes these rules **from top to bottom**. To prevent conflicts, place broad rules (like “All Countries”) **at the bottom**, and more specific ones (e.g. “Only US and JP”) **above** them.

When finished, click **Update** to apply your changes.


# Tiered rewards module- general settings
Source: https://docs.aftersell.com/upcart/tiered_rewards_module_general_settings

Configure Upcart's Rewards Module general settings: empty-cart display, colors, completion text, bar version, item count, and pre-discounted cart total.

The Rewards Module is a key Upcart feature that displays a visual progress bar in the cart drawer, encouraging customers to spend more by tracking their progress toward rewards like free shipping, discounts, or gift items.

This is the first of three guides covering Rewards settings:

* **General Settings** (this document)
* **[Rewards Settings](/upcart/tiered_rewards_module_rewards_settings)**
* **[Advanced Settings](/upcart/tiered_rewards_module_advanced_settings)**

<img alt="Upcart rewards progress bar with free shipping and product milestone icons" />

⚠️ *This module is purely visual and does not apply discounts or shipping logic. To make rewards functional, refer to the [Rewards Settings](/upcart/tiered_rewards_module_rewards_settings) document.*

# General Settings

## Show rewards on empty cart

Enable this option to display the rewards bar even when the cart is empty.

## Colors

Customize the visual appearance of the bar:

* **Bar background color**: Represents what remains to be earned
* **Bar foreground color**: Indicates progress toward a reward
* **Complete reward tier icon color**: The tier icons a customer has already unlocked. **Version 2 only.**
* **Incomplete reward tier icon color**: The tier icons still to be unlocked. **Version 2 only.**

<img alt="Rewards bar preview above bar background and foreground color fields" />

## Text after completing full rewards bar

Add a custom message that appears once all reward tiers have been met. Use formatting tools (bold, italic, underline, color) to style the message as needed. When applying a color, you can use the color picker swatch or type or paste a hex code (for example `#DDDDDD`) into the text field below the picker.

<img alt="Rewards completion message editor with formatting toolbar and sample unlocked text" />

***

## Rewards calculation

This is its own card, below **General settings**. Choose how progress is calculated:

* **Cart total (\$)**\
  Tracks based on the total cart value (e.g., reward at \$100).
* **Cart quantity (#)**\
  Tracks based on the number of items (e.g., reward at 5 items).

  * The selected basis applies to the entire rewards bar and cannot vary by tier.

## Use pre-discounted prices for cart total

In the same **Rewards calculation** card, and only shown when the basis is **Cart total (\$)**. When enabled, rewards are calculated using the cart total before any discounts. This prevents customers from being disqualified for a reward by their own coupon. See [How to exclude discounts in reward goal](/upcart/how_to_exclude_discounts_in_reward_goal).

***

## Filter Which Products Count Toward Rewards

With **Product Filters**, you can control which items in the cart are eligible to contribute toward reward progress. This allows for greater precision and use-case flexibility, such as excluding gift cards or targeting only specific product groups.

<Note>
  These filters require the **Version 2** Rewards module. On Version 1 the filter section doesn't appear at all.
</Note>

You can apply filters by **product**, **collection**, **item property**, or **subscription status**. Each filter can be set to either **include** (only selected items contribute) or **exclude** (everything contributes except selected items). Multiple filters can be combined for layered logic.

## **Product Filter**

This filter lets you include or exclude individual products from the rewards bar.

* **Include**: Only selected products will count toward the reward.
* **Exclude**: All products count except the ones you've excluded.

Use this to isolate high-margin SKUs, exclude promotional items, or remove low-value products like gift cards from reward calculations.

## **Collection Filter**

This filter applies the same logic as the product filter, but at the **collection level**.

* You can include a full Shopify collection (e.g. "Holiday Collection") to count toward rewards.
* Or exclude a collection like "Sale Items" if you don't want discounted products contributing.

Great for batch control without needing to select products individually.

## **Item Property Filter**

Use this filter to include or exclude items based on **line item properties** — metadata that is often added by other apps, custom product options, or internal tagging.

* Add filters using **key-value pairs** (e.g. `upsell: true`, `__upcartRecommendation: [ID]`)
* You can leave the value field blank to filter by key alone (e.g. exclude all items with the key `upsell`, regardless of value)

This is ideal for excluding upsell items, subscriptions, personalized orders, or anything dynamically tagged through your storefront or automation setup.

## **Subscription Status Filter**

This filter lets you include or exclude items based on whether they are subscription items or one-time purchases.

* **Subscription items**: Only items with an active subscription plan will count toward the reward
* **One-time items**: Only items purchased as one-time (non-subscription) will count toward the reward

Use this to create rewards specifically for subscription purchases (e.g., "Add 3 subscription items and get free shipping") or to exclude subscriptions from certain reward tiers.

***

## Advanced Settings

Opens the Advanced Rewards Settings menu. For features like currency-specific rewards and advanced conditions, refer to the **[Advanced Settings](/upcart/tiered_rewards_module_advanced_settings)** guide.


# Tiered rewards module - rewards settings
Source: https://docs.aftersell.com/upcart/tiered_rewards_module_rewards_settings

Display multiple offer tiers using Upcart's rewards bar to encourage higher cart value.

This guide covers how to configure and manage reward tiers, set up different reward types, and customize the customer-facing messaging.

📘 *This is the second of three guides on configuring the Rewards Module.*\
See also:\
[General Settings](/upcart/tiered_rewards_module_general_settings) | [Advanced Settings](/upcart/tiered_rewards_module_advanced_settings)

# Managing Reward Tiers

<img alt="Upcart Tier settings panel with reward type, minimum amount, and tier title fields" />

You can configure **up to four reward tiers** in Upcart's reward bar by default. (Some stores are raised above four — the header tells you your own limit.) The tier settings section displays a tabbed interface where you can manage each tier individually.

The header shows how many tiers you've created (e.g., "2 of 4 tiers created"). By default, one tier appears. Click the **+ Add tier** button to create additional tiers (up to your maximum limit).

To switch between tiers, click on the tier tabs at the top of the settings panel. To delete a tier, click the **X** icon on the active tier's tab.

### Show Reward Icons

Enable this toggle to display an icon alongside your reward tier. Icons are shown automatically if you have **more than one tier.**

# **Reward Types**

The **Reward Type** dropdown determines what kind of reward you're offering. The Tiered Rewards module is a visual progress bar and does not apply the underlying discount or shipping on its own. To activate the actual reward when a customer reaches a tier, create a matching rule in the Discounts module inside Upcart (the simplest option), set up an automatic discount in Shopify Admin, or use a discount management app like Abra.

## Shipping

<img alt="Truck icon representing the free shipping reward type" /> Shows a **truck icon** in the cart drawer. Requires a matching free shipping rule, either in the Discounts module (**Free Shipping** reward, **Cart total** trigger), in Shopify Admin as an automatic discount, or via a discount management app like Abra.

## Discount

<img alt="Discount tag icon representing the discount reward type" /> Shows a **discount tag icon**. Requires a matching discount rule, either in the Discounts module (a **cart discount** reward, **Cart total** trigger), in Shopify Admin as an automatic discount, or via a discount management app like Abra.

### Advanced Discount Code Option

With the **Discount** reward type, you can optionally assign a **manual discount code** that automatically applies when the tier is reached.

* This overrides any manually applied code
* The code stays applied even if the tier is no longer met
* This behaves like a standard Shopify discount once triggered

**Manual discount code stops working when tiered rewards are active**

If your manual discount code stops applying at checkout while tiered rewards are active, this is typically a Shopify discount combination issue. The rewards bar does not create Shopify discounts for free-shipping or free-product tiers — those need a separate rule. It is not inert, though: a **Discount** tier with a **Manual discount code** has Upcart apply that code to the cart itself. Either way the code is a real Shopify discount, so if it isn't set to combine with your other discounts, Shopify will block it.

**Fix:** In Shopify Admin, open the discount code and enable **"Combine with other discounts."** The manual code should then apply alongside active reward tiers as expected.

## Product

<img alt="Gift box icon representing the free product reward type" /> Shows a **gift box icon**

### *Duplicate Product Setup*

1. [**Duplicate the product**](https://help.shopify.com/en/manual/sell-in-person/shopify-pos/inventory-management/products/duplicate-product) in Shopify
2. Set the duplicated version's price to **\$0**
3. Add "Free" to the title to differentiate it
4. Use that product as the reward in Upcart

### ***Discount Method***

You can also create an **automatic discount** in Shopify to apply a **100% discount** to the reward product.

This approach supports inventory tracking, but note that **only one automatic discount** can be applied per checkout. If another is already active, it may override the product reward discount. For more info, refer to [Shopify Discount Documentation](https://help.shopify.com/en/manual/discounts/discount-combinations#considerations-for-discount-combinations).

🛍️ **Multiple Product Reward**:\
You can add up to **three products** to a single reward tier.\
When the tier is reached, **all products are added to the cart**, customers cannot choose just one.

# **Reward Configuration Fields**

### **Reward Description**

Set the display title shown below the reward icon in the cart drawer.

### **Minimum amount**

(Shown when *Rewards calculation = Cart total (\$)*)\
The cart's total (in your store's primary currency) required to unlock the reward.

### **Minimum quantity**

(Shown when *Rewards calculation = Cart quantity (#)*)\
The number of cart items required to unlock the reward.

### **Title before achieving tier**

Customize the message shown above the reward bar when the customer hasn't yet reached the reward.

* Format text using **bold**, *italics*, underline, or color. When applying a color, use the color picker swatch or type or paste a hex code (for example `#DDDDDD`) into the text field below the picker.
* Insert the remaining **amount** (Cart total calculation) or the remaining **count** (Cart quantity calculation) with a variable

The variable syntax depends on which version of the Rewards module your cart is on — the field's own help text shows the right one:

| Rewards module | Remaining amount | Remaining count |
| -------------- | ---------------- | --------------- |
| Version 1      | `{AMOUNT}`       | `{COUNT}`       |
| Version 2      | `{{amount}}`     | `{{count}}`     |


# Traffic allocation
Source: https://docs.aftersell.com/upcart/traffic_allocation

Control what percentage of visitors see Upcart on your store

# **Overview**

Upcart includes a **Traffic Allocation Percentage** slider that lets you define what portion of store visitors will see the cart drawer.

* **100%** (default): All customers see Upcart.
* **50%**: Only half of customers see it.
* **0%**: Upcart is disabled for all customers.

This setting is found in **Settings → Cart settings → Traffic Allocation Percent**.

# **How It Works**

When a customer visits your store for the first time, Upcart generates a random value to determine whether they should see the cart. The value is saved in their browser's **local storage** — deliberately, so a shopper who sees the cart one day doesn't lose it the next.

Because it's local storage rather than a cookie, clearing cookies alone won't reset it. The customer would need to clear the site's local storage, or use a private window.

## **Behavior in Preview Mode**

Preview links from the Cart Editor and the Carts page **skip traffic allocation entirely** — the cart is force-enabled so you always see it, whatever your allocation percentage is set to.

That means a preview can't show you the disabled side of the split. To check what an excluded shopper sees, visit your storefront normally in a browser whose local storage hasn't been assigned yet (a private window works).

## **How to Adjust Traffic Allocation**

1. Navigate to **Settings** in the Upcart Cart Editor.
2. Use the **Traffic Allocation Percent** slider to set the desired percentage.
3. Click **Save** to apply your changes.

<img alt="Cart settings with the Traffic allocation percent slider set to 50 percent" />

### Example:

* Set to **75%**: 3 out of every 4 new visitors will see Upcart.
* Set to **0%**: Useful for temporary disablement without uninstalling the app.


# Troubleshooting Upcart not opening or redirecting to cart page
Source: https://docs.aftersell.com/upcart/troubleshooting_upcart_not_opening_or_redirecting

Troubleshooting guide for cart drawer issues in Upcart including the drawer not opening, redirecting to the cart page, two carts appearing at the same time, cart not loading, or Upcart not responding when adding items to cart.

If Upcart is not opening when customers add items to their cart, opens and then redirects to the cart page, a double cart appears, or one does not appear at all, this guide will help you identify and fix the issue.

## What are you experiencing?

Start here to jump straight to the right solution:

* [**Upcart opens briefly, then redirects to the cart page**](#issue-1--2-upcart-redirecting-to-the-cart-page)
* [**Customers are taken directly to the cart page instead of seeing Upcart**](#issue-1--2-upcart-redirecting-to-the-cart-page)
* [**Two carts are appearing at the same time (Upcart and the theme cart)**](#3-change-theme-cart-type-to-page)
* [**Upcart is not opening at all**](#issue-4-upcart-is-not-opening-at-all)

Not sure which applies? Start with [Step 1](#step-1-make-sure-upcart-is-fully-active) to confirm Upcart is fully enabled before diving into a specific issue.

Most Upcart cart drawer issues are caused by:

* Upcart not being fully enabled
* Theme cart settings conflicting with Upcart
* Enhanced AJAX API Compatibility configuration
* Third-party apps overriding cart behavior
* Theme cart drawers conflicting with Upcart

Follow the steps below in order and test after each change.

***

## Step 1: Make Sure Upcart Is Fully Active

Before troubleshooting anything else, confirm Upcart is properly enabled.

### 1. Ensure the Cart Is Activated

If the cart is disabled inside the Upcart editor, it will not appear on your storefront.

* Open Upcart
* Go to **Manage all carts**
* Confirm the cart is published

### 2. Enable the App Embed

If the app embed is disabled, Upcart will not load.

* Go to **Shopify Admin > Online Store > Themes > Customize**
* Open **App Embeds**
* Toggle **Upcart ON**
* Save

Test your cart after enabling these settings.

<img alt="Activating the Upcart cart and enabling its app embed in Shopify admin" />

***

## Issue 1 & 2: Upcart Redirecting to the Cart Page

If Upcart briefly opens and then redirects, or customers are taken directly to the cart page, this is usually caused by one of the following. Work through each step and test after every change.

### 1. Check Checkout Button Setting in Upcart

If customers click Checkout and are sent back to the cart page:

1. Go to **Upcart > Cart Editor > Settings > Cart settings**
2. Locate **"Go to cart page when pressing checkout button"**
3. Turn this **OFF**
4. Save and test

When enabled, this forces the checkout button to redirect to the cart page instead of proceeding to checkout.

<img alt="Upcart cart settings highlighting the Go to cart page when pressing checkout option" />

### 2. Check Enhanced AJAX API Compatibility

Go to **Upcart > Cart Editor > Settings > Cart settings**, expand **Advanced Settings**, and locate **Enhanced AJAX API Compatibility**.

This setting changes how Upcart handles Add to Cart events:

* **Disabled (recommended for most stores)** - Upcart intercepts Add to Cart calls and prevents redirects
* **Enabled** - Upcart stops intercepting Add to Cart calls, allowing other apps to control cart behavior including redirects

This setting is **disabled by default**. Enable it ONLY if your store uses a non-standard AJAX cart API and Upcart is not intercepting add-to-cart events. If enabling this setting causes redirects, disable it and use the manual Upcart API (`upcartRegisterAddToCart`) instead.

For complete guidance, see [Enhanced AJAX API Compatibility](/upcart/enhanced_ajax_api_compatibility).

<img alt="The Enhanced Ajax API compatibility setting and its description in Upcart" />

### 3. Change Theme Cart Type to "Page"

Your theme's cart drawer or popup may be overriding Upcart.

1. Go to **Shopify Admin > Online Store > Themes**
2. Click **Customize**
3. Open **Theme Settings > Cart**
4. Change **Cart Type** to **Page**
5. Save and test

Setting the cart to "Page" prevents the theme's native drawer from opening instead of Upcart.

<img alt="Setting the theme Cart type to Page in Shopify theme settings" />

<Note>
  If your theme does not include a "Cart Type" (or equivalent) setting, contact your theme developer to locate or add the correct option. Upcart cannot modify theme settings directly.
</Note>

### 4. Disable Theme Cart Redirect Settings

Some themes automatically redirect customers to the cart page after adding a product, bypassing Upcart entirely.

1. Go to **Shopify Admin > Online Store > Themes > Customize**
2. Open **Theme Settings > Products** (or Cart)
3. Look for settings like:
   * Enable cart redirection
   * Redirect to cart after add
   * Go to cart after add
4. Turn these **OFF**, save, and test

### 5. Check for Conflicts With Other Apps

Many third-party apps override cart behavior. Open the settings of any cart-related apps and look for options such as:

* Redirect to cart
* Go to cart after add
* Automatically open cart page
* Action after product is added

Change these to **Stay on page** or **Do nothing** and test after each adjustment.

**Common app-specific fixes:**

* **Globo Product Options** - Disable "Redirect to the shopping cart page after adding a product"
* **Zepto Product Personalizer** - Go to Zepto > Settings > Add to Cart Settings and change "Action after a product is added to the cart" to "Stay on the product page and show a success message"
* **PageFly** - Disable any cart redirect or redirection rules in PageFly settings
* **Replo** - Adjust "go to page" settings to allow the cart drawer to open

If you are unsure which app is causing the conflict, disable cart-related apps one at a time and test after each until Upcart starts working.

***

## Issue 4: Upcart Is Not Opening at All

If nothing happens when customers add to cart or click the cart icon, this is usually caused by a theme conflict or Upcart not detecting the correct buttons.

### Disable Theme's Native Cart Drawer

1. Go to **Shopify Admin > Online Store > Themes > Customize**
2. Open **Theme Settings > Cart**
3. Set cart type to **Page**
4. Save

Make sure Drawer or Popup modes are disabled.

### Upcart Not Detecting Your Buttons?

Some themes use custom code that prevents Upcart from automatically detecting the Add to Cart button or Cart icon. If that's the case, you can manually specify the button selectors.

**Step 1: Find the class name**

1. Open your store in **Google Chrome**
2. Right-click the **Add to Cart button** or **Cart icon**
3. Click **Inspect**
4. In the highlighted code, look for something like:

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
class="icon icon-cart"
```

or

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
class="product-form__submit button"
```

Copy just **one class name** (for example: `icon-cart`). Do not copy `class=` or the quotation marks.

<img alt="Inspecting the cart icon in Chrome DevTools to find its class name" />

**Step 2: Add it in Upcart**

You must add a **dot (.)** before the class name when entering it in Upcart. For example: `.icon-cart`

1. Open **Upcart**
2. Go to **Cart Editor > Settings > Cart settings**, then expand **Advanced Settings**
3. Find the selector group you need:
   * **Open cart button selector** — for the cart icon
   * **Add to cart button selector** — for the add to cart button
4. In that group's **Options** dropdown, choose **Add additional selector** (keeps Upcart's own detection and adds yours) or **Use custom selector** (yours only). The **Custom selector** field stays disabled while **Use default selector** is chosen.
5. Paste `.icon-cart` into **Custom selector** and save

<img alt="Entering a custom Open cart button selector in Upcart advanced settings" />

***

## Additional Troubleshooting

If the issue persists after working through the steps above, try the following one at a time, testing after each change.

### Toggle Shadow DOM (ON/OFF)

In some themes, the Shadow DOM setting affects how Upcart detects buttons and cart events.

1. Go to **Upcart > Cart Editor > Settings > Cart settings**, then expand **Advanced Settings**
2. Locate **Render cart in shadow DOM**
3. Toggle **ON**, save, and test
4. Toggle **OFF**, save, and test again

Use whichever setting produces consistent behavior.

### Toggle AJAX Setting (ON/OFF)

Some stores behave better with AJAX handling switched, depending on theme and app setup.

1. Go to **Upcart > Cart Editor > Settings > Cart settings**, then expand **Advanced Settings**
2. Locate **Enhanced Ajax API compatibility**
3. Toggle **ON**, save, and test
4. Toggle **OFF**, save, and test again

Note that this setting also disables Upcart's own Add to Cart handling, so if turning it on fixes the redirect it's worth confirming add-to-cart still behaves as you expect. See [Enhanced Ajax API compatibility](/upcart/enhanced_ajax_api_compatibility).

### Clear Browser Cache

Old cached scripts can retain previous cart behavior and prevent Upcart from loading correctly.

1. Open browser settings
2. Go to **Privacy & Security**
3. Select **Clear Browsing Data**
4. Clear cached images, files, and cookies
5. Refresh and test

### Test With a Default Shopify Theme

1. Go to **Shopify Admin > Online Store > Themes**
2. Add a free theme such as Dawn
3. Enable it temporarily
4. Test Upcart

If Upcart works with Dawn, the issue is specific to your custom theme. Contact your theme developer for assistance.

### Disable Apps One by One

1. Go to **Shopify Admin > Apps**
2. Disable one cart-related app at a time
3. Test after each

When Upcart starts working, you have identified the conflicting app.

### Check Browser Console for Errors

1. Open your store
2. Press **F12** (or right-click > Inspect)
3. Open the **Console** tab
4. Add a product to cart
5. Look for errors, especially anything related to add.js or cart events
6. Screenshot any errors to share with support

***

## When to Contact Support

If you have completed all steps and Upcart still is not working, reach out to support with:

* Theme name and version
* List of cart-related apps installed
* Console error screenshots
* Steps you have already tried

You can reach Upcart Support through the in-app chat or by emailing [support@upcart.app](mailto:support@upcart.app).


# Trust badges module
Source: https://docs.aftersell.com/upcart/trust_badges_module

Display a trust-building image at the top or bottom of the cart drawer.

You can upload your own badge or select from preset payment icon images. The built-in Trust Badge module simplifies displaying trust badges in your cart and is recommended for ease of use and compatibility.

<img alt="Trust Badge module with payment icon presets, preset image dropdown, and position setting" />

# **Preset Images**

Use the dropdown to apply built-in options like **Payment Icons**. To customize this preset, save the image, edit it in your preferred design tool, and upload it as a new custom badge. Using the built-in Trust Badge module is preferred over custom HTML for simpler styling and reduced conflicts.

# **Custom Badge Upload**

Drag and drop or click the image box to upload your own trust badge. Your image will automatically scale to fit the cart width. This feature is available within the Upcart app’s Trust Badge module, offering an integrated solution for badge uploads.

### Recommended dimensions:

* **1037 × 94 px**, or **1000 px wide** minimum for best quality
* Any image format your browser can upload, including **PNG**, **JPEG**, **GIF** (including animated) and **WebP** — Upcart's own Payment icons preset is a WebP\
  PNG is preferred for clarity and transparency.

## **How to Make a Custom Image**

Need help designing your badge?

Use **[Canva](https://www.canva.com)**, free, beginner-friendly, and perfect for setting custom dimensions.

For high-quality icons or logos, try:

* **[Unsplash](https://unsplash.com)**
* **[Pexels](https://www.pexels.com)**
* **[Pixabay](https://pixabay.com)**

Design your image to fit the recommended dimensions, export as PNG or JPEG, and upload it to Upcart.

# **Position**

Choose to place the image at the **top** or **bottom** of the cart.


# Understanding savings display in Upcart
Source: https://docs.aftersell.com/upcart/understanding_savings_display_in_upcart



Learn how Upcart displays savings to customers, the difference between savings types, and how to troubleshoot common display issues.

Upcart provides multiple ways to display savings to customers, helping to highlight discounts and incentivise purchases. This article explains how each savings display works, where it appears, and how to resolve common issues.

***

### Types of Savings Displayed

**Save Label Below Product Prices**

The `(Save $__)` text shown beneath each product price is the **strikethrough price minus what that line costs now**. Because the second half is the line total *after* product-level discounts, a discount that reduced the line — an automatic discount or a code — does widen this figure; it is not purely a compare-at difference.

Turn it on in **Settings > Cart settings** under **"Show savings with product prices."** You can also configure whether the strikethrough is the compare-at price or the base price. See [Show Discounts from Base Price Instead of Compare at Price](/upcart/show_discounts_from_base_price_instead_of_compare_at_price).

**Savings Above the Checkout Button**

By default, the savings figure above the checkout button reflects only discounts applied at checkout — automatic discounts, manual codes, or bundle discounts — and excludes compare-at price differences.

You can change that. Enabling **Show compare-at price savings in footer total** (in **Settings > Cart settings > Advanced Settings**) switches the row to a combined figure: every item's compare-at difference *plus* the cart's discounts. See [Show compare-at price savings in footer total](/upcart/show_compare_at_price_savings_in_footer_total).

**How Discounts Appear in the Cart**

Product-level discounts display next to the individual product in the cart, whereas order-level discounts show only the total savings in the cart summary row.

***

### Troubleshooting

**Save label not showing on a specific product**

The product must have a compare-at price set that is higher than the current price, and **"Show savings with product prices"** must be enabled in **Settings > Cart settings**. If you are using base price discounts instead of compare-at pricing, check your Advanced Settings configuration. See [Show Savings Below Product Prices](/upcart/show_savings_below_product_prices) for more detail.

**Save label not showing on any products**

No compare-at price is set on the product in Shopify. Set a compare-at price in your Shopify product settings to enable the label.

**Savings line showing a smaller amount than expected**

By default the savings line at the bottom of the cart reflects only checkout discounts — automatic or manual codes — and leaves out compare-at price differences, so it can read lower than the per-product Save labels above it.

The usual fix is to make the two agree: enable **Show compare-at price savings in footer total** in **Settings > Cart settings > Advanced Settings**, and the footer figure will include compare-at savings as well. If you'd rather remove the row instead, see [Hide the Discount Row or Specific Savings Elements](/upcart/hide_the_discount_row_or_specific_savings_elements).

***

### Advanced Customization

A combined savings total — compare-at savings and checkout discounts in one figure — is a **standard setting**, not a custom build: enable **Show compare-at price savings in footer total**. Reach for the [Upcart Public API](/upcart/introduction_to_upcarts_public_api) only for a calculation the built-in options genuinely don't cover.

***

### Related Articles

* [Show Savings Below Product Prices](/upcart/show_savings_below_product_prices)
* [Show compare-at price savings in footer total](/upcart/show_compare_at_price_savings_in_footer_total)
* [Show Discounts from Base Price Instead of Compare at Price](/upcart/show_discounts_from_base_price_instead_of_compare_at_price)
* [Hide the Discount Row or Specific Savings Elements](/upcart/hide_the_discount_row_or_specific_savings_elements)


# Upcart API frequently asked questions
Source: https://docs.aftersell.com/upcart/upcart_api_frequently_asked_questions

Find answers to common questions about using Upcart’s API, including setup, troubleshooting, and third-party integrations.

# Overview

Here are answers to some of the most common questions about using Upcart's API.

* **[Where to add Upcart API Scripts?](#where-to-add-upcart-api-scripts)**
* **[Do I Need to Be a Developer to Use Upcart’s API?](#do-i-need-to-be-a-developer-to-use-upcarts-api)**
* **[Can Upcart’s API integrate with Other Third-Party Apps?](#can-upcarts-api-integrate-with-other-third-party-apps)**
* **[How Do I Test If My API Changes Are Working?](#how-do-i-test-if-my-api-changes-are-working)**
* **[What Should I Do If an API Script Isn’t Working?](#what-should-i-do-if-an-api-script-isnt-working)**
* **[How Do I Undo Changes If I Add a Script That Breaks Something?](#how-do-i-undo-changes-if-i-add-a-script-that-breaks-something)**

***

## **Where to Add Upcart API Scripts?**

You can add scripts in Upcart’s Custom HTML settings or directly in your Shopify theme code. The best option depends on your customization needs.

## How Do I Use Upcart’s Custom HTML?

1. Navigate to **Upcart → Settings → Custom HTML**
2. Use API scripts to modify cart behavior, like opening timing or upsell displays
3. Adjust elements outside Upcart, such as hiding product page buttons

#### 💡 *Example: Hide the sticky cart button when the cart is empty*

```
<script>  
  window.upcartSubscribeCartLoaded((event) => {  
    const itemCount = event.cart.items.reduce((total, item) => total + item.quantity, 0);  
    document.querySelector("#upCartStickyButton").style.display = itemCount === 0 ? "none" : "block";  
    console.log("Sticky Cart is hiding!");  
  });  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnCartLoaded` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeCartLoaded` for all new scripts. Note that `event.cart` does not have an `item_count` property—use `event.cart.items.reduce((total, item) => total + item.quantity, 0)` to calculate the total item count.
</Note>

***

# **Do I Need to Be a Developer to Use Upcart’s API?**

No! Upcart’s API is easy to use, even without coding skills. Many features are built-in, and our [customization docs](/upcart/add_a_mandatory_terms_and_conditions_checkbox_to_your_cart) include pre-written scripts you can copy into Upcart’s Custom HTML settings—no coding required!

If you’d like to write custom scripts, basic JavaScript knowledge helps. If you're new to JavaScript, don’t worry! These beginner-friendly resources—**W3Schools** and **[MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript)**—can help you get started.

***

# Can Upcart’s API integrate with Other Third-Party Apps?

Yes! Upcart’s API works with apps for translations, analytics, upsells, and more. Some integrate automatically, while others may need a small script.

For example, if you're using **[TripleWhale](https://kb.triplewhale.com/en/articles/6610178-adding-the-triple-pixel-to-third-party-checkouts#h_eccf979512)** for tracking, you'll need to add the following script to ensure it records cart activity correctly:

```
<script>  
window.upcartSubscribeAddedToCart((event) => {  
	window.TriplePixel('AddToCart', {item: event.item.variantId, q: event.item.quantityAdded});  
});  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnAddToCart` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeAddedToCart` for all new scripts. Note that the event properties are on `event.item` (with `variantId` and `quantityAdded`), not passed as separate parameters.
</Note>

Since each app is different, consult your app’s support team to see if extra code is needed. Upcart doesn’t offer script support for third-party apps, but your app provider may have an integration guide.

***

# How Do I Test If My API Changes Are Working?

After adding a script to Upcart’s Custom HTML settings, follow these steps to ensure it works:

1. **Refresh your store** and add an item to the cart.

2. **Clear your cache** and try again to see the latest changes.

3. **Add a test message**: Insert `console.log("The script works!");` before `</script>` to check if your script runs.

4. Check your browser console:

   * Open **Dev Tools** (`F12` or `Ctrl + Shift + J` on Windows, `Cmd + Option + J` on Mac).
   * Go to the **Console tab** and look for **"The script works!"**
   * If you see the message, your script is running! If not, the script may not be executing correctly.

5. **Test different actions** (e.g., removing an item) to ensure expected behavior.

**Troubleshoot issues** by checking for typos or console errors and adjusting the code as needed.

***

# What Should I Do If an API Script Isn’t Working?

If your API script isn’t working, try these troubleshooting steps:

* **Check for typos** – Even small errors can break a script. Look for missing characters or incorrect syntax.

* **Verify script placement** – Make sure the script is in the correct section under Upcart → Settings → Custom HTML. Upcart has ten script sections (nine HTML injection points plus one Scripts-before-load section) — [Review these sections here.](/upcart/custom_html)

* **Check the browser console** – Follow the steps above to look for errors.

* **Test a different script** – Try another pre-written Upcart API script to see if the issue is with your code.

* **Still stuck?** – If you're modifying your Shopify theme or integrating third-party apps, a Shopify Expert from the [Shopify Partner Directory](https://www.shopify.com/partners/directory) can help.

These steps should help you identify and resolve most script issues!

***

# How Do I Undo Changes If I Add a Script That Breaks Something?

If you add a script that doesn’t work as expected, you can **easily remove or disable it**:

* **Go to Upcart’s Custom HTML settings** where the script was added.

* **Remove the script** or temporarily disable it by adding `//` at the start of each line (this turns it into a comment, preventing it from running).

* **Save changes & refresh your store** to check if the issue is resolved.

If the issue persists, try clearing your cache or reverting recent theme changes—this often resolves hidden conflicts.

***

🚧 **Looking for Advanced Customizations?**

Need store-wide customizations or third-party app integrations? You may need a developer to add Upcart’s API to your Shopify theme.

Consider hiring a Shopify Expert through the **[Shopify Partner Directory](https://www.shopify.com/partners/directory)** and share our [API documentation](/upcart/introduction_to_upcarts_public_api) with them for assistance


# Upcart CSS selector library (V1)
Source: https://docs.aftersell.com/upcart/upcart_css_selector_library_v1

This article outlines the CSS selectors available in Upcart Version 1, allowing you to apply custom styling to the legacy cart drawer.

📝 **Note**

V1 selectors target the legacy cart drawer modules. If you have upgraded to V2, the module selectors on this page no longer match — see the [V2 CSS Selector Library](/upcart/upcart_css_selector_library_v2) for current selectors.

Two exceptions are worth knowing: `.upcart-cart` and `.upcart-cart-body` are on the drawer shell rather than on a module, so they still apply on V2. Layout fixes that target the drawer as a whole (constraining its width, stopping horizontal overflow) keep working after an upgrade.

# Overview

If you want to change the appearance of your cart, such as hiding a price, adjusting text size, or repositioning a button, this is the place to begin. This CSS selector library provides the tools you need to make those changes with your own custom code.

All available CSS selectors are grouped in this article, along with links to helpful resources for writing and testing your styles.

## **Note**

While we provide this library for your convenience, the Upcart support team **cannot help with building or fixing custom code.** This is part of our [Customization Policy](/upcart/upcart_customization_policy).

We recommend consulting with a Shopify Expert for custom code solutions.

[See Shopify Experts](https://www.shopify.com/ca/partners/directory)

# How to Use Upcart CSS Selectors

This article is a **library of CSS selectors** you can use to style and customize your Upcart cart drawer. Each selector targets a specific part of the cart—like the header, product rows, upsells, rewards module, and more.

You can use these selectors to:

* Hide or restyle elements
* Change spacing, fonts, or colors
* Adjust layout based on your store's branding

To apply your CSS, open the Cart Editor, go to **Settings**, select the **Custom CSS** tab, and paste your styles into the editor.

# What to Know Before Adding CSS

Before jumping into your custom styles, here are a few tips to help things go smoothly. These will make it easier to test changes, avoid surprises, and get the look you want without breaking anything in your cart.

## CSS Customization Checklist:

* **Test in a safe environment:** Use a preview or unpublished theme when possible before going live.

* **Start small:** Make one change at a time so it's easier to track what worked or didn't.

* **Paste styles in the right place:** Use the **Upcart Editor > Settings > Custom CSS** field to add your code.

* **Use Inspect Tool:** Right-click on elements in your browser and select **Inspect** to find and test selectors live.

* **Avoid assumptions:** Not every element appears on all carts—test with different carts (with/without rewards, upsells, etc.).

# CSS Selectors Library

Below is a list of all the CSS selectors available in Upcart. These are grouped by **module** (like header, products, upsells, etc.) to make it easier for you to find what you want to customize. Use this as a reference when writing your own styles.

## General Settings

### Design Module

|                     |                                                |
| ------------------- | ---------------------------------------------- |
| **CSS Selector**    | **Description**                                |
| `.upcart-cart`      | Main container for the cart drawer.            |
| `.upcart-cart-body` | Holds the primary content of the cart.         |
| `.upcart-backdrop`  | The dark overlay that appears behind the cart. |

### Header Module

|                                    |                                                                     |
| ---------------------------------- | ------------------------------------------------------------------- |
| **CSS Selector**                   | **Description**                                                     |
| `.upcart-header`                   | Container for the cart header, including the logo and close button. |
| `.upcart-header-close-button`      | Button used to close the cart drawer.                               |
| `.upcart-header-close-button-icon` | The icon displayed inside the close button.                         |
| `.upcart-header-logo`              | Displays the logo image in the cart header.                         |
| `.upcart-header-text`              | The title text displayed in the cart header.                        |

## Body Settings

### Announcements Module

|                                 |                                                    |
| ------------------------------- | -------------------------------------------------- |
| **CSS Selector**                | **Description**                                    |
| `.upcart-announcement`          | Banner or announcement section within the cart.    |
| `.upcart-announcement-skeleton` | Skeleton placeholder for the announcement section. |

### Rewards Module

|                                    |                                                   |
| ---------------------------------- | ------------------------------------------------- |
| **CSS Selector**                   | **Description**                                   |
| `.upcart-rewards`                  | Main container for the rewards section.           |
| `.upcart-rewards-message`          | Displays progress messages related to rewards.    |
| `.upcart-rewards-bar-background`   | Background layer of the rewards progress bar.     |
| `.upcart-rewards-bar-foreground`   | Foreground/progress fill of the rewards bar.      |
| `.upcart-rewards-tier`             | Represents a specific tier in the rewards system. |
| `.upcart-rewards-tier-circle`      | Visual circle indicator for a reward tier.        |
| `.upcart-rewards-tier-icon`        | Icon inside a reward tier circle.                 |
| `.upcart-rewards-tier-description` | Description text under each reward tier.          |
| `.upcart-rewards-skeleton`         | Skeleton container for the rewards section.       |
| `.upcart-rewards-message-skeleton` | Skeleton for the rewards progress message.        |
| `.upcart-rewards-bar-skeleton`     | Skeleton for the rewards progress bar.            |

### Recommendations Module

|                                           |                                                              |
| ----------------------------------------- | ------------------------------------------------------------ |
| **CSS Selector**                          | **Description**                                              |
| `.upcart-recommendation-module`           | Wrapper for the entire product recommendation module.        |
| `.upcart-recommendations-title`           | Title text for the recommendations section.                  |
| `.upcart-recommendations-shop-now-button` | Button to shop a recommended product directly from the cart. |

### Subscription Upgrades Module

|                                         |                                                            |
| --------------------------------------- | ---------------------------------------------------------- |
| **CSS Selector**                        | **Description**                                            |
| `.upcart-subscription-upgrade-section`  | Section for promoting subscription upgrades in the cart.   |
| `.upcart-subscription-upgrade-button`   | Button used to trigger a subscription upgrade.             |
| `.upcart-subscription-upgrade-dropdown` | Dropdown to select available subscription upgrade options. |

### Upsells Module

|                                        |                                                |
| -------------------------------------- | ---------------------------------------------- |
| **CSS Selector**                       | **Description**                                |
| `.upcart-upsells`                      | Main container for the upsells section.        |
| `.upcart-upsells-module`               | Wrapper for the upsells module.                |
| `.upcart-upsells-title`                | Title of the upsells section.                  |
| `.upcart-upsells-button`               | Button to add upsell items to cart.            |
| `.upcart-upsell-item-card`             | Card layout for each upsell product.           |
| `.upcart-upsell-item-title`            | Title of the upsell product.                   |
| `.upcart-upsell-item-image-wrapper`    | Wrapper around the upsell product image.       |
| `.upcart-upsell-item-image`            | Image of the upsell product.                   |
| `.upcart-upsell-item-price`            | Price of the upsell item.                      |
| `.upcart-upsell-item-price-row`        | Row containing price and compare price.        |
| `.upcart-upsell-item-compare-price`    | Original price (strikethrough) for the upsell. |
| `.upcart-upsell-item-variant-selector` | Variant dropdown for upsell products.          |

### Product Settings

|                                      |                                                   |
| ------------------------------------ | ------------------------------------------------- |
| **CSS Selector**                     | **Description**                                   |
| `.upcart-products-section`           | Container for all products in the cart.           |
| `.upcart-product-item`               | Wrapper for an individual product item.           |
| `.upcart-product-title`              | Name of the product in the cart.                  |
| `.upcart-product-title-link`         | Link that wraps the product title.                |
| `.upcart-item-prices-row`            | Row that contains pricing information.            |
| `.upcart-item-price`                 | Final price shown to the customer.                |
| `.upcart-item-compare-price`         | Original (strikethrough) price.                   |
| `.upcart-product-savings`            | Specific savings for a cart item.                 |
| `.upcart-item-option`                | Container for product options like size or color. |
| `.upcart-item-option-category`       | Label for the product option category.            |
| `.upcart-item-option-value`          | Value of the selected product option.             |
| `.upcart-item-properties`            | Wrapper for additional product metadata.          |
| `.upcart-item-property`              | Individual product property.                      |
| `.upcart-item-property-subscription` | Displays subscription details for the item.       |
| `.upcart-product-quantity-input`     | Quantity input field for the product.             |
| `.upcart-product-quantity-minus`     | Button to decrease quantity.                      |
| `.upcart-product-quantity-plus`      | Button to increase quantity.                      |
| `.upcart-product-image-wrapper`      | Wrapper around the product image.                 |
| `.upcart-quantity-warning`           | Container for any quantity limit message.         |
| `.upcart-quantity-warning-text`      | Text for quantity warning shown to the user.      |

## Footer Settings

### Add-ons Module

|                                      |                                               |
| ------------------------------------ | --------------------------------------------- |
| **CSS Selector**                     | **Description**                               |
| `.upcart-addons`                     | Main container for the add-ons section.       |
| `.upcart-addons-title`               | Title of the add-ons section.                 |
| `.upcart-addons-product-description` | Description of the add-on product.            |
| `.upcart-addons-price`               | Price of the add-on product.                  |
| `.upcart-addons-compare-price`       | Original (strikethrough) price of the add-on. |
| `.upcart-addons-toggle`              | Toggle switch to add/remove an add-on.        |
| `.upcart-addons-image-wrapper`       | Wrapper for the add-on image.                 |

### Discount Codes Module

### Savings Row

|                                  |                                                                      |
| -------------------------------- | -------------------------------------------------------------------- |
| **CSS Selector**                 | **Description**                                                      |
| `.upcart-savings-row`            | Wrapper for the entire discount/savings section in the cart.         |
| `.styles_Footer__savingsCodes__` | Container for the label ("Discounts") and associated discount codes. |
| `.upcart-discount-code-badge`    | Wrapper for each discount code badge shown in the UI.                |
| `.upcart-discount-code-icon`     | Container for the discount icon (e.g., SVG ticket symbol).           |
| `.upcart-discount-code-text`     | Textual representation of the discount code (e.g., "AUTO 5").        |
| `.upcart-savings-amount`         | Displays the actual amount saved from discounts.                     |

### Express Payments Module

## Note

The Express Payments buttons in Upcart serve as visual containers, while the content and functionality within them are fully controlled by Shopify. As a result, we're unable to modify their behavior or appearance. Refer to the [**Express Payments Module**](/upcart/express_payments_module) Guide for more information.

|                                         |                                                 |
| --------------------------------------- | ----------------------------------------------- |
| **CSS Selector**                        | **Description**                                 |
| `.upcart-express-pay-buttons-container` | Container for all express pay buttons.          |
| `.upcart-express-pay-buttons-row`       | Row layout for express pay buttons.             |
| `.upcart-express-pay-button`            | General selector for an express payment button. |
| `.upcart-express-pay-button-shop-pay`   | Specific button for Shop Pay.                   |
| `.upcart-express-pay-button-google-pay` | Specific button for Google Pay.                 |
| `.upcart-express-pay-button-paypal`     | Specific button for PayPal.                     |
| `.upcart-express-pay-button-apple-pay`  | Specific button for Apple Pay.                  |
| `.upcart-express-pay-button-amazon-pay` | Specific button for Amazon Pay.                 |
| `.upcart-express-pay-button-meta-pay`   | Specific button for Meta Pay.                   |

### Trust Badges Module

|                             |                                      |
| --------------------------- | ------------------------------------ |
| **CSS Selector**            | **Description**                      |
| `.upcart-trust-badge`       | Container for the trust badges.      |
| `.upcart-trust-badge-image` | Image element used in a trust badge. |

### Additional Notes Module

|                                                   |                                                  |
| ------------------------------------------------- | ------------------------------------------------ |
| **CSS Selector**                                  | **Description**                                  |
| `.NotesModule_NotesModule__`                      | Container for the additional notes.              |
| `.NotesModule_NotesModule__titleContainer__`      | Title container of the notes section             |
| `.NotesModule_NotesModule__dropdownContainer__`   | Title for the dropdown of the notes section      |
| `.NotesModule_NotesModule__textModule__ textarea` | Input area for adding a custom note to the cart. |

## Upcart Settings Module

### Skeleton Selectors

|                                                  |                                                 |
| ------------------------------------------------ | ----------------------------------------------- |
| **CSS Selector**                                 | **Description**                                 |
| `.upcart-skeleton`                               | General skeleton loader wrapper for the cart.   |
| `.upcart-product-item-skeleton`                  | Placeholder while a product loads.              |
| `.upcart-product-image-skeleton`                 | Placeholder for a product image.                |
| `.upcart-product-title-skeleton`                 | Placeholder for product title text.             |
| `.upcart-product-price-container-skeleton`       | Placeholder for pricing area.                   |
| `.upcart-product-quantity-skeleton`              | Placeholder for quantity controls.              |
| `.upcart-item-option-skeleton`                   | Placeholder for item options.                   |
| `.upcart-upsells-module-skeleton`                | Skeleton for the upsells module.                |
| `.upcart-upsells-title-skeleton`                 | Skeleton for upsell section title.              |
| `.upcart-upsell-item-image-skeleton`             | Skeleton for upsell product image.              |
| `.upcart-upsell-item-title-skeleton`             | Skeleton for upsell product title.              |
| `.upcart-upsell-item-price-skeleton`             | Skeleton for upsell product price.              |
| `.upcart-upsells-button-skeleton`                | Skeleton for upsell action button.              |
| `.upcart-trust-badge-skeleton`                   | Skeleton for trust badge container.             |
| `.upcart-trust-badge-image-skeleton`             | Skeleton for trust badge image.                 |
| `.upcart-announcement-skeleton`                  | Skeleton placeholder for announcements.         |
| `.upcart-rewards-skeleton`                       | Skeleton for the rewards section.               |
| `.upcart-rewards-message-skeleton`               | Skeleton for reward messages.                   |
| `.upcart-rewards-bar-skeleton`                   | Skeleton for reward progress bar.               |
| `.upcart-addons-skeleton`                        | Skeleton for the add-ons section.               |
| `.upcart-addons-image-wrapper-skeleton`          | Skeleton for add-on product image.              |
| `.upcart-addons-skeleton-text-container`         | Skeleton for text content in add-ons.           |
| `.upcart-discount-code-module-skeleton`          | Skeleton for discount code module.              |
| `.upcart-discount-code-input-skeleton`           | Skeleton for discount code input.               |
| `.upcart-discount-code-button-skeleton`          | Skeleton for discount code apply button.        |
| `.upcart-checkout-button-container-skeleton`     | Skeleton for checkout button wrapper.           |
| `.upcart-checkout-button-skeleton`               | Skeleton for checkout button.                   |
| `.upcart-express-pay-buttons-container-skeleton` | Skeleton for express payment container.         |
| `.upcart-express-pay-button-skeleton`            | Skeleton for individual express payment button. |

## **Helpful resources to get started:**

* **[Getting Started with Custom CSS](/upcart/custom_css):** Learn how to safely add custom CSS in Upcart.
* **[Intro to Customizations in Upcart](/upcart/getting_started_with_upcart_customizations):** Understand how customization works and where to start.
* **[Use AI to Write Custom Code for Upcart](/upcart/ai_prompt_suggestions_for_adding_custom_code_to_your_upcart_settings):** Get help writing CSS or JavaScript using simple prompts.
* **[Best Practices to Increase Cart Conversions](/upcart/best_practices_to_increase_upcart_conversions):** Optimize your cart design with proven tips.


# Upcart CSS selector library (V2)
Source: https://docs.aftersell.com/upcart/upcart_css_selector_library_v2

This article outlines the CSS selectors available in Upcart Version 2, designed to support custom styling for the updated cart drawer and module structure.

⚠️ **IMPORTANT NOTICE**

These selectors apply **only to Version 2 (V2)** of the Upcart cart modules. If you are using **Version 1 (V1)**, these selectors will not work.

For V1 carts, please refer to the **[Version 1 CSS Selectors documentation](/upcart/upcart_css_selector_library_v1)**, which covers the legacy module structure and selectors.

To check which version you’re using, open the Cart Editor and look at the top of the left-hand menu. A **Cart version** dropdown appears there once every module in the cart is on V2; if you don’t see it, your cart still has V1 modules. For more information about migrating from V1 to V2, see the [V2.0 migration guide](/upcart/upcart_v20_migration_guide).

# Overview

If you want to change the appearance of your cart, such as hiding a price, adjusting text size, or repositioning a button, this is the place to begin. This CSS selector library provides the tools you need to make those changes with your own custom code.

All available CSS selectors are grouped in this article, along with links to helpful resources for writing and testing your styles.

## NOTE

While we provide this library for your convenience, the Upcart support team **cannot help with building or fixing custom code.** This is part of our [Customization Policy](/upcart/upcart_customization_policy).

We recommend consulting with a Shopify Expert for custom code solutions.

[See Shopify Experts](https://www.shopify.com/ca/partners/directory)

##

# How to Use Upcart CSS Selectors

This article is a **library of CSS selectors** you can use to style and customize your Upcart cart drawer. Each selector targets a specific part of the cart—like the header, product rows, upsells, rewards module, and more.

You can use these selectors to:

* Hide or restyle elements
* Change spacing, fonts, or colors
* Adjust layout based on your store’s branding

To apply your CSS, open the Cart Editor, go to **Settings**, select the **Custom CSS** tab, and paste your styles into the editor.

# What to Know Before Adding CSS

Before jumping into your custom styles, here are a few tips to help things go smoothly. These will make it easier to test changes, avoid surprises, and get the look you want without breaking anything in your cart.

## CSS Customization Checklist:

* **Test in a safe environment:** Use a preview or unpublished theme when possible before going live.

* **Start small:** Make one change at a time so it's easier to track what worked or didn’t.

* **Paste styles in the right place:** Use the **Upcart Editor > Settings > Custom CSS** field to add your code.

* **Use Inspect Tool:** Right-click on elements in your browser and select **Inspect** to find and test selectors live.

* **Avoid assumptions:** Not every element appears on all carts—test with different carts (with/without rewards, upsells, etc.).

The following selectors work with Version 2 of Upcart cart modules. V2 introduces a structured naming system with **public** and **internal** class prefixes.

## **Important guidelines for V2 selectors**

⚠️ **Use only public selectors for customization**

* **Public selectors** (prefixed with `upcart-public-`) are part of the stable API and safe to use for custom styling
* **Internal selectors** (prefixed with `upcart-internal-`) are reserved for internal use and may change without notice

✅ **DO:** Use public class names for styling

```
/* ✅ Correct usage */   
.upcart-public-header {     
    font-size: 18px;     
    font-weight: bold;   
}
```

❌ **DON’T:** Override internal classnames or use deep selectors

```
/* ❌ Avoid this */   
.upcart-internal-header {     
    font-size: 18px;     
    font-weight: bold;   
}    
  
/* ❌ Avoid this */   
.upcart-public-upsell div a {     
   font-size: 18px;     
   font-weight: bold;   
}
```

#

# CSS Selectors

### **General Components**

|                                                          |                                                 |
| -------------------------------------------------------- | ----------------------------------------------- |
| **CSS Selector**                                         | **Description**                                 |
| `.upcart-public-skeleton`                                | General skeleton loader wrapper for the cart.   |
| `.upcart-public-component__button`                       | General button component used across modules.   |
| `.upcart-public-component-loader`                        | Loading spinner component.                      |
| `.upcart-public-component-tag`                           | Tag component wrapper.                          |
| `.upcart-public-component-tag__icon`                     | Icon inside a tag.                              |
| `.upcart-public-component-tag__text`                     | Text content of a tag.                          |
| `.upcart-public-component-tag__remove-button`            | Remove ("x") button inside a removable tag.     |
| `.upcart-public-component-collapse__dropdown-container`  | Container for collapsible dropdown sections.    |
| `.upcart-public-component-collapse__expand-icon`         | Icon that indicates expand/collapse state.      |
| `.upcart-public-component-carousel__container`           | Outer wrapper of a carousel.                    |
| `.upcart-public-component-carousel__window`              | Clipping window the slides scroll inside.       |
| `.upcart-public-component-carousel__track`               | The moving track holding the slides.            |
| `.upcart-public-component-carousel__slide`               | A single carousel slide.                        |
| `.upcart-public-component-carousel__button`              | Previous / next arrow button.                   |
| `.upcart-public-component-progress-bar`                  | Plain (unsegmented) progress bar component.     |
| `.upcart-public-component-progress-bar__track`           | Track of the plain progress bar.                |
| `.upcart-public-component-progress-bar__fill`            | Filled portion of the plain progress bar.       |
| `.upcart-public-component-progress-bar__milestone`       | Milestone marker on the plain progress bar.     |
| `.upcart-public-component-progress-bar__milestone-icon`  | Icon at a milestone on the plain progress bar.  |
| `.upcart-public-component-progress-bar__milestone-label` | Label at a milestone on the plain progress bar. |

#

### **Header module**

|                                            |                                         |
| ------------------------------------------ | --------------------------------------- |
| **CSS Selector**                           | **Description**                         |
| `.upcart-public-header`                    | Main container for the cart header.     |
| `.upcart-public-header__logo`              | Logo image in the cart header.          |
| `.upcart-public-header__close-button`      | Button used to close the cart drawer.   |
| `.upcart-public-header__close-button-icon` | Icon displayed inside the close button. |

### **Announcements module**

|                                        |                                                 |
| -------------------------------------- | ----------------------------------------------- |
| **CSS Selector**                       | **Description**                                 |
| `.upcart-public-announcement`          | Banner or announcement section within the cart. |
| `.upcart-public-announcement-skeleton` | Skeleton loader for announcement bar.           |

### **Recommendation and Upsell modules**

|                                                          |                                                     |
| -------------------------------------------------------- | --------------------------------------------------- |
| **CSS Selector**                                         | **Description**                                     |
| `.upcart-public-upsell`                                  | Main wrapper for the upsell module.                 |
| `.upcart-public-upsell__header`                          | Header of the upsell section.                       |
| `.upcart-public-upsell__title`                           | Title text of the upsell section.                   |
| `.upcart-public-upsell__shop-now-button`                 | Shop Now button on upsell items.                    |
| `.upcart-public-upsell__vertical-layout-wrapper`         | Wrapper for vertical upsell layout.                 |
| `.upcart-public-component-upsell-tile`                   | Card layout for each upsell/recommendation product. |
| `.upcart-public-component-upsell-tile__image-container`  | Container for the upsell product image.             |
| `.upcart-public-component-upsell-tile__image`            | Image of the upsell product.                        |
| `.upcart-public-component-upsell-tile__info`             | Information section of the upsell tile.             |
| `.upcart-public-component-upsell-tile__title-link`       | Link wrapper for the product title.                 |
| `.upcart-public-component-upsell-tile__title`            | Title of the upsell product.                        |
| `.upcart-public-component-upsell-tile__rating-row`       | Row containing product ratings.                     |
| `.upcart-public-component-upsell-tile__stars`            | Star rating display.                                |
| `.upcart-public-component-upsell-tile__star--partial`    | Partial star for fractional ratings.                |
| `.upcart-public-component-upsell-tile__reviews`          | Review count display.                               |
| `.upcart-public-component-upsell-tile__price-row`        | Row containing price information.                   |
| `.upcart-public-component-upsell-tile__price-compare-at` | Original (strikethrough) price for the upsell.      |
| `.upcart-public-component-upsell-tile__price`            | Current price of the upsell item.                   |
| `.upcart-public-component-upsell-tile__variant-row`      | Row containing variant selection.                   |
| `.upcart-public-upsell__skeleton`                        | Skeleton placeholder for upsell module.             |
| `.upcart-public-upsell__skeleton-title`                  | Skeleton for upsell section title.                  |
| `.upcart-public-upsell__skeleton-image`                  | Skeleton for upsell product image.                  |
| `.upcart-public-upsell__skeleton-product-title`          | Skeleton for upsell product title.                  |
| `.upcart-public-upsell__skeleton-product-price`          | Skeleton for upsell product price.                  |

### **Notes module**

|                                        |                                                       |
| -------------------------------------- | ----------------------------------------------------- |
| **CSS Selector**                       | **Description**                                       |
| `.upcart-public-notes`                 | Main container for the notes section.                 |
| `.upcart-public-notes__text-container` | Container for the notes text area.                    |
| `.upcart-public-notes__textarea`       | Text input area for adding a custom note to the cart. |

### **Discount code module**

|                                                 |                                                |
| ----------------------------------------------- | ---------------------------------------------- |
| **CSS Selector**                                | **Description**                                |
| `.upcart-public-discount-code`                  | Main container for the discount code section.  |
| `.upcart-public-discount-code__form`            | Form wrapper for discount code input.          |
| `.upcart-public-discount-code__input-wrapper`   | Wrapper for the discount code input field.     |
| `.upcart-public-discount-code__input`           | Input field for entering discount codes.       |
| `.upcart-public-discount-code__suffix`          | Suffix element for the input field.            |
| `.upcart-public-discount-code__error`           | Error message display for invalid codes.       |
| `.upcart-public-discount-code__button`          | Button to apply discount code.                 |
| `.upcart-public-discount-code__skeleton`        | Skeleton placeholder for discount code module. |
| `.upcart-public-discount-code__skeleton-input`  | Skeleton for discount code input field.        |
| `.upcart-public-discount-code__skeleton-button` | Skeleton for discount code apply button.       |

### **Trust badges module**

|                                      |                                      |
| ------------------------------------ | ------------------------------------ |
| **CSS Selector**                     | **Description**                      |
| `.upcart-public-trust-badges`        | Container for the trust badges.      |
| `.upcart-public-trust-badges__image` | Image element used in a trust badge. |

### **Tiered rewards module**

|                                                                                  |                                                |
| -------------------------------------------------------------------------------- | ---------------------------------------------- |
| **CSS Selector**                                                                 | **Description**                                |
| `.upcart-public-rewards`                                                         | Main container for the rewards section.        |
| `.upcart-public-rewards__message`                                                | Displays progress messages related to rewards. |
| `.upcart-public-rewards__bar`                                                    | Container for the rewards progress bar.        |
| `.upcart-public-component-segmented-progress-bar`                                | Segmented progress bar component.              |
| `.upcart-public-component-segmented-progress-bar__segments-container`            | Container for all progress bar segments.       |
| `.upcart-public-component-segmented-progress-bar__segment`                       | Individual segment of the progress bar.        |
| `.upcart-public-component-segmented-progress-bar__segment-fill`                  | Fill portion of a progress bar segment.        |
| `.upcart-public-component-segmented-progress-bar__milestone`                     | Milestone marker on the progress bar.          |
| `.upcart-public-component-segmented-progress-bar__milestone--bottom`             | Milestone positioned at the bottom.            |
| `.upcart-public-component-segmented-progress-bar__milestone--top`                | Milestone positioned at the top.               |
| `.upcart-public-component-segmented-progress-bar__milestone--middle`             | Milestone positioned in the middle.            |
| `.upcart-public-component-segmented-progress-bar__milestone-icon`                | Icon displayed at a milestone.                 |
| `.upcart-public-component-segmented-progress-bar__milestone-label`               | Label text for a milestone.                    |
| `.upcart-public-component-segmented-progress-bar__milestone-label--align-right`  | Right-aligned milestone label.                 |
| `.upcart-public-component-segmented-progress-bar__milestone-label--align-center` | Center-aligned milestone label.                |
| `.upcart-public-rewards__skeleton`                                               | Skeleton container for the rewards section.    |
| `.upcart-public-rewards__skeleton-message`                                       | Skeleton for the rewards progress message.     |
| `.upcart-public-rewards__skeleton-bar`                                           | Skeleton for the rewards progress bar.         |

### **Cart items module**

|                                                                   |                                                     |
| ----------------------------------------------------------------- | --------------------------------------------------- |
| **CSS Selector**                                                  | **Description**                                     |
| `.upcart-public-cart-items`                                       | Main wrapper for the cart items list.               |
| `.upcart-public-cart-item`                                        | Individual cart item wrapper.                       |
| `.upcart-public-cart-items-skeleton__content`                     | Skeleton loader for cart items.                     |
| `.upcart-public-component-product-tile`                           | Wrapper for an individual product item in the cart. |
| `.upcart-public-component-product-tile__content`                  | Content area of the product tile.                   |
| `.upcart-public-component-product-tile__image-wrapper`            | Wrapper around the product image.                   |
| `.upcart-public-component-product-tile__image`                    | Image of the product in the cart.                   |
| `.upcart-public-component-product-tile__info`                     | Information section of the product tile.            |
| `.upcart-public-component-product-tile__header`                   | Header section of the product tile.                 |
| `.upcart-public-component-product-tile__product-title`            | Name of the product in the cart.                    |
| `.upcart-public-component-product-tile__title-link`               | Link that wraps the product title.                  |
| `.upcart-public-component-product-tile__remove-button`            | Button to remove the product from cart.             |
| `.upcart-public-component-product-tile__variant`                  | Variant information display.                        |
| `.upcart-public-component-product-tile__properties`               | Wrapper for additional product metadata.            |
| `.upcart-public-component-product-tile__bundle`                   | Bundle information section.                         |
| `.upcart-public-component-product-tile__product-pricing`          | Pricing section of the product tile.                |
| `.upcart-public-component-product-tile__price-compare-at`         | Original (strikethrough) price.                     |
| `.upcart-public-component-product-tile__price`                    | Final price shown to the customer.                  |
| `.upcart-public-component-product-tile__price-group`              | Wrapper around the price and compare-at price.      |
| `.upcart-public-component-product-tile__savings`                  | Specific savings for a cart item.                   |
| `.upcart-public-component-product-tile__controls`                 | Controls section (quantity, etc.).                  |
| `.upcart-public-component-product-tile__quantity-selector`        | Quantity selector wrapper.                          |
| `.upcart-public-component-product-tile__quantity-minus`           | Button to decrease quantity.                        |
| `.upcart-public-component-product-tile__quantity-plus`            | Button to increase quantity.                        |
| `.upcart-public-component-product-tile__discount-codes`           | Discount codes applied to the item.                 |
| `.upcart-public-component-product-tile__subscription-upgrade`     | Subscription upgrade section.                       |
| `.upcart-public-component-product-tile__subscription-upgrade-btn` | Button that applies the subscription upgrade.       |
| `.upcart-public-component-product-tile__select-wrapper`           | Wrapper for select dropdown.                        |
| `.upcart-public-component-product-tile__select`                   | Select dropdown element.                            |
| `.upcart-public-product-properties__subscription`                 | Displays subscription details for the item.         |
| `.upcart-public-product-properties__item`                         | Individual product property.                        |
| `.upcart-public-product-properties__link`                         | Link within product properties.                     |
| `.upcart-public-cart-items__key-value-pair`                       | Key-value pair display for item properties.         |
| `.upcart-public-bundle-properties`                                | Container for bundle properties.                    |
| `.upcart-public-bundle-properties__variant-title`                 | Variant title for bundle items.                     |
| `.upcart-public-bundle-properties__header`                        | Header for bundle properties section.               |
| `.upcart-public-bundle-properties__item-components`               | Container for bundle item components.               |
| `.upcart-public-bundle-properties__item-component-row`            | Row for each bundle item component.                 |
| `.upcart-public-bundle-properties__image-wrapper`                 | Wrapper for bundle item image.                      |
| `.upcart-public-bundle-properties__content`                       | Content area for bundle item.                       |
| `.upcart-public-bundle-properties__product-title`                 | Product title for bundle item.                      |

### **Add-ons module**

|                                                |                                               |
| ---------------------------------------------- | --------------------------------------------- |
| **CSS Selector**                               | **Description**                               |
| `.upcart-public-addons`                        | Main container for the add-ons section.       |
| `.upcart-public-addons__image-wrapper`         | Wrapper for the add-on image.                 |
| `.upcart-public-addons__content-wrapper`       | Content wrapper for add-on information.       |
| `.upcart-public-addons__content-title-wrapper` | Wrapper for add-on title.                     |
| `.upcart-public-addons__content-title`         | Title of the add-on product.                  |
| `.upcart-public-addons__content-price`         | Price section for add-on.                     |
| `.upcart-public-addons__compare-at-price`      | Original (strikethrough) price of the add-on. |
| `.upcart-public-addons__price`                 | Current price of the add-on product.          |
| `.upcart-public-addons__content-description`   | Description of the add-on product.            |
| `.upcart-public-addons__toggle-wrapper`        | Wrapper for the add-on toggle.                |
| `.upcart-public-addons__toggle`                | Toggle switch to add/remove an add-on.        |
| `.upcart-public-addons__toggle-switch`         | Switch element of the toggle.                 |
| `.upcart-public-addons__toggle-slider`         | Slider element of the toggle.                 |
| `.upcart-public-addons__skeleton`              | Skeleton placeholder for add-ons section.     |
| `.upcart-public-addons__skeleton-image`        | Skeleton for add-on product image.            |
| `.upcart-public-addons__skeleton-text`         | Skeleton for text content in add-ons.         |

### **Express payments module**

|                                              |                                        |
| -------------------------------------------- | -------------------------------------- |
| **CSS Selector**                             | **Description**                        |
| `.upcart-public-express-payments__container` | Container for express payment buttons. |

### **Cart summary module**

|                                               |                                          |
| --------------------------------------------- | ---------------------------------------- |
| **CSS Selector**                              | **Description**                          |
| `.upcart-public-cart-summary`                 | Main container for the cart summary.     |
| `.upcart-public-cart-summary__discount-codes` | Container for discount codes in summary. |
| `.upcart-public-cart-summary__discount-label` | Label for discount section.              |
| `.upcart-public-cart-summary__slide-codes`    | Sliding container for discount codes.    |
| `.upcart-public-cart-summary__total-discount` | Total discount amount display.           |

## **Helpful resources to get started:**

* **[Getting Started with Custom CSS](/upcart/custom_css):** Learn how to safely add custom CSS in Upcart.
* **[Intro to Customizations in Upcart](/upcart/getting_started_with_upcart_customizations):** Understand how customization works and where to start.
* **[Use AI to Write Custom Code for Upcart](/upcart/ai_prompt_suggestions_for_adding_custom_code_to_your_upcart_settings):** Get help writing CSS or JavaScript using simple prompts.
* **[Best Practices to Increase Cart Conversions](/upcart/best_practices_to_increase_upcart_conversions):** Optimize your cart design with proven tips.

##

##


# Upcart customization policy
Source: https://docs.aftersell.com/upcart/upcart_customization_policy

This article explains Upcart's customization policy, detailing which changes are supported, which are not, and how to request assistance with advanced customizations.

We frequently receive inquiries regarding what aspects of Upcart can be customized and what our support team is able to assist with directly. This article outlines the scope of support, identifies requests that fall outside of coverage, and provides guidance on where to obtain additional assistance.

## Areas Supported by the Upcart Team

If an element does not display or function as intended out of the box, our team will provide support to correct the issue. Examples include:

* Upsell images that appear stretched or compressed
* Overlapping text or buttons
* Layout issues that occur on specific screen sizes or devices

As a general principle, if the cart does not align with its default design or expected functionality, it is within the scope of support.

## Areas Not Supported by the Upcart Team

If the cart is functioning as designed but modifications are desired to change its appearance or behavior, these requests are considered customizations and are not covered by support. Examples include:

* Implementing one of our premade customization snippets
* Moving, hiding, or restyling elements
* Adding custom icons or additional text
* Repositioning features within the cart

## Options for Customization Assistance

For changes beyond the default capabilities of Upcart, the following resources are recommended:

* Review the [AI Prompt Suggestions](/upcart/ai_prompt_suggestions_for_adding_custom_code_to_your_upcart_settings) article and consult ChatGPT (or another AI tool) for assistance with styling adjustments
* Explore the [premade customization collection](/upcart/premade_customizations_database), which provides useful code snippets and styling options
* Engage a [Shopify Expert](https://www.shopify.com/partners/directory/services/development-and-troubleshooting/custom-apps-integrations) to implement more advanced customizations

If a visual defect or layout problem is observed in the cart, please contact our support team. We are committed to assisting with the resolution of functional or display-related issues.


# Upcart HTML location library
Source: https://docs.aftersell.com/upcart/upcart_html_location_library

Learn where custom HTML and JavaScript will appear in the cart drawer.

# Overview

Upcart allows you to insert HTML or JavaScript into specific locations throughout the cart using the **Custom HTML** editor. This gives you full control over layout, visibility, and conditional content inside the cart experience.

Use this guide to understand how each location behaves and where your content will appear.

## Available HTML locations

#### **Above announcements/rewards**

Renders directly below the cart header, before any modules.\
Use this to add site-wide messages, flags, or dynamic banners.

#### **Below header/announcements/rewards**

Displays directly after the Announcements and Rewards modules, and just before the product list.

#### **Between each line item**

Repeats your HTML after every product in the cart.\
Ideal for showing disclaimers or additional product-specific info.

#### **Below cart items**

Renders below the product list, after all cart line items. Use this for messaging, banners, or custom content that should appear under the products but above upsells and add-ons.

#### **Above footer/add-ons**

Appears below the product list and upsells, but above the Add-ons section.\
Great for messaging that leads into warranty or shipping protection offers.

#### **Above checkout button**

Displays within the footer area, just above the checkout button and subtotal.\
Often used to show price breakdowns, shipping notices, or terms.

#### **Below checkout button**

Also in the footer, positioned after the checkout button and before the express payment buttons. Add-ons render at the top of the footer, well above this.\
Helpful for secondary CTAs or legal notices.

#### **Bottom of cart**

Displays outside the footer area at the very bottom of the cart drawer.\
Does not inherit the footer's background color.

#### **On empty cart screen**

Only shows when the cart is empty.\
Displays directly **below** the “Your cart is empty” message and above the recommendations module — useful for a supporting line or a link out to a collection.

#### **Scripts (Before Load)**

Invisible placement used to run JavaScript **before** the cart loads.\
Use this for defining variables, setting conditions, or modifying Upcart behavior.

* All custom HTML placements are managed under:\
  **Upcart > Cart Editor > Settings > Custom HTML**

## Visual reference

For a clear understanding of where each location renders inside the cart, refer to the labeled layout below

<Frame>
  <img alt="Labeled Upcart cart drawer showing where each custom HTML location renders" />
</Frame>


# Upcart pricing structure
Source: https://docs.aftersell.com/upcart/upcart_pricing_structure

This article outlines how Upcart's pricing structure works and highlights some frequently asked billing questions.

# Overview of Upcart Billing Policies

The Upcart Cart Drawer app follows Shopify’s standard billing practices. Charges are based on whether the app is installed, rather than how often it’s used or which features are active. This means billing continues as long as the app stays installed, even if you’re not currently using its features.

Additionally, Upcart's **Growth** plan uses a usage-based pricing model, where billing is calculated automatically based on your store's monthly order volume. The **Enterprise** plan is a flat monthly rate instead.

You might see charges in the following situations:

* **After your 14-day free trial ends**, if the app is still installed.
* **During Shopify’s billing cycle**, if a charge was created before you uninstalled the app.

Keep in mind that uninstalling the app after your free trial ends or before the next billing cycle doesn’t automatically cancel pending or accrued charges. If a charge was generated before you removed the app, it may still appear on your next Shopify invoice and doesn’t automatically cancel pending or accrued charges.

# Free Trial

Upcart is free to use for the first 14 days. Your free trial starts on the day you first choose a plan and approve the Shopify charge, which normally happens right after you install the app. The clock runs from that first start date and does not reset: if you’ve installed and uninstalled Upcart before, accepting a plan again gives you only the days still left of the original 14, and none at all once 14 days have passed.

Once the trial ends, your Shopify store will automatically be charged the subscription fee. To avoid charges, make sure to uninstall the app before your trial period ends. Billing begins as soon as the trial expires, even if you’re not actively using the app on your store.

You do need to choose a plan and approve the Shopify charge before you can use Upcart. After installing, the app sends you to the plan-selection screen and keeps you there until a plan is accepted. Once approved, billing operates through Shopify's billing infrastructure.

***

# Shopify Billing Cycles and Upcart Charges

Charges for Upcart are synchronized with Shopify’s standard billing cycle. This means that even if you uninstall the app, you may still see charges on your Shopify bill for the current billing period if they were generated before you uninstalled the app.

Upcart offers two plans: **Growth**, priced by order volume, and **Enterprise**, a flat rate at any volume.

The tiers below are the Growth plan. Each store within a multi-store account is billed individually based on its own order volume, without linkage to other stores in the account.

|                  |                |
| ---------------- | -------------- |
| Monthly orders   | Monthly price  |
| 0-200 orders     | \$29.99/month  |
| 201-500 orders   | \$34.99/month  |
| 501-1000 orders  | \$54.99/month  |
| 1001-2000 orders | \$89.99/month  |
| 2001-3000 orders | \$119.99/month |
| 3001-5000 orders | \$149.99/month |
| 5001+ orders     | \$199.98/month |

The **Enterprise** plan is a flat \$299.00/month with no usage fees at any order volume.

**Note:** Store orders refer to how many total orders you have on your Shopify store each month, not orders that are generated by the app. This means that your bill may increase or decrease based on your order volume each month.

## Upcart Usage Price

This section describes the **Growth** plan. The Enterprise plan is a flat \$299.00/month and never incurs usage charges.

On Growth, Upcart costs a flat **\$29.99 USD per month** for stores with **200 orders or fewer**. Above 200 orders you also see a single **usage charge**. That charge is not per extra order — it is a fixed amount for the tier your store's *total* monthly order count falls into: \$5 for 201–500 orders, \$25 for 501–1,000, \$60 for 1,001–2,000, \$90 for 2,001–3,000, \$120 for 3,001–5,000, and \$169.99 above 5,000. Crossing into a tier changes the whole charge, so the totals in the table above are what you pay.

This billing structure is integrated seamlessly into Shopify's platform, ensuring that billing and usage calculations are automated without requiring any additional user input.

For example, if your monthly bill includes a \$29.99 subscription fee and a \$5 usage charge, your total would be \$34.99. Based on the pricing tiers, this means your store had between 201–500 orders that month.

For stores with over 5,000 orders per month, the total charge is \$199.98 — the \$29.99 subscription plus a \$169.99 usage charge — which reflects the highest pricing tier.

Note:

If you have **more than 200 orders**, the subscription and usage charges will appear as separate line items on your Shopify invoice but will always add up to a single total price.

***

# **Frequently Asked Questions**

## How is the billing period determined?

Charges are **prorated for the next 30-day period.** For example, if a charge is dated **04/01/2025**, it applies to the billing period from **04/01/2025 to 05/01/2025**. This means charges are calculated based on your store’s order volume for the **previous 30 days**. The prorated billing approach allows for a simpler and more affordable billing structure.

## How do I change my plan?

You can upgrade or downgrade your plan directly in the app without contacting support. From the Upcart home page, click **Plan & billing** in the header. Your current plan is marked, and you can select a different plan to switch. The new charge will appear in your Shopify billing history.

<img alt="Upcart home page with an arrow pointing to the Plan and billing button" />

## How do I prevent charges?

To avoid unexpected charges:

1. Uninstall the app before the 14-day free trial expires.
2. Confirm that the app is completely removed from your Shopify account.
3. Regularly review your Shopify billing statements for pending charges.

## Why was I billed after uninstalling?

Shopify collects app billing charges as part of your regular Shopify subscription billing cycle. This means that even if a charge from Upcart was generated earlier, it won’t be collected until your next Shopify billing date.

Because app billing and Shopify billing cycles may not always align, you might still see charges appear after uninstalling the app. If this happens, check the charge dates in your invoice to confirm when the billing originated.

You can learn more about how Shopify’s billing cycles work [here.](https://help.shopify.com/en/manual/your-account/manage-billing/your-invoice/apps)

## I have unexpected charges?

Please reach out to us through live chat or by emailing [**support@upcart.app**](mailto:support@upcart.app). Include details about the unexpected charge and include any relevant Shopify billing screenshots showing the amounts and billing periods.

## Why was I double charged?

If you’re seeing two charges, it's because of how the **Growth** plan works. The first charge is the **flat monthly fee of \$29.99 USD**, and the second is a **usage charge** based on your store’s order volume for that billing period. (Enterprise is billed as a single \$299.00/month charge with no usage component.)

It’s normal for these to appear as separate line items on your Shopify bill. This helps clearly show the difference between your base subscription cost and any additional usage charges.

For example, if your store processes more than 5,000 orders in a month, you might see two charges that total \$199.98, which aligns with the highest pricing tier.

You can refer to the pricing table above for a detailed breakdown.

## Why do charges vary month to month?

The charges vary depending on your store’s monthly order volume. If the number of orders exceeds a certain threshold, the usage charge for that month will increase correspondingly.

## Do you have enterprise pricing?

Yes. The **Enterprise** plan is a flat **\$299.00/month** with no usage fees, whatever your order volume. You can switch to it yourself from **Plan & billing** in the app — choose the Enterprise plan and approve the Shopify charge.

If you have questions before switching, message us on live chat or email [support@upcart.app](mailto:support@upcart.app).

## Is there a way to predict charges in advance?

Yes. On the **Growth** plan, use your order history and the current tier thresholds to estimate the total by summing the \$29.99 flat subscription with the appropriate usage fee tier. On **Enterprise** the charge is always \$299.00/month, so there is nothing to estimate.

## Will charges decrease if my order volume drops in the future?

Yes, if your store's orders fall below the threshold levels in subsequent months, you will only be billed the associated charge.

***

### Need more help?

If you have any other questions about Upcart's pricing or billing, our support team is always happy to help through **live chat** or [**support@upcart.app**](mailto:support@upcart.app).


# Upcart V2.0 migration guide
Source: https://docs.aftersell.com/upcart/upcart_v20_migration_guide

This article is a migration guide for upgrading from Upcart V1.0 to V2.0 modules. It covers breaking changes, CSS class mappings, JavaScript selector updates, troubleshooting, and the step-by-step migration process.

## Overview

Upcart V2.0 modules introduce a complete architectural redesign of the cart system. The update focuses on improved performance, enhanced customization, and better maintainability.

This guide will help you understand what changes when migrating from V1.0 to V2.0 modules, what compatibility issues you may encounter, and how to update your existing customizations safely.

***

## Breaking changes - CSS classname changes

### V1 Classes (Deprecated)

🚨 The following V1.0 class names are no longer supported in V2.0:

```
.styles_Header__  
.styles_ProductRow__  
.styles_Rewards__  
.styles_TieredRewards__  
...
```

<Note>
  The out-of-stock warning classes `upcart-quantity-warning` and `upcart-quantity-warning-text` are also **unchanged**. They come from the cart initializer rather than a versioned module, so they are emitted identically whether your modules are on V1 or V2.
</Note>

<Note>
  **`.styles_CartPreview__card__` is not in this list** — it is the shared cart-shell wrapper rendered around every module regardless of version, so rules targeting it keep working on V2. The rewards classes are `.styles_Rewards__` (simple bar) and `.styles_TieredRewards__` (tiered bar); there is no `.styles_RewardsModule__`.
</Note>

```
/*******************  
*** Cart Header ***  
*******************/  
'upcart-header',  
'upcart-header-text',  
'upcart-header-logo',  
'upcart-header-close-button',  
'upcart-header-close-button-icon',  
  
/******************  
*** Line Items ***  
******************/  
'upcart-products-section',  
'upcart-product-item',  
/** > Title */  
'upcart-product-title',  
'upcart-product-title-link',  
/** > Prices */  
'upcart-item-prices-row',  
'upcart-item-price',  
'upcart-item-compare-price',  
'upcart-product-savings',  
/** > Options/Variants */  
'upcart-item-option',  
'upcart-item-option-category',  
'upcart-item-option-value',  
/** > Bundle Item Components */  
'upcart-bundle-item-image-wrapper',  
'upcart-bundle-item-product-title',  
'upcart-bundle-item-variant-title',  
'upcart-bundle-detail-toggle',  
/** > Properties */  
'upcart-item-properties',  
'upcart-item-property',  
'upcart-item-property-subscription',  
/** > Quantity Selector */  
'upcart-product-quantity-input',  
'upcart-product-quantity-minus',  
'upcart-product-quantity-plus',  
/** > Image */  
'upcart-product-image-wrapper',  
  
/*********************  
*** Announcements ***  
*********************/  
'upcart-announcement',  
  
/***************  
*** Rewards ***  
***************/  
'upcart-rewards',  
'upcart-rewards-message',  
'upcart-rewards-bar-background',  
'upcart-rewards-bar-foreground',  
'upcart-rewards-tier',  
'upcart-rewards-tier-circle',  
'upcart-rewards-tier-icon',  
'upcart-rewards-tier-description',  
  
/***************  
*** Upsells & Recommendations ***  
***************/  
'upcart-upsells-module',  
'upcart-upsells-title',  
'upcart-upsells-button',  
'upcart-upsell-item-title',  
'upcart-upsell-item-card',  
'upcart-upsell-item-image-wrapper',  
'upcart-upsell-item-image',  
'upcart-upsell-item-price',  
'upcart-upsell-item-price-row',  
'upcart-upsell-item-compare-price',  
'upcart-upsell-item-variant-selector',  
'upcart-upsells', // deprecated  
'upcart-recommendation-module',  
'upcart-recommendations-title',  
'upcart-recommendations-shop-now-button',  
  
/***************  
*** Add-ons ***  
***************/  
'upcart-addons',  
'upcart-addons-title',  
'upcart-addons-product-description',  
'upcart-addons-price',  
'upcart-addons-compare-price',  
'upcart-addons-toggle',  
'upcart-addons-image-wrapper',  
  
/**********************  
*** Discount Codes ***  
**********************/  
'upcart-discount-code-row',  
'upcart-discount-code-module',  
'upcart-discount-code-button',  
'upcart-discount-code-input',  
'upcart-discount-code-badge',  
'upcart-discount-code-icon',  
'upcart-discount-code-text',  
'upcart-discount-code-input-wrapper',  
  
/*****************************  
*** Subscription Upgrades ***  
*****************************/  
'upcart-subscription-upgrade-section',  
'upcart-subscription-upgrade-button',  
'upcart-subscription-upgrade-dropdown',  
  
/***************************  
*** Express Pay Buttons ***  
***************************/  
'upcart-express-pay-buttons-container',  
'upcart-express-pay-buttons-row',  
'upcart-express-pay-button',  
'upcart-express-pay-button-shop-pay',  
'upcart-express-pay-button-google-pay',  
'upcart-express-pay-button-paypal',  
'upcart-express-pay-button-apple-pay',  
'upcart-express-pay-button-amazon-pay',  
'upcart-express-pay-button-meta-pay',  
  
/********************  
*** Trust Badges ***  
********************/  
'upcart-trust-badge',  
'upcart-trust-badge-image',  
  
/********************  
*** Integrations ***  
********************/  
'upcart-integration-zapiet-pickup',  
  
/*****************  
*** Skeletons ***  
*****************/  
'upcart-skeleton',  
'upcart-product-item-skeleton',  
'upcart-product-image-skeleton',  
'upcart-product-title-skeleton',  
'upcart-item-option-skeleton',  
'upcart-product-quantity-skeleton',  
'upcart-product-price-container-skeleton',  
'upcart-announcement-skeleton',  
'upcart-rewards-skeleton',  
'upcart-rewards-message-skeleton',  
'upcart-rewards-bar-skeleton',  
'upcart-upsells-module-skeleton',  
'upcart-upsells-title-skeleton',  
'upcart-upsell-item-image-skeleton',  
'upcart-upsell-item-title-skeleton',  
'upcart-upsell-item-price-skeleton',  
'upcart-upsells-button-skeleton',  
'upcart-trust-badge-skeleton',  
'upcart-trust-badge-image-skeleton',  
'upcart-checkout-button-container-skeleton',  
'upcart-checkout-button-skeleton',  
'upcart-addons-skeleton',  
'upcart-addons-image-wrapper-skeleton',  
'upcart-addons-skeleton-text-container',  
'upcart-discount-code-module-skeleton',  
'upcart-discount-code-input-skeleton',  
'upcart-discount-code-button-skeleton',  
'upcart-express-pay-buttons-container-skeleton',  
'upcart-express-pay-button-skeleton'
```

### V2.0 classes (new system)

V2.0 introduces a structured naming system with **internal** and **public** class prefixes.

#### Internal classnames

These are reserved for internal use and may change without notice.

If you override these classes, future compatibility is not guaranteed.

```
/* Internal classes - for Upcart's internal styling */   
.upcart-internal-header  
.upcart-internal-header__close-button  
.upcart-internal-cart-items  
.upcart-internal-rewards  
...
```

#### Public classnames

🚨 Public classnames available list

```
/*******************  
***** Skeleton *****  
*******************/  
'upcart-public-skeleton'  
  
/*******************  
****** Header ******  
*******************/  
'upcart-public-header'  
'upcart-public-header__close-button'  
'upcart-public-header__close-button-icon'  
  
/*******************  
*** Announcement ***  
*******************/  
'upcart-public-announcement'  
  
/*******************  
** Recommendation **  
****** Upsell ******  
*******************/  
'upcart-public-component-upsell-tile'  
'upcart-public-component-upsell-tile__image-container'  
'upcart-public-component-upsell-tile__image'  
'upcart-public-component-upsell-tile__info'  
'upcart-public-component-upsell-tile__title-link'  
'upcart-public-component-upsell-tile__title'  
'upcart-public-component-upsell-tile__rating-row'  
'upcart-public-component-upsell-tile__stars'  
'upcart-public-component-upsell-tile__star--partial'  
'upcart-public-component-upsell-tile__reviews'  
'upcart-public-component-upsell-tile__price-row'  
'upcart-public-component-upsell-tile__price-compare-at'  
'upcart-public-component-upsell-tile__price'  
'upcart-public-component-upsell-tile__variant-row'  
'upcart-public-component__button'  
'upcart-public-component-loader'  
'upcart-public-upsell__skeleton'  
'upcart-public-upsell__skeleton-title'  
'upcart-public-upsell__skeleton-image'  
'upcart-public-upsell__skeleton-product-title'  
'upcart-public-upsell__skeleton-product-price'  
  
/*******************  
****** Notes *******  
*******************/  
'upcart-public-notes'  
'upcart-public-component-collapse__dropdown-container'  
'upcart-public-component-collapse__expand-icon'  
'upcart-public-notes__text-container'  
'upcart-public-notes__textarea'  
  
/*******************  
** Discount Code ***  
*******************/  
'upcart-public-discount-code'  
'upcart-public-discount-code__form'  
'upcart-public-discount-code__input-wrapper'  
'upcart-public-discount-code__input'  
'upcart-public-discount-code__suffix'  
'upcart-public-discount-code__error'  
'upcart-public-discount-code__button'  
'upcart-public-component__button'  
'upcart-public-skeleton'  
'upcart-public-discount-code__skeleton'  
'upcart-public-discount-code__skeleton-input'  
'upcart-public-discount-code__skeleton-button'  
  
/*******************  
** Trust Badges ****  
*******************/  
'upcart-public-trust-badges'  
'upcart-public-trust-badges__image'  
  
/*******************  
** Tiered Rewards **  
*******************/  
'upcart-public-rewards'  
'upcart-public-rewards__message'  
'upcart-public-rewards__bar'  
'upcart-public-component-segmented-progress-bar'  
'upcart-public-component-segmented-progress-bar__segments-container'  
'upcart-public-component-segmented-progress-bar__segment'  
'upcart-public-component-segmented-progress-bar__segment-fill'  
'upcart-public-component-segmented-progress-bar__milestone'  
'upcart-public-component-segmented-progress-bar__milestone--bottom'  
'upcart-public-component-segmented-progress-bar__milestone--top'  
'upcart-public-component-segmented-progress-bar__milestone--middle'  
'upcart-public-component-segmented-progress-bar__milestone-icon'  
'upcart-public-component-segmented-progress-bar__milestone-label'  
'upcart-public-component-segmented-progress-bar__milestone-label--align-right'  
'upcart-public-component-segmented-progress-bar__milestone-label--align-center'  
'upcart-public-rewards__skeleton',  
'upcart-public-rewards__skeleton-message',  
'upcart-public-rewards__skeleton-bar',  
  
/*******************  
**** Cart Items ****  
*******************/  
'upcart-public-component-product-tile'  
'upcart-public-component-product-tile__content'  
'upcart-public-component-product-tile__image-wrapper'  
'upcart-public-component-product-tile__image'  
'upcart-public-component-product-tile__info'  
'upcart-public-component-product-tile__header'  
'upcart-public-component-product-tile__product-title'  
'upcart-public-component-product-tile__title-link'  
'upcart-public-component-product-tile__remove-button'  
'upcart-public-component-loader'  
'upcart-public-component-product-tile__variant'  
'upcart-public-component-product-tile__properties'  
'upcart-public-component-product-tile__bundle'  
'upcart-public-component-product-tile__product-pricing'  
'upcart-public-component-product-tile__price-compare-at'  
'upcart-public-component-product-tile__price'  
'upcart-public-component-product-tile__savings'  
'upcart-public-component-product-tile__controls'  
'upcart-public-component-product-tile__quantity-selector'  
'upcart-public-component-product-tile__quantity-minus'  
'upcart-public-component-product-tile__quantity-plus'  
'upcart-public-component-product-tile__discount-codes'  
'upcart-public-component-tag'  
'upcart-public-component-tag__icon'  
'upcart-public-component-tag__text'  
'upcart-public-component-product-tile__subscription-upgrade'  
'upcart-public-component__button'  
'upcart-public-component-product-tile__select-wrapper'  
'upcart-public-component-product-tile__select'  
'upcart-public-product-properties__subscription'  
'upcart-public-product-properties__item'  
'upcart-public-product-properties__link'  
'upcart-public-cart-items__key-value-pair'  
'upcart-public-bundle-properties'  
'upcart-public-bundle-properties__variant-title'  
'upcart-public-component-collapse__dropdown-container'  
'upcart-public-bundle-properties__header'  
'upcart-public-component-collapse__expand-icon'  
'upcart-public-notes__text-container'  
'upcart-public-bundle-properties__item-components'  
'upcart-public-bundle-properties__item-component-row'  
'upcart-public-bundle-properties__image-wrapper'  
'upcart-public-bundle-properties__content'  
'upcart-public-bundle-properties__product-title'  
'upcart-public-upsell__skeleton'  
'upcart-public-upsell__skeleton-title'  
'upcart-public-upsell__skeleton-image'  
'upcart-public-upsell__skeleton-product-title'  
'upcart-public-upsell__skeleton-product-price'  
  
/*******************  
***** Add-ons ******  
*******************/  
'upcart-public-addons'  
'upcart-public-addons__image-wrapper'  
'upcart-public-addons__content-wrapper'  
'upcart-public-addons__content-title-wrapper'  
'upcart-public-addons__content-title'  
'upcart-public-addons__content-price'  
'upcart-public-addons__compare-at-price'  
'upcart-public-addons__price'  
'upcart-public-addons__content-description'  
'upcart-public-addons__toggle-wrapper'  
'upcart-public-addons__toggle'  
'upcart-public-addons__toggle-switch'  
'upcart-public-addons__toggle-slider'  
'upcart-public-skeleton'  
'upcart-public-addons__skeleton'  
'upcart-public-addons__skeleton-image'  
'upcart-public-addons__skeleton-text'  
  
/*******************  
*** Cart summary ***  
*******************/  
'upcart-public-cart-summary'  
'upcart-public-cart-summary__discount-codes'  
'upcart-public-cart-summary__discount-label'  
'upcart-public-cart-summary__slide-codes'  
'upcart-public-cart-summary__total-discount'
```

These are part of the public styling API (`upcart-public-`) and are safe to override for custom designs.

```
.upcart-public-header  
.upcart-public-header__close-button  
.upcart-public-rewards  
...
```

###

### ✅ DO’s

Use only `upcart-public-` class names for styling.

```
/* ✅ Correct usage */  
.upcart-public-header {     
  font-size: 18px;  
  font-weight: bold;   
}
```

### ❌ DON’T’s

Avoid override internal classnames

```
/* ❌ Avoid this */  
.upcart-internal-header {     
  font-size: 18px;  
  font-weight: bold;   
}
```

Avoid targeting specific nodes with deep or custom selectors.

```
/* ❌ Avoid this */  
.upcart-public-upsell div a {     
  font-size: 18px;  
  font-weight: bold;   
}
```

***

## Data attribute system

V2.0 introduces a structured **data attribute system** for improved targeting and advanced customization.

```
<!-- V2 data attributes for targeting -->   
<div data-upcart-chunk="header-title-content" />     
<div data-internal-properties="hasNonDefaultTitleAlignment=true" />       
<div data-placement="topOfFooter" />
```

These attributes make it easier to create flexible, data-driven templates while maintaining code clarity.

***

## Template variable changes

V2 modules use a **new template variable syntax** with double curly braces `{{ }}`.

## Announcement Module

* V1.0: `` `{TIMER}` ``
* V2.0: `` `{{timer}}` ``

## Tiered Rewards Module

* V1.0: `` `{AMOUNT}` `` → V2: `` `{{amount}}` ``
* V1.0: `` `{COUNT}` `` → V2: `` `{{count}}` ``

***

## Migration process

#### 1. Backup Current Configuration

Before making any changes, back up your existing **custom CSS** and **HTML** files.

#### 2. Test in Sandbox Mode

Set up your updated cart using **sandbox mode** to safely test new modules before going live.

***

## Advanced customization with V2.0

### Custom templates

V2.0 modules support fully **custom templates** for merchants who want complete control over layout and structure.

To enable custom templates:

1. Go to **Settings > Cart settings**, expand **Advanced Settings**, and tick **Access custom templates**. The checkbox is inside that collapsed section, not on the Cart settings tab itself.
2. Enable the feature toggle.
3. Reference Upcart’s developer documentation for syntax and examples.

<img alt="Enabled Access custom templates checkbox with its description in Upcart cart settings" />

**Note:** Upcart’s support team cannot assist with developing, debugging, or troubleshooting custom templates.

***

## Best Practices

* Always test updates in **sandbox mode** first.
* Migrate and update customizations incrementally.
* Use **public classes** for styling instead of internal ones.
* Keep backups of all previous versions before updating live settings.

***

## Future Considerations

* V2 modules will continue to receive new features, optimizations, and updates.
* V1 modules are now in **maintenance mode** with limited support and no new features.
* Merchants are encouraged to migrate to V2 as soon as possible for full compatibility.

##

##


# Upcart x Abra integration
Source: https://docs.aftersell.com/upcart/upcart_x_abra_integration

This article explains how to use Abra with Upcart to offer dynamic in-cart rewards, VIP promotions, and personalized gifts that drive conversions and increase average order value (AOV).

# Overview

**Abra** is a discounting app that helps you automatically apply discounts, add free gifts with purchase, and boost sales through smart, dynamic promotions that turn browsers into buyers.

With the **Abra + Upcart integration**, you can bring these powerful promotions directly into your cart drawer using the **Rewards Module**.

Reward customers based on cart value, item count, or subscription products, and test it out with a **30-day free trial**.

This guide will walk you through:

* How to connect Abra to your Upcart cart drawer
* What you can do with the integration
* How to troubleshoot common setup issues

Getting started with Abra inside Upcart is quick and simple. Follow the steps below to connect your account and start displaying dynamic rewards in your cart drawer.

<Callout type="note">
  **📝 When to use Abra vs. the Discounts module**

  Upcart's native Discounts module can create automatic discounts, free gifts, and free shipping rules based on cart conditions, with no third-party app required. Use the Discounts module for straightforward discount logic tied to cart total, quantity, products, collections, subscriptions, or customer login status. Use Abra when you need broader promotion management features such as VIP-targeted promotions, branded gift catalogs, dynamic popups, or cross-surface promotion banners that extend beyond the cart drawer.
</Callout>

***

# Getting started with **Abra** inside **Upcart** is quick and simple.

Follow the steps below to connect your account and start displaying dynamic rewards in your cart drawer.

## 1. Connect Abra

1. Open your **Upcart Editor** and navigate to the **Rewards Module**.
2. Scroll to the bottom of the module.
3. Click the button labeled **“Learn more about Abra.”**
4. Abra's Shopify App Store listing opens in a new tab, where you can install Abra and create or sign in to your account.

<Note>
  The two buttons behave differently. **Learn more about Abra** removes the card for good — it clears the shop-level flag that renders it, so it is not a repeatable way back into Abra; go to Abra directly or through your Shopify Apps list afterwards. **Dismiss** only hides it for the current browser session, so it returns next time you open Upcart.
</Note>

<img alt="Upcart Rewards Module editor with the Learn more about Abra promotion card at the bottom" />

## 📝 Connection Tip:

After connecting, you’ll **manage your Abra account and product catalog in Abra’s dashboard.**

***

## 2. Activate the Integration in Abra

In your **[Abra account settings](https://abrapromotions.com/blogs/help-center)**, activate the **Upcart integration**. This allows Abra to send your promotions and rewards directly to the cart drawer.

<img alt="Abra Integrations page showing the UpCart integration card with an Activate button" />

***

## 3. Create a Promotion in Abra

1. In your **Abra dashboard**, click **Create Promotion**.
2. Set the **Title** to the exact code or label you want customers to see when they reach the reward threshold.
3. Configure your reward type, such as a **discount**, **free gift**, or **VIP promotion**.

These promotions will automatically sync with your reward conditions in Upcart, displaying dynamically in your cart drawer when triggered.

It will look similar to this (based on your promotion type):

<img alt="Abra promotion page showing an active UpcartXAbra promotion with its private link and title" />

## 💡 **Tip:**

The promotion title in Abra should match the reward code or label you plan to use in your Upcart Tiers.

***

## 4. Add Your Promotion Banners in Abra

1. Upload your **promotion banners** directly inside Abra.
2. Assign each banner to your **cart template**.

When your reward conditions are met, these banners will appear automatically inside your **Upcart cart drawer** with no additional setup required.

<img alt="Abra cart template Add block menu listing banner types like Basic banner and Dynamic text" />

***

## 5. Connect Abra Promotions in Upcart

1. Return to **Upcart** to complete the connection.
2. Open the **Rewards Module** in your Upcart Editor.
3. For each reward tier whose **Reward type** is **Discount**, click **Show advanced settings**. Shipping and Product tiers have no advanced settings — switch the tier to Discount if you need to attach an Abra code to it.
4. Enter the **Abra Title (code)** that matches your promotion into the **Manual discount code** field. Switching a tier away from Discount clears any code you entered.
5. Click **Save** when finished.

<img alt="Upcart reward tier Advanced Settings showing the Abra title entered as the manual discount code" />

## 🧠 **Note:**

Make sure the promotion title in Abra exactly matches the title you enter in your Upcart Tier. Otherwise, the reward won’t trigger correctly.

***

## 6. Test and Launch

Before going live, test your setup to ensure everything works correctly:

* Add products to your cart to reach the reward threshold.
* Confirm that your promotion banners appear inside the cart drawer.
* Verify that the correct promotion triggers based on **cart value** or **item count**.

💡 **Pro Tip:**

Test multiple cart scenarios (like hitting different tier levels) to make sure all your promotions are working correctly before going live.

***

# What You Can Do with Abra + Upcart

Abra gives you powerful new ways to personalize and enhance your cart experience inside Upcart, helping you increase conversions and AOV through meaningful in-cart rewards.

With the integration, you can:

* Offer branded gifts and dynamic rewards based on **cart value**, **item count**, or **specific products**, giving shoppers more incentive to complete their purchase.
* Auto-apply discounts and combine offers across **collections**, **products**, and the **entire cart**, with no discount codes required.
* Create targeted promotions for **VIPs** and **subscribers**, using popups and dynamic messages that keep customers engaged before checkout.

💡 **Want to see it in action?**\
Explore how [Abra personalizes the Upcart experience](https://abrapromotions.com/blogs/conversion-labs/personalize-your-upcart-with-dynamic-rewards-from-abra) and how to auto-apply unique links for VIPs [here](#).

***

# Why It Works

* **Increase AOV by up to 35%:** Combine Abra’s tiered gifting with Upcart’s upsells to drive higher order values.
* **Lift conversions by up to 30%:** In-cart promotions reduce friction and encourage shoppers to complete their purchase.
* **Surprise and delight customers:** Branded gifts feel more personal than discounts, helping you build loyalty and repeat purchases.
* **Keep rewards consistent:** Abra promotions appear across product pages, collections, and now directly inside your Upcart cart drawer.

## 💡 **Real Results:**

Curious how it performs in the real world?\
**See how [Good Protein used Abra + Upcart to increase conversions and AOV](https://www.aftersell.com/case-study/good-protein)**

***

# Tips and Troubleshooting

* Make sure your **Abra account** is fully connected through Upcart.
* Verify that your **Upcart reward logic** (cart value, item triggers, etc.) matches your **Abra reward setup**.
* Confirm that your **gift or discount** is active and available in your **Abra product catalog**.
* Abra rewards only appear **in-cart**, not during checkout or post-purchase.
* Test your cart with a qualifying setup to trigger reward conditions.

📩 For setup help with Abra-specific settings, visit the **[Abra Help Center](https://abrapromotions.com/blogs/help-center)**

***

# Common Questions

## **Do I need an Abra account to use this?**

Yes. You’ll need to create an Abra account, install the app, and connect it through the **Upcart Rewards Module**.

## **Can I use Abra gifts and discounts with other Upcart features?**

Absolutely. Abra works seamlessly with **Upsells**, **Add-ons**, and **Discount Codes**.

## Where do the rewards show up?

Once enabled, your Abra rewards will appear directly inside the **Upcart cart drawer**, under your reward offer.

## Is the Abra trial automatic?

Yes. After connecting Abra to Upcart, your **30-day free trial** starts automatically. Billing follows the same structure as other Shopify apps.

***

# Keep Exploring

Learn more about customizing Upcart rewards through each of our Rewards Module help docs:

* [General Settings](/upcart/tiered_rewards_module_general_settings)

* [Rewards Settings](/upcart/tiered_rewards_module_rewards_settings)

* [Advanced Settings](/upcart/tiered_rewards_module_advanced_settings)


# Upcart x GemPages landing page builder
Source: https://docs.aftersell.com/upcart/upcart_x_gempages_landing_page_builder

This article explains how to set up GemPages to work seamlessly with Upcart’s cart drawer.

# Overview

GemPages is a flexible drag-and-drop page builder, but its default settings redirect customers to the cart page after clicking “Add to Cart.” This interrupts the intended Upcart flow, which is designed to show a slide-out cart drawer.

To ensure compatibility, you’ll need to disable this redirect behavior so the customer stays on the page and the Upcart drawer opens as expected.

***

## How to prevent redirects from Add to Cart buttons

1. Open your **Product Page** in the GemPages editor
2. Click on the **Add to Cart** button to select it
3. In the right-side panel, go to the **Interactions** section
4. Locate the dropdown labeled **Action After Click**
5. Select **Keep Shopping**

This change ensures that:

* Products are added to the Shopify cart normally
* The page doesn’t reload or redirect
* Upcart detects the cart update and opens the drawer

<img alt="GemPages editor Add to Cart settings with the after click action set to Keep shopping" />

***

## Final result

After saving and publishing:

* Clicking **Add to Cart** will keep the customer on the same page
* Upcart will slide in automatically to show the updated cart

This setup works for both product and landing pages built in GemPages.

***

**Note:**

These settings are available in **GemPages V7**. Earlier versions do not include this button customization option. Please reach out to [GemPages Help Center](https://help.gempages.net/) if you are not able to find these settings.


# Upcart x Globo Product Options, Variant
Source: https://docs.aftersell.com/upcart/upcart_x_globo_product_options_variant

This article explains how to integrate Globo Product Options and Variant with Upcart to ensure both apps work together smoothly.

## Overview

On most themes, third-party apps like Globo modify the default **Add to Cart** button with a custom function. This can prevent Upcart from triggering properly, leading to cart redirects or skipped drawer openings.

***

## How to Fix

Follow these steps to adjust settings in both Upcart and Globo:

1. In the **Upcart** app, go to **Cart Editor > Settings > Cart settings**, then expand **Advanced Settings**.
2. Enable the option **Enhanced Ajax API Compatibility**.

This setting improves compatibility with apps that use custom add-to-cart actions. Without it enabled, customers may be redirected to the store’s default cart page instead of seeing the Upcart drawer.

Next, update your Globo settings:

1. Open the **Globo Product Options** app.
2. Locate and disable the option:

   **“Redirect to the shopping cart page after adding a product.”**

Disabling this ensures that the Upcart drawer opens correctly after a product is added to the cart.

***

## Why This Happens

Globo Product Options replaces Shopify’s default **Add to Cart** process with a custom script. When this happens, Upcart cannot detect the cart update unless **Enhanced Ajax API Compatibility** is enabled.

Turning on this setting allows Upcart to recognize custom add-to-cart actions and prevents unwanted redirects to the default cart page.


# Upcart x Kaching bundle quantity breaks
Source: https://docs.aftersell.com/upcart/upcart_x_kaching_bundle_quantity_breaks

Instructions on how to integrate Upcart and Kaching Bundles

# Overview

If you're using variants in the Kaching Bundles app, make sure to enable the Enhanced Ajax API Compatibility setting in Upcart. You can find it here: Additional bundle apps may also cause interference by modifying how the "Add to Cart" action is processed, leading to issues with Upcart's enhanced features.

**Cart Editor > Settings > Cart settings > Advanced Settings > Enhanced Ajax API Compatibility:** This setting ensures other apps can function without interference but may disable Upcart’s ability to prevent redirection to the cart page. Please review additional app settings to manage any such behavior.

<img alt="Upcart Enhanced Ajax API compatibility setting with its checkbox and description" />

# Troubleshooting Steps

1. Ensure Enhanced Ajax API Compatibility is enabled in Upcart settings.
2. Test if disabling Upcart resolves conflicts temporarily. If the issue disappears, proceed to update your theme or check the bundle app settings.
3. Review the settings of any conflicting bundle apps to disable features causing interference.
4. If incompatibility persists, consult your theme or app developer for technical adjustments.

If you are still experiencing issues between Upcart and Kaching offers, additional work by the Kaching app developers may need to be done. In these cases, please reach out to the Kaching Support via their **[documentation page](https://support.kachingappz.com/en/articles/8367723-i-m-using-upcart-and-the-bundles-do-not-work-properly)**. Before contacting support, it is recommended to document the problem with a video demonstration and include details about the conflicting app settings to streamline the resolution process.


# Upcart x PageFly landing page builder
Source: https://docs.aftersell.com/upcart/upcart_x_pagefly_landing_page_builder

This article explains how to prevent cart page redirection when using PageFly with Upcart.

## How to Fix It

Follow these steps to ensure your **Add to Cart** button works correctly with Upcart:

1. Open the **PageFly** app in your Shopify admin.
2. Go to the **Add to Cart** button settings.
3. Find the section labeled **After add to cart action**.
4. Select the option **Stay on the same page**.

   <img alt="PageFly button settings with After add to cart action set to Stay on the same page" />

This ensures that customers remain on the same page and the **Upcart drawer** opens correctly after adding a product to the cart.

***

## Learn More

For additional details about this setting, refer to **[PageFly’s documentation](https://help.pagefly.io/manual/shopify-elements-product-add-to-cart/)** on configuring the **Add to Cart** button.


# Upcart x Replo landing page builder
Source: https://docs.aftersell.com/upcart/upcart_x_replo_landing_page_builder

This article explains how to set up Replo to open the Upcart drawer when a product is added to the cart.

Replo is a powerful landing page builder, but its default "Add to Cart" behavior redirects to the Shopify cart page. This interrupts the intended Upcart experience, which uses a slide-out drawer.

With a simple JavaScript snippet, you can tell Replo to notify Upcart when a product is added, keeping the customer on the same page and opening the drawer immediately.

This highlights how JavaScript can be used not only for Upcart integration but also for broader cart customization on your store.

***

## Why this integration matters

By default, Replo supports multiple post-cart behaviors:

* Redirect to Shopify cart page
* Redirect to checkout
* Stay on the page (no drawer interaction)

Upcart doesn’t open automatically unless you explicitly trigger it. This setup ensures the drawer opens right after the Replo "Add to Cart" button is clicked.

***

## Step 1: Open the product page in Replo

1. Open your product or landing page in the Replo editor
2. Select the **Add to Cart** button in the page layout
3. In the right-hand sidebar, click the **Interactions** tab

<img alt="Replo editor Interactions tab adding an On Click interaction to the Add to Cart button" />

## Step 2: Add a second interaction

1. Confirm that the button already uses the **Add Product to Cart** interaction
2. Click the `+` icon under **On Click**
3. From the list of actions, select **Run JavaScript**
4. In the code input, paste the following:
   ```javascript theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
   window.upcartRegisterAddToCart();
   ```
   This tells Upcart to open the drawer as soon as the product is added to the cart.

## Step 3: Disable Replo redirect to the cart page

1. Select the **Add Product to Cart** interaction again
2. Disable the **Go to cart after?** toggle

This prevents Replo from redirecting to the Shopify cart page, which would bypass the Upcart drawer entirely.

## Step 4: Preview and publish

1. Click **Preview** in Replo to test the interaction
2. Add a product to the cart and confirm that the Upcart drawer opens automatically
3. Once confirmed, click **Publish Page** to push changes live

***

## Notes

* This setup must be applied to **each page** where you use Replo + Upcart together
* The `window.upcartRegisterAddToCart();` function comes from Upcart’s public API and works without additional code installations
* This works for both mobile and desktop versions of Replo pages

# **Notes**

Replo should now stop redirecting to the Shopify Cart Page and instead notify Upcart when an item is added to the cart.

Please note: you'll need to complete this process for each product page you design in Replo Landing Page Designer.


# Upcart x Shopify bundles
Source: https://docs.aftersell.com/upcart/upcart_x_shopify_bundles

This article explains Upcart’s compatibility with the Shopify Bundles app.

## Overview

**Shopify Bundles** is a fully supported bundle management app in Upcart. No additional configuration is required for your customers to view and interact with bundle details created through Shopify Bundles directly within the **Upcart cart popup**.

All bundles display automatically, showing their contents and pricing as configured in Shopify.

<img alt="Upcart cart drawer showing a Snowboard bundle expanded to reveal its four included products" />

***

## Best Practices

To ensure bundles appear and function correctly in Upcart:

* Keep **bundle visibility** enabled in Shopify so products can display in the cart.
* Verify that **bundle pricing and inventory tracking** are set up properly within Shopify Bundles.
* Test your bundle setup in a **Draft theme** before publishing to confirm it displays as expected in Upcart.

Following these best practices helps maintain accurate product data and ensures a smooth shopping experience for your customers.

***

If you encounter any problems with this, please contact Upcart support.


# Upcart x Wide Bundles – quantity breaks
Source: https://docs.aftersell.com/upcart/upcart_x_wide_bundles_quantity_breaks

This article explains how to resolve add-to-cart issues that can occur when using Wide Bundles with Upcart for quantity break offers.

# Overview

When using Wide Bundles and Upcart together, you may notice that the cart does not open correctly after a customer adds an item. This usually happens when the **Add-to-Cart Redirection** setting in Wide Bundles is not configured to work with Upcart.

***

## How to Fix It

Follow these steps to resolve the issue:

1. Open your **Wide Bundles** settings.
2. Locate the **Add-to-cart Button** section.
3. Change **Click redirection** to **Side Cart**.

Setting it to **Side Cart** ensures that your cart opens correctly in Upcart after a customer adds a product to their cart:

<img alt="WideBundle Add-to-cart Button setting with Click redirection set to Side Cart" />

***

## **Need More Help?**

For any support questions about the integration with Wide Bundles, or if this integration is not working, **please email the Wide bundle support team at:** [support@widebundle.com](mailto:support@widebundle.com).

If you’re a developer looking for more integration options, check out our [Upcart Public API](https://rokt.notion.site/upcart-public-api).


# Upcart x Zepto Product Personalizer integration
Source: https://docs.aftersell.com/upcart/upcart_x_zepto_product_personalizer_integration

Learn how to fix redirect and price update issues when using Zepto Product Personalizer with Upcart, self-serve walkthrough.

# Overview

Zepto Product Personalizer is compatible with Upcart, but a few setting adjustments may be needed for optimal performance. This guide covers two common issues—cart redirection and price updates—and how to resolve them.

# 1: Zepto Redirects to the Cart Page (Not Upcart)

By default, Zepto redirects customers to the cart page instead of displaying the Upcart side cart.

**How to Fix It:**

1. Go to **Zepto** > **Settings** > **Add to Cart Settings**
2. Find the section titled **“Action after a product is added to the cart”**
3. Select **“Stay on the product page and show a success message”**
4. Save your changes

Here’s where you can find those settings in Zepto:

<img alt="Zepto Add to Cart Settings selecting Stay on the product page and show a success message" />

***

# Sometimes, the product price doesn’t update in Upcart after personalization. This is often due to Zepto using Shadow DOM, which can prevent Upcart from detecting price changes.

**How to Fix It:**

1. Go to **Upcart** > **Cart Editor** > **Settings** > **Cart settings**, then expand **Advanced Settings**
2. Uncheck the box labeled **Shadow DOM**
3. Save your changes
4. Test thoroughly, as this may impact the behavior of other apps or theme features

💡 **Note:** Disabling Shadow DOM may fix this issue but can introduce CSS conflicts with your theme. See the [Shadow DOM Setting](/upcart/render_cart_in_shadow_dom_setting) doc for the full trade-off.

For more details, you can also refer to [Zepto’s documentation](https://productpersonalizer.com/docs/)

## ⚠️ What’s Shadow DOM?

Shadow DOM is an advanced setting in Upcart that helps Upcart run smoothly by keeping it separate from other code on the page (like your theme or apps). But in some cases, like with Zepto, this "wall" needs to come down so the cart can update prices correctly.

***

# Need More Help?

If you're still having trouble:

* **For Zepto settings**, reach out to **[Zepto support](mailto:support@product-personalizer.zendesk.com)**
* If something else isn’t working, double-check that all settings were saved and tested.
* If you need any assistance with advanced customizations, we recommend consulting with a [Shopify Expert](https://www.shopify.com/partners/directory)


# What is an API?
Source: https://docs.aftersell.com/upcart/what_is_an_api

Application Programming Interface serves as an intermediary that enables different software applications to interact and exchange data.

# A Simple Analogy: A Restaurant & a Waiter

Imagine you're dining at a restaurant.

1. **You, the customer**, browse the menu and place an order for a cheeseburger and fries (similar to making a request for cart data).
2. **The waiter (API)** takes your order and communicates it to the kitchen (just like an API receives your request and sends it to a server).
3. **The kitchen (server)** prepares your meal, processing the order and gathering the necessary ingredients (much like how a server retrieves or manipulates cart data).
4. **The waiter (API)** then delivers the meal to your table, allowing you to enjoy your food (just as an API returns the requested data and updates your cart).

This analogy provides a simple way to understand how APIs function, especially if you're new to them. When using Upcart’s API, think of it like ordering at a restaurant—decide what you want the cart to do, and let the API handle the rest.

Discover how Upcart's API can elevate your store by exploring our [API documentation](/upcart/introduction_to_upcarts_public_api).

***

# How This Relates to Upcart’s API

Upcart’s Public API gives you the flexibility to customize and manage your cart’s functionality, much like providing specific instructions to a waiter.

For instance, if you want to test whether Upcart’s API is functioning correctly, you can run a simple script within your custom HTML that logs a message whenever the cart opens:

```
<script>  
  window.upcartSubscribeCartOpened(() => {  
    console.log("UpCart API Test - The cart has been opened!");  
  });  
</script>
```

## Verifying If It’s Working

1. Open your store and navigate to **Upcart Settings → Custom HTML** to add the script.
2. Save your changes and refresh your store.
3. Open the browser console (**F12** or **Ctrl + Shift + J** on Windows, or **Cmd + Option + J** on Mac).
4. Open Upcart’s cart, and you should see the confirmation message appear in the console:

```
Upcart API Test - The cart has been opened!
```

<img alt="Upcart Custom HTML test script logging a cart opened message in the browser console" />

***

## Want to Learn More About APIs?

If you're interested in diving deeper into APIs and JavaScript, here are some beginner-friendly resources to help you get started.

**Beginner-Friendly API & JavaScript Learning:**

* [W3Schools: JavaScript Basics](https://www.w3schools.com/js/) – Learn basic scripting to use Upcart’s API
* [MDN Web Docs: APIs for Beginners](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Client-side_web_APIs) – Understand how APIs work in web stores
* Shopify Developer Docs – [Shopify AJAX API](https://shopify.dev/docs/api/ajax) (useful for merchants integrating Upcart with Shopify’s cart)

Upcart’s API works seamlessly without the need for external tools like Postman—you can use it directly within Upcart’s Custom HTML settings or your Shopify theme code

***

## Need Assistance?

If you're new to APIs, no worries! You don’t have to write JavaScript from scratch—simply copy and paste pre-written scripts into Upcart’s Custom HTML settings to customize your cart in minutes.

Not sure where to begin? Reach out to a [Shopify Expert](https://www.shopify.com/partners/directory), or explore our [API documentation](/upcart/introduction_to_upcarts_public_api).

***


# Why does 'add to cart' go to the cart page instead of Upcart?
Source: https://docs.aftersell.com/upcart/why_does_add_to_cart_go_to_the_cart_page_instead_of_upcart

This article explains how to fix unexpected redirects to the Shopify cart page by adjusting your theme, app, or Upcart settings.

# Overview

If clicking "Add to Cart" on your storefront sends customers to the Shopify cart page instead of opening the Upcart drawer, it's usually due to a simple configuration issue. This guide walks through the most common causes and how to resolve them.

***

## Common causes

The cart redirect is usually triggered by one of the following:

* **Upcart settings** – certain compatibility settings may be disabled
* **Theme settings** – the theme may force a redirect by default
* **App conflicts** – another app could be controlling the cart behavior

***

## Step-by-step troubleshooting

Follow these steps in order. Test the cart after each step to check if the issue is resolved.

## 1. Check your Upcart settings

Go to **Upcart > Cart Editor > Settings > Cart settings**, then expand **Advanced Settings**.

Make sure **Enhanced Ajax API compatibility** is **off**.

<Warning>
  **Turning this on is a common *cause* of this problem, not a fix.** Among other things, the setting disables Upcart's own Add to Cart handling so another app or theme can take over — which is exactly what lets a theme redirect to `/cart` instead of opening the drawer. It's off by default; if something turned it on, turn it back off and retest.
</Warning>

Only leave it on if your store genuinely needs it (several scripts writing to Shopify's Ajax cart at once). In that case, register your add-to-cart buttons with Upcart explicitly using `upcartRegisterAddToCart` so the drawer still opens.

For complete guidance on this setting, see [Enhanced Ajax API compatibility](/upcart/enhanced_ajax_api_compatibility).

<img alt="Upcart Enhanced Ajax API compatibility setting with its checkbox and description" />

## 2. Check your Shopify theme settings

Go to:\
**Shopify Admin > Online Store > Themes > Customize > Theme Settings > Products**

Look for the setting labeled **"Enable cart redirection"** and turn it off.\
This setting, when enabled, automatically redirects customers to the cart page after clicking Add to Cart, bypassing Upcart entirely.

## 3. Review other installed apps

Some apps like **ReCharge**, **WideBundle**, **Bold**, or **CartKit** may override cart behavior.

In each app's settings:

* Look for a toggle like "Redirect to Cart" or "Go to Cart After Add"
* Change it to **Stay on Page** or **Do Nothing**

If you're unsure whether an app is interfering, contact the app developer or their support team to confirm Upcart compatibility.

***

## Testing as you go

After each fix:

* Add a product to your cart
* Confirm whether Upcart opens the drawer or if you're still redirected
* Only move to the next step if the issue persists

This will help isolate what's causing the conflict.

***

## If it's still not working

If you've completed all steps above and Upcart still doesn't open, try the following:

## Switch to a default theme

* Temporarily enable a Shopify base theme like **Dawn**
* Activate Upcart and test the Add to Cart behavior
* If it works in Dawn but not in your current theme, the issue is theme-related

## Disable other cart-related apps one by one

Turn off one app at a time and test the cart each time. If Upcart works after disabling a specific app, you've identified the conflict.

## Use browser developer tools

* Press **F12** (or right-click → Inspect)
* Go to the **Console** and **Network** tabs
* Look for error messages or failed script loads (especially from `add.js`)
* Check if another app's script is overriding or hijacking the Add to Cart behavior

## When to contact support

If the issue persists after completing all steps, gather the following before reaching out:

* Your current **theme name and version**
* A list of **cart-related apps** you're using
* Any **error messages** from your browser console

Send this information to the Upcart support team via in-app chat for faster troubleshooting.

***

## Summary

This issue is almost always caused by one of three things:

* A theme or app is forcing cart redirects
* Upcart's compatibility setting is off
* Another script is hijacking the add-to-cart behavior


# Auto-fulfill shipping protection is not working as expected
Source: https://docs.aftersell.com/upcart/auto_fulfill_shipping_protection_is_not_working_as_expected

This article outlines how Upcart's auto-fulfill shipping protection feature works and outlines steps to troubleshoot when it is not functioning as expected.

## How Auto-Fulfillment Works

Upcart automatically fulfills the **shipping protection** item when all of the following conditions are met:

1. **Auto-Fulfill Shipping Protection Is Enabled in Upcart**
   * In the Cart Editor, open the **Add-ons** module and go to its **Advanced settings** section.
   * Make sure **Auto-fulfill shipping protection** is turned on. The checkbox only appears once shipping protection itself is active in the module's **General settings** — if you can't find it, turn shipping protection on first.
2. **The Shipping Protection Product Is a Digital Item**
   * In Shopify, go to **Products** and locate the **Shipping Protection** product created by Upcart.
   * Open the product, scroll to the **Shipping** section, and ensure the checkbox **This is a physical product** is **unchecked**.
     * This ensures Shopify treats it as a digital product and allows automatic fulfillment. **Tip:** If you have multiple shipping protection tiers, all related products must meet this same condition.
3. **Required Product Properties Are Present**\
   Upcart fulfills the item by listening to the **orders/partially\_fulfilled** webhook.\
   When part of an order is fulfilled, Upcart automatically fulfills shipping protection if it identifies the following line item properties:
   * `__upcartAddon: XXX`
   * `__upcartShippingProtection: true` Check your product settings to confirm both properties are included.

<img alt="Shopify unfulfilled order showing a Shipping Protection line item with the Upcart add-on and shipping-protection line item properties" />

***

## Why Shipping Protection Is Treated as a Product

Shipping protection in Shopify is configured as a **product** to support tiered pricing and interaction with cart rules.\
This allows Upcart to calculate and apply protection dynamically based on order value or cart contents.

However, this approach can cause the product to appear in discount operations or visible storefronts unless configured properly.

***

## Managing Storefront Visibility

Because shipping protection is a real Shopify product, it can appear in your storefront search, collections, and recommendations unless you hide it. The simplest way to keep it out of view is Shopify's **Unlisted** product status.

1. In your Shopify admin, go to **Products** and open the **Shipping Protection** product created by Upcart.
2. In the **Status** dropdown near the top of the product page, select **Unlisted**.
3. Click **Save**.

An **Unlisted** product is hidden from your storefront search, collection pages, product recommendations, the Shopify Catalog, and search engines, while still working normally in the cart, at checkout, and for order fulfillment. This keeps shipping protection out of view for browsing customers while Upcart continues to add and auto-fulfill it in the background.

<Note>
  Unlisted products behave like Active products in the cart, at checkout, and on orders, so setting Shipping Protection to Unlisted does not interfere with auto-fulfillment or with how the add-on is applied to the cart.
</Note>

<Tip>
  Unlisted replaces the older approach of hiding this product through a `seo.hidden` metafield. You no longer need to edit metafields to keep it out of your storefront.
</Tip>

***

## Summary

To ensure shipping protection auto-fulfills correctly:

* Enable **Auto-fulfill shipping protection** in Upcart.
* Mark the product as **non-physical** in Shopify.
* Verify the correct **line item properties** are applied.
* Exclude it from discount rules, and set it to **Unlisted** to keep it out of your storefront, if needed.

Following these steps ensures seamless fulfillment and prevents conflicts with Shopify's discount or product visibility settings.


# Cart allows left/right scrolling on mobile
Source: https://docs.aftersell.com/upcart/cart_allows_left_right_scrolling_on_mobile

This article explains how to fix a bug that allows Upcart contents to move left and right.

# Overview

On certain mobile devices, users might be able to scroll the Upcart horizontally, exposing an unintended white space on the right. This usually occurs when a child element within the cart exceeds the viewport width or disrupts the layout’s natural constraints, resulting in horizontal overflow.

<img alt="Mobile Upcart cart drawer scrolling sideways to reveal unwanted white space on the right" />

***

## **CSS Solution**

To prevent this behavior and keep the cart constrained to the viewport width, simply copy the code below and add it to the following directory:

In the Cart Editor, open **Settings** and select the **Custom CSS** tab. Settings is a row of tabs — if you don't see Custom CSS, it's behind **More settings**.

```
.upcart-cart-body  
{  
	overflow-x: hidden !important;  
}
```


# Cart icon quantity/counter not updating
Source: https://docs.aftersell.com/upcart/cart_icon_quantity_counter_not_updating

This article outlines how to fix your cart icon quantity when not updating in Upcart.

# Overview

Some themes don't update the icon automatically and this guide will walk you through how to fix it using a bit of custom code. Follow the steps below to get everything syncing correctly.

**Here's an example of what this mismatch looks like:**

<img alt="Upcart drawer showing Cart 2 while the theme cart icon bubble still displays 1" />

***

# Important Steps Before You Start!

To fix the cart icon issue, you'll need to identify the class name of your cart icon. Every theme is different, and this step ensures the code works specifically for your store.

### **1. Use Chrome Developer Tools**

Every theme is different, so you'll need to use Chrome Developer Tools (Inspect) to identify the class name of your cart icon.

* Right-click your cart icon on your storefront and select **Inspect** in Google Chrome.
* Find the HTML element for your cart icon (e.g., **`<span class="cart-count-bubble">`**).
* **Need help using Chrome Developer Tools?** Check out [this guide](https://developer.chrome.com/docs/devtools/overview/) for step-by-step instructions.

### **2. Reach Out for Help (Optional)**

If you're unable to locate your cart icon class or feel stuck, don't worry! You have options:

* **Contact Your Theme Developer:** They know your theme best and can help you find the correct class.
* **Hire a Shopify Expert:** If you need additional support, Shopify has a directory of trusted experts who can assist. [Find a Shopify Expert here](https://experts.shopify.com/).

## 🚧 **Custom Code Disclaimer**

The example code provided below is just a template, **it won't work if you copy and paste it directly**. You must replace the placeholder class name (e.g., **`.cart-count-bubble > span`**) with the specific class name for your cart icon.

***

# Step by Step Fix

We've broken this process into three levels of fixes, starting with the simplest solution (Level 1). Each level builds on the previous one, try Level 1 first, then move to Level 2 or 3 only if needed.

## **Step 1: Add Custom Code in Upcart**

First, since we'll need to add some custom HTML code in the Upcart editor, let's get that section ready:

1. Go to **Upcart Editor > Settings**, then open the **Custom HTML** tab (behind **More settings** if it doesn't fit on the tab row).
2. Set the location as **Scripts (Before Load)**.
3. Paste your edited code here (we'll provide examples for each level below).

Here's what this looks like:

<img alt="Upcart Custom HTML settings with the HTML location set to Scripts Before Load" />

***

# **Step 2: Apply the fix by level**

## Level 1 (Basic)

When the cart loads, this script totals the quantities on the cart's line items and writes that into the count element inside your theme's cart bubble. It fits themes where the count lives in a simple nested element (for example, `.cart-count-bubble > span`).

**Don't Forget**

* Replace **`.cart-count-bubble > span`** with your cart icon class.
* Test it on your storefront after adding the code.

<img alt="Pasting the Level 1 count script into Upcart Custom HTML using the cart-count-bubble selector" />

## Example Code for Level 1

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>  
window.upcartSubscribeCartLoaded((event) => {  
    const countEl = document.querySelector('.cart-count-bubble > span');  
    const itemCount = event.cart.items.reduce((total, item) => total + item.quantity, 0);  
    countEl.innerText = itemCount;  
});  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnCartLoaded` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeCartLoaded` for all new scripts. Note that `event.cart` does not have an `item_count` property, use `event.cart.items.reduce((total, item) => total + item.quantity, 0)` to calculate the total item count.
</Note>

***

## Level 2 (Moderate)

If Level 1 didn't work, your theme may replace the entire cart icon HTML when the count changes. This version rebuilds the icon markup for empty vs. non-empty cart states so the count and icon stay in sync.

**Don't Forget**

* Replace **`#cart-icon-bubble-custom`** with your theme's cart icon wrapper selector.
* Test it after saving.

<Frame>
  <img alt="Pasting the Level 2 cart icon script into Upcart Custom HTML using the cart-icon-bubble-custom selector" />
</Frame>

### Example Code for Level 2

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>  
;(() => {  
function updateCartCount(itemCount) {  
    const iconWrapperEl = document.querySelector('#cart-icon-bubble-custom');  
    if (itemCount === 0) {  
        iconWrapperEl.innerHTML = `<span class="svg-wrapper"><svg xmlns="http://www.w3.org/2000/svg" fill="none" class="icon icon-cart-empty" viewBox="0 0 40 40"><path fill="currentColor" fill-rule="evenodd" d="M15.75 11.8h-3.16l-.77 11.6a5 5 0 0 0 4.99 5.34h7.38a5 5 0 0 0 4.99-5.33L28.4 11.8zm0 1h-2.22l-.71 10.67a4 4 0 0 0 3.99 4.27h7.38a4 4 0 0 0 4-4.27l-.72-10.67h-2.22v.63a4.75 4.75 0 1 1-9.5 0zm8.5 0h-7.5v.63a3.75 3.75 0 1 0 7.5 0z"></path></svg></span><span class="visually-hidden">Cart</span>`;  
    } else {  
        iconWrapperEl.innerHTML = `<span class="svg-wrapper"><svg xmlns="http://www.w3.org/2000/svg" fill="none" class="icon icon-cart" viewBox="0 0 40 40"><path fill="currentColor" fill-rule="evenodd" d="M20.5 6.5a4.75 4.75 0 0 0-4.75 4.75v.56h-3.16l-.77 11.6a5 5 0 0 0 4.99 5.34h7.38a5 5 0 0 0 4.99-5.33l-.77-11.6h-3.16v-.57A4.75 4.75 0 0 0 20.5 6.5m3.75 5.31v-.56a3.75 3.75 0 1 0-7.5 0v.56zm-7.5 1h7.5v.56a3.75 3.75 0 1 1-7.5 0zm-1 0v.56a4.75 4.75 0 1 0 9.5 0v-.56h2.22l.71 10.67a4 4 0 0 1-3.99 4.27h-7.38a4 4 0 0 1-4-4.27l.72-10.67z"></path></svg></span><span class="visually-hidden">Cart</span><div class="cart-count-bubble"><span aria-hidden="true">${itemCount}</span><span class="visually-hidden">${itemCount} item</span></div>`;  
    }  
}  
  
window.upcartSubscribeCartLoaded((event) => {  
    const itemCount = event.cart.items.reduce((total, item) => total + item.quantity, 0);  
    updateCartCount(itemCount);  
});  
})();  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnCartLoaded` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeCartLoaded` for all new scripts.

  Note that `event.cart` has **no** `item_count` property — the scripts above derive the total with `event.cart.items.reduce((total, item) => total + item.quantity, 0)` and pass it in as `itemCount`. Older copies of these snippets that interpolate `cart.item_count` throw a `ReferenceError` and silently never update the icon.
</Note>

***

## Level 3 (Advanced)

If your theme uses **separate** cart icon markup for desktop and mobile, run the same update logic against two selectors so each viewport gets the correct HTML and count.

**Don't Forget**

* Replace **`#cart-icon-bubble-custom-desktop`** and **`#cart-icon-bubble-custom-mobile`** with your theme's classes.
* Test thoroughly on both desktop and mobile views.

<img alt="Pasting the Level 3 script into Upcart Custom HTML with separate desktop and mobile cart icon selectors" />

### Example Code for Level 3

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>  
;(() => {  
function updateCartCount(itemCount) {  
    // Desktop  
    const desktopIconWrapperEl = document.querySelector('#cart-icon-bubble-custom-desktop');  
    if (itemCount === 0) {  
        desktopIconWrapperEl.innerHTML = `<span>Cart</span><span class="svg-wrapper"><svg xmlns="http://www.w3.org/2000/svg" fill="none" class="icon icon-cart-empty" viewBox="0 0 40 40"><path fill="currentColor" fill-rule="evenodd" d="M15.75 11.8h-3.16l-.77 11.6a5 5 0 0 0 4.99 5.34h7.38a5 5 0 0 0 4.99-5.33L28.4 11.8zm0 1h-2.22l-.71 10.67a4 4 0 0 0 3.99 4.27h7.38a4 4 0 0 0 4-4.27l-.72-10.67h-2.22v.63a4.75 4.75 0 1 1-9.5 0zm8.5 0h-7.5v.63a3.75 3.75 0 1 0 7.5 0z"></path></svg></span>`;  
    } else {  
        desktopIconWrapperEl.innerHTML = `<span>Cart (${itemCount})</span><span class="svg-wrapper"><svg xmlns="http://www.w3.org/2000/svg" fill="none" class="icon icon-cart" viewBox="0 0 40 40"><path fill="currentColor" fill-rule="evenodd" d="M20.5 6.5a4.75 4.75 0 0 0-4.75 4.75v.56h-3.16l-.77 11.6a5 5 0 0 0 4.99 5.34h7.38a5 5 0 0 0 4.99-5.33l-.77-11.6h-3.16v-.57A4.75 4.75 0 0 0 20.5 6.5m3.75 5.31v-.56a3.75 3.75 0 1 0-7.5 0v.56zm-7.5 1h7.5v.56a3.75 3.75 0 1 1-7.5 0zm-1 0v.56a4.75 4.75 0 1 0 9.5 0v-.56h2.22l.71 10.67a4 4 0 0 1-3.99 4.27h-7.38a4 4 0 0 1-4-4.27l.72-10.67z"></path></svg></span>`;  
    }  
  
    // Mobile  
    const mobileIconWrapperEl = document.querySelector('#cart-icon-bubble-custom-mobile');  
    if (itemCount === 0) {  
        mobileIconWrapperEl.innerHTML = `<span class="svg-wrapper"><svg xmlns="http://www.w3.org/2000/svg" fill="none" class="icon icon-cart-empty" viewBox="0 0 40 40"><path fill="currentColor" fill-rule="evenodd" d="M15.75 11.8h-3.16l-.77 11.6a5 5 0 0 0 4.99 5.34h7.38a5 5 0 0 0 4.99-5.33L28.4 11.8zm0 1h-2.22l-.71 10.67a4 4 0 0 0 3.99 4.27h7.38a4 4 0 0 0 4-4.27l-.72-10.67h-2.22v.63a4.75 4.75 0 1 1-9.5 0zm8.5 0h-7.5v.63a3.75 3.75 0 1 0 7.5 0z"></path></svg></span><span class="visually-hidden">Cart</span>`;  
    } else {  
        mobileIconWrapperEl.innerHTML = `<span class="svg-wrapper"><svg xmlns="http://www.w3.org/2000/svg" fill="none" class="icon icon-cart" viewBox="0 0 40 40"><path fill="currentColor" fill-rule="evenodd" d="M20.5 6.5a4.75 4.75 0 0 0-4.75 4.75v.56h-3.16l-.77 11.6a5 5 0 0 0 4.99 5.34h7.38a5 5 0 0 0 4.99-5.33l-.77-11.6h-3.16v-.57A4.75 4.75 0 0 0 20.5 6.5m3.75 5.31v-.56a3.75 3.75 0 1 0-7.5 0v.56zm-7.5 1h7.5v.56a3.75 3.75 0 1 1-7.5 0zm-1 0v.56a4.75 4.75 0 1 0 9.5 0v-.56h2.22l.71 10.67a4 4 0 0 1-3.99 4.27h-7.38a4 4 0 0 1-4-4.27l.72-10.67z"></path></svg></span><span class="visually-hidden">Cart</span><div class="cart-count-bubble"><span aria-hidden="true">${itemCount}</span><span class="visually-hidden">${itemCount} item</span></div>`;  
    }  
}  
  
window.upcartSubscribeCartLoaded((event) => {  
    const itemCount = event.cart.items.reduce((total, item) => total + item.quantity, 0);  
    updateCartCount(itemCount);  
});  
})();  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnCartLoaded` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeCartLoaded` for all new scripts.

  Note that `event.cart` has **no** `item_count` property — the scripts above derive the total with `event.cart.items.reduce((total, item) => total + item.quantity, 0)` and pass it in as `itemCount`. Older copies of these snippets that interpolate `cart.item_count` throw a `ReferenceError` and silently never update the icon.
</Note>

***

# Still not working?

If none of these levels solve the issue, don't worry, you're not out of options! This likely means your theme requires more advanced customization.

**Here's what you can do next:**

* Reach out to your theme developer for help.
* Hire a [Shopify Expert](https://www.shopify.com/partners/directory) who can create a custom solution tailored to your store.


# Change cart type in theme
Source: https://docs.aftersell.com/upcart/change_cart_type_in_theme

This article explains how to troubleshoot Upcart drawer issues by modifying your theme’s cart type setting.

## Overview

This guide helps you troubleshoot situations where **Upcart does not open** or customers are redirected to the cart page instead of seeing the Upcart drawer. Most of these issues are caused by theme cart type settings, Enhanced AJAX API Compatibility configuration, third-party app redirects, or checkout button routing.

<Note>
  If Upcart is not opening at all or redirecting to the cart page, see [Troubleshooting Upcart Not Opening or Redirecting to Cart Page](/upcart/troubleshooting_upcart_not_opening_or_redirecting) for a more comprehensive troubleshooting guide.
</Note>

***

## What Cart Type to Choose

Before diving into troubleshooting, check your theme's cart type setting first as this is the most common cause.

* **Page** - This is usually the best option since Upcart intercepts requests to the **/cart** page.
* **Drawer** - Select this if Upcart fails to launch and the **/cart** page is being triggered instead.
* **Confirmation Popup** - Use this if your theme supports it and the other options do not resolve the issue.

Testing both options only takes a few minutes, but **Page** is typically the most effective choice.

### How to Change Cart Type in Your Theme

1. Go to **Online Store > Themes > Customize** in your Shopify admin.
2. Open **Theme Settings > Cart > Cart Type**.
3. Choose either **Page** or **Drawer** based on the behavior you are troubleshooting.
4. Save your changes and test the cart on your storefront.

<img alt="Shopify theme editor cart settings showing the cart type option" />

<Note>
  If you cannot locate this setting, contact your theme developer. This setting is controlled by your theme and Upcart cannot modify it directly.
</Note>

***

## Troubleshooting Steps

If changing the cart type does not resolve the issue, work through the following steps in order.

### 1. Check Enhanced AJAX API Compatibility

This setting controls how Upcart handles Add to Cart events and is one of the most common causes of redirect issues.

1. Go to **Upcart > Cart Editor > Settings > Cart settings**, then expand **Advanced Settings**.
2. Locate **Enhanced Ajax API compatibility**.
3. This setting is **disabled by default** for most stores. When disabled, Upcart intercepts Add to Cart calls and prevents redirects.
4. If it is enabled, other apps can take control of cart behavior and redirect customers to the cart page. Try disabling it and test.
5. If disabling it causes other issues, re-enable it and use the manual Upcart API (`upcartRegisterAddToCart`) instead.

For full guidance on this setting, see [Enhanced AJAX API Compatibility](/upcart/enhanced_ajax_api_compatibility).

### 2. Check for Third-Party App Redirects

Many third-party apps override cart behavior and can redirect customers away from the Upcart drawer. If your Add to Cart button is specifically sending customers to the cart page, see [Why Does 'Add to Cart' Go to the Cart Page Instead of Upcart?](/upcart/why_does_add_to_cart_go_to_the_cart_page_instead_of_upcart) for more detail.

Open the settings of any cart-related apps and look for options such as:

* Redirect to cart
* Go to cart after add
* Automatically open cart page
* Action after product is added

Change these to **Stay on page** or **Do nothing**.

**Common app-specific fixes:**

* **PageFly** - Disable redirection rules in the PageFly app settings.
* **Globo Product Options** - Deactivate auto-redirection to Shopify's cart.
* **Replo** - Adjust the "go to page" settings to enable the cart drawer.
* **Zepto Product Personalizer** - Go to Zepto > Settings > Add to Cart Settings and change "Action after a product is added to the cart" to "Stay on the product page and show a success message."

If you are unsure which app is causing the conflict, disable cart-related apps one at a time and test after each until Upcart starts working correctly.

### 3. Check Checkout Button Routing

If customers click the checkout button inside Upcart and are redirected to the cart page instead of checkout:

1. Go to **Upcart > Cart Editor > Settings > Cart settings**.
2. Locate **"Go to cart page when pressing checkout button"**.
3. Turn this **OFF**.
4. Save and test.

<Note>
  Custom checkout page redirection requires advanced coding and is not directly supported by Upcart. If you need to route customers to a custom checkout page, you will need to work with a developer.
</Note>

### 4. Check Theme Cart Redirect Settings

Some themes automatically redirect customers after adding a product, bypassing Upcart entirely.

1. Go to **Online Store > Themes > Customize**.
2. Open **Theme Settings > Products** (or Cart).
3. Look for settings like:
   * Enable cart redirection
   * Redirect to cart after add
   * Go to cart after add
4. Turn these **OFF**.
5. Save and test.

### 5. Clear Browser Cache

Old cached scripts can retain previous cart behavior and prevent Upcart from loading correctly.

1. Open your browser settings.
2. Go to **Privacy and Security**.
3. Select **Clear Browsing Data**.
4. Clear cached images, files, and cookies.
5. Refresh your store and test.

### 6. Test With a Default Shopify Theme

If the issue persists, temporarily switch to a default Shopify theme such as Dawn to rule out a theme-specific conflict.

1. Go to **Shopify Admin > Online Store > Themes**.
2. Add and enable a free theme like Dawn.
3. Test Upcart on the default theme.

If Upcart works correctly on Dawn, the issue is with your custom theme. Contact your theme developer for assistance.

***

## Preventative Measures

* **Review configurations after updates** - Theme and app updates can reset or override cart settings. Check your cart type and app configurations after any major update.
* **Test app compatibility before installing** - Before adding new third-party apps, confirm they are compatible with Upcart.
* **Use a Draft theme for testing** - Test changes on a Draft theme before publishing to avoid disrupting your live store. See [Enabling Upcart in a Draft Theme Only](/upcart/enabling_upcart_in_a_draft_theme_only) for instructions.

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can the Upcart checkout button redirect to a custom checkout page?">
    No, custom checkout page redirection requires advanced coding and is not directly supported by Upcart. If you need this, you will need to work with a developer.
  </Accordion>

  <Accordion title="Why does the cart still redirect to Shopify after enabling Upcart?">
    Make sure Upcart is active and published in the Cart Editor. Also clear your browser cache to ensure the updated behavior takes effect. If the issue persists, check for third-party app conflicts using the steps above.
  </Accordion>

  <Accordion title="How do I fix a product add-on app causing a redirect?">
    Open the add-on app's settings and look for any auto-redirection or "go to cart" configurations. Disable them if they conflict with Upcart. See Step 2 above for app-specific examples.
  </Accordion>
</AccordionGroup>

***

**Need help?**

If you have worked through all the steps above and the issue persists, reach out to our support team via the in-app chat or by emailing [support@upcart.app](mailto:support@upcart.app).


# Discount module not showing
Source: https://docs.aftersell.com/upcart/discount_module_not_showing

Troubleshoot missing discount modules in customized store setups.

# Overview

If your discount module isn’t appearing in the cart drawer, it’s typically due to one of the reasons outlined below.

In most cases, the issue is related to the type of discount being used, a legacy cart system, or a theme/app conflict.

# Reason 1 – Not a True Shopify Discount

The Discount or Savings row in the cart footer will only display when a **true Shopify discount** is applied to the cart.

This means the discount row will **not** display for:

* Simulated or “fake” discounts created by bundle apps
* Apps that adjust line item pricing instead of applying a real Shopify discount
* Custom pricing logic that shows “before” and “after” pricing
* **Compare-at prices set in the Shopify admin** — by default. These are product pricing displays rather than active discounts, so the row ignores them unless you opt in (see below).

If no real Shopify discount is applied through Shopify’s backend, the discount row will remain hidden by design.

<Note>
  **Compare-at savings can be included, on Cart Summary 2.0.** Enable **Show compare-at price savings in footer total** under **Settings > Cart settings > Advanced Settings**, and the savings row adds every item's compare-at difference to the discounts it already counts. Only the Version 2 Cart Summary module reads this setting — on Version 1 the savings row keeps counting discount codes alone. See [Show compare-at price savings in footer total](/upcart/show_compare_at_price_savings_in_footer_total).
</Note>

## Bundle Apps & Discounts

Some bundle or discount apps use pricing adjustments instead of applying a true Shopify discount.

Shopify only recognizes discounts that are created and applied through the Shopify admin (discount codes or automatic discounts). If an app:

* Adjusts line item prices
* Shows “before” and “after” pricing
* Displays a calculated “savings” amount
* Combines products into a discounted bundle price

but does not apply an actual Shopify discount object, Upcart will not detect it as a discount.

As a result, the discount row in the cart footer will not display.

# Reason 2 - Legacy Cart Token

Some stores still use Shopify’s older cart system, which lacks support for the features required by Upcart’s discount module. When this is detected, Upcart automatically hides the discount module to prevent issues.

## How to identify

To check if your store uses an outdated cart token:

1. Add an item to your cart with Upcart enabled.
2. Open your browser’s developer console.
3. Paste and run the following code:

```
window.upcartModifyCart = (cart) => { if (!cart.token) { alert('No cart token found'); return; } const isLegacyCartToken = cart.token.match(/^[0-9a-f]{32}$/) !== null; alert("Is this a legacy cart token? " + (isLegacyCartToken ? "Yes" : "No")); return cart; }
```

1. Change the quantity of any cart item to trigger the alert.

## How to fix

If you confirm the use of a legacy cart token, you’ll need to contact **Shopify support** or your **theme developer** to update your store’s cart system.\
See Shopify’s documentation on [Cart API Migration](https://shopify.dev/docs/api/ajax#cart-token).

# Reason 3 - Theme or App Conflict

Custom CSS or JavaScript from your theme or other installed apps may be unintentionally hiding the discount module.

## How to Identify

Inspect your theme and custom CSS for any styles that include:

* `display: none;`
* `visibility: hidden;`
* `opacity: 0;`

These could be targeting the discount module’s container or children elements.

## How to Fix

Reach out to your theme developer or the developer of the conflicting app. Let them know the discount module needs to remain visible, and ask them to adjust their CSS or JavaScript accordingly.


# Enabling Upcart in a draft theme only
Source: https://docs.aftersell.com/upcart/enabling_upcart_in_a_draft_theme_only

This article explains how to enable and test Upcart in a draft theme without making it live on your storefront.

# Overview

While Upcart includes a built-in preview feature that lets you view the cart on your live theme without publishing it (found in the top-left corner next to **Cart Status**), there are cases where you may need to test it directly within the **theme editor**.

***

**Steps to Follow**

1. In the **Upcart Cart Editor**, ensure your cart is **published**.
2. In your **Shopify Admin**, go to **Online Store → Themes**.
3. On your **Live Theme**, click **Customize → App embeds** and confirm the **Upcart** embed is disabled. Save if you made any changes.
4. On your **Draft Theme**, click **Customize → App embeds**, enable the **Upcart** embed, and click **Save**.
5. Click the three-dot menu in the top-left corner of the theme editor and select **Preview**.

✅ **Success!** Upcart is now active only on your Draft Theme. Any changes saved in the Upcart Cart Editor will be visible there without affecting your Live Theme.

Here’s a quick tutorial walking you through these steps:

<img alt="Shopify Themes page showing the live theme and a draft theme in the library" />

***

## Important Notes

1. As outlined in the **Quickstart Guide to Upcart**, showing the cart to shoppers takes two parts:

* Publishing a cart in the **Upcart interface**.
* Enabling the **Upcart** app embed on the theme you want it to appear on.

The two are independent. Publishing a cart doesn’t require the app embed to be on anywhere — a cart can be Live while every theme has the embed off, which the app shows as an **App embed off** badge. So you do **not** need to temporarily enable the embed on your live theme first; enabling it on the draft theme alone is enough.

2. If you have Discounts configured in your cart, those rules will remain active via Shopify's discount system **even when the app embed is disabled**.

Disabling the app embed only hides the Upcart cart drawer from your storefront. It does not disable your active Discount rules. Customers will still see Discount adjustments applied at checkout.


# Express payment buttons not clickable in Upcart
Source: https://docs.aftersell.com/upcart/express_payment_buttons_not_clickable_in_upcart

This article explains how to troubleshoot Shopify express checkout buttons, when they aren't working in Upcart

⚠️ **Important notice**

The theme snippet below applies to both versions of the Upcart cart modules — it makes Shopify render the accelerated-checkout buttons on the page, which is what Upcart needs regardless of module version.

The `.additional-checkout-buttons` selector below is Shopify's own class on the accelerated-checkout container, not an Upcart module class, so it is the same on either cart version.

## Overview

Sometimes express checkout buttons are not clickable or do not appear inside Upcart. This is a common issue caused by how **Shopify controls the rendering of express payment buttons** within themes.

This guide explains why this happens and what you can do to fix it.

***

## Required Setup for the New Module

⚠️ **Important:** These steps apply to the **new Express Payments module** in Upcart, not the legacy version.

To make express checkout buttons work correctly in Upcart, you must add a small snippet of code to your Shopify theme. Without this snippet, Shopify will not load the payment buttons properly inside the cart drawer.Before making these changes, verify that relevant payment methods (e.g., Shop Pay, PayPal, Apple Pay, Google Pay) are enabled in your Shopify Admin account settings. Without enabling these methods, the buttons will not be visible. Additionally, ensure that the snippet is placed directly under the opening `<body>` tag in your theme file (e.g., `<body class="...">`). If placed incorrectly, such as after the closing `</body>` tag, the express checkout buttons may not function properly.

***

## How to Fix

1. Go to your **Shopify Admin**.
2. Navigate to **Online Store > Themes > Edit Code**.
3. Open **layout/theme.liquid**, find the `<body>` line, and add the snippet below on a new line directly beneath it. It has to go there — not in `cart-drawer.liquid` or elsewhere — because the buttons must exist on every page where the cart can open.

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{% if additional_checkout_buttons %} <div style="display: none !important">     {{ content_for_additional_checkout_buttons }} </div> {% endif %}
```

1. Save your changes and refresh your storefront.
2. Reopen the cart drawer to verify that express checkout buttons (such as Shop Pay, PayPal, Apple Pay, or Google Pay) now appear and are clickable.

Refer to the [**Express Payments Module**](/upcart/express_payments_module)\*\* Guide\*\* for full setup instructions.

***

## Why This Happens

Express payment buttons are fully managed by **Shopify**, not Upcart. This means:

* Upcart doesn't render its own buttons. It **clones Shopify's** accelerated-checkout buttons from the page into the cart drawer, which is why they have to be present on the page in the first place — that's what the theme snippet above guarantees.
* **Apple Pay** will only show on Apple devices that have Apple Pay set up.
* Upcart does not control which express buttons appear, since the content and functionality are handled by Shopify.

🎨 **Note:**\
The buttons in Upcart act as visual containers, while Shopify controls their display and behavior. Upcart cannot modify their appearance or function.

***

## Common Problems and Fixes

## 1. The Buttons Aren't Rendered on the Page

This is the most common cause. Upcart clones Shopify's buttons out of the page, so if the page doesn't render them there is nothing to clone and the cart shows an empty space.

**What to do:**

* Add the theme snippet from **How to Fix** above, directly below the `<body>` line in `layout/theme.liquid`.

<Warning>
  **Don't remove your theme's own express buttons to "avoid a conflict".** Upcart depends on them being present. Removing them from the theme, or turning them off in theme settings, removes the source Upcart clones from — which makes this problem worse, not better.
</Warning>

***

## 3. CSS Is Blocking the Buttons

Some themes hide express buttons by default using CSS. For example:

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.additional-checkout-buttons {   display: none !important; }
```

**What to do:**

* Review your theme’s CSS.
* Ask your theme developer to ensure no CSS rules are hiding or disabling the buttons in the Upcart drawer.

***

## 4. Legacy Settings Are Interfering

If you used the older version of the Express Payments module, saved settings may conflict with the new setup.

**What to do:**

* Open the old Express Payments module (if still visible).
* Uncheck any previous options and save.
* Test again using the new module.

***

## Still Having Issues?

## Disable Shadow DOM in Upcart

In some cases, express payment buttons may fail to load or update because **Shadow DOM** is enabled in Upcart.

**What is Shadow DOM?**\
Shadow DOM isolates Upcart from the rest of your store’s code to improve stability. However, in rare cases, this separation can prevent Shopify’s express buttons from updating correctly.

**How to Disable Shadow DOM:**

1. Go to **Upcart > Cart Editor > Settings > Cart settings**, then expand **Advanced Settings**.
2. Uncheck **Render Cart in Shadow DOM**.
3. Save and test again.

⚠️ **Important:**\
Always test your cart after turning off Shadow DOM, as it may affect how other apps or theme elements interact with Upcart.

💡 **Note:** Disabling Shadow DOM may fix this issue but can introduce CSS conflicts with your theme. See the [Shadow DOM Setting](/upcart/render_cart_in_shadow_dom_setting) doc for the full trade-off.

***

## Need More Help?

If the issue persists after completing these steps:

* Contact your **theme developer** to help remove conflicting code or settings.
* You can also reach out to a [**Shopify Expert**](https://www.shopify.com/partners/directory) for advanced theme edits or integration assistance.

***

## References

* Shopify Help – Accelerated Checkouts
* Shopify Dev Docs – Express Payment Buttons


# Fixing missing carousel arrows in Upcart's upsell module V1.0
Source: https://docs.aftersell.com/upcart/fixing_missing_carousel_arrows_in_upcarts_upsell_module_v10

This article explains how to fix missing carousel arrows on the live storefront when they appear in the editor preview.

# Overview

If you're experiencing an issue where the carousel arrows are missing in Upcart's upsell module, it's usually due to a compatibility issue with your store's theme.

To resolve this, you can manually add the arrows by applying a customization using custom HTML in Upcart's editor settings.

**To access the custom code fields in Upcart:**

**Cart Editor** > **Settings**, then the **Custom HTML** and **Custom CSS** tabs. Settings is a row of tabs — anything that doesn't fit sits behind **More settings**.

***

## HTML

For this fix, open the HTML dropdown menu and select **"Scripts (before load)"**, then paste the following code into that section:

```
<script>
  window.upcartSubscribeCartOpened(() => {
    setTimeout(() => {
      // The cart may render inside a shadow root, where document.querySelector
      // cannot reach it. Search the shadow root when there is one.
      const host = document.getElementById('upCart');
      const scope = host?.shadowRoot ?? document;

      const buttonLeft = scope.querySelector('.control-arrow.control-prev');
      if (buttonLeft) buttonLeft.innerText = "<";

      const buttonRight = scope.querySelector('.control-arrow.control-next');
      if (buttonRight) buttonRight.innerText = ">";
    }, 300);
  });
</script>
```

<Warning>
  **Don't use a bare `document.querySelector` here.** Upcart renders inside a shadow root on most stores (it's the default for newer installs), and `document.querySelector` can't see into one — the script would find nothing and, without the `if` guards, throw on `null`. The `host?.shadowRoot ?? document` line above works either way.
</Warning>

<Note>
  **Legacy note:** `window.upcartOnCartOpened` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeCartOpened` for all new scripts.
</Note>

Here's what your custom HTML settings should look like in Upcart:

<img alt="Upcart Custom HTML settings with the carousel arrow script in Scripts Before Load" />

## CSS

If you're still having issues with the position of the carousel arrows, try applying the following CSS fix:

```
.carousel.carousel-slider .control-next {  
  right: -34px !important;  
}
```

***

## Explanation

We often use CSS pseudo-elements (`::before`) that are contained inside the buttons to display the carousel arrows. However, some store themes choose to block the rendering of pseudo-elements, which causes the carousel arrows to disappear from the cart drawer.

This creates an issue where the upsell carousel arrows appear correctly in the editor preview but not on the actual live storefront.


# How to exclude discounts in reward goal
Source: https://docs.aftersell.com/upcart/how_to_exclude_discounts_in_reward_goal

This article explains how to stop applied discounts from reducing progress in the Upcart rewards bar.

# Overview

By default, a discount a customer applies reduces their progress toward a reward: the rewards bar measures the cart total **after** discounts. A \$100 cart with a \$20 discount counts as \$80 against your tier thresholds.

One checkbox changes that, no code required.

<img alt="Use pre-discounted prices for cart total checkbox setting with description" />

***

## How to ignore discounts in reward calculations

Go to the **Rewards** module in the Cart Editor and open the **Rewards calculation** section.

Enable the checkbox labeled:\
**“Use pre-discounted prices for cart total”**

<Note>
  The checkbox only appears when **Rewards calculation** is set to **Cart total (\$)**. On **Cart quantity (#)** there is nothing for it to do, so it's hidden.
</Note>

When this is turned on:

* The rewards bar bases progress on the **cart total before any discounts**
* Applied discounts — manual codes or automatic — no longer reduce progress
* Customers don't lose reward progress after applying a coupon

Use this if you want customers to still unlock rewards even when they apply a coupon.

***

## Default behavior without this setting enabled

With the checkbox **off**, progress is measured against the cart total after all discounts have been applied.

Example:

* Tier 1 = Free shipping at \$100
* Cart = \$100 before a \$20 discount → now \$80
* Result = the bar shows \$80 of \$100, so the reward is **not** unlocked

This prevents a customer being told they unlocked free shipping when their cart no longer meets the threshold.

<Warning>
  **This does not vary by reward type.** Whether Tier 1 is free shipping, a product, or a discount, the same calculation applies. The one checkbox above is what controls it.
</Warning>

***

## Rewards you've already earned don't count toward the next tier

Separately from the discount setting, the value of any reward items already in the cart is subtracted before progress is measured. A free gift the customer just unlocked can't push them toward the next tier on its own. Gift cards are excluded from this subtraction.

***

## Quick summary

| Setting                                                      | What progress is measured against                                      |
| ------------------------------------------------------------ | ---------------------------------------------------------------------- |
| **Use pre-discounted prices for cart total** — on            | Cart total before discounts, minus any reward items already granted    |
| **Use pre-discounted prices for cart total** — off (default) | Cart total after all discounts, minus any reward items already granted |


# How to fix broken cart editor layout from invalid HTML
Source: https://docs.aftersell.com/upcart/how_to_fix_broken_cart_editor_layout_from_invalid_html

Fixing the app UI in case it appears broken after adding custom code.

# Overview

If invalid or broken HTML is added to the Cart Editor’s Custom HTML field, it can break the layout and make the editor interface unusable. This guide walks you through how to temporarily fix the layout so you can safely remove the broken code and restore full functionality.

## What Causes the Issue

This problem usually occurs when a merchant:

* Inserts `<style>` or `<script>` tags without proper structure
* Leaves HTML tags unclosed or mismatched
* Adds layout-breaking content to the Custom HTML field

As a result, the Cart Editor becomes unreadable or unusable and may lock users out from editing or even scrolling the page.

## Temporary Fix Using Developer Tools

Follow these steps to temporarily fix the layout using your browser’s Developer Tools so you can access the Custom HTML field.

## Step 1: Open DevTools

1. Open the Cart Editor in the Upcart app
2. Right-click anywhere on the page and select **Inspect**, or press:

   * `Cmd + Option + I` (Mac)
   * `Ctrl + Shift + I` (Windows)

## Step 2: Find the Broken Layout Container

1. In the **Elements** tab of DevTools, click the selector tool (top-left corner of DevTools)
2. Hover over the Cart Editor layout and find the green-highlighted section to the left of the settings panel. It should be labeled:

   ```
   .Polaris-Page__Content--fullWidth
   ```
3. Go six levels up in the hierarchy until you reach:

   ```
   .Polaris-Frame__Content
   ```

## Step 3: Disable the Fixed Position

1. With `.Polaris-Frame__Content` selected, look under the **Styles** tab
2. Find the `position: fixed` property and uncheck it

This should unlock the page and let you scroll through the layout again.

## Remove the Invalid HTML

Now that the layout is accessible again:

1. Scroll to the **Custom HTML** field
2. Look for any broken HTML or embedded CSS that might have caused the issue

Example of what typically breaks the layout:

```
<style>  
  body {  
    background: red;  
  }  
</style>
```

1. Copy the content elsewhere as a backup, then delete it
2. Save your changes

## Confirm It’s Fixed

After saving, the Cart Editor should load normally again. If the issue persists, check again for leftover invalid tags or reach out to the merchant to confirm what was added.

## Best Practices to Prevent This Issue

* Only insert complete and valid HTML
* Avoid adding inline `<style>` blocks directly in HTML locations
* Use the **Custom CSS** section instead of adding CSS into HTML fields
* Always preview your changes in Sandbox mode if unsure


# Manual upsell trigger limitations
Source: https://docs.aftersell.com/upcart/manual_upsell_trigger_limitations

This article outlines how to resolve manual upsell errors in Upcart by following these tips to avoid Shopify’s data size limitations.

# Overview

This article explains why you might encounter an error when saving **manual upsell triggers** in Upcart and how to prevent it.

You can find this setting by going to **Upcart > Editor > Upsells Module**.

If you see the error toast **“Unable to save changes,”** it is usually due to exceeding **Shopify’s data size limit**. When Shopify returns a more specific reason, Upcart shows that message instead.

There is no fixed number of upsell lines that will cause this issue. The limit depends on the **total amount of data** being saved. Some products, especially those with many variants or detailed configurations, contain more data than others. As a result, the limit can vary depending on product complexity and quantity.

***

## Tips to Avoid the Shopify Data Size Limit Error

**1. Use Collections**\
Instead of adding products individually, use **collections**. This reduces data load and makes your setup easier to manage.

**2. Combine Upsell Rows**\
If multiple rows share the same trigger product, merge them into a single row. This helps conserve data space.

**3. Choose Upsells Wisely**\
Display only the most relevant upsells. Showing too many options can confuse shoppers and reduce their effectiveness due to decision fatigue.

***

## Additional Resources

For more information on setting up and optimizing the Upsells module, see our [module setup guide](/upcart/upsells_module).

##


# Preventing reward exploits and automatically open Upcart on Shopify cart page
Source: https://docs.aftersell.com/upcart/preventing_reward_exploits_and_automatically_open_upcart_on_shopify_cart_page

This article shows how to stop customers from getting unlimited free products on your store.

# Overview

Upcart rewards allow you to offer free gifts or bonus items based on customer behaviour. However, without proper controls, customers may be able to access these reward products without actually qualifying for them.

This guide outlines two recommended methods for securing your rewards. You can implement one or both depending on your level of control and theme flexibility.

***

# Method 1: Remove Manual Add-to-Cart and Quantity Controls in Shopify

Some customers may try to:

* Add reward products from their **product pages** using the regular “Add to Cart” button
* Visit Shopify’s **/cart** page and manually increase the quantity of reward items

These actions occur outside of the Upcart experience and are not automatically restricted. This method helps prevent those behaviours entirely.

***

# Method 2: Automatically Open Upcart on the Theme Cart Page

If you prefer a lighter approach, you can redirect customers into the Upcart experience anytime they attempt to access the Shopify cart page.

## Overview

* Automatically opens the Upcart drawer when visiting `/cart`
* Can be combined with hiding cart content and showing a message

## Setup Instructions

1. In the Cart Editor, go to **Settings**, open the **Custom HTML** tab (behind **More settings** if it doesn't fit on the tab row), and set the location to **Scripts (Before Load)**
2. Paste the following script:

Modern API (recommended):

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  var cartWasOpened = false;
  window.upcartSubscribeCartLoaded(function (event) {
    if (!cartWasOpened && document.location.pathname === "/cart") {
      window.upcartOpenCart();
      cartWasOpened = true;
    }
  });
</script>
```

Legacy API (still works but deprecated):

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>  
  var cartWasOpened = false;  
  upcartOnCartLoaded = (cart) => {  
    if (document.location.pathname == "/cart") {  
      upcartOpenCart();  
      cartWasOpened = true;  
    }  
  }  
</script>
```

3. Optionally, edit the Shopify cart page to:

* Hide the **Items** section
* Add a **Rich Text** block such as:\
  “To view your cart, please use the drawer in the top-right corner.”

This does not block editing but encourages customers to interact with Upcart instead.

***

## Watch the Video Walkthrough

**For a full demonstration, watch the step-by-step video guide.**

It covers hiding Add to Cart buttons, removing quantity selectors, and preventing unauthorized cart edits:

<iframe title="Preventing Reward Exploits" />

## Step-by-Step Instructions from the Video

## Step 1: Create a Custom Product Template

1. Navigate to **Online Store > Themes > Customise**
2. Select **Products > Create Template**
3. Enter a name (e.g., `free-products`) and click **Create Template**

## Step 2: Remove Purchase Elements

1. In the new template editor, remove:
   * The **variant picker**
   * The **quantity selector**
   * The **Add to Cart / Buy buttons**
2. Click **Save**

## Step 3: Assign the Template to Your Reward Product

1. In the Shopify admin, search for your free gift product
2. Scroll to the **Theme Template** section
3. Select your new `free-products` template instead of the default one

This removes the ability for customers to manually add the product to their cart via its product page.

## Step 4: Disable Cart Quantity Controls

1. Go to **Online Store > Themes > Edit Code**
2. Open the file responsible for rendering the cart page (commonly `main-cart-items.liquid`)
3. Search for `quantity`, then:
   * Comment out the **quantity heading**
   * Comment out the entire **quantity selector block** (`<td>` through `</td>`)
   * Optionally comment out the **remove button** (trash icon), if applicable

Use `Control + /` or wrap code blocks with `{% comment %}` and `{% endcomment %}` to safely disable them.

This ensures customers cannot edit reward quantities or manipulate their cart through Shopify’s native cart page.

***

## Choosing the Right Approach

|                                     |                           |
| ----------------------------------- | ------------------------- |
| Objective                           | Recommended Method        |
| Fully block unauthorized reward use | Method 1                  |
| Nudge customers into Upcart         | Method 2                  |
| Maximise protection                 | Use both methods together |

***

## Need Assistance?

If you're unsure which files to edit or prefer help setting this up, please contact our support team. We're happy to guide you through the process.


# Product images in Upcart are stretched / squished
Source: https://docs.aftersell.com/upcart/product_images_in_upcart_are_stretched_squished

This article explains how to fix product images in Upcart that appear cut off, stretched, or squished.

⚠️ **Important notice**

This customization only works with Version 1 of the Upcart cart modules. If you recently upgraded your cart to Version 2, these customizations may not work. You will need to use the new selectors provided for Version 2 in the [migration guide.](/upcart/upcart_v20_migration_guide)

If your customizations are not working as expected, you can also revert your cart back to Version 1 instead of using Version 2.

We are currently working on new customization templates for Version 2 of the modules, and they will be available soon.

## Overview

If your product images look stretched, squished, or cut off in Upcart, this is usually caused by a **theme styling conflict**. Some Shopify themes apply global image styling that affects how product images display inside Upcart.

You can fix this issue by adding a short CSS customization directly within Upcart’s editor settings.

***

## How to Fix It

Follow these steps to apply a CSS customization that preserves your product image proportions.

## Accessing Custom CSS Settings

1. Open the **Upcart App** from your Shopify dashboard.
2. Navigate to the **Cart Editor**.
3. Open **Settings** and select the **Custom CSS** tab. Settings is a row of tabs — if you don't see Custom CSS, it's behind **More settings**.

***

## Adding the CSS

1. Copy and paste the following CSS snippet into the **Custom CSS** field:

```
#CartPopup img {  
  object-fit: contain !important;  
}  
  
.upcart-upsell-item-image-wrapper a {  
  height: 100% !important;  
  display: flex !important;  
}  
  
.upcart-upsell-item-image-wrapper {  
  background-color: transparent !important;  
}  
  
@media (max-width: 600px) {  
  [class*="styles_ProductRow__imageWrapper__"] {  
    height: auto !important;  
  }  
}
```

1. Save your changes.
2. Refresh your storefront and open Upcart to confirm that the images now display correctly.

***

## Why This Happens

Some Shopify themes apply global CSS rules that resize or crop images in ways that affect how they appear in third-party apps like Upcart. These rules can override Upcart’s default styling and distort image proportions.

The CSS snippet above ensures that product images **maintain their original aspect ratio** and display correctly on both desktop and mobile devices.


# Site header overlaps Upcart
Source: https://docs.aftersell.com/upcart/site_header_overlaps_upcart

This article explains how to fix an issue where the Upcart widget is hidden behind your site header when opened.

### Why This Happens

In some Shopify themes, the header has a higher **z-index** than Upcart, causing the cart to appear underneath it. This can make Upcart look partially hidden or inaccessible when customers open the cart.

***

## How to Fix

Follow the steps below to bring Upcart in front of your site header:

1. **Copy the code** provided at the bottom of this article.
2. In your Shopify admin, open the Upcart **Cart Editor**, go to **Settings**, and select the **Custom HTML** tab. Settings is a row of tabs — if you don't see Custom HTML, it's behind **More settings**.
3. Click the **HTML dropdown** and select **Scripts (Before Load)**.
4. **Paste the code** into the field.
5. Click **Save changes**.
6. **Refresh your storefront** and test your cart.

After completing these steps, the cart should display correctly above your site header.

***

## Code Required:

```
<script>  
	// Find UpCart  
	let upcart = document.querySelector("#upCart");  
  
	// Find the site's body  
	let body = document.body;  
	  
	// If we found both  
	if(upcart && body)  
			// Move upcart to the top of the body's children so it takes priority over site header  
	    body.firstChild.before(upcart)  
</script>
```


# Unable to scroll the store page when Upcart closes
Source: https://docs.aftersell.com/upcart/unable_to_scroll_the_store_page_when_upcart_closes

This article outlines how to fix store page scrolling issues that occur after closing Upcart.

## Overview

If your store page becomes unscrollable after closing Upcart, it is likely caused by your theme’s logic that locks the page scroll when a cart drawer is open. Additionally, Upcart now provides built-in settings to address these issues, such as overriding existing scroll locking logic.

You can fix this by using built-in settings within Upcart or by adding a small customization to remove the scroll lock behavior.

***

How to Fix It

# Using Built-In Solutions

For most cases, built-in options in Upcart settings can resolve scrolling issues without requiring custom code.

1. **Enable "Override existing scroll locking logic"**:

   * Open the Cart Editor in your Upcart settings.
   * Go to **Settings** → **Cart settings**, then expand **Advanced Settings**.
   * Enable **Override existing scroll locking logic**. Its description covers exactly this case: a theme or third-party app leaving the page scroll-locked after the cart closes.

   There is no separate mobile or overlay scroll setting — this one checkbox covers both.

Follow these steps to apply a customization that restores page scrolling after the cart closes.

***

## Accessing Custom HTML Settings

1. Open the **Upcart App** from your Shopify dashboard.
2. Navigate to the **Cart Editor**.
3. Open **Settings** and select the **Custom HTML** tab. Settings is a row of tabs — if you don't see Custom HTML, it's behind **More settings**.

***

## Adding the Code

1. For advanced or specific cases where built-in solutions do not resolve the issue, you can apply custom HTML code in Upcart. Choose where to apply the HTML code in Upcart. For this fix, select the section **Above Announcements/Rewards**.
2. Add the following code snippet:

```
<script>  
window.upcartSubscribeCartOpened(() => {  
  var elementLockingThePage = document.querySelector('body');  
  if (elementLockingThePage != null) {  
    elementLockingThePage.setAttribute('style', 'overflow-Y:hidden !important');  
  }  
});  
window.upcartSubscribeCartClosed(() => {  
  var elementLockingThePage = document.querySelector('body');  
  if (elementLockingThePage != null) {  
    elementLockingThePage.setAttribute('style', 'overflow-Y:scroll !important');  
  }  
});  
</script>
```

<Note>
  **Legacy note:** `window.upcartOnCartOpened` and `window.upcartOnCartClosed` callbacks still work but are deprecated and log console warnings. Use `upcartSubscribeCartOpened` and `upcartSubscribeCartClosed` for all new scripts.
</Note>

1. Save your changes.
2. Refresh your storefront and test closing the cart to confirm scrolling is restored.

***

## Why This Happens

When Upcart opens, it hides your store’s native cart drawer and takes over its visual space. However, some themes include code that locks page scrolling whenever a drawer is active. After Upcart closes, that lock may remain in place, preventing the page from scrolling. On mobile devices, additional issues such as overlays persisting or causing the page to become unclickable can occur. These problems are often tied to mobile-specific scroll locking behaviors or unreset overlays.

The script above restores normal scroll behavior by manually resetting the page’s overflow property when the cart is opened or closed.

***

Need Help or Further Troubleshooting

# Additional Steps Before Contacting Support

1. Ensure **Override existing scroll locking logic** is enabled.
2. Double-check if custom code or third-party scripts might interfere.

If you are still experiencing scrolling issues after applying the fix, your theme may use a different selector or custom scroll logic.

Contact **Upcart Support** for assistance identifying the correct selector, or reach out to your **theme developer** for help adjusting your theme’s scroll settings.


# Upcart requires two clicks for an action
Source: https://docs.aftersell.com/upcart/upcart_requires_two_clicks_for_an_action

This article explains why certain actions in Upcart may require two clicks to complete and how to troubleshoot this issue.

## Overview

A common issue merchants experience is the theme’s cart opening behind Upcart. This can appear in two ways: Another issue that can arise is interference from additional add-ons, such as toggle designs or footer section controls, which may conflict with Upcart's functionality.

1. **Visible Cart Issue:** The theme’s cart appears visibly in the background behind Upcart.
2. **Non-visible Cart Issue:** Customers may report needing to tap or click twice for actions to work. This often happens because the theme’s cart is still opening in the background.

This guide walks you through how to resolve both visible and non-visible cart opening issues. These conflicts typically stem from theme compatibility problems, especially when using custom or outdated **Shopify** themes. Properly updating and configuring your theme settings can improve Upcart’s performance and prevent these issues.

***

## Fixing the Visible Cart Issue

If your theme’s cart is opening behind Upcart and is visible in the background, follow these steps:

1. **Set the Cart to “Page” in Theme Settings**

   * Go to your **Shopify Admin** and navigate to **Online Store > Themes > Customize > Settings > Cart**.
   * Switch the cart type to **Page** instead of **Drawer** or **Popup**.
   * Some themes may label this setting as **Cart Page**.
2. **Turn Off the Ajax Setting in Upcart**

   * Go to your **Upcart Settings** and disable the Ajax functionality.
   * Navigate to **Settings > Advanced > Enhanced Ajax API Compatibility**.

Setting the cart to “Page” ensures that the theme’s native cart functionality does not interfere with Upcart’s performance. These two steps should stop the theme’s cart from opening in the background.

After making these changes, refresh your Upcart app in Shopify to ensure that the updates take effect properly.

***

## Fixing the Non-Visible Cart Issue

If the cart is not visible but actions require two clicks to work, the theme’s cart may still be opening behind Upcart. Try the following:

1. **Turn Off the Ajax Setting in Upcart**

   * Go to your Upcart settings and disable the Ajax setting as described above.
2. **If the Issue Persists**

   * Set your cart type to **Page** in your Shopify theme settings.
   * Turn off Ajax functionality in Upcart if not already done.

***

## Need Further Assistance?

If you are still encountering issues after following these steps, please reach out to our **Upcart Support Team** for additional help. Additionally, you can refer to the Upcart help center for troubleshooting guides or consult your theme's documentation for specific compatibility settings.


# Upcart upsells not showing on translated store versions
Source: https://docs.aftersell.com/upcart/upcart_upsells_not_showing_on_translated_store_versions

This article helps troubleshoot missing upsells on translated stores or different subdomains.

# Overview

In order to display Upcart's upsells, we have to fetch the products using Shopify's Product API. However, according to Shopify's [specifications](https://shopify.dev/docs/api/ajax/reference/product), we have to use a reference to the product handle that is contained in the product page URL.

For example, we can use their API to fetch a product that is located in the `products/red-rain-coat` section of the store.

<img alt="Shopify Product API documentation showing a fetch example for the red-rain-coat product handle" />

Unfortunately, this creates conflicts if you are using a store theme or third party translation application that also translates the product handles in the page URLs. This means that whenever we try to fetch the products using Shopify's Product API, Shopify is looking for a particular product handle (in one language) that does not exist when the product gets translated.

Here is a real store example where trying to fetch Spanish product handles return an error from Shopify because the product handles on their system are stored in English:

<img alt="Browser network inspector showing a 404 Not Found error fetching a Spanish product handle" />

In order to fix this, we suggest keeping the product handles in the product page URLs the same no matter what the language is set to on the store.

***

## Need Help?

As always, we are here to help. If you need further clarification or assistance with other features in Upcart, please do not hesitate to contact us.


# Why can’t I see my add-on on the storefront?
Source: https://docs.aftersell.com/upcart/why_cant_i_see_my_add_on_on_the_storefront

This article explains how to troubleshoot why your shipping protection or product add-on isn’t appearing in the cart drawer.

## Overview

If your add-on is not showing in the cart, it’s usually due to a **product configuration issue in Shopify**. This guide covers the most common causes and how to fix them, whether you are using Upcart’s built-in **Shipping Protection** or a **custom product-based add-on**.

**Note: Shipping Protection in Upcart is created as a standard Shopify product, so it follows the same publishing rules and limitations as any other product.**

***

## 1. Inventory Settings

**Go to:** Shopify Admin > Products > \[Your Add-on Product]

## Track Quantity

If **Track quantity** is enabled, your product must have at least **one available unit in stock**.

* If inventory is **0**, the add-on will not display in the cart.

## Continue Selling When Out of Stock

If you want the add-on to be available at all times:

1. Enable **Continue selling when out of stock** in Shopify.
2. Make sure this option is applied to **all variants** if your add-on product has more than one.

Learn more in Shopify’s [Sell when out of stock](https://help.shopify.com/en/manual/products/inventory/setup/selling-when-out-of-stock) documentation.

***

## 2. Product Status

Your add-on product must be set to **Active** in Shopify to appear in Upcart.

**To check:**

1. Go to **Shopify Admin > Products**.
2. Look at the **Status** column next to the product name.
3. Ensure it is marked as **Active**, not **Draft**.

If the product is a draft, it will not appear in Upcart.

***

## 3. Online Store Sales Channel

Your add-on product must be published to the **Online Store** sales channel.

**To check:**

1. Go to your product’s admin page.
2. In the **Publishing** section, look for **Online Store**.
3. If it’s missing, click the **three dots**, then select **Manage sales channels**.
4. Enable **Online Store** and click **Save**.

Without this setting, Upcart cannot detect or display the add-on in the cart.

***

## 4. Add-on Product Type Limitations

Not all product types are compatible with Upcart add-ons. The following product configurations are **not supported**:

* Products configured as **subscriptions**
* **Bundles** or dynamically generated products from bundle apps

Products with multiple variants are supported — when selecting your add-on product, expand it in the picker to choose the specific variant you want to offer.

***

## Still Not Showing?

If you’ve checked everything above and your add-on still isn’t appearing:

## Clear Browser Cookies

Cookies can sometimes affect how add-ons sync between Shopify and Upcart.

* Clear your browser cookies for your store and refresh the page.

## Contact Support

If the issue persists, contact the **Upcart Support Team** via the in-app chat.\
When reaching out, include:

* The product name or link
* A screenshot of the product’s **status and inventory settings**
* Confirmation that it’s **published to the Online Store**

Our team will help you troubleshoot and confirm if the issue is theme- or configuration-related.

***

## Learn More

For complete instructions on setting up and styling add-ons, visit the **[Add-ons Module](/upcart/add_ons_module)** documentation.


# Why doesn't the cart in the editor match my live store?
Source: https://docs.aftersell.com/upcart/why_doesnt_the_cart_in_the_editor_match_my_live_store

This article explains why the cart preview in the editor may look different from how it appears on your live storefront.

## Overview

The **cart editor preview** is not 100% accurate and may look slightly different when viewed on your live store. Upcart runs directly on your storefront, which means your **theme's CSS styling files** can affect how cart elements appear. These theme styles can change font sizes, colors, spacing, or other design aspects.

Upcart's editor does not have access to your theme's files, so it cannot perfectly reflect your store's live appearance.

We recommend working in a **Draft theme** so you can view real-time changes on your storefront without affecting your live cart. Before testing, make sure the cart you want to see is **published** (from the **Carts** page — its badge reads *Live*) and that the **Upcart** app embed is enabled on the theme you're testing on. A cart whose badge reads *App embed off* is live but has no theme to render on.

***

## Why the Editor and Live Store Look Different

The editor preview renders your cart using **default theme settings**. Your live store may have custom CSS overrides applied at the theme level that the editor cannot access or replicate.

Common reasons for differences include:

* **Custom CSS in your theme** - Global heading, font, color, or spacing rules in your theme's CSS files apply to all elements on your storefront, including Upcart. The editor has no access to these files.
* **App-injected styles** - Third-party apps may inject CSS that affects how Upcart elements render on the live store but not in the editor.
* **Browser rendering differences** - The editor preview may render fonts or spacing slightly differently depending on your browser and screen resolution.

***

## Common Differences

| Element                   | Editor Preview      | Live Store                                              |
| ------------------------- | ------------------- | ------------------------------------------------------- |
| **Font size**             | Uses Upcart default | May inherit theme's global font rules                   |
| **Font color**            | Uses Upcart default | May be overridden by theme heading or text color rules  |
| **Spacing and padding**   | Uses Upcart default | May be affected by theme global margin or padding rules |
| **Product title styling** | Uses Upcart default | May inherit H3 or H4 styles from theme CSS              |
| **Button styling**        | Uses Upcart default | May be overridden by theme button CSS                   |
| **Custom app styles**     | Not reflected       | Third-party app CSS may apply on live store only        |

***

## Example

In this example, the store's theme includes a CSS rule that says:

"All level 3 headings (H3) should have a font size of 20px and be red."

Upcart renders some cart titles using heading elements, so theme heading rules can bleed in. Which titles are affected depends on your cart version:

* **V2 (the current default):** upsell item titles render as `<h3>`, product titles as `<h4>`, and add-on titles as a `<span>`. A theme H3 rule would therefore restyle **upsell item titles** only.
* **V1 (legacy):** product titles, upsell item titles, and add-on titles all render as `<h3>`, so the theme rule would restyle all three.

As a result, the affected titles display in red at 20px on the live cart, even though they appear correctly in the editor.

***

## How to Force-Refresh the Editor Preview

If you have made changes in Upcart but the editor preview is not updating:

1. Save your changes in the Upcart Cart Editor.
2. Hard refresh the editor by pressing **Ctrl + Shift + R** (Windows) or **Cmd + Shift + R** (Mac) to clear the cached preview.
3. If the preview still does not update, try opening the editor in a private or incognito browser window.
4. To see how your changes look on the live store without publishing, use a **Draft theme** with the **Upcart** app embed enabled. See [Enabling Upcart in a Draft Theme Only](/upcart/enabling_upcart_in_a_draft_theme_only) for instructions.

<Note>
  The editor preview will never be a perfect match for your live store. For the most accurate view of how your cart looks to customers, always test on a Draft theme or place a test order on your live store.
</Note>

***

## Solution 1: Enable Shadow DOM

You can fix theme CSS conflicts by enabling **Render Cart in Shadow DOM** in your Upcart settings. This isolates Upcart from your theme's CSS, preventing theme or app code from changing Upcart's styling.

1. Go to **Upcart > Cart Editor > Settings > Cart settings**, then expand **Advanced Settings**.
2. Check **Render cart in Shadow DOM**.

<Note>
  For a detailed explanation of how Shadow DOM works, when to enable it, and edge cases where it may need to be temporarily disabled for specific integrations, see the full [Shadow DOM Setting](/upcart/render_cart_in_shadow_dom_setting) guide.
</Note>

***

## Solution 2: Use Custom CSS

If you prefer to manually adjust styling, you can add **Custom CSS** directly in Upcart's settings.

1. Go to **Upcart > Cart Editor > Settings > Custom CSS**.
2. Add or modify CSS to match your desired design. The class names differ between cart versions, so use the block that matches your cart.

**For V2 carts (the current default):**

```css theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.upcart-public-component-product-tile__product-title,
.upcart-public-component-upsell-tile__title,
.upcart-public-addons__content-title {
  font-size: 16px !important;
  color: black !important;
}
```

**For V1 (legacy) carts:**

```css theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.upcart-product-title, .upcart-upsell-item-title, .upcart-addons-title {
  font-size: 16px !important;
  color: black !important;
}
```

This sets the product, upsell, and add-on titles to a 16px font size and black color, overriding your theme's inherited styles. New carts are V2 by default; only pre-existing carts may still be on V1 (see [Cart versioning](/upcart/multicart#cart-versioning-v2)).

After saving your changes, refresh your storefront to confirm the cart displays correctly.

***

## Recommendation

To ensure the best results:

* Test your cart design using a **Draft theme** for an accurate preview before publishing.
* Review your theme's CSS files for global heading or text rules that may affect Upcart elements.
* Use **Shadow DOM** to keep your cart styling consistent and isolated from theme CSS.

**Need help?**

If you are still seeing unexpected differences between the editor and your live store, reach out to our support team via the in-app chat.


# Why is Upcart always open?
Source: https://docs.aftersell.com/upcart/why_is_upcart_always_open

This article outlines the troubleshooting steps for determining why Upcart is always open.

If you're experiencing an issue in Upcart where the cart drawer remains visible, whether on the left side of the screen or appearing to the right or below the store interface, there are two potential causes, depending on whether you're using a translation app.

# The cart appears on the right side or overlays the product page interface.

This issue typically appears as shown on desktop (highlighted on the right):

<img alt="Storefront product page with the Upcart cart drawer stuck open overlaying the right side" />

You will need to insert a short script into Upcart's HTML Settings to fix this issue.

Please follow these steps:

1. In your Shopify Admin, go to **Upcart > Cart Editor > Settings**
2. Under Custom HTML, **Select HTML Location dropdown > Scripts (Before load)** <img alt="Upcart Custom HTML location dropdown with Scripts Before Load highlighted at the bottom" />
3. Copy and paste the following code:
   ```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
   <script>  
       window.onload = () => {  
           const upcartHTML = document.getElementById("upCart");  
           document.body.append(upcartHTML);  
       }  
   </script>
   ```
   This is how your custom HTML settings should look like in Upcart: <img alt="Upcart Custom HTML editor set to Scripts Before Load with the window.onload append script pasted" />
4. Scroll to the top and click **Save**. Saving Upcart changes will require up to a minute for the changes to take place.

### Why does this happen?

When Upcart loads, we expect it to appear off-screen to the right of the store page. However, certain store themes and third-party Shopify apps may alter the page layout, including Upcart's placement. As a result, Upcart may load in a different position, leading to a visual bug where it's visible at all times. Implementing the above code changes will reposition Upcart, restoring its original behavior.

## **Additional Steps**

If you're experiencing any flickering during the page loading stage by Upcart, you can also try applying some CSS changes to hide the cart drawer. Please keep in mind, **this will hide Upcart on the preview page as well**.

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.upcartPopupShow [class*="styles_CartPreview__right__"] {  
    width: 100%;  
    max-width: 440px;  
}  
  
[class*="styles_CartPreview__right__"] {  
    width: 0px;  
    max-width: 440px;  
}
```

You'll find the editor on the **Custom CSS** tab under **Settings** (behind **More settings** if it doesn't fit on the tab row). Paste the code above there:

<img alt="Upcart Custom CSS editor with rules setting the CartPreview right panel width to hide the drawer" />

# Cart is stuck on the left

This is usually caused by a translation app translating Upcart settings that should stay in English.

Upcart stores certain settings as English words in Shopify metafields. For example, the cart position setting is stored as "right" or "left." If a translation app changes "right" to "droite" in French, Upcart can't understand the instruction and defaults to the top left of the screen, staying open permanently.

**Not all metafields should be translated**

There are two types of Upcart metafields:

* **Text fields** like button labels or reward messages are safe to translate
* **Behavior settings** like cart position or upsells direction must stay in English

Translating behavior settings will cause Upcart to break.

**The fix**

1. Open your translation app and find the **store metadata** or **metafields** section
2. Look through the Upcart metafields and remove any translations on behavior-related fields such as `cartPosition` and `upsellsDirection`
3. Refresh your storefront and the cart should return to its correct position

**Note:** Upcart now has built-in translation support, which avoids this issue entirely. If you haven't set up translations yet, we recommend using that instead. See [Cart Translations ](/upcart/cart_translations)for more details.


# Why isn't my upsell showing?
Source: https://docs.aftersell.com/upcart/why_isnt_my_upsell_showing

This article explains how to troubleshoot when your upsell products aren’t appearing in the cart drawer.

# Overview

Upsells in Upcart rely on multiple Shopify and app-specific conditions to display correctly. If your upsell isn’t appearing on the storefront, this guide walks you through every step to identify and resolve the issue.

***

## Common Causes of Missing Upsells

The most frequent reasons an upsell might not appear include:

* Inventory issues or product status in Shopify
* Incorrect product or channel configuration
* Upsell module settings in Upcart (such as triggers or limits)
* Missing collection relationships for AI-recommended upsells

Let’s look at each of these in more detail.

***

## Shopify Product Configuration

## Inventory Settings

There are two inventory settings that affect product visibility:

* **Track quantity:** If enabled, the product must have available inventory to appear.
* If **Track quantity** is disabled, the product won’t sell out and the upsell will display regardless of stock level.

💡 **To verify:**

1. Go to **Shopify Admin > Products > Inventory**.
2. For single-variant products, scroll to the **Inventory** section.
3. For multi-variant products, scroll to **Variants** and check stock for each one.

<img alt="Shopify product Inventory panel with tracking enabled and stock levels per location" />

📘 Learn more: Shopify Inventory Management Docs

***

## Product Status: Active vs Draft

Ensure the upsell product is marked as **Active**, not **Draft**.\
Draft products will not appear in the cart drawer.

💡 **To check:**

* Go to **Shopify Admin > Products** or open the product and check the status badge in the top right.

<img alt="Shopify product Status dropdown set to Active in the product sidebar" />

📘 More info: Shopify Product Status Docs

***

## Sales Channels: Online Store

Upsell products must be published to the **Online Store** sales channel.

💡 **To verify:**

1. Open the product in Shopify.
2. Look for the **Publishing** section and confirm **Online Store** is selected.
3. If missing, click the **three-dot menu > Manage sales channels** and check **Online Store**, then save.

   <img alt="Shopify product Publishing section showing the Online Store sales channel" />

## Product Type Limitations

Upcart doesn’t support certain product types for upsells:

* ❌ Subscription-only products
* ❌ Bundle products (unless built as standard Shopify products)

***

## Upcart Module Settings

## “Show upsell offer if item already in cart”

This setting determines whether upsells appear when the product is already in the cart.

* ✅ **Checked:** The upsell always displays.
* ❌ **Unchecked:** The upsell hides if the product is already in the cart.

***

## “Limit the number of upsells in the cart”

If this setting is enabled, a **Maximum number of upsells to display** field appears and only that many upsells will show.

The Upsells module reads from **top to bottom** in your list.\
If the cart already includes the maximum number of upsells, any lower-priority ones won’t display.

🧠 **Example:**\
If the maximum number of upsells is set to **2**, and the first two upsells are triggered, any additional upsells (even if valid) will not appear.

<img alt="Upcart Upsell settings highlighting the show-if-in-cart and limit-number-of-upsells options" />

***

## Upsell Triggers

Manual upsells require a **trigger product** to function.

✅ The trigger product must be:

* In stock
* Active
* Published to the **Online Store** channel

✅ At least one trigger product must be selected in the **Upsell settings**.

⚠️ If the trigger product list is empty, the upsell will not appear even if all other conditions are met. Note that unchecking a product's last variant removes the product from the list entirely — that's the state to watch for, rather than a product sitting there with no variants ticked.

A trigger that carries no variant restriction matches **every** variant of that product, so you don't need to tick variants individually unless you want to narrow it.

Also, make sure the upsell product itself meets the same criteria.

<img alt="Shopify product list highlighting a snowboard marked Draft and Out of Stock" />

***

# AI-Recommended Upsells

If you’re using **AI-recommended upsells**, there are specific conditions to check:

## Related Algorithm

Upsells only appear if the cart item shares a **collection** with other products in the store.

✅ **Solution:** Add both products to the same Shopify collection.

## Complementary Algorithm

These upsells are based on **Shopify’s purchase behavior data**.

* Shopify must have sufficient data to identify product pairings.
* Ensure your store’s data settings allow for AI-based recommendations.

📘 Learn how to set up complementary upsells:\
[Shopify Complementary Products Guide](https://help.shopify.com/en/manual/online-store/themes/customizing-themes/common-customizations/add-product-recommendations#complementary-products)

***

## Summary

If your upsells aren’t showing, review the following:

* The upsell product is **Active**, **in stock**, and **published** to the **Online Store** channel.
* Your **Upsell Module settings** are correctly configured (no limiting conditions preventing display).
* Your **trigger product** and upsell product meet Shopify visibility requirements.
* Collections and AI configurations are correctly set for AI-based upsells.

***

## Need Help?

If your upsell still isn’t appearing after reviewing these steps, contact **Upcart Support** through in-app chat. Please include:

* The upsell product name
* A screenshot of your module settings
* A short description of the issue

Our team will help identify and resolve the problem quickly.

***

## Need Help Setting Up Upsells?

For full setup instructions and best practices, visit our [Upsells Module Guide](/upcart/upsells_module).