Skip to content
Documentation

Configuration

Every setting on the Paddle payment method screen, and what each one controls.

Gateway settings

Navigate to WooCommerce → Settings → Payments → Paddle and configure:

  • License — shows whether a license key is saved and active, with a link to WooCommerce → PimiPay License, where the key is entered. Without an active key the plugin keeps working but receives no updates.
  • Environment — Staging (sandbox) or production.
  • Staging / Production API Key — separate Paddle API keys for each environment.
  • Staging / Production Seller ID — your Paddle seller ID for each environment.
  • Checkout Display — whether Paddle's payment form opens as an overlay popup (the default) or is embedded inline in the page. See Checkout for what each mode means in practice.
  • Checkout Theme — Paddle's hosted checkout is white by default, which can look out of place on a dark page. Dark switches Paddle's own checkout theme to match. It changes the Paddle checkout only, not your store around it.
  • Checkout Language — by default Paddle follows the customer's browser language, even if they deliberately switched your store to another language first. "Match the store language" sends Paddle whatever language WordPress is serving the page in, so a WPML or Polylang store gets the right checkout language on every request. If the store's language is not one Paddle supports, it falls back to following the browser.
  • Pricing — what Paddle charges. Catalog price (the default) opens the checkout with the Paddle price synced from each product, so WooCommerce coupons and fees are not charged and a discounted cart makes the gateway unavailable. Order total creates the Paddle transaction from the order's own lines, so coupons, fees, shipping and dynamically priced items are billed exactly as WooCommerce recorded them; each product must be synced to Paddle but its synced price is not used. Tax follows your Paddle account's own tax setting — added on top for a tax-exclusive account, carved out of the amount for a tax-inclusive one — against line amounts that are always sent excluding WooCommerce tax. See Order-total pricing for how the transaction is prepared and which order notes to read on a disputed order.
  • Discount Codes — hide Paddle's own discount-code field at checkout. That field is separate from WooCommerce coupons: a code entered there reduces what Paddle charges without changing the order total in your store. In Order total mode, WooCommerce coupons are billed by Paddle through the order's own lines; in Catalog price mode a discounted cart hides the gateway instead of overcharging the customer. Enable this if all your discounts are WooCommerce coupons; leave it off if you deliberately run discounts from the Paddle dashboard.
  • Physical Products — hide Paddle when the cart contains a shippable item. Paddle is a merchant of record for digital goods and its terms do not cover physical ones. Off by default.
  • Payment method style — how the payment option row looks at checkout: logo only (the default), title only, or logo and title. Whichever you pick, the Title stays the gateway's name on orders, in admin columns, in customer emails and for screen readers.
  • Payment method logo — replace the Paddle wordmark on the checkout row with your own image, picked from the media library — for example the card brands you accept. Leave empty to show the Paddle logo; if the chosen image is ever deleted, the row falls back to the Paddle logo rather than breaking.
  • Webhook Settings — register webhooks to receive real-time payment notifications from Paddle, and check delivery health.
  • Auto-Sync — enable scheduled product sync, set the interval (minimum 5 minutes), and choose the product tag that marks products for syncing (default: paddle).
  • Default Tax Category — the Paddle tax category products are sold under unless one is set on the product itself. See Tax categories — only Standard and SaaS are enabled on a Paddle account by default.
  • API failure alerts — on by default. Paddle API keys expire and cannot be renewed, and a key that stops working takes the gateway off your checkout. With this on, the store emails you seven days before a key expires, as soon as Paddle rejects it, with a reminder every 24 hours while it stays broken, and once more when a new key works.
  • Alert email address — where those alerts go. Leave blank to use the site admin email.
  • Debug log — enable logging to WooCommerce → Status → Logs for troubleshooting.

The API Key and Webhook Secret fields are password inputs, so a saved value is never displayed back to you in the settings form. To change one, type the new value over it.