Skip to content
Documentation

Product sync

Keep WooCommerce products and Paddle Billing in step — all at once, automatically as you publish, one at a time, or on a schedule.

Sync all products

Paddle is only offered at checkout when every product in the cart is in Paddle, and on a new install none is. Once the gateway is enabled and its API key works, a notice on the Paddle settings and the Products list says how many products are not in Paddle yet, with a Sync all products button.

  • The Products in Paddle row on the Paddle settings shows "Products in Paddle: 12 of 37" and a Sync 25 products to Paddle button.
  • It asks before it starts, because products created in Paddle can be archived but not deleted.
  • The sync runs in the background, so you can leave the page. While it runs you see "Syncing… 10 of 25" and a Stop button.
  • Afterwards it says how many were synced, how many could not be, and the first reason. Each product's Paddle tab shows its own reason.
  • Counted: published simple and variable products with no Paddle product for the active environment. With Physical Products on, products that are not Virtual are left out. With Subscriptions off, recurring products are left out.
  • You can dismiss the notice, for example if you sell only part of your catalogue through Paddle. It goes away on its own once every product is in Paddle.

Sync new products automatically

With Sync new products automatically on, a product is sent to Paddle in the background when it is published, or when you update it on its edit screen or with Quick Edit while it is published and not in Paddle yet. Saving never waits for Paddle; the product is usually in Paddle about 40 seconds later.

  • On for new installs. Stores updated from 2.1.3 or earlier have it off until it is switched on; while it is off, the Sync all notice links to it.
  • Switching it on does not send the products you already have until you publish them or update them on their edit screen or with Quick Edit. Use Sync all products for all of them.
  • No other save sends a product: stock changes after an order never do, and Bulk Edit, imports and API updates of existing products do only when they publish the product.
  • It covers the same products as Sync all. A product with no price is not sent; its Paddle tab says why. A product that already has a Paddle product ID is not sent again.
  • WooCommerce's new product editor (an opt-in feature) does not send an existing product on Update. Publishing still does; for an existing product, use Sync with Paddle or the classic edit screen.
  • Paddle products can be archived but not deleted: leave this off if you sell only some products through Paddle, or keep some out with the filter below.

To keep some products out, add this to your theme's functions.php or a small plugin:

add_filter( 'pimipay_paddle_sync_new_product', function ( $sync, $product ) {
    return ! has_term( 'not-on-paddle', 'product_cat', $product->get_id() );
}, 10, 2 );

See which products are in Paddle

Products → All Products has a Paddle column for the active environment (staging or production):

  • ✓ In Paddle: Paddle is offered at checkout for it.
  • 2 of 3: a variable product where only some of the variations customers can buy are in Paddle (Catalog price mode).
  • — Not in Paddle: a cart holding it does not offer Paddle at checkout.
  • ⚠ Sync failed: not in Paddle, and its last sync failed. Hover for the reason.
  • Blank: nothing to do for it, such as a grouped or external product, or a draft with no Paddle IDs.

The column uses checkout's own rule and never contacts Paddle. Hide it under Screen Options if you do not need it.

The Paddle dropdown above the list narrows it to:

  • In Paddle: products with a Paddle product for the active environment.
  • Not in Paddle: the same products Sync all counts as not in Paddle yet.
  • Sync failed: products whose last sync failed. The reason is on the product's Paddle tab.

Pick Not in Paddle or Sync failed, select the products, and use the Sync with Paddle bulk action.

How product sync works

Sync your WooCommerce products to Paddle Billing so prices and products stay consistent across both platforms.

  • Simple products — 1 Paddle product + 1 Paddle price.
  • Variable products — 1 Paddle product + 1 price per variation.
  • Each variation is mapped to its own Paddle price, so customers can buy any variation.
  • Paddle IDs (_paddle_{environment}_product_id, _paddle_{environment}_price_id) are stored as product meta, kept separate per environment (production / staging).

With the Pricing setting on Order total, a product must still be synced so its order lines can reference its Paddle product, but the synced Paddle price is not what is charged — the amount on the WooCommerce order is. See Order-total pricing.

Recurring prices. With Subscriptions on, a simple virtual product whose Billing is Recurring syncs a Paddle price with a billing cycle. Paddle cannot change a price's type or cycle, so switching a product between one-time and recurring, or changing its cycle, archives the old price and creates a new one; existing subscriptions keep renewing on the old price.

