Merchant Guide

Welcome to Cross-Sell Pro! This comprehensive guide will help you set up and configure the app to display cross-sell product recommendations to your customers in the Cart Preview and Checkout Page.

Table of Contents

1. Introduction
2. Getting Started
3. Subscription Management
4. Settings Configuration
5. Styling Customization
6. Script Customization
7. Product List Configuration
8. Troubleshooting

1. Introduction↑

Cross-Sell Pro is a BigCommerce app that helps you increase your average order value by displaying relevant product recommendations to customers at key moments in their shopping journey:

• Cart Preview: Shows cross-sell products when customers view their cart preview dropdown
• Checkout Page: Displays cross-sell products on the checkout page before customers complete their purchase

The app intelligently:

• Excludes products already in the customer's cart
• Filters out products with no available inventory
• Allows you to pin specific products to always appear first
• Randomizes other products for variety

2. Getting Started↑

Installation

1. Install the Cross-Sell Pro app from the BigCommerce App Marketplace.
2. The app will automatically create a script in your store's Script Manager during installation.
3. Once installed, you'll be redirected to the app's main dashboard.

Initial Setup

After installation, you'll need to:

1. Subscribe to the App: The app requires an active subscription to function. Navigate to the Subscription Management page to subscribe.
2. Adjust Settings: Configure display limits and styling.
3. Customize Script Anchors: Configure where the cross-sell products appear on your storefront.
4. Configure Product Lists: Set up which products should be shown as cross-sell recommendations.

3. Subscription Management↑

Subscribing to the App

1. Navigate to the Subscription Management page in the app
2. Click the Subscribe button
3. You'll be redirected to BigCommerce's checkout page to complete your subscription
4. After successful subscription, the app will be enabled automatically

Managing Your Subscription

• View Subscription Status: The Subscription Management page shows whether your subscription is active
• Cancel Subscription: Click the Cancel Subscription button to cancel your subscription
  • Note: The app will continue working until the end of your current billing period
  • After cancellation, you'll need to resubscribe to reactivate the app

App Status

• Active Subscription: The app is fully functional and all features are available
• Cancelled Subscription: The app continues working until the end of the current billing period
• No Subscription: The app is disabled and will not display cross-sell products on your storefront

4. Settings Configuration↑

The Settings page allows you to configure how cross-sell products are displayed. All settings are only available when the app is enabled.

Cart Preview Limit

• Purpose: Controls how many cross-sell products are displayed in the cart preview dropdown
• Format: Enter a number (e.g., 3, 5, 10)
• Default: Set based on your preference
• Recommendation: 3-5 products work well for cart previews to avoid overwhelming customers

Checkout Limit

• Purpose: Controls how many cross-sell products are displayed on the checkout page
• Format: Enter a number (e.g., 3, 5, 10)
• Default: Set based on your preference
• Recommendation: 3-5 products work well for checkout pages

Products Pinned List

• Purpose: Products that will always appear first in cross-sell recommendations
• Format: Comma-separated list of product IDs
  • Format: productId,productId
  • Example: 123,789,456
• Note: Currently disabled for editing in the UI (configured separately)
• Behavior: Pinned products appear first in the exact order specified, then randomized products fill the remaining slots up to your limit
• Precedence: If a product is in both Pinned and Randomized lists, it will be treated as Pinned only and will not appear in the randomized section
• Empty List: If no products are pinned, all products will be selected from the Randomized list

Products List

• Purpose: The pool of products from which cross-sell recommendations are randomly selected
• Format: Comma-separated list of product IDs
  • Format: productId,productId
  • Example: 123,789,345
• Note: Currently disabled for editing in the UI (configured separately)
• Behavior: Products are randomly selected and shuffled from this list each time, excluding:
  • Products already in the customer's cart
  • Products with no available inventory
  • Products that don't exist or are unavailable
  • Products that are in the Pinned list (pinned products take precedence)
