Troubleshooting & FAQ

This guide covers common issues, solutions, and frequently asked questions about the Quick Order Matrix. Use this as your first resource when encountering problems.

Common Installation Issues

"Alpine is not defined" Error

Symptoms:

• Browser console shows error: ReferenceError: Alpine is not defined
• Matrix displays but inputs don't work
• Clicking "Add to Cart" does nothing

[IMAGE PLACEHOLDER: console-error.png]

Browser console showing "Alpine is not defined" error in red

Cause: Your Shopify theme doesn't include Alpine.js

Solution: Your theme needs to support the Quick Order Matrix's interactive features.

Option 1: Contact Your Theme Developer

• Ask if your theme supports the Quick Order Matrix
• They can add the necessary support if needed

Option 2: Switch Themes

• Consider using a modern Shopify theme that supports advanced sections
• Many themes built in the last few years include the required features

Option 3: Hire a Developer

• A Shopify developer can add the necessary support to your current theme
• This is usually a quick, one-time setup

Tailwind Classes Not Styling

Symptoms:

• Matrix displays but looks completely unstyled
• No colors, borders, or spacing
• Layout is broken or appears as plain text

Cause: Your theme doesn't include Tailwind CSS

Solution: The matrix styling isn't loading correctly.

Option 1: Contact Your Theme Developer

• Ask if your theme is compatible with the Quick Order Matrix
• They can help ensure proper styling

Option 2: Switch Themes

• Consider using a modern Shopify theme
• Many newer themes support the styling requirements

Option 3: Hire a Developer

• A Shopify developer can add custom styling to match your theme
• This ensures the matrix looks correct in your store

Template Doesn't Appear in Dropdown

Symptoms:

• "quick-order" template not visible in Theme template dropdown
• Only see "Default" or other templates

Causes & Solutions:

1. File Naming Issue

Template must be named exactly: collection.quick-order.liquid

Check:

• Go to Themes → Edit Code → Templates
• Look for collection.quick-order.liquid
• If named differently (e.g., quick-order.liquid or collection.quick-order), rename it

2. File Location Issue

File must be in the Templates folder, not Sections or Assets.

Check:

• Verify it's in the Templates folder
• If it's in the wrong folder, delete it and recreate in Templates

3. Cache Issue

Shopify may not have updated the template list.

Try:

• Hard refresh your browser (Ctrl+F5 / Cmd+Shift+R)
• Log out and back into Shopify admin
• Wait a few minutes and try again
• Re-save the template file in the code editor

Files Won't Upload or Save

Symptoms:

• Error when trying to save file
• "File already exists" error
• Changes don't persist

Solutions:

If file exists:

• Delete the existing file first, then create new one
• Or edit the existing file instead of creating new

If permissions error:

• Verify you have theme editing permissions in Shopify
• Contact store owner to grant access

If network error:

• Check your internet connection
• Try a different browser
• Clear browser cache

Runtime Issues

"Add to Cart" Button Does Nothing

Symptoms:

• Click the button but nothing happens
• No redirect to cart
• No errors visible

Debugging Steps:

1. Check Browser Console

Open Developer Tools (F12) → Console tab

Look for errors:

• Alpine is not defined → See Alpine.js troubleshooting above
• fetch failed → Network issue
• Any red error messages

2. Check for Errors

Look for any red error messages in the console. Common issues:

• Interactive features not loading
• Network connection problems
• Theme compatibility issues

3. Test Basic Functionality

• Try entering a quantity in one field
• Check if the total updates
• If nothing happens, there may be a compatibility issue with your theme

[IMAGE PLACEHOLDER: network-tab.png]

Network tab showing successful POST request to /cart/add.js with 200 status

4. Test With Simple Quantity

• Enter quantity: 1 in a single input
• Leave all others empty
• Click "Add to Cart"
• Does it work? If yes, issue may be with multiple items

Common Fixes:

• Check for theme compatibility issues (see Alpine.js troubleshooting above)
• Verify products have valid variants in Shopify admin
• Try disabling browser extensions temporarily
• Test in incognito/private browsing mode
• Check if other apps might be interfering

Prices Show $0.00

Symptoms:

• "Total" column shows $0.00 for all products
• Footer total shows $0.00

Cause: Price calculation may not be working correctly

Check:

1. Verify products have prices set in Shopify admin
2. Check that variant prices are set (not just product prices)
3. Ensure your theme is compatible with the matrix