To sync a product:

  1. Go to Products in WordPress Admin.
  2. Hover over a product row.
  3. Click "Sync with Paddle".

Syncing many products at once

To sync more than one product, select them on the Products screen, choose "Sync with Paddle" from the Bulk actions dropdown, and click Apply.

A bulk sync runs inside the normal admin request, so it is bounded by time rather than by a fixed number of products. Every product costs at least two Paddle API calls, and a variable product costs one more for each of its variations — so a hundred simple products and a hundred variable ones are very different amounts of work.

If a selection is large enough to run out of time, the sync stops early and tells you how many products were not synced. Those products are left exactly as they were, so you can select the rest and run it again as many times as you need. A partial run is always reported — it will never quietly look like it finished.

Tax categories

Paddle uses a product's tax category to decide how each sale is taxed in every jurisdiction. Because Paddle is the merchant of record, that decision is made on your behalf — so the category needs to match what you actually sell.

Set it per product on the Paddle tab in Product data, or set a store-wide default under WooCommerce → Settings → Payments → Paddle. A product left on "Use the store default" follows that default if you later change it.

Only Standard and SaaS are enabled on a Paddle account by default. The other seven — digital goods, ebooks, website hosting, implementation services, professional services, software programming services and training services — must be requested in the Paddle dashboard first. Syncing a product under a category your account is not approved for fails, and the plugin will tell you so in the sync notice and on the product's Paddle tab.

The default is Standard, which means pre-written software downloaded and installed on a local device. If that does not describe what you sell, change it.

Duplicated products

When you duplicate a product, the copy is deliberately created unsynced — it does not inherit the original's Paddle product or price IDs, and neither do its variations. Its first sync creates its own Paddle product and price.

This matters because two WooCommerce products pointing at one Paddle price both charge that price at checkout regardless of what WooCommerce shows, and syncing either one rewrites the price the other sells at. The problem is invisible for as long as the two products happen to cost the same — which is exactly the situation immediately after duplicating.

If two products already share Paddle IDs, for example from a duplicate made before version 1.2.0, the plugin limits the damage:

  • Sync is refused. A product that carries another product's Paddle product ID is not synced. The check runs before anything is sent to Paddle, and the message names the product that owns the ID: "Each WooCommerce product needs its own Paddle product, so nothing was synced."
  • Price changes are held back. When you change a WooCommerce price, it is not sent automatically to a Paddle price that another product also uses. The product's Paddle tab says why.
  • A warning lists them. On the Products list, the product editor and the Paddle settings, a notice names the products that share a Paddle price.

To fix it, decide which product owns the Paddle product and price, then open each of the others, clear the Paddle Product ID and Price ID on its Paddle tab, and sync it. It gets its own Paddle product and price.

Auto sync

Products tagged with a configurable tag (default: paddle) can be synced automatically on a schedule via WordPress cron.

  1. Go to WooCommerce → Settings → Payments → Paddle.
  2. Set Product Tag for Auto-Sync.
  3. Enable Enable Auto Sync.
  4. Set Auto Sync Interval in minutes (minimum 5, default 60).
  5. Save settings.

The tag only decides which products the scheduled sync covers.

To trigger a sync run immediately from the command line:

wp cron event run paddle_auto_sync_products

Price changes

When a product's WooCommerce price changes, the new price is sent to Paddle in the background shortly after you save, for every product or variation already in Paddle, tagged or not.

  • A product put in Paddle by version 2.1.3 or earlier starts sending its price changes after its next save. An untagged one does not send its price on that save; to send it now, use Sync with Paddle on the product.
  • A price change replaces the Paddle price's amount and details, including a price you linked by pasting a Paddle price ID on the Paddle tab.
  • A price change is not sent when another product holds the same Paddle price, because it would change what that product charges. The product's Paddle tab says so.

To send price changes only for tagged products, as before 2.2.0, use the pimipay_paddle_sync_price_on_change filter (replace paddle with your tag). Sync with Paddle still sends the price.

add_filter( 'pimipay_paddle_sync_price_on_change', function ( $sync, $product ) {
    $id = $product->get_parent_id() ? $product->get_parent_id() : $product->get_id();
    return has_term( 'paddle', 'product_tag', $id );
}, 10, 2 );