• Randomization: Products are shuffled each time the cart preview or checkout page loads, ensuring different product orders on each visit
• Standalone Use: If no products are pinned, all products from this list will appear in random order up to your limit

Saving Settings

After making changes to any settings:

1. Click the Save settings button
2. Wait for the confirmation that settings have been saved
3. Changes take effect immediately on your storefront

5. Styling Customization↑

• Purpose: Custom CSS to style the cross-sell product display
• Format: CSS code
• Default: The app includes default styles that work with most BigCommerce themes
• Customization: You can override default styles or add new ones

Default Styles

The app includes these default styles:

#cart-preview-dropdown {
  max-width: 500px;
}

.upsell-title {
  font-weight: 700;
  margin-top: 1.6rem;
  padding-left: 0.6rem;
  text-align: left;
  text-transform: uppercase;
}

.upsell-product {
  display: flex;
  align-items: center;
  background-color: rgb(241, 241, 241);
  gap: 1rem;
  padding: 0.5rem;
  text-align: left;
}

.upsell-product__image {
  max-width: 25%;
}

.upsell-product__image img {
  max-height: 90px;
}

.upsell-product__info {
  flex-grow: 1;
}

.upsell-product__name {
  padding-right: 1rem;
}

.upsell-product__price {
  font-family: "Benton Sans", Arial, Helvetica, sans-serif;
  margin-top: 0.4rem;
}

.upsell-product__cta .button {
  background-color: transparent;
  border-color: #000000;
  color: #000000;
  font-size: 1rem;
  margin: 0;
  padding: 1rem;
  text-wrap: nowrap;
}

.upsell-product__cta .button:hover {
  background-color: #000000;
  color: #FFFFFF;
}

Customizing Styles

You can customize any aspect of the cross-sell display:

• Colors: Change background colors, text colors, button colors
• Layout: Adjust spacing, alignment, sizing
• Typography: Modify fonts, sizes, weights
• Responsive Design: Add media queries for mobile devices

Example custom styles:

.upsell-title {
  color: #your-brand-color;
  font-size: 1.2rem;
}

.upsell-product {
  background-color: #f9f9f9;
  border: 1px solid #e0e0e0;
  border-radius: 8px;
}

.upsell-product__cta .button {
  background-color: #your-button-color;
  border-radius: 4px;
}

6. Script Customization↑

The Script Customization page allows you to configure where cross-sell products appear on your storefront by setting CSS selectors (anchors).

Understanding Anchors

Anchors are CSS selectors that tell the app where to insert cross-sell products in your store's HTML. The app uses these selectors to find specific elements on your page and insert the cross-sell products after them.

Cart Preview Anchor

