As a distributor, the Item Connections tool lets you turn any item detail page into a selling opportunity. In Pepper Management Center (PMC), you can choose which Similar Items (substitutes) and recommended ‘You Might Also Like’ items (add-ons) appear when buyers view an item – helping guide what they purchase next, promote priority SKUs, and keep orders moving.
The tool has two tabs: Recommended + Similar, where you assign similar and recommended items, and Item Substitutions, where you manage substitution settings for your customers.
Note: Item connections are available for all storefront subscriptions. The Item Substitutions tab is only visible for Enterprise accounts with item substitutions enabled.
How Item Connections Help You Sell More
Increase average order value with add-ons: Use recommended 'You Might Like' to surface complementary products.
Get priority products in front of buyers: Attach new items, private label, or high-margin SKUs to high-traffic item pages so buyers discover them without needing to search.
Reduce lost sales with Similar Items: Add Similar Items so buyers can quickly choose an alternative if their first choice isn’t available or isn’t the right fit.
Reduce buyer friction: Help buyers find alternatives and add-ons without leaving the item page or running a new search.
React quickly to promos and inventory changes: Update connections in PMC anytime (seasonal swaps, promo bundles, preferred substitutes) without waiting on manual updates.
Control what shows up first: Reorder Similar and Recommended ‘You Might Also Like’ items to prioritize the options buyers see first.
Types of Item Connections
Recommended + Similar Items
Similar Items are browsing suggestions — "If this isn't right, try this instead." They help buyers explore alternatives but don't trigger automatically.
Recommended Items ('You might also like') are cross-sells — "You're buying this, you may also need this." They increase basket size by surfacing complementary products.
Item Substitutions
Substitutions are 1:1 replacements when an item is out of stock. The system will suggest the configured substitutes at checkout, with an option to search the catalog for other alternatives.
Tip: It’s up to you what items are displayed and what section they appear in!
Example: If no direct substitutes are available for an item, suggest items within the same product category under ‘You Might Also Like’.
The ‘You Might Also Like’ section suggests other fruit items a user might add to their order, since they are likely purchasing other types of fruit. The Similar Items section highlights close alternatives that could be used as a direct substitute for Apple, Gala.
How to Use the Item Connections Tool
Sync Settings
Before adding connections, review the two Sync Settings at the top of the Recommended + Similar tab. These control how connections behave across your catalog.
Bi-directional Sync
When enabled, similar and recommended items are linked both ways automatically. If you connect Item A to Item B, Item B will also show Item A — without needing to configure it separately.
Notes:
i. Turning Bi-directional Sync off does not change existing item connections. It only affects new connections saved going forward. To remove an existing connection, search for the item and delete it manually.
ii. Bi-directional Sync does not apply to bulk upload. Only connections added manually through the item search will follow this setting.
Apply to all pack sizes
When enabled, connections you make for an item apply to every pack size that shares the same item code. For example, if an item is sold as both a case and a single unit, connections added to one pack size are automatically applied to the other.
This setting is on by default. If you turn it off, connections apply only to the specific pack size you select.
Note: Buyers only see connections for pack sizes that are available in their catalog. If a connected item is not available to a buyer, it won't appear on their item page.
Configuring Recommended + Similar Items:
Step 1: Search for an item to add connections to:
In the search bar, search by item name or code. Then, click on the item.
Searching for an item to add connections to.
Step 2: Add connections:
In the Similar Items and Recommended Items tabs, search for catalog items to connect, and click Add.
Add up to 6 Similar Items:
Add up to 6 Recommended Items:
Step 3: Change the order of how items appear in-app:
Click and hold the dotted 'drag' icon and drag the item to reorder it:
Step 4: Save changes:
Click the Save Changes button at the bottom of the screen.
Bulk Upload Item Connections
If you have a large catalog, use the Bulk Upload feature to assign similar and recommended items across many items at once using a CSV file, instead of configuring each item individually.
Step 1: Open the bulk upload flow
At the top of the Recommended + Similar tab, click the Bulk Upload banner. This opens the upload screen directly.
To get the CSV template, click Download blank template at the bottom of the screen. Fill it in before proceeding.
Step 2: Fill in the CSV template
The template includes the following columns: item_code, similar_1 through similar_6, and recommended_1 through recommended_6.
One row per main item.
Enter the item codes of up to 6 similar items and up to 6 recommended items in the correct columns.
Use the exact item codes from your catalog. Leave any unused cells blank.
Important: Before entering any item codes, set every column to plain text format in Google Sheets or Excel (select all columns → Format → Number → Plain text).
Otherwise, item codes that start with a zero — such as "04727" — may be silently changed to "4727", causing codes not to match.
Step 3: Upload your CSV
On the upload screen, drag and drop your completed file onto the upload area, or click Choose CSV to browse for it. Once uploaded, a preview of your file is shown for review.
Click Match item codes to continue.
Step 4: Review item matching
The Item Matching screen shows a summary of how your item codes were matched:
Multiple pack sizes: item codes that matched more than one pack size in your catalog.
Unmatched: item codes that were not found in your catalog at all. Return to your CSV to correct these before continuing.
Handling items with multiple pack sizes
Some item codes correspond to more than one pack size in your catalog (for example, MAYONNAISE · EACH and MAYONNAISE · CASE). When this happens, you can choose how to handle each code using the dropdown next to it:
Apply to all pack sizes: The connections from that row are applied to every matching pack size. This is the default.
Select a specific pack size: The connections are applied to one pack size only.
Skip this code (drop the row): The row is excluded from the upload.
To apply the same setting to all ambiguous codes at once, use the Apply to all pack sizes toggle at the top of the screen. Toggle it off to default each ambiguous code to its newest pack size instead, while still allowing per-code overrides below.
Once you've reviewed all codes, click Build update plan.
Step 5: Review and confirm the update plan
Before anything saves, you'll see a row-by-row preview of what will be updated. Review the summary at the top:
Total rows: the number of rows in your CSV.
Will update: the number of items that will be updated.
Skipped: rows that will not be updated (for example, codes you chose to skip).
Items exceeding limit: items where the total number of connections across all pack sizes exceeds the maximum of 6 similar or 6 recommended. Extra pack sizes are dropped from the end of the list to fit within the cap. Check the row-by-row preview to see which connections were dropped.
Row status labels
Each row in the preview shows a status label:
Applied (green): connections were applied successfully.
Applied to all pack sizes (green): connections were applied to all matching pack sizes.
Applied — too many similar items or Applied — too many recommended items (yellow): some connections were dropped because the item exceeded the connection limit. The dropped codes are listed in the row under "Dropped (too many items)".
Note: Each item can have a maximum of 6 similar and 6 recommended connections, counted by pack size. Because a single item code can map to more than one pack size (for example, a case and a single unit), a row with only a few item codes could still hit the limit if those items each have multiple pack sizes. When the limit is exceeded, the last pack sizes in the list are dropped in order until the total fits within the cap. Check rows marked "Applied — too many similar items" or "Applied — too many recommended items" to see which codes were dropped, and update your CSV if needed.
Overwrite existing connections
By default, bulk upload merges your new connections with any that already exist on each item. If you want to replace existing connections entirely with what's in your CSV, turn on the Overwrite existing connections toggle before submitting.
Note: Pack size, units, and other item details are never affected by a bulk upload.
When you're ready, click Submit [N] item updates to apply the changes.
Step 6: Confirm completion
Once submitted, a Bulk update complete banner confirms how many items were updated. The row-by-row summary remains visible for reference.
Item Substitutions
The Item Substitutions tab is available to distributors who currently offer item substitutions through their Pepper app. If item substitutions are in use but the tab is not visible, contact your Pepper representative.
How the tab works based on how substitutions are managed:
Managed through an ERP: The tab is view-only. Admins can search for items to see their available substitution options, but substitutions are managed through the ERP integration. Learn more about item substitutions.
Not managed through an ERP: Item substitutions can be configured directly in PMC using the Item Connections tool.
Note: Substitutions rely on real-time inventory data to determine when an item is out of stock. Make sure inventory sync is turned on for substitutions to work correctly.
View-only (ERP-managed substitutions)
If substitutions are managed through an ERP, the Item Substitutions tab displays substitution options as read-only. Use the search bar to look up an item and see which substitutes are assigned to it.
Configuring item substitutions (non-ERP managed substitutions)
Assigning Substitute Items
In the Item Substitutions tab, use the search bar to find the item you want to configure substitutions for. Recently edited items also appear below the search bar and can be clicked directly.
Click on the item to open its substitution settings.
Search for and add the items that should be offered as substitutes when this item is out of stock.
Click Save Changes.
Substitution Settings
The Substitution Settings panel controls how substitutions behave for all customers. It can be accessed by clicking the icon to the right of the item search bar, shown in the image below. Two settings are available:
Substitute from Catalog: When enabled, buyers have the option to manually search the catalog and select an item to use as a substitute.
Require Substitution Action: When enabled, buyers must confirm a substitution before it is applied to their order.
Toggling Substitutions per Customer
Item substitutions are enabled for all customers by default. To disable substitutions for specific customers, use the Toggle Substitutions Per-Customer section.
Click the arrow next to Toggle Substitutions Per-Customer to expand it.
Search for a customer by name, or scroll through the list.
Customers showing Default have substitutions enabled. To disable substitutions for a customer, toggle their setting to Off.
Click Save Changes.
