Troubleshooting Guide

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

For Collection Trigger:

1. Add ANY product from the specified collection
2. Verify the product is actually in that collection in Shopify Admin
3. Gift should add immediately

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

Solution 5: Enable Debug Mode

For advanced troubleshooting, you can enable debug mode to see detailed logs:

1. Add ?cartsprinkle_debug=true to any page URL
2. Example: yourstore.com/products/shirt?cartsprinkle_debug=true
3. Open browser console (F12 → Console tab)
4. Look for [CartSprinkle] logs showing exactly what's happening
5. Screenshot the logs and send to support if needed

Discount Not Being Applied

Problem: Gift adds to cart but shows full price instead of discounted/free price.

Solution 1: Check at Checkout (Most Common)

Many Shopify automatic discounts only apply at checkout, not in the cart:

1. Proceed to Checkout
2. Verify gift shows correct discount/price
3. This is normal Shopify behavior ✓

Solution 2: Check Shopify Discount

1. Go to Shopify Admin → Discounts
2. Look for discount named "CartSprinkle Gift Discount" (automatic discount)
3. Verify it's Active
4. Note: This discount is automatically created and managed by CartSprinkle via Shopify Functions

If Discount is Inactive or Missing:

• Check the promotion status in CartSprinkle dashboard
• Look for health status indicators (should be green)
• The discount is automatically created/managed - toggle the promotion OFF then ON to recreate if needed

Solution 3: 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: hello@cartsprinkle.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

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