Troubleshooting Guide

Fix common issues quickly

Having issues with CartSprinkle? This guide will help you fix the most common problems quickly.

Quick Diagnostic

Before diving into specific issues, run this quick check:

✅ Pre-Flight Checklist

  1. App Installed? ✓
    • Go to Shopify Admin → Apps
    • CartSprinkle should be in your list
  2. Theme Extension Enabled? ✓
    • Online Store → Themes → Customize
    • App embeds → CartSprinkle Gift Auto-Add → ON
  3. Promotion Active? ✓
    • Dashboard shows Status = Active (green)
    • Today's date is between start and end dates
  4. Gift In Stock? ✓
    • Check gift product inventory > 0
    • Product not archived or hidden
  5. Criteria Met? ✓
    • Cart total ≥ spend threshold (OR)
    • Trigger product in cart

Common Issues

Gift Not Appearing in Cart

Problem: Customer meets criteria but gift doesn't auto-add to cart.

Solution 1: Check Promotion Status

  1. Go to CartSprinkle dashboard
  2. Find your promotion
  3. Verify status shows Active (green badge)

If Inactive:

  • Click the toggle to turn it ON
  • Verify dates include today

Solution 2: Verify Trigger Criteria

For Spend Threshold:

  1. Open your store in incognito window
  2. Add products totaling MORE than threshold
  3. Check cart subtotal (before tax/shipping)
  4. Gift should add within 1-2 seconds

For Product Trigger:

  1. Add the EXACT product specified
  2. Check variant matches (if product has variants)
  3. Gift should add immediately

💡 Testing Tip

Always test in incognito/private browsing mode - this ensures no cached data interferes.

Solution 3: Check Gift Inventory

  1. Go to Shopify Admin → Products
  2. Find your gift product
  3. Check Inventory - must be > 0
  4. If out of stock, restock and promotion auto-resumes

Solution 4: Clear Browser Cache

  1. Open incognito/private window
    • Chrome/Edge: Ctrl+Shift+N (Windows) or Cmd+Shift+N (Mac)
    • Firefox: Ctrl+Shift+P (Windows) or Cmd+Shift+P (Mac)
    • Safari: Cmd+Shift+N (Mac)
  2. Visit your store
  3. Test the promotion again

Discount Not Being Applied

Problem: Gift adds to cart but shows full price instead of $0.00.

Solution 1: Check Shopify Discount

  1. Go to Shopify Admin → Discounts
  2. Look for discount starting with "GWP:"
  3. Verify it's Active

If No Discount Found:

  • Go to CartSprinkle dashboard
  • Delete and recreate the promotion
  • This will create a new discount

Solution 2: Check for Conflicting Discounts

Shopify Limitation: Only ONE automatic discount can apply per order.

  1. Shopify Admin → Discounts
  2. Look for other automatic discounts that are Active
  3. Temporarily disable them to test
  4. Your gift discount should then apply

Discount types:

  • Automatic discounts = Conflict with GWP (only one can apply)
  • Discount codes = Do NOT conflict (customer can still use)

Theme Extension Not Showing

Problem: Can't find "CartSprinkle Gift Auto-Add" in theme customizer app embeds.

Solution 1: Refresh Theme Customizer

  1. Close the theme customizer
  2. Go to Online Store → Themes
  3. Click Customize again
  4. Scroll to App embeds
  5. Look for CartSprinkle Gift Auto-Add

Solution 2: Hard Refresh Browser

  1. In theme customizer, press:
    • Windows/Linux: Ctrl + Shift + R
    • Mac: Cmd + Shift + R
  2. This forces browser to reload everything
  3. Check App embeds again

Solution 3: Verify App Installation

  1. Shopify Admin → Apps
  2. Confirm "CartSprinkle" is listed
  3. If not, reinstall from App Store

Changes Not Showing on Storefront

Problem: Edited promotion but changes don't appear on live store.

Solution 1: Wait for Sync

Changes can take 1-2 minutes to propagate:

  1. Wait 2 minutes after saving
  2. Hard refresh storefront (Ctrl/Cmd + Shift + R)
  3. Test again

Solution 2: Clear All Caches

  1. Browser cache: Open incognito window
  2. Theme cache: Hard refresh (Ctrl/Cmd + Shift + R)
  3. CDN cache: Wait 2-3 minutes

Error Messages

"Promotion not found"

Means: Promotion was deleted or never created

Fix:

  1. Check promotions list in dashboard
  2. Recreate promotion if needed
  3. Verify you're testing the right store (dev vs production)

"Gift out of stock"

Means: Gift product inventory is 0

Fix:

  1. Shopify Admin → Products → Gift product
  2. Add inventory
  3. Promotion auto-resumes

"Invalid dates"

Means: Start date is after end date, or dates are invalid

Fix:

  1. Edit promotion
  2. Set start date BEFORE end date
  3. Ensure dates are in correct format
  4. Save changes

"API error"

Means: Can't connect to app backend

Fix:

  1. Check your internet connection
  2. Try again in 1-2 minutes
  3. If persists, contact support

"Theme extension not found"

Means: Extension isn't enabled in theme

Fix:

  1. Online Store → Themes → Customize
  2. App embeds → CartSprinkle Gift Auto-Add → ON
  3. Save

Still Stuck?

If you've tried everything above and it's still not working:

Contact Support

Email: tjmapes@gmail.com
Include:

  1. ✅ Store URL (yourstore.myshopify.com)
  2. ✅ Promotion title
  3. ✅ What you've tried from this guide
  4. ✅ Screenshots of:
    • Promotion settings
    • Theme extension toggle (ON)
    • Browser console errors (F12)
  5. ✅ Steps to reproduce the issue

Response time: Within 24 hours (usually much faster!)

Quick Reference

Problem Quick Fix
Gift not adding Check: Active status, dates, inventory, criteria
Discount not applying Check: Shopify Discounts, conflicts, gift product
Extension not showing Refresh customizer, verify app installed
Changes not live Wait 2 min, hard refresh, toggle OFF/ON

Last Updated: October 2025
Need more help? Contact Support | FAQ