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