Documentation

Refunds

Refunds are issued from WooCommerce and carried out by Paddle. Paddle does not always approve them instantly, so it is worth knowing what the order screen is telling you.

The gateway supports refunds, so you use WooCommerce's own refund UI — no separate screen. Each refund is sent to Paddle as a refund adjustment against the original transaction.

Issuing a refund

  1. Open the order in WooCommerce → Orders and click Refund under the line items.
  2. Enter a full or partial amount, and a reason if you want one. If you leave the reason empty the plugin supplies a default, because Paddle requires one.
  3. Click the refund button. The plugin fetches the current transaction from Paddle and builds the adjustment from its items.

A full refund is sent as a full adjustment on every transaction item, but only when nothing has been refunded or adjusted before and the amount matches the Paddle transaction total. Otherwise the amount is allocated across the transaction items as partial adjustments, largest remaining item first, after subtracting whatever has already been adjusted at Paddle.

If the refund cannot be submitted at all, WooCommerce reports it as a browser alert and nothing else — so the plugin also writes an order note recording the attempt and why it failed.

Paddle does not always approve instantly

Paddle auto-approves some refund adjustments and reviews others manually. Manual review can take days, and the refund can be rejected. The plugin never records a WooCommerce refund for money that has not moved yet, so what you see on the order depends on which of the three outcomes Paddle returns:

  • Approved — the refund is recorded in WooCommerce straight away and an order note names the adjustment.
  • Awaiting approval — no refund is recorded. WooCommerce shows a message saying the refund was submitted and is awaiting approval, and an order note says the same. The WooCommerce refund record is created automatically once Paddle approves the adjustment.
  • Rejected — nothing is recorded, and the order note explains that Paddle rejected the refund.

The "awaiting approval" case is the one that surprises people: the refund request succeeded, but WooCommerce deliberately discards its refund record until the money actually moves. Check the order notes if you are not sure which state a refund is in.

One refund request at a time

Paddle accepts only one refund request per transaction at a time. While an adjustment is awaiting approval, a second request on the same order is refused — the plugin stops it before contacting Paddle and tells you the amount that is already pending, rather than surfacing a raw API error.

So you are not left guessing, a notice appears next to the refund buttons on the order screen for as long as something is pending, saying that a refund is awaiting approval from Paddle, that Paddle will not accept another refund on this order until it clears, and that the WooCommerce refund is recorded automatically when it does.

Refunds made in the Paddle dashboard

You do not have to refund from WooCommerce. An approved refund adjustment that the store did not initiate is treated as a dashboard-initiated refund and synced into WooCommerce as a new refund record, using the amount Paddle reports on the adjustment. Adjustments Paddle rejected, which the store never knew about, are ignored.

This is also the fallback when a refund cannot be sent from WooCommerce: refund in the Paddle dashboard, and it syncs back on its own.

How the refund reaches WooCommerce

Two paths lead back into WooCommerce, and whichever resolves first wins:

  • The adjustment.created and adjustment.updated webhooks — an approved adjustment becomes a WooCommerce refund, a rejected one adds an order note.
  • A scheduled fallback that polls Paddle for the status of each pending adjustment, starting 15 minutes after it was submitted and rescheduling itself while anything is still unresolved. Approvals are therefore picked up even if the adjustment webhooks never arrive.

Both paths share the same code and apply each adjustment at most once, so a redelivered webhook, both adjustment events arriving approved, or an overlapping scheduled run cannot produce a duplicate refund. In short: once you have submitted a refund, reconciliation completes on its own.

Webhook subscriptions created before version 1.1.0 do not include the adjustment events. The plugin adds them to an existing subscription automatically, and Check Webhook does the same on demand.

When a refund cannot be sent

  • Currency mismatch — if the order currency differs from the Paddle transaction currency the amounts cannot be mapped one to one, so the refund is refused. Refund from the Paddle dashboard instead; it syncs back automatically.
  • Amount too large — more than what remains refundable on the transaction items is refused before anything is sent to Paddle.
  • No Paddle transaction — an order with no recorded transaction ID cannot be refunded through the gateway.