Note: If prices show $0.00 but products have prices in Shopify, this may be a theme compatibility issue.

Workaround: The core functionality (adding to cart) still works. Customers can check totals on the cart page after adding items.

Matrix is Empty / No Products Showing

Symptoms:

• Table headers show but no product rows
• "Loading..." disappears but table is empty
• Blank white space where products should be

Causes & Solutions:

1. Collection Has No Products

Check:

• Go to Products → Collections in Shopify admin
• Open your collection
• Verify products are added
• Ensure products are "Active" (not draft or archived)

2. Product Limit Reached

The matrix displays up to 200 products per collection.

Check:

• Does your collection have more than 200 products?
• If yes, only the first 200 will display
• Consider splitting into multiple collections by category

3. All Variants Unavailable

The matrix shows all variants, including unavailable ones. But if filtering logic is wrong, they might not display.

Check:

• Verify at least some variants are marked "Available" in Shopify
• Check variant inventory quantities

4. Customization Issue

If you've made changes to the matrix files, you may have introduced an error.

Check:

• Restore the original files from your download
• Test if products appear
• If yes, your customization may have caused the issue

Images Not Showing

Symptoms:

• Broken image icons (🖼️)
• Blank spaces where product images should be
• Browser console shows 404 errors for image URLs

Causes & Solutions:

1. Products Missing Featured Images

Check:

• Go to Products in Shopify admin
• Open each product
• Verify "Featured Image" is set
• Add images if missing

2. Shopify CDN Issues (rare)

Check:

• View page source
• Find an image URL (search for img_url)
• Copy the URL and paste in new browser tab
• Does image load? If no, Shopify CDN issue

Solution: Contact Shopify support

3. File Issue

If you've edited the matrix files, there may be an error in the image code.

Solution:

• Restore the original files from your download
• Images should work automatically if products have featured images set

Display Issues

Table Layout Broken

Symptoms:

• Columns misaligned
• Text overlapping
• Unreadable layout

Causes:

• Theme compatibility issue
• CSS conflicts with your theme
• Browser compatibility

Solutions:

• Test in different browser
• Disable other apps temporarily to test for conflicts
• Contact your theme developer for compatibility check
• Consider switching to a compatible theme

Sticky Footer Not Sticking

Symptoms:

• Footer scrolls off-screen instead of staying fixed
• Footer appears at bottom of page content

Cause: Theme compatibility issue with sticky positioning

Solution:

• This may be a theme compatibility issue
• Contact your theme developer
• Or consider using a theme that supports sticky footers

Mobile View Broken

Symptoms:

• Unusable on mobile devices
• Text too small
• Buttons not tappable

Expected Behavior: The matrix is designed primarily for desktop. On mobile, it should:

• Scroll horizontally
• Have touch-friendly inputs
• Show sticky footer

If Not Working:

• Verify viewport meta tag in theme: <meta name="viewport" content="width=device-width, initial-scale=1">
• Check for CSS overrides
• Test in mobile browser (not just resized desktop browser)

Performance Issues

Slow Loading with Many Products

Symptoms:

• Page takes 3+ seconds to load
• Browser becomes unresponsive
• Janky scrolling

Cause: Too many products for optimal performance

Solutions:

1. Reduce Product Count

• Limit collection to 200 products or fewer for optimal performance
• For 150 to 200 products, expect 2 to 3 second load times
• Split into multiple collections by category if you have more

2. Optimize Images

• Ensure product images aren't excessively large
• Shopify should auto-optimize, but check source images

3. Reduce Variants

• If you have products with 20+ variants each, consider restructuring
• 200 products × 10 variants = 2,000 rows (may be slow on older devices)

Expected Performance:

• 50 products: less than 1 second load
• 100 products: 1 to 2 seconds load
• 200 products: 2 to 3 seconds load
• 300+ products: 4 to 5+ seconds load (not recommended)

Frequently Asked Questions

Can I Show More Than 200 Products?

Yes, technically. The 200 product limit can be increased, but it will impact performance.

Why 200? Shopify's system slows down with larger product counts. 200 products provides the best balance between catalog size and page speed (2 to 3 second loads).

Can I increase it?

• Technically yes, but it requires editing theme code (developer task)
• 300 products: approximately 4 to 5 second loads (acceptable but slower)
• 500+ products: ~10+ second loads (poor user experience)
• We strongly recommend keeping it at 200 or lower

