Advanced Troubleshooting Guide (for Developers)

Systematic procedure for diagnosing and resolving campaign issues for support staff, developers, and technical users.

Triage: Identify the Symptom

Start by identifying which symptom matches the reported issue:

Section 1: Gift Not Appearing

Diagnostic flow:

1.1 Verify cart meets threshold

• [ ] Check cart subtotal (after discounts, before shipping/tax)
• [ ] Confirm threshold amount in campaign settings
• [ ] If using product trigger, confirm qualifying product is in cart

Fix: Add items to meet threshold or adjust campaign threshold.

1.2 Verify campaign is active

• [ ] Check campaign status on dashboard (Active, Scheduled, Paused, Ended)
• [ ] Verify current time is within start/end dates
• [ ] Check store timezone (Settings > General) matches expectations

Fix: Adjust dates or unpause campaign.

1.3 Verify gift product is available

• [ ] Gift product is published to Online Store channel
• [ ] Gift product is in stock (or set to continue selling when out of stock)
• [ ] Gift variant specifically selected in campaign exists and is available

Fix: Publish product, restock, or swap gift product.

1.4 Verify theme embed is enabled

• [ ] Go to Online Store > Themes > Customize > App embeds
• [ ] Confirm Promo Party Pro is toggled ON
• [ ] Save theme if changes made

Fix: Enable embed and save.

1.5 Test in clean environment

• [ ] Open incognito/private browser window
• [ ] Disable browser extensions (especially ad blockers)
• [ ] Test on different device or browser

Fix: If works in incognito, issue is browser cache or extensions. Clear cache.

Still not working? Escalate to support with: campaign name, cart contents, screenshots.

Section 2: Gift Added But Not Free

Root cause: Discount combination conflict (95% of cases).

2.1 Check Promo Party discount settings

• [ ] Open campaign in Promo Party
• [ ] Verify "Combine with other discounts" is enabled
• [ ] Save if changes made

2.2 Check other active discounts

• [ ] Go to Shopify admin > Discounts
• [ ] Identify which discount the customer is using
• [ ] Open that discount and check Combinations settings
• [ ] Enable combinations with automatic discounts

Both discounts must allow combinations. If either is set to "not combinable," only one applies.

2.3 Test the combination

• [ ] Apply the discount code in cart
• [ ] Add items to meet gift threshold
• [ ] Verify gift shows as $0 at checkout

Fix: Enable combinations on both sides.

Edge case: Customer has a discount that explicitly excludes combinations. Solution: They must choose one or the other, or you adjust the discount settings.

Section 3: Popup Not Showing

3.1 Verify popup is enabled

• [ ] Open campaign in Promo Party
• [ ] Confirm "Show gift picker popup" is toggled ON
• [ ] Verify multiple gift options are selected (popup not needed for single variant)

3.2 Verify theme embed

• [ ] Go to Online Store > Themes > Customize > App embeds
• [ ] Confirm Promo Party Pro is toggled ON
• [ ] Save theme

3.3 Check for theme conflicts

• [ ] Test with default Shopify theme (Dawn) temporarily
• [ ] If popup works in Dawn, issue is theme-specific
• [ ] Check for JavaScript errors in browser console (F12 > Console)

3.4 Check browser environment

• [ ] Disable ad blockers and privacy extensions
• [ ] Test in incognito mode
• [ ] Test on mobile and desktop

3.5 Check popup re-display settings

• [ ] If customer previously dismissed popup, check re-display delay setting
• [ ] Wait for delay period or clear cookies to reset

Fix: Enable popup, fix embed, or identify theme conflict.

Theme conflict identified? Escalate to support with theme name and console errors.

Section 4: Wrong Gift Offered

4.1 Check campaign configuration

• [ ] Open campaign and verify correct gift product(s) selected
• [ ] Verify correct variant(s) selected if applicable

4.2 Check for multiple active campaigns

• [ ] Review all campaigns on dashboard
• [ ] Look for overlapping campaigns with different gifts
• [ ] Check if customer qualifies for multiple campaigns

4.3 Verify trigger conditions

• [ ] Confirm which trigger is set (subtotal vs. product in cart)
• [ ] If product trigger, verify the correct qualifying product

Fix: Correct gift selection or resolve campaign overlap.

Section 5: Campaign Active But Nothing Works

5.1 Run full diagnostic

Complete all checks from Section 1:

• [ ] Cart threshold
• [ ] Campaign dates/status
• [ ] Gift product availability
• [ ] Theme embed

5.2 Check for dashboard warnings

• [ ] Look for yellow/red warning banners
• [ ] Common warnings: out of stock, embed missing, product unpublished

5.3 Force refresh

• [ ] In Promo Party, click Save on the campaign (even without changes)
• [ ] Clear store cache if using caching app
• [ ] Test in incognito

5.4 Verify Shopify discount created

• [ ] Go to Shopify admin > Discounts
• [ ] Look for automatic discount created by Promo Party
• [ ] Verify it's active and not expired

Fix: Address specific warning or re-save campaign.

No warnings, all checks pass? Escalate to support with full configuration details.

Section 6: Gift Added Then Disappeared

6.1 Cart value dropped below threshold

• [ ] Customer removed items from cart
• [ ] Customer applied discount that lowered subtotal below threshold
• [ ] Expected behavior: gift is removed when threshold no longer met

Fix: Not a bug. Explain to customer or adjust threshold.

6.2 Gift went out of stock

• [ ] Another customer purchased last unit of gift product
• [ ] Check inventory levels
• [ ] Check dashboard for out-of-stock warning

Fix: Restock or substitute gift product.

6.3 Campaign ended

• [ ] Campaign hit end date while customer was shopping
• [ ] Check campaign schedule

Fix: Extend campaign or honor gift manually if appropriate.

Escalation Protocol

Before escalating to support, collect:

1. Campaign name
2. Symptom (which section above)
3. Steps already attempted
4. Screenshots of:

• Campaign settings
• Cart contents with prices
• Checkout showing issue
• Dashboard warnings (if any)

5. Browser/device used
6. Theme name

Contact: Live chat in app (preferred) or apps@ethercycle.com

Quick Reference Card

Revision History

Updated on: 23/01/2026