WC_Product_Variation and WC_Product_Variable. Covers parent/child storage, cached variation prices, deferred parent synchronization, WooCommerce 11.0 product instance caching, stock inheritance, frontend variation data, and raw versus display-tax price reads. Use when creating, importing, querying, or debugging stale variation data.\nmetadata:\nwp-skills-author: \"Soczó Kristóf\"\nwp-skills-contact: \"mailto:lonsdale201@hotmail.com\"\nwp-skills-plugin: \"woocommerce\"\nwp-skills-plugin-version-tested: \"11.0.0\"\nwp-skills-php-min: \"7.4\"\nwp-skills-last-updated: \"2026-08-05\"For plugin code that reads, queries, or programmatically writes product variations. The pricing/display side (filter chain, sale-price overrides, frontend \"Variation X is selected\" hooks) is sibling skill wc-variations-pricing-filters — this one stops at the data layer.
\n\n\"A variation is just a product. I'll
\nwp_insert_post( 'product_variation', ... )andupdate_post_metafor price.\"
Variations work that way at the database level, but the data layer caches aggressively at the parent level. A raw post-insert leaves the parent's stored _price values, lookup table row, child-list transient, and wc_var_prices_<id> transient stale — your variation exists but the catalog shows the OLD price range, \"Out of stock\" stays on a re-stocked variable product, and frontend variation data may not see the new child until caches are rebuilt.
Trigger when ANY of the following is true:
\nwp_insert_post, wp_update_post, update_post_meta, or raw $wpdb writes against product_variation post type.WC_Product_Variation, WC_Product_Variable, get_variation_prices, get_available_variations, wc_var_prices_, sync_variation_names, or 'product_variation' post type references.Variable product (parent)\n post_type = 'product'\n class = WC_Product_Variable\n WP post id = 100\n Holds: product attributes (Color: Red, Blue; Size: S, M, L)\n cached min/max prices, derived stock status\n\n └── Variation (child)\n post_type = 'product_variation'\n class = WC_Product_Variation\n post_parent = 100\n WP post id = 101, 102, 103, ...\n Holds: attribute values (attribute_pa_color = red, attribute_pa_size = m)\n own price, own stock, own SKU\nThe parent stores aggregated / derived data; each child variation stores its own concrete values. Almost every \"stale data\" bug comes from writing to a child without telling the parent to re-aggregate.
\nwc_var_prices_<id>WC_Product_Variable::get_variation_prices( $for_display ) (includes/class-wc-product-variable.php:99) returns an array shaped:
array(\n 'price' => array( 101 => '15.00', 102 => '18.00', 103 => '20.00' ), // sorted\n 'regular_price' => array( ... ),\n 'sale_price' => array( ... ),\n)\nThe aggregation is backed by a transient named wc_var_prices_<parent_id> (includes/data-stores/class-wc-product-variable-data-store-cpt.php). The transient stores entries keyed by:
WC_Cache_Helper::get_transient_version( 'product' ) (busted by wc_delete_product_transients())woocommerce_variation_prices_* callbacks — different hashes for \"include tax\" vs \"exclude tax\", different for VAT-exempt vs not, etc.The $for_display parameter matters:
false (default): RAW prices, before any tax adjustment. Use for storage / comparison / programmatic logic.true: prices adapted for the woocommerce_tax_display_shop setting (include / exclude tax). Use ONLY when rendering UI.A common bug: read with $for_display = true then do business logic on the result — the value drifts depending on tax settings. Always read raw for logic, display-mode only at the render edge.
$parent_id = 100; // an existing WC_Product_Variable\n\n$variation = new WC_Product_Variation();\n$variation->set_parent_id( $parent_id );\n\n// Attributes — keys are attribute slugs (taxonomy or custom), values are\n// the chosen term slug. Both must already exist on the parent.\n$variation->set_attributes( array(\n 'pa_color' => 'red',\n 'pa_size' => 'm',\n) );\n\n$variation->set_regular_price( '20.00' );\n$variation->set_price( '20.00' ); // current price (= sale or regular)\n$variation->set_manage_stock( true );\n$variation->set_stock_quantity( 50 );\n$variation->set_stock_status( 'instock' );\n$variation->set_sku( 'TSHIRT-RED-M' );\n\n$variation_id = $variation->save();\nIn WooCommerce 11.0, variation CRUD clears variation and parent transients and WC_Product::save() queues the parent ID through wc_deferred_product_sync(). WC_Post_Data::do_deferred_product_sync() deduplicates and synchronizes parents at shutdown. Normal CRUD therefore needs no manual cache delete or parent sync.
WooCommerce 11.0 enables product_instance_caching for newly installed stores while upgraded stores retain their previous state. Variation and parent CRUD invalidates that request cache; WordPress post/meta API writes also trigger its invalidation hooks, but raw SQL does not. Test both feature states and never depend on repeated wc_get_product() calls returning the identical PHP object.
Direct post/meta/SQL writes bypass that contract and can leave the catalog stale. Avoid them. If the same request must read rebuilt parent aggregates before shutdown, call WC_Product_Variable::sync( $parent_id ) explicitly after the final child write.
// CHILDREN OF A PARENT — use $variable->get_children() (returns IDs)\n$variable = wc_get_product( $parent_id );\nif ( $variable instanceof WC_Product_Variable ) {\n foreach ( $variable->get_children() as $variation_id ) {\n $variation = wc_get_product( $variation_id );\n // $variation is a WC_Product_Variation\n }\n}\n\n// FRONTEND DISPLAY DATA — JSON-shaped for swatch / dropdown UIs\n$available = $variable->get_available_variations(); // array of arrays\n\n// Each entry has: variation_id, attributes, display_price, display_regular_price,\n// is_in_stock, max_qty, min_qty, image, sku, weight_html, dimensions_html, etc.\nget_available_variations() is what the classic variable-product template embeds inline when the variation count is below woocommerce_ajax_variation_threshold (default 30). Above that threshold, WC AJAX resolves one matching variation and calls get_available_variation() for that variation. The default array mode is heavy; if you only need objects, use $variable->get_available_variations( 'objects' ), or use get_children() and read only the properties you need.
WooCommerce 11.0's matching-variation AJAX endpoint refuses to expose a non-published parent unless the current user can edit it. Custom variation lookup routes must preserve the same visibility boundary; never return unpublished/private variation data merely because the caller knows a parent ID and attributes.
\nAuthenticated wc/v3/products and wc/v3/products/<product_id>/variations collection requests now accept image_size=<registered-size>. It affects the generated image URL (and the product image srcset/sizes) but not stored attachment IDs. The default is full; an unregistered size falls back through WordPress image handling to the full image.
Use a registered WordPress size such as woocommerce_thumbnail and keep clients tolerant of a full-size fallback. Do not persist an API presentation choice into product or variation metadata.
| Setting on | \nWhat it does | \n
|---|---|
Parent manage_stock = 'yes', variation manage_stock = 'no' | \nVariation inherits the parent's stock quantity / backorders / stock status. Internally WC_Product_Variation::get_manage_stock() returns 'parent'. | \n
Variation manage_stock = 'yes' | \nPer-variation stock. The variation has its own stock_quantity and is managed by its own ID even if the parent also manages stock. This is the common case for size/color inventory. | \n
Parent manage_stock = 'no', variation manage_stock = 'no' | \nVariation has only stock_status (instock / outofstock / onbackorder) without a quantity counter. | \n
Reading the effective stock status:
\n// Variation's own stock status (already accounts for managed-quantity rollover)\n$variation->get_stock_status(); // 'instock' / 'outofstock' / 'onbackorder'\n\n// Parent's display status — derived from children, set by sync()\n$variable->get_stock_status();\nAfter CRUD stock changes, deferred parent sync recomputes the parent's display status at shutdown. Explicitly sync only when same-request code needs the updated parent immediately.
\nCRUD writes affecting these values queue parent synchronization:
\nThe shutdown queue deduplicates parent IDs, so CRUD-based imports do not need their own per-row sync. If code bypasses CRUD, it owns lookup-table updates, transient invalidation, and parent synchronization.
\nUse these when a plugin needs to observe or extend variation data without taking over pricing filters:
\n| Hook | \nUse | \n
|---|---|
woocommerce_new_product_variation | \nA variation was created through CRUD. Args: variation ID, WC_Product_Variation. | \n
woocommerce_update_product_variation | \nA variation was updated through CRUD. Good for external index refreshes. | \n
woocommerce_new_product_variation_data | \nLast chance to alter the post array before wp_insert_post() creates a variation. | \n
woocommerce_available_variation | \nModify the frontend variation data array returned by get_available_variation(). | \n
woocommerce_hide_invisible_variations | \nDecide whether disabled / empty-price variations are hidden from get_available_variations(). | \n
woocommerce_show_variation_price | \nDecide whether selected variation price HTML is included in the frontend data array. | \n
woocommerce_variable_product_sync_data | \nParent variable product has just re-synced from children. Use for dependent caches. | \n
$variable = wc_get_product( $parent_id );\n\n// \"From €X to €Y\" range string — handles all the formatting + tax display\necho wp_kses_post( $variable->get_price_html() );\n\n// Manually if you need the raw values:\n$prices = $variable->get_variation_prices( true ); // for_display = true for UI\n$min = current( $prices['price'] );\n$max = end( $prices['price'] );\nFor non-display logic (filtering, sorting in custom listings), pass $for_display = false — raw prices, no tax adjustment.
WC_Product_Variation is the right class for programmatic create/update of a single variation. Don't wp_insert_post( 'product_variation', ... ) directly.set_parent_id + set_attributes + save() is the minimum sequence; attributes MUST match the parent's available attribute terms.WC_Product_Variable::sync() only for immediate consistency or after unavoidable raw writes.get_variation_prices( $for_display ) — always be explicit about $for_display. Default is false (raw); pass true only at the render edge.get_children() for cheap iteration, get_available_variations() for full UI-ready data — different costs.manage_stock on the variation, manage_stock = no on the parent).WP_Query / get_posts for hot-path code. Use $variable->get_children() and wc_get_product() per ID — the data store handles visible-child rules and cached child lists.wp_posts / wp_postmeta even with HPOS on (HPOS is order-table only). Variation reads / writes don't change between HPOS and legacy modes.// WRONG — raw post insert leaves parent caches stale\n$variation_id = wp_insert_post( array(\n 'post_type' => 'product_variation',\n 'post_parent' => $parent_id,\n 'post_status' => 'publish',\n) );\nupdate_post_meta( $variation_id, '_price', '20.00' );\n// Catalog shows old price range; frontend variation data may be stale.\n\n// RIGHT\n$variation = new WC_Product_Variation();\n$variation->set_parent_id( $parent_id );\n$variation->set_attributes( array( 'pa_color' => 'red' ) );\n$variation->set_regular_price( '20.00' );\n$variation->set_price( '20.00' );\n$variation->save();\n\n// WRONG — passing $for_display = true and then doing logic on the value\n$prices = $variable->get_variation_prices( true );\nif ( current( $prices['price'] ) < 10 ) { /* ... */ }\n// On a tax-inclusive store, current('price') is post-tax — your < 10 threshold is wrong.\n\n// RIGHT — read raw for logic, display-mode only at the render edge\n$prices = $variable->get_variation_prices( false );\nif ( (float) current( $prices['price'] ) < 10 ) { /* ... */ }\n\n// RIGHT — CRUD queues and deduplicates parent sync at shutdown.\nforeach ( $rows as $row ) {\n $v = new WC_Product_Variation();\n $v->set_parent_id( $row['parent_id'] );\n $v->set_regular_price( $row['price'] );\n $v->save();\n}\nAlso avoid: assuming parent stock applies to variation-managed stock, and querying child variations via WP_Query / get_posts in hot paths instead of $variable->get_children().
wc-variations-pricing-filters for the price filter chain (woocommerce_product_variation_get_price, woocommerce_variation_prices_price, etc.) — when a plugin needs to mutate variation prices via filters rather than direct CRUD.wc-variation-gallery for WooCommerce 10.9+ native variation gallery data (gallery_image_ids, gallery_images_html, REST v3 gallery payloads, and Additional Variation Images migration).wc-product-search-select when the UI needs an admin product picker — woocommerce_json_search_products_and_variations returns variation IDs alongside parent products.wp-plugin-cron for batch imports — cron callbacks scheduled idempotently are the right place for bulk variation operations.wc-variations-pricing-filters.found_variation JS event, AJAX swatch / dropdown logic). That's frontend territory; this skill is data-layer.set_image_id(). Native variation galleries are covered by wc-variation-gallery.WC_Product_Variable::get_variation_prices and the cache: wp-content/plugins/woocommerce/includes/class-wc-product-variable.php:99.WC_Product_Variable::sync() (static): wp-content/plugins/woocommerce/includes/class-wc-product-variable.php.wc_var_prices_, price hash inputs: wp-content/plugins/woocommerce/includes/data-stores/class-wc-product-variable-data-store-cpt.php.WC_Product_Variation: wp-content/plugins/woocommerce/includes/class-wc-product-variation.php.wc_delete_product_transients() for cache invalidation: wp-content/plugins/woocommerce/includes/wc-product-functions.php.wp-content/plugins/woocommerce/includes/data-stores/class-wc-product-variation-data-store-cpt.php