# Substitutions App Help Center > Full documentation content for Substitutions App Help Center --- # Default ## How It Works ### How substitutions work **URL:** https://substitutions.mantledocs.com/how-substitutions-work ### **When are substitutions triggered?** Substitutions are applied after checkout, during order processing. When an order contains an out-of-stock variant: - The app checks your substitution rules - If a substitute is available, it replaces the out-of-stock item in the order - The order is updated automatically for fulfillment ### **Priority rules** If you've added multiple substitutes, the app tries them in order: 1. First substitute is checked 2. If unavailable, the next one is tried 3. This continues until an available substitute is found If all substitutes are also out of stock, the original item remains on the order. **What customers experience** Nothing changes on the customer's end—they complete checkout normally. The substitution happens behind the scenes, and only you see the activity on the order screen and our log. ![how-it-works](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/c904e04b-5daf-4df6-87ac-3c5e9a9a2a03/how-it-works.png) ### **How inventory settings are managed** When you activate a substitution rule, the app automatically enables "Continue selling when out of stock" on the primary variant. This allows customers to still purchase it, knowing a substitute will be fulfilled. If all substitute variants become unavailable, the app automatically disables this flag to prevent orders that can't be fulfilled. --- ## Getting Started ### Who is Substitutions for? **URL:** https://substitutions.mantledocs.com/who-is-substitutions-for Substitutions is designed for Shopify store owners who want to keep their customers happy by ensuring products are always available, even when certain SKUs go out of stock. If you’re tired of seeing sales drop because an item is temporarily unavailable, Substitutions is the app for you. ### **Growing E-Commerce Stores:** Stores experiencing rapid growth often face inventory challenges. Substitutions helps you manage these issues seamlessly by setting up replacement products whenever key items are unavailable, ensuring no sale slips away. ### **Stores with High SKU Variability:** If you have products with multiple SKUs for the same product—Substitutions makes sure customers always find something in stock, keeping them engaged and reducing lost sales. ### **Multi-Product Sellers:** Stores that sell many different items can use Substitutions to avoid the hassle of manually managing out-of-stock products and substitutions, ensuring your entire catalog remains attractive and purchasable. Your fulfillment provider will also thank you. #### **Not Sure if It’s Right for You?** Substitutions is perfect for store owners who want to make inventory management simpler, improve sales, and create a seamless shopping experience. Whether you run a small store looking to get started with smarter inventory handling or a larger store dealing with complex stock issues, Substitutions helps you keep customers happy and revenue steady. Get started today and make sure your store is always ready for every sale opportunity! --- ### First-time setup **URL:** https://substitutions.mantledocs.com/first-time-setup ### **When you first open Substitutions, we'll get everything ready so substitutions just work.** ### **What happens during setup?** - We sync your products and variants - We connect your inventory to our substitution engine You'll see a progress indicator while this runs. Large stores may take up to an hour. ![setup1](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/d9cfd73e-e4fd-4552-8794-2c059c29d6c2/setup1.png) ### **Important things to know** - Setup runs automatically - Large stores may take up to an hour to complete - You don’t need to keep the page open **Do I need to stay on the page?** Nope. Setup runs in the background—just check back later. When it's done, you'll see a **Create your first substitution** button and can start right away. **Need help?** If setup seems stuck or you run into an issue, contact us at [[support@automatethis.dev](mailto:support@automatethis.dev) ]. ![setup2](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/cadaa17a-1c17-484d-96d8-2cd07b9408ab/setup2.png) --- ## How It Works ### Managing substitute variants **URL:** https://substitutions.mantledocs.com/managing-substitute-variants ### **Adding substitute variants** You can add one or more substitutes for each out-of-stock variant. Each substitute displays: - Product name - Price - Stock status - Priority order ### **Reordering priority** Drag and drop to control which substitute is tried first. ### **Stock indicators** - 🟢 **Green** – In stock - 🟡 **Yellow** – Low stock - 🔴 **Red** – Out of stock ![managing-variants](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/d57f97fc-ad9e-4465-b4a5-f014414e3154/managing-variants.png) ### **Best practices** - **Choose similar or equivalent products** — Customers receive what they paid for in spirit, even if not the exact SKU - **Monitor substitute stock** — A backup that's also unavailable won't help - **Review rules regularly** — Seasonal inventory changes may require updates --- ## Getting Started ### Create your first substitution **URL:** https://substitutions.mantledocs.com/create-your-first-substitution ### **What is a substitution?** A substitution automatically replaces an out-of-stock variant with an alternative you choose. You keep the sale, and your customer still gets what they need. ### **How to create one** 1. Click **Create substitution** 2. Select the **out-of-stock variant** ![first-sub1](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/7fa0c8e8-59d8-42d5-af1f-f219d524a34e/first-sub1.png) 1. **substitute variants** ![first-sub2](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/d24b079a-9dcd-41c7-a081-1ec42adc514d/first-sub2.png) 1. Arrange substitutes by drag-and-drop priority (first available wins) ![first-sub3](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/66352dde-519b-4309-aed7-2c11c9449718/first-sub3.png) 1. Turn on the substitution ![first-sub4](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/aee71a03-49d1-48b8-bf33-899a59e8610e/first-sub4.png) ### **What happens next?** When the primary variant goes out of stock, the app swaps in your substitute automatically at checkout. Customers see the substitute in their cart—no extra steps for them or you. You can deactivate or delete any substitution rule from your dashboard. ## **Tips for Success** - **Maintain Relevant Substitutions**: Ensure that substitute variants are the same or very similar to the original to decrease the likelihood of a customer complaint or dissatisfaction (e.g. it's the same color, size and price). - **Update Substitutions Regularly**: Regularly update your substitution groups to reflect changes in your product lineup or inventory strategy. Setting up substitution groups can minimize missed sales opportunities and ensure your customers always have an available option, improving overall satisfaction. --- ## How It Works ### Quantity-based substitutions **URL:** https://substitutions.mantledocs.com/quantity-based-substitutions ### **What are quantity-based substitutions?** Instead of replacing one item with one item, you can substitute using multiple units of another product. This is useful when you sell products in different sizes or pack quantities—for example, replacing a 12-pack with two 6-packs. Example: - 1 × Large Pack → 2 × Small Pack ### **How to enable quantity substitutions** 1. Open a substitution rule 2. Enable **Quantity-based substitutions** ![quantity-sub1](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/772c7703-c7b1-4343-bbce-fc09c01b8563/quantity-sub1.png) 1. Set the quantity for each substitute variant (if there is more than one) ![quantity-sub2](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/15ce48f7-4022-415b-a8c8-f9d1a9744b46/quantity-sub2.png) **How pricing works** The customer pays the original item's price. If the substitute total costs more or less, the difference is absorbed by you or passed as margin—review your pricing to ensure substitutes make sense financially. **Good to know** - Quantities must be at least 1 - Quantity-based substitutions are available on paid plans - Priority rules still apply—if multiple substitutes are set, the first available is used --- ### Bundle substitutions **URL:** https://substitutions.mantledocs.com/bundle-substitutions ### **What are bundle substitutions?** Bundle substitutions let you apply substitution rules to individual items inside a product bundle. If a bundle contains an out-of-stock component, the app can replace just that item while keeping the rest of the bundle intact. **Example:** A gift set contains Candle A, Soap B, and Lotion C. If Soap B is out of stock, it's automatically swapped with Soap D—the rest of the bundle ships as expected. ### **How bundle substitutions work** - Bundles are evaluated item by item after checkout - If a bundled variant is out of stock, the app checks for a matching substitution rule - The first available substitute is used automatically - All other bundle components remain unchanged ### **How to set up a bundle substitution** Bundle-specific substitution rules are configured in the substitution edit screen. Create a rule for the variant that may go out of stock—when that variant appears in a bundle, the rule applies. ![bundle](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/8d5f7c62-d366-41db-a49d-70d0102df47b/bundle.png) ### **Important: Always pair with a variant substitution** When you activate a bundle substitution, the app enables "Continue selling when out of stock" on that variant. However, Shopify does not distinguish between a variant sold individually and one sold as part of a bundle. This means the variant will remain available for individual purchase too—even if you only intended the rule for bundles. **Recommendation:** Always create a standard variant substitution alongside any bundle substitution. This ensures the variant is covered whether a customer buys it on its own or as part of a bundle. **Good to know** - Bundle substitutions are available on paid plans - Standard priority rules apply—if multiple substitutes exist, the first available is used --- ## General ### Get the app **URL:** https://substitutions.mantledocs.com/get-the-app Install the Substitutions app from the Shopify App Store to start managing product substitutions in your store. Log in to your **Shopify admin** using the store account where you want to install the app. Open the **Substitutions** app listing in the **Shopify App Store**. On the app listing page, click **Add app**. Review the installation screen in Shopify, then click **Install app** to finish installing Substitutions. You must be logged in to the correct Shopify store before you install the app. --- ### Common questions **URL:** https://substitutions.mantledocs.com/common-questions Our app is designed for merchants who carry many variants of similar products under different SKUs. We highly recommend that you substitute like-for-like variants—any differences between the substituted items should be imperceptible to your customers. This ensures consistency and helps maintain trust in your store's quality and transparency. ![questions](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/5dbc7a62-9b8b-4ae7-85ac-bb983c4579ef/questions.png) Merchants should always behave ethically when using Substitutions. Customers expect that the product they receive matches their expectations and descriptions accurately. Misleading substitutions could lead to customer dissatisfaction, returns, and a damaged reputation. If you're ever unsure whether a substitution is appropriate, we encourage you to reach out to us. Our team is here to assist you in making the right decisions for your store and ensuring the best possible customer experience. Setting up substitution groups can minimize missed sales opportunities and ensure your customers always have an available option, improving overall satisfaction. --- ## How It Works ### Understanding your dashboard **URL:** https://substitutions.mantledocs.com/understanding-your-dashboard ![dashboard](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/af526af9-c482-42c1-a23f-19672297e9b5/dashboard.png) ### **Dashboard overview** Your dashboard shows how substitutions are performing across your store and gives you quick access to manage your rules. ### **Summary bar** At the top, you'll see key metrics: - **Substitution total sales** — Revenue from orders that included a substitution - **Substitution orders** — Number of orders where at least one item was substituted - **Performance change** — Comparison to the previous period of equal length ### **Date ranges** Use the date picker to switch between: - Today - Last 7 days - Last 30 days Metrics update automatically when you change the range. ### **Performance indicators** - Green arrow → Increase from previous period - Red arrow → Decrease from previous period - Grey arrow → No change ### **Substitution list** Below the summary bar, you'll see all your substitution rules. From here you can: - Filter by Active, Inactive, or All - Click any rule to view or edit it - Create a new substitution - Select one or more rules to deactivate or delete in bulk ### **New to the app?** If you haven't had any substitutions trigger yet, your metrics will show zero—that's normal. Once orders start flowing and substitutions activate, your dashboard will populate automatically. --- ## General ### View Substitution Activity / History **URL:** https://substitutions.mantledocs.com/view-substitution-activity-history ![activity](https://cdn.heymantle.com/orgs/5179bb05-ca78-4650-97c5-eb5505fc97b4/assets/4c136740-07c5-4c63-a267-315d6c4f92c1/activity.png) Substitution Activity helps you understand **when and how your substitutions are actually used** in real customer orders. You can view activity **per substitution rule**, directly inside the app. **Usage History** shows every time a substitution rule was successfully applied to an order. An entry appears **only when a substitution is used** — not when a rule is created or edited. --- ### Plans and Pricing **URL:** https://substitutions.mantledocs.com/plans-and-pricing Substitutions offers flexible plans so you can start small and scale as your store grows. All plans are managed through Shopify billing. ## **Available Plans** ### **Free** Best for testing substitutions and small stores. **Price:** Free, forever ### **What’s included** - Core substitution functionality - Create up to **3 substitution** - **100 substitutions orders per month** - Dashboard and performance overview - **30-day substitution history** - Email support (response within 48 hours) ### **Not included** - Bundle substitutions - Quantity-based substitutions - Priority support ### **Good to know** When you reach the monthly usage limit: - Existing substitution rules remain saved - Substitutions stop triggering automatically - You’ll see an upgrade prompt in the dashboard ### **Growth** **Most Popular! Best for growing stores with frequent out-of-stock items** **Price:** - **$49.99/month** - **$479/year** (20% discount when billed annually) ### **What’s included** Everything in **Free Forever**, plus: - **Create up to 15 substitutions** - **1,000 substitution orders per month** - **Bundle substitutions** - **Quantity based substitutions** - **90-day substitution history** - Priority support (response within 24 hours) ### **Good to know** The Growth plan is ideal if you: - Sell bundles - Have quantity/weight based products ### **Scale** **Enterprise Grade** **Best for high-volume stores and complex catalogs** **Price:** - **$249.99/month** - **$2,399/year** (20% discount when billed annually) ### **What’s included** Everything in **Growth**, plus: - **Unlimited substitutions** - **Unlimited substitutions orders per month** - 24/7 priority support with **30-minute SLA** - Dedicated Account Manager - White-glove onboarding - **99.9% uptime SLA** with service credits - **5 hours of strategic consulting per quarter** ### **Good to know** The Scale plan is designed for merchants who: - Rely heavily on substitutions for revenue protection - Operate at high order volumes - Need guaranteed performance and hands-on support ## **Billing & Payments** - Billing is handled directly by Shopify - Charges appear on your Shopify invoice - Plan upgrades take effect immediately - Downgrades apply at the next billing cycle --- ### Billing and payments **URL:** https://substitutions.mantledocs.com/billing-and-payments ## All billing and payments are handled through your Shopify app store. ## **Need help?** If you have any questions or concerns about billing and payments, don't hesitate to reach out to our support team. We're here to help! --- ### Usage Limits **URL:** https://substitutions.mantledocs.com/usage-limits Each plan includes a monthly usage allowance. Usage is counted when a substitution is **successfully applied to an order**. ## **What counts toward usage?** - Each substituted item counts as **one usage** - Quantity-based substitutions count as **one usage per order**, not per unit - Bundle substitutions count **per substituted bundle component** ## **What happens when you reach your limit?** - You won’t be able to add new substitutions - Your existing rules remain saved - You’ll see an upgrade prompt in the dashboard Once you upgrade, substitutions resume automatically ---