Troubleshooting

Common Problems and Solutions

Form does not display on the page

Possible causes:

1. Module is not active

   • Check: WPify → WPify Woo
   • Enable the “Withdrawal & Claim” module

2. Page is not assigned in settings

   • Go to WPify → WPify Woo → Withdrawal & Claim
   • Assign a page to Withdrawal page (and/or Claim page)
   • Without a page assigned, the corresponding shortcode/block silently renders empty

3. Shortcode not added to the page

   • Add [wpify_woo_withdrawal_form] (or the Withdrawal form Gutenberg block) to the page content

4. ?form= parameter mismatches the shortcode type

   • If you have both shortcodes on one page and the URL has ?form=claim, the withdrawal shortcode renders an empty wrapper (and vice versa)
   • This is intentional, only one form is active at a time per URL

---

Block in editor doesn’t appear or shows nothing

Possible causes:

1. JS not built

   • Run npm run build after plugin update — the block editor JS is compiled by wp-scripts

2. Hard cache in editor

   • Reload the editor with Ctrl+Shift+R

3. Module disabled

   • Block in editor shows an admin-only red placeholder if the half is disabled (page not assigned)

---

Customer doesn’t receive the confirmation email

Possible causes:

1. WC email is disabled

   • Go to WooCommerce → Settings → Emails
   • Find “Withdrawal — confirmation to customer” (or claim equivalent) and enable it

2. Email goes to billing email, not the entered email

   • This is by design — for security, the customer notification always goes to billing_email (no redirection allowed)

3. Email server / SMTP misconfigured

   • Test general WordPress email functionality first
   • Use a plugin like WP Mail SMTP for reliable delivery

4. Email triggered before WC mailer initialized

   • Check error log for warnings about WC()->mailer()

---

Admin doesn’t receive the notification email

Possible causes:

1. WC email is disabled

   • Go to WooCommerce → Settings → Emails
   • Find “Withdrawal — admin notification” (or claim equivalent) and enable it

2. Recipient is empty

   • Check the Recipient(s) field on the email settings page
   • Defaults to admin_email if blank

---

”Invalid form type” error

Cause: REST endpoint received a request without the form type field.

Fix: This was a known bug in older versions where the REST endpoint expected type but the form sent wpify_woo_request_type. Update to the latest version. If still occurring, check that the form was rendered by the latest template (not cached HTML).

---

Form submit shows “Working…” then nothing happens

Possible causes:

1. Browser autofilled the honeypot field

   • Some browsers (especially older Chrome) autofill any <input> that looks email-related
   • Latest version uses field name wpify_woo_url to avoid this — update if using older version

2. Time-trap fired (form submitted within 1 second of page load)

   • Wait at least 1 second after page load before submitting

3. Validation failed silently (older versions)

   • Latest version returns a clear error message to the user

4. JavaScript error in console

   • Open browser DevTools → Console — check for errors

---

Customer gets “This order is not eligible…” error

Cause: The order is in a blocked status.

Default blocked statuses:

• refunded (Refunded)
• cancelled (Cancelled)
• failed (Failed)
• checkout-draft, auto-draft (Draft)

Fix: Either change the order status (in WC admin) to an active one, or use the wpify_woo_withdrawal_claims_blocked_statuses filter to customize.

---

Withdrawal period seems wrong

Possible causes:

1. Period start status is not configured to match your workflow

   • Default is “Completed”. If your shop uses a custom “Delivered” status for actual delivery, select it in Order statuses that start the period

2. Legacy order (pre-module-activation)

   • For orders that existed before the module was active, the period uses fallback (date_completed → date_paid → date_created). The configured period_start_statuses are NOT enforced retroactively.

3. Per-product override is set

   • Check the product’s Withdrawal & Claim tab for an override value

---

”No eligible items in this order”

Possible causes:

1. Period expired for all items
2. All products excluded from withdrawal/claim via per-product setting
3. Order has no line items

The form shows individual reason tags (“Period expired” / “Excluded by seller”) next to disabled items in the eligibility section.

---

”Too many attempts. Please try again later.”

Cause: Layer B rate limit hit.

Cooldown: 1 hour. The transient wpify_woo_req_attempts_{md5(ip)} expires automatically.

Fix for stuck legitimate users:

• Increase the limit in Settings → Security → Max attempts per IP per hour
• Or delete the transient manually via WP-CLI: wp transient delete wpify_woo_req_attempts_*

---

Item count in admin column doesn’t match what the customer sees

Cause: Customer’s submission was filtered server-side.

scope = whole_order means “all eligible items at submission time” — items excluded by per-product settings or expired periods are NOT included. Only the final filtered list is stored in items_json.

---

Email styling doesn’t match my customizations

Cause: Theme override of email-styles.php not loaded.

The plugin’s email templates use class="td" and rely on WC’s email-styles.php (processed by Emogrifier into inline CSS). To customize:

1. Copy wp-content/plugins/woocommerce/templates/emails/email-styles.php to wp-content/themes/[your-theme]/woocommerce/emails/email-styles.php
2. Customize there
3. Both WC native order emails and our withdrawal/claim emails will use your styles

---

HPOS — metabox doesn’t appear in order detail

Cause: Older plugin version registered metabox only on legacy shop_order screen.

Fix: Update to the latest version. The plugin declares HPOS compatibility via FeaturesUtil::declare_compatibility('custom_order_tables', …) and registers the metabox on both shop_order and woocommerce_page_wc-orders screens.

---

Cache plugin serves outdated form

Cause: Full-page cache (WP Rocket, LiteSpeed, server-level Varnish) cached the form page, including stale nonces and time-trap tokens.

Fix: The plugin sets DONOTCACHEPAGE and nocache_headers() on assigned form pages. If your cache plugin doesn’t honor these, manually exclude the withdrawal/claim pages from caching.

Logs

Plugin uses Wpify\Log\RotatingFileLog with parent slug wpify. There are two ways to access logs:

1. Admin UI: WPify → WPify Logs

Pick a log file from the dropdown (one file per plugin per day) and click Display log. The selected file is rendered as a table with entry timestamp, level badge (DEBUG / INFO / NOTICE / WARNING / ERROR — color-coded), message and context. Below the table you can set how many log files per plugin to keep (default 5).

There is no built-in level filter or full-text search — pick the day’s file and read the entries.

2. Filesystem: wp-content/uploads/wpify-logs/wpify_log_wpify-woo_*.log

Levels used by the module:

• error — DB exceptions, email send failures
• warning — rate-limit hits, honeypot trips, time-trap fails, invalid tokens
• info — successful submissions (request_id + order_id only)

Review logs first when troubleshooting failed submissions.

Contact Support

If the problem persists, contact support at support@wpify.io.

Please prepare the following information:

• WordPress version
• WooCommerce version (and HPOS enabled?)
• WPify Woo plugin version
• Logged-in vs. guest scenario
• Browser + version
• Screenshot of the problem
• Excerpt from wp-content/uploads/wpify-logs/wpify-woo-*.log around the time of the issue