Workaround: Create multiple collections organized by category:

• "Wholesale - Electronics"
• "Wholesale - Accessories"
• "Wholesale - Apparel"

Customers can navigate between collections.

Can I Add Search or Filtering?

Not in this version. The free Quick Order Matrix does not include search or filtering functionality.

Why?

• The free version is designed for simplicity and performance
• Adding search requires advanced development work
• Search for large catalogs is reserved for the paid Matrix B2B theme

Workaround: Use browser's Find function (Ctrl+F / Cmd+F) to search the page for product names or SKUs.

Upcoming: The full Matrix B2B theme (coming soon) will include advanced search for SKU, barcode, and product name that searches ALL products across your entire catalog, regardless of pagination.

Does It Work with Shopify POS?

No. The Quick Order Matrix is designed for the online store only, not Shopify POS.

However, you can:

• Use it on a tablet in-store
• Take orders by having customers browse the online collection
• Process payment through standard Shopify checkout

Can I Hide Prices from Certain Customers?

Not in this version. The matrix displays standard product prices to all visitors.

Workaround:

• This requires custom development work
• Consider hiring a Shopify developer if you need this feature

Upcoming: The full Matrix B2B theme will include customer-specific pricing and price list management.

Can Customers Save Their Order for Later?

Not built-in. The matrix doesn't save quantities between sessions.

Workaround: Quantities entered are cleared on page refresh. Customers should complete orders in one session.

Future Feature: This may be added in a future update. For now, customers should complete orders in one session.

Does It Support Variants?

Yes! Each variant appears as its own row in the matrix.

Example:

• Product: T-Shirt
  • Row 1: Small / Red
  • Row 2: Small / Blue
  • Row 3: Large / Red
  • Row 4: Large / Blue

All variants are fully supported.

Can I Customize Colors and Text?

Yes. See the Customization Guide for details on:

• Changing colors
• Modifying text labels
• Adjusting stock thresholds
• Button styling

Is There a Product Limit Per Variant?

No variant limit. If you have 200 products with 20 variants each, all 4,000 rows will display (though this may be slow on older devices).

The limit is on products (200), not variants.

Does It Work With Shopify Subscriptions?

Partially. The matrix can add subscription products to the cart, but:

• Customers must select subscription frequency on cart/checkout
• No subscription options shown in matrix
• Limited subscription functionality

For full subscription support, use Shopify's standard product pages or a dedicated subscription app.

Can I Use Multiple Matrices on One Page?

Not recommended. The section is designed for one instance per collection page.

Multiple instances may cause:

• ID conflicts
• Alpine.js state confusion
• Unexpected behavior

Is It Compatible with My Theme?

Compatibility: The Quick Order Matrix works best with modern Shopify themes.

Check Your Theme:

1. View your theme's documentation
2. Contact your theme developer to ask about Quick Order Matrix compatibility
3. Test the installation - if it works, your theme is compatible!

Generally Compatible:

• Modern themes (2020 and newer)
• Themes that support custom sections
• Most popular Shopify themes

May Have Issues:

• Very old themes (pre-2020)
• Heavily customized themes
• Themes with limited section support

Still Having Issues?

If your problem isn't covered here:

1. Double-Check Installation

• Review the Installation Guide
• Verify all three files are uploaded correctly
• Confirm file names are exact

2. Review Documentation

• Getting Started - System requirements
• How It Works - Customer experience
• Customization - Theme Editor customization

3. Check Browser Console

• Open Developer Tools (F12)
• Look for error messages
• Screenshot errors for reference

4. Test in Different Environment

• Try different browser
• Test in incognito mode
• Disable browser extensions
• Try different device

5. Restore Original Files

• If you've customized, restore the original files
• Test if that fixes the issue
• Helps identify if customization caused the problem

6. Consider Hiring a Developer For complex issues or custom requirements, hire a Shopify expert:

• Shopify Experts Marketplace
• Fiverr, Upwork, or other freelance platforms
• Your theme developer (if applicable)

Error Messages Reference

Quick Diagnostic Checklist

Before seeking help, verify:

• All three files uploaded to correct locations
• File names are exactly correct
• Matrix displays with proper styling
• Collection has products added
• Products have featured images
• Products have prices set
• Browser console shows no errors
• Tested in different browser
• Template is assigned to collection

If all items are checked and issue persists, you may have a theme compatibility issue. Contact your theme developer or consider hiring a Shopify expert for assistance.