Documentation

Troubleshooting

Turn on the log first, then work through the symptom that matches what you are seeing.

Start with the system status report

Go to WooCommerce → Status and find the Paddle section. It answers most questions in one screen without you having to open the Paddle dashboard:

  • Which environment you are transacting in, and whether the seller ID, API key and webhook secret are set for it.
  • Whether a webhook is registered, when the last one arrived, what happened to it, and recent processed / rejected counts.
  • Whether auto sync is on, and when it is next due — Overdue here usually means WP-Cron is not running.
  • How many products are synced, and whether any refunds are waiting on Paddle's approval.

Every figure comes from data already recorded on your own site, so the report still works when Paddle is unreachable — which is exactly when you are likely to be reading it.

Clicking Get system report includes these rows in the copyable text. Your API key and webhook secret are reported only as set or not set, never by value, so the report is safe to paste into a support email.

Site Health checks

The other place to look is Tools → Site Health → Status, where the plugin adds six checks while the gateway is enabled. These are the failures that are otherwise silent — nothing on your store looks broken, orders simply stop completing or products quietly stop syncing.

  • Paddle API key — a key is configured for the environment you are transacting in.
  • Paddle webhook secret — a signing secret is saved, without which every delivery is rejected.
  • Paddle webhook registration — a destination actually exists in Paddle for this environment.
  • Paddle webhook deliveries — deliveries are arriving and being processed. A store receiving a steady stream of deliveries that all fail verification is flagged, rather than counted as healthy because something arrived.
  • Paddle auto sync schedule — auto sync is on and its next run is actually scheduled. "Overdue" here usually means WP-Cron is not running.
  • Paddle product sync failures — products whose last sync failed, so a scheduled run that starts failing does not go unnoticed.

Each failing check explains what breaks in practice and links to the screen where you fix it. The matching admin notices clear themselves once the problem is gone — you do not have to dismiss them to find out whether they were resolved.

Debug logging

Enable Debug log in the gateway settings to log sync operations, payment processing, API requests, and webhook activity.

View logs in WooCommerce → Status → Logs (source: paddle).

Common issues

Products not syncing

  • Verify API key and seller ID for the active environment.
  • Ensure the product has a valid price.
  • Check logs at WooCommerce → Status → Logs (source: paddle).

Payment not completing

  • Confirm the product has a _paddle_{environment}_price_id meta (e.g. _paddle_production_price_id) — i.e. it has been synced.
  • Check the browser console for JavaScript errors on the order-received page.
  • In sandbox mode, test with Paddle test cards.

A customer's card was declined

  • Open the order and read the notes. A failed attempt records the reason in plain English along with Paddle's own error code, so you can tell an expired card from a spending limit from a bank that could not be reached.
  • The customer sees a shorter message that says only whether trying the same card again is worth it. Some reasons — a payment flagged by fraud screening, for example — are deliberately not shown to the buyer.
  • If the reason is temporary, such as the issuer being unreachable, the same card may well work a few minutes later. If it is an expired, blocked or unsupported card, the customer needs a different one.

Two products charging the same amount

  • Look for the warning on the Products screen — it names any products sharing one Paddle price.
  • This normally comes from duplicating a product before version 1.2.0. See Duplicated products for how to repair it.

Order stuck in pending

  • Verify the webhook is registered and reachable from the public internet.
  • Review WooCommerce logs for webhook signature failures.
  • Check the Paddle dashboard to confirm the transaction actually completed.

Webhooks not working

  • Read the webhook health panel in the gateway settings first — it names the rejection reason and what to do about it.
  • Make sure a webhook secret is saved for the active environment. Without one, every delivery is rejected.
  • Make sure that secret matches the one in your Paddle notification settings.
  • Confirm your site is reachable over HTTPS from outside.
  • Ensure server time is accurate — signatures are only accepted within 60 seconds.

Refund not showing in WooCommerce

  • Check the order notes. "Awaiting approval" means Paddle has not resolved the adjustment yet, and no WooCommerce refund is recorded until it does.
  • Confirm the webhook subscription includes the adjustment events — Check Webhook adds them if they are missing.
  • The scheduled fallback picks approvals up even without webhooks, so verify WP-Cron is running on the site.
  • See Refunds for the full picture.

Still stuck? Email [email protected] with your site URL, plugin version, and a copy of the relevant log lines.