Transfer product add-ons with WooCommerce CSV

Use WooCommerce's product CSV tools to back up or move the Product Add-Ons configuration owned by individual products. This workflow supports simple products, variable products, and variation rows. It does not repeat groups that apply globally through all-product, category, or direct-product assignments.

Prerequisites

  • Enable Product Add-Ons under Settings → POM Tweaks → E-Commerce → Products.
  • Use an account that can export and edit WooCommerce products.
  • When moving products between sites, create or import any global groups that the products explicitly exclude before importing the product CSV.
  • Keep the generated JSON cells intact. Edit Product Add-Ons through the POM interface and create a new export instead of hand-editing nested definitions.

Export products

  1. Go to Products → All Products.
  2. Select Export.
  3. Include these columns:
    • POM Add-Ons: Local definition (JSON)
    • POM Add-Ons: Exclude global groups (JSON)
    • POM Add-Ons: Excluded groups (JSON)
  4. Choose the required product types or products and select Generate CSV.
  5. Store the CSV securely with the rest of the product export.

Each populated POM cell is a JSON object with schema_version: 1, a column-specific type, a configuration mode, and the product's inheritance or override state. The local-definition cell contains the self-contained POM JSON package, including referenced reusable choices and supported option images. It contains UUIDs rather than source product, choice, group, or attachment IDs. It does not contain upload filesystem paths.

The excluded-groups cell contains only exact group UUIDs. A source group that cannot be represented safely is reported inside the cell as an unresolved reference; importing that row is then blocked instead of silently dropping the exclusion.

Import products

  1. Go to Products → All Products and select Import.
  2. Upload the CSV and choose whether existing products should be updated.
  3. On Column mapping, confirm that the three POM column names map to their matching POM fields.
  4. Run the import.
  5. Review the WooCommerce import report. A malformed or unresolved POM value is reported against its product row.
  6. Edit an imported product and open Product data → Add-Ons to verify its local fields and exclusions.

For reusable choices, import uses exact UUID identity. An existing destination choice with the same UUID is linked without overwriting its destination content. An absent choice is created from the embedded record while retaining its UUID and enabled or disabled status. Labels are never used for linking. Duplicate UUIDs, missing non-embedded choices, future schemas, invalid JSON, and unavailable excluded groups stop that row.

All POM writes for one successful row are applied together. If reusable choices, images, the local definition, or exclusions cannot be completed, POM rolls them back and leaves the previous POM product metadata intact. WooCommerce reports the row error. Only the imported product's resolved-model cache generation changes; product CSV imports do not rebuild the global assignment index.

Simple products, variable products, and variations

WooCommerce exports a variable parent and its variation rows according to the selection used in the native exporter. POM writes only the configuration stored directly on each exported row:

  • A variable parent's local fields remain the parent layer used by its variations.
  • A variation row can carry its own local fields and exclusions as the later variation layer.
  • Effective global groups are not copied into either row.
  • Polylang inheritance or an explicit translation override is preserved when the destination row belongs to the corresponding translated product structure.

Always include and inspect variation rows when the source catalog stores variation-specific Product Add-Ons configuration.

Convert an official Product Add-Ons column

An official WooCommerce Product Add-Ons export commonly exposes its product fields as Meta: _product_addons. POM detects that source through an explicit mapping choice; it never starts a site-wide migration during product import.

  1. On the WooCommerce Column mapping screen, locate Meta: _product_addons.
  2. Change its destination from generic metadata to POM Add-Ons: Convert official _product_addons.
  3. Import the CSV and review row errors.

The selected row is converted through the same POM field validator used by administration and migration. Official attachment IDs are removed because they are not portable between sites. The conversion does not create reusable choices by matching labels, does not write _product_addons, and does not alter global official groups. Leave the column mapped as generic metadata when you need to preserve the official value without converting it.

Verify the result

  1. Open one imported simple product and confirm its fields, prices, exclusions, and reusable choices.
  2. Open one imported variable product and at least one variation that had its own configuration.
  3. View both products on the storefront and submit a valid selection.
  4. On a cross-site import, confirm excluded groups resolve to destination groups with the same UUID.
  5. Confirm the import report rejects a test row with invalid JSON or an unavailable UUID without changing that product's previous POM configuration.

Troubleshooting and recovery

  • Excluded group UUID is missing: import or create the matching group first, then run the product row again. POM does not guess by group name.
  • Reusable choice UUID is duplicated: resolve the duplicate records on the destination site before retrying. One UUID must identify one reusable choice.
  • Cell reports an export error: correct the unavailable choice, group reference, image, or size problem on the source product and export again.
  • Package exceeds the limit: reduce embedded image sizes or split the product transfer. Each JSON cell is limited to 1 MiB.
  • You need to undo a successful import: import the earlier product CSV backup or restore the fields and exclusions in Product data → Add-Ons. Remove newly created reusable choices only after their Usage count is zero.

Related guidance: Create groups, reusable choices, and standalone JSON transfers and Migrate an existing official catalog.

Show active plugins first
Previous
Use conditional logic for Product Add-On fields
Next