• Purpose: CSS selector for the element in the cart preview where products should appear
• Default: .previewCartList
• How to Find:
  1. Open your storefront
  2. Add a product to cart
  3. Open the cart preview dropdown
  4. Right-click on the cart items list and select "Inspect"
  5. Look for a class or ID on the cart items container
  6. Use that as your anchor (e.g., .cart-items, #cart-list)

Cart Preview Dropdown Anchor

• Purpose: CSS selector for the cart preview dropdown container that the app monitors
• Default: #cart-preview-dropdown
• How to Find:
  1. Inspect the cart preview dropdown element
  2. Find the main container element's class or ID
  3. Use that as your anchor

Checkout App Anchor

• Purpose: CSS selector for the checkout app container that the app monitors
• Default: #checkout-app
• How to Find:
  1. Go to your checkout page
  2. Right-click on the checkout area and select "Inspect"
  3. Find the main checkout container's class or ID
  4. Use that as your anchor

Checkout Product List Anchor

• Purpose: CSS selector for where products should appear on the checkout page
• Default: .productList
• How to Find:
  1. Go to your checkout page
  2. Inspect the area where order items are listed
  3. Find the container element's class or ID
  4. Use that as your anchor

Updating Scripts

After modifying anchor values:

1. Click the Update scripts button
2. The app will update the script in your Script Manager
3. Changes take effect immediately (you may need to clear your browser cache)

Troubleshooting Anchors

If cross-sell products don't appear:

1. Verify Anchors: Use browser developer tools to verify the selectors exist on your page
2. Check Theme Compatibility: Some themes may use different class names
3. Test Selectors: Test your selectors in the browser console: document.querySelector('your-selector')
4. Contact Support: If you're unable to find the correct selectors, contact support with your theme name

7. Product List Configuration↑

Understanding Product Lists

The app uses two types of product lists:

1. Products Pinned List: Products that always appear first (if available and not in cart)
2. Products List: The pool of products for random selection

Product ID Format

Products are specified by their product ID:

• Format: 123 (product ID)
• Example: 123,789,456 (comma-separated list of product IDs)

Best Practices

1. Relevant Products: Choose products that complement items typically in the cart
2. Inventory Management: Only include products you regularly keep in stock
3. Pinned Products: Use for high-margin items or bestsellers you want to promote
4. List Size: Include 10-20 products in your main list for good variety

Example Configurations

Example 1: Pinned + Randomized

Products Pinned List: 123,789
Products List: 100,101,102,103,104,105,106,107,108,109,110
Cart Preview Limit: 5

This configuration:

• Always shows product 123 first, then product 789 (in that order, if available and not in cart)
• Randomly selects and shuffles 3 products from the list (100-110) to fill remaining slots
• Total: 2 pinned + 3 random = 5 products (order changes each time for random products)

Example 2: Randomized Only

Products Pinned List: (empty)
Products List: 100,101,102,103,104,105
Cart Preview Limit: 3

This configuration:

• No pinned products, so all 3 slots are filled from the randomized list
• Products are shuffled each time, so different products and orders appear on each load

Example 3: Product in Both Lists

Products Pinned List: 123,456
Products List: 123,100,101,102,103
Cart Preview Limit: 4

This configuration:

• Product 123 is in both lists, but will appear as Pinned only (precedence)
• Shows: 123 (pinned), 456 (pinned), then 2 random products from [100,101,102,103]
• Product 123 will NOT appear in the randomized section

8. Troubleshooting↑

Cross-Sell Products Not Appearing

Possible Causes:

1. App Not Enabled: Check that your subscription is active
2. Incorrect Anchors: Verify your script anchors match your theme's HTML structure
3. No Products Configured: Ensure you have products in your Products List
4. All Products in Cart: If all configured products are already in the cart, nothing will show
5. No Inventory: Products with zero inventory won't appear
6. Script Not Loaded: Check that the script exists in Script Manager

Solutions:

1. Go to Subscription Management and verify subscription status
2. Use browser developer tools to verify anchor selectors
3. Check your Products List configuration
4. Test with a cart that doesn't contain all your cross-sell products
5. Verify product inventory levels in BigCommerce
6. Check Script Manager for "Cross-Sell Pro" script

Products Appearing Incorrectly

Possible Causes:

1. Styling Issues: Custom styles may conflict with theme styles
2. Anchor Placement: Anchors may be pointing to wrong elements
3. Theme Compatibility: Theme may have unique HTML structure

Solutions:

1. Review and adjust App Styles in Settings
2. Verify anchor selectors are correct
3. Test with default styles first, then customize
4. Contact support if theme-specific issues persist

Subscription Issues

If subscription doesn't activate:

1. Check your BigCommerce account billing information
2. Verify payment method is valid
3. Contact BigCommerce support if payment processed but app not enabled

If app stops working after cancellation:

1. This is expected behavior - app works until end of billing period
2. Resubscribe to reactivate immediately

Performance Issues

If storefront loads slowly:

1. Reduce the number of products in your Products List
2. Lower the display limits (Cart Preview Limit, Checkout Limit)
3. Check for conflicts with other apps or scripts
4. Contact support if issues persist

Last Updated: 2/10/2026
App Version: 1.0.1