> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.promoparty.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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:

| Symptom | Go to |
|---------|-------|
| Gift not appearing at all | Section 1 |
| Gift appears but isn't free | Section 2 |
| Popup not showing | Section 3 |
| Wrong gift offered | Section 4 |
| Campaign shows active but nothing works | Section 5 |
| Gift was added then disappeared | Section 6 |

---

## 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

| Issue | First Check | Common Fix |
|-------|-------------|------------|
| Gift not appearing | Cart threshold + campaign status | Meet threshold, check dates |
| Gift not free | Discount combinations | Enable combining on both discounts |
| No popup | Popup toggle + embed | Enable popup, check embed |
| Wrong gift | Campaign config | Verify gift selection |
| Active but broken | Dashboard warnings | Address warning, re-save |
| Gift disappeared | Cart value change | Expected behavior if below threshold |

---

## Revision History

| Date | Version | Changes |
|------|---------|---------|
| 2026-01-20 | 1.0 | Initial SOP |