Skip to content
Documentation

Checkout and order details

What your customer sees when they pay with Paddle, how the plugin brings them back if they don't finish, and what lands on the order afterwards.

Checkout flow

Payment happens in Paddle's hosted checkout, which the plugin opens for the customer once the order exists.

  1. Customer selects Paddle as the payment method and clicks "Place Order".
  2. Order is created immediately with Pending status.
  3. Customer is redirected to the order-received page, where the Paddle checkout opens automatically with pre-filled email and name, and the items to charge — see Order-total pricing for how those are decided.
  4. After successful payment, the transaction ID is sent via AJAX to the server.
  5. The server validates the transaction with the Paddle API — verifies status, custom data, and amount.
  6. If valid, the order status is updated and the page reloads with the order confirmation.

Final order status is driven by Paddle webhooks, which are the authoritative source of truth.

The order-received page is also where a repeat customer lands after paying — see how to add an "Order Again" button to it.

Checkout display: overlay or inline

The Checkout Display setting on the gateway settings screen decides how Paddle's payment form is presented.

  • Overlay (popup) — the default. Paddle's checkout opens in a popup on top of your page. This is the simpler, more thoroughly tested path and the right choice for most stores.
  • Inline (embedded in the page) — Paddle renders the payment form into a container in the page, so the customer never leaves it. Paddle renders the payment form only; your page stays responsible for showing the order summary, and custom checkout templates may need styling work.

Worth knowing before you switch to inline:

  • The container is printed on the order-received page and, on the order-pay page, inside the payment box. The regular checkout page never opens Paddle in place, so no container is printed there.
  • Space for the frame is reserved only when the checkout actually opens, so an empty container never pushes the page around.
  • If the container is missing — a theme overriding the checkout templates, for example — the plugin logs an error to the browser console and falls back to the overlay.
  • Once the embedded form has loaded, the "Pay Now" button is hidden: re-opening the checkout would re-render the frame and wipe whatever the customer had typed. If the form never loads, the button stays visible and opens the overlay instead.

Order-total pricing: what Paddle charges

The Pricing setting on the gateway settings screen decides where the amount Paddle collects comes from. Both modes end in the same hosted checkout; they differ in what is put into it.

  • Catalog price — the default. The checkout opens with the price synced to Paddle for each product, at the quantity ordered. WooCommerce coupons and fees never reach Paddle. Since 1.6.3 a cart carrying a coupon discount or a negative fee hides the gateway at checkout rather than charging the customer the full catalog price; positive fees are simply not charged.
  • Order total — the plugin creates the Paddle transaction on the server from the WooCommerce order's own line items, fees and shipping lines, as non-catalog prices with fixed amounts. WooCommerce does the coupon math; the plugin bills the resulting line totals, net of coupons and excluding WooCommerce tax. Coupons, positive fees, shipping and dynamic or per-customer prices are therefore charged exactly as WooCommerce recorded them, and the checkout shows the real total.

What Order total mode needs from your products

  • Every product on the order must still be synced to Paddle, because each line references its Paddle product for Paddle's own reporting. The synced price is not used — the amount on the order is. A variable product's lines reference the parent product's Paddle product.
  • Fees and shipping are sent as inline products, under the store's default tax category.

Quantities, tax and negative fees

  • Quantity — when a line total divides evenly by its quantity, Paddle shows unit price × quantity. When it does not (a coupon that leaves a total not expressible as whole cents per unit, for example), the line is sent as one unit carrying the whole amount, with "(x3)" appended to its name. The total is right either way; only the per-unit figure in the Paddle dashboard changes.
  • Tax — lines are sent with Paddle's tax_mode: account_setting, the same way synced catalog prices behave. On a tax-exclusive Paddle account tax is added on top of the amount; on a tax-inclusive account it is carved out of it. Line amounts are always sent excluding WooCommerce tax, so a tax-inclusive WooCommerce total differs from the Paddle total by that tax.
  • Negative fees — a negative fee, which is how most third-party discount plugins apply a reduction, blocks the gateway in both modes. Paddle cannot represent a reduction line, so the plugin refuses to prepare the payment and adds an order note rather than charge the wrong amount.

How the transaction is prepared

  • The transaction is created when the order-received or order-pay page renders, before the checkout opens. The overlay is then opened with just the transaction ID.
  • Reloading the page reuses the same transaction: the plugin keeps a fingerprint of the order's lines and currency and only creates a fresh draft when the order has changed — an item edited from the admin screen, say.
  • Every draft issued for the order is accepted by the webhook, so a customer who completes an earlier draft — from a tab left open before the order was edited — is still marked paid. The order gets a note saying which transaction was paid and which one was current.
  • If Paddle's grand total differs from the order total, the webhook still completes the order and adds a warning note with both figures, so the difference is never silent.
  • If the transaction cannot be prepared — a product on the order is not synced, a fee is negative, or the Paddle API returned an error — the order gets a note beginning "Paddle: could not prepare the transaction" with the reason, and the customer sees a notice asking them to contact support instead of a checkout.

Order total is opt-in in 1.7.0 and Catalog price remains the default. See Configuration for the setting itself, and Troubleshooting for the order notes it can leave.

Cart & Checkout Blocks

The gateway is registered with the WooCommerce Cart & Checkout Blocks as well as the classic checkout, so it works either way with no extra configuration.

  • The title, payment method style and logo, description, and place-order button label shown in the block checkout all come from the gateway settings.
  • Availability is decided on the server, so the method disappears from the block checkout when the Paddle API is not configured or a cart item has not been synced to Paddle.
  • Registration is guarded, so a site running a WooCommerce version without Blocks is unaffected.
  • Payment completes on the order-received page exactly as in the classic flow.

Cart recovery

Paddle can send recovery emails to customers with pending payments. The plugin auto-detects recovery links and routes the customer back to their order.

  • URLs with ?_paction=recovery&_ptxn=… are intercepted automatically.
  • Orders are found by stored transaction ID, or by Paddle API lookup using custom_data.order_id as a fallback.
  • Pending orders redirect to the order-pay page; completed orders redirect to order-received.

Paddle details on the order screen

Orders paid with Paddle get a Paddle Transaction Details panel in the side column of the order edit screen, on both the classic and HPOS order screens. It shows:

  • Transaction ID — linked to the transaction in the Paddle dashboard, using the environment the order was processed in, so sandbox orders link to the sandbox dashboard.
  • Status — the Paddle transaction status.
  • Payment method — card brand, last four digits, and expiry, when Paddle reported them.
  • Totals — subtotal, tax, grand total, Paddle fee, and your earnings.
  • Subscription ID and billing period, when the transaction carries them.
  • View invoice (PDF) — opens the Paddle invoice for the transaction.

Paddle's invoice URLs expire after about an hour, so none is stored: the link mints a fresh URL when you click it. It requires the same permissions as the rest of the order screen, and will not open for an order processed in a different Paddle environment than the one currently configured.

Refunds are issued from this same screen — see Refunds.