wc_get_products and product queries

wc_get_products and WC_Product_Query provide a standard way of retrieving products that is safe to use and will not break due to database changes in future WooCommerce versions. Building custom WP_Queries or database queries is likely to break your code in future versions of WooCommerce as data moves towards custom tables for better performance. This is the best-practices way for plugin and theme developers to retrieve multiple products. wc_get_products and WC_Product_Query are similar to WordPress get_posts and WP_Query. Just like those, you pass in an array of arguments defining the criteria for the search.

Basic usage

Examples

Here are a few examples:

// Get downloadable products created in the year 2016.
$products = wc_get_products( array(
    'downloadable' => true,
    'date_created' => '2016-01-01...2016-12-31',
) );

// Get 10 most recent product IDs in date descending order.
$query = new WC_Product_Query( array(
    'limit' => 10,
    'orderby' => 'date',
    'order' => 'DESC',
    'return' => 'ids',
) );
$products = $query->get_products();

// Get products containing a specific SKU.
// Does partial matching, so this will get products with SKUs "PRDCT-1", "PRDCT-2", etc.
$query = new WC_Product_Query();
$query->set( 'sku', 'PRDCT' );
$products = $query->get_products();

Note that wc_get_products() is mostly a shortcut to WC_Product_Query::get_products().

API reference

Method	Description
wc_get_products( $args )	Retrieve products matching query $args.
WC_Product_Query::get_query_vars()	Get an array of all of the current query variables set on the query object.
WC_Product_Query::get( string $key, mixed $default = '' )	Get the value of a query variable or the default if the query variable is not set.
WC_Product_Query::set( string $key, mixed $value )	Set a query variable to a value.
WC_Product_Query::get_products()	Get all products matching the current query variables.

Query parameters/arguments that can be used with these functions are described below.

Query parameters reference

General

Parameter	Description
status	Accepts a string or array of strings: one or more of 'draft', 'pending', 'private', 'publish', or a custom status. See ProductStatus constant class.
type	Accepts a string or array of strings: one or more of 'external', 'grouped', 'simple', 'variable', or a custom type. See ProductType constant class.
include	Accepts an array of integers: only includes products with IDs in the array.
exclude	Accepts an array of integers: excludes products with IDs in the array.
parent	Accepts an integer: post ID of the product parent.
parent_exclude	Accepts an array of integers: excludes products with parent IDs in the array.
order	Accepts a string: 'DESC' or 'ASC'. Use with 'orderby'. Default: 'DESC'.
orderby	Accepts a string: 'none', 'ID', 'name', 'type', 'rand', 'date', 'modified'. Default: 'date'.
return	Return type. Accepts a string: 'ids' or 'objects'. Default: 'objects'.

Examples

// Get draft products.
$products = wc_get_products( array( 'status' => 'draft' ) );

// Using constant class for status.
$products = wc_get_products( array( 'status' => \Automattic\WooCommerce\Enums\ProductStatus::DRAFT ) );

// Get external products.
$products = wc_get_products( array( 'type' => 'external' ) );

// Get external products limited to specific IDs.
$args = array(
    'type' => 'external',
    'include' => array( 134, 200, 210, 340 ),
);
$products = wc_get_products( $args );

// Get products that aren't the current product.
$products = wc_get_products( array( 'exclude' => array( $product->get_id() ) ) );

// Get products with a specific parent.
$products = wc_get_products( array( 'parent' => 20 ) );

// Get most recently modified products.
$args = array(
    'orderby' => 'modified',
    'order' => 'DESC',
);
$products = wc_get_products( $args );

// Get some random products.
$products = wc_get_products( array( 'orderby' => 'rand' ) );

// Return only product IDs.
$products = wc_get_products( array( 'return' => 'ids' ) );

Product archive URL query parameters

The query parameters in this reference are PHP arguments for wc_get_products() and WC_Product_Query. Storefront product archives, including the shop page and product category pages, can also read query parameters from the URL to build the main catalog query. For example, the orderby URL query parameter changes the catalog sort order.

To link visitors to a catalog view that lists products with prices before products without prices, sort the archive by price from high to low:

https://example.com/shop/?orderby=price-desc
https://example.com/product-category/clothing/?orderby=price-desc

The price-desc value maps to the "Price: high to low" catalog sort. Products with no price or a zero price are sorted after products with a higher price. Use orderby=price for the "Price: low to high" catalog sort.

Pagination

Parameter	Description
limit	Accepts an integer: maximum number of results to retrieve or -1 for unlimited. Default: site posts_per_page setting.
page	Accepts an integer: page of results to retrieve. Does nothing if 'offset' is used.
offset	Accepts an integer: amount to offset product results.
paginate	Accepts a boolean: true for pagination, or false for not. Default: false. If enabled, modifies the return results to give an object with fields: products (array of found products), total (number of found products), and max_num_pages (total number of pages).

Examples

// Get latest 3 products.
$products = wc_get_products( array( 'limit' => 3 ) );

// First 3 products.
$args = array(
    'limit' => 3,
    'page'  => 1,
);
$page_1_products = wc_get_products( $args );

// Second 3 products.
$args = array(
    'limit' => 3,
    'page'  => 2,
);
$page_2_products = wc_get_products( $args );

// Get products with extra info about the results.
$results = wc_get_products( array( 'paginate' => true ) );
echo $results->total . " products found\n";
echo 'Page 1 of ' . $results->max_num_pages . "\n";
if ( count( $results->products ) > 0 ) {
    echo 'First product id is: ' . $results->products[0]->get_id() . "\n";
}

// Get second to fifth most-recent products.
$args = array(
    'limit' => 4,
    'offset' => 1,
);
$products = wc_get_products( $args );

Product lookup

Parameter	Description
sku	Accepts a string: product SKU to match on. Does partial matching on the SKU.
name	Accepts a string: the product name (title) to match on. Case sensitivity depends on the collation of the WordPress posts table.
tag	Accepts an array: limit results to products assigned to specific tags by slug.
product_tag_id	Accepts an integer or array of integers: limit results to products assigned to specific tags by ID.
category	Accepts an array: limit results to products assigned to specific categories by slug.
product_category_id	Accepts an integer or array of integers: limit results to products assigned to specific categories by ID.

Examples

// Get products with "PRDCT" in their SKU (e.g. PRDCT-1 and PRDCT-2).
$products = wc_get_products( array( 'sku' => 'PRDCT' ) );

// Get a product named "Test Product".
$products = wc_get_products( array( 'name' => 'Test Product' ) );

// Get products with the "Excellent" or "Modern" tags.
$products = wc_get_products( array( 'tag' => array( 'excellent', 'modern' ) ) );

// Get products by tag IDs.
$products = wc_get_products( array( 'product_tag_id' => array( 17, 23 ) ) );

// Get shirts.
$products = wc_get_products( array( 'category' => array( 'shirts' ) ) );

// Get products by category IDs.
$products = wc_get_products( array( 'product_category_id' => array( 17, 23 ) ) );

Dimensions & pricing

Parameter	Description
weight	Accepts a float: the weight measurement to match on.
length	Accepts a float: the length measurement to match on.
width	Accepts a float: the width measurement to match on.
height	Accepts a float: the height measurement to match on.
price	Accepts a float: the current price to match on.
regular_price	Accepts a float: the regular price to match on.
sale_price	Accepts a float: the sale price to match on.
total_sales	Accepts an integer: gets products with that many sales.

Examples

// Get products 5.5 units wide and 10 units long.
$args = array(
    'width' => 5.5,
    'length' => 10,
);
$products = wc_get_products( $args );

// Get products that currently cost 9.99.
$products = wc_get_products( array( 'price' => 9.99 ) );

// Get products that have never been purchased.
$products = wc_get_products( array( 'total_sales' => 0 ) );

Product settings

Parameter	Description
virtual	Accepts a boolean: limit to virtual products.
downloadable	Accepts a boolean: limit to downloadable products.
featured	Accepts a boolean: limit to featured products.
sold_individually	Accepts a boolean: limit to products sold individually.
manage_stock	Accepts a boolean: limit to products with stock management enabled.
reviews_allowed	Accepts a boolean: limit to products that allow reviews.
backorders	Accepts a string: 'yes', 'no', or 'notify'.
visibility	Accepts a string: 'visible', 'catalog', 'search', or 'hidden'. See CatalogVisibility constant class.
download_limit	Accepts an integer: the download limit or -1 for unlimited.
download_expiry	Accepts an integer: the download expiry (days) or -1 for unlimited.

Examples

// Get downloadable products that don't allow reviews.
$args = array(
    'downloadable' => true,
    'reviews_allowed' => false,
);
$products = wc_get_products( $args );

// Get products that allow backorders.
$products = wc_get_products( array( 'backorders' => 'yes' ) );

// Get products that show in the catalog.
$products = wc_get_products( array( 'visibility' => 'catalog' ) );

// Using constant class for visibility.
$products = wc_get_products( array( 'visibility' => \Automattic\WooCommerce\Enums\CatalogVisibility::CATALOG ) );

// Get products with unlimited downloads.
$products = wc_get_products( array( 'download_limit' => -1 ) );

Stock & inventory

Parameter	Description
stock_quantity	Accepts an integer: the quantity of a product in stock.
stock_status	Accepts a string: 'outofstock', 'instock', or 'onbackorder'. See ProductStockStatus constant class.

Examples

// Get products that only have one left in stock.
$products = wc_get_products( array( 'stock_quantity' => 1 ) );

// Get out of stock products.
$products = wc_get_products( array( 'stock_status' => 'outofstock' ) );

// Using constant class for stock status.
$products = wc_get_products( array( 'stock_status' => \Automattic\WooCommerce\Enums\ProductStockStatus::OUT_OF_STOCK ) );

Tax & shipping

Parameter	Description
tax_status	Accepts a string: 'taxable', 'shipping', or 'none'. See ProductTaxStatus constant class.
tax_class	Accepts a string: a tax class slug.
shipping_class	Accepts a string or array of strings: one or more shipping class slugs.

Examples

// Get taxable products.
$products = wc_get_products( array( 'tax_status' => 'taxable' ) );

// Using constant class for tax status.
$products = wc_get_products( array( 'tax_status' => \Automattic\WooCommerce\Enums\ProductTaxStatus::TAXABLE ) );

// Get products in the "Reduced Rate" tax class.
$products = wc_get_products( array( 'tax_class' => 'reduced-rate' ) );

// Get products in the "Bulky" shipping class.
$products = wc_get_products( array( 'shipping_class' => 'bulky' ) );

Reviews & ratings

Parameter	Description
average_rating	Accepts a float: the average rating.
review_count	Accepts an integer: the number of reviews.

Examples

// Get products with all 5-star ratings.
$products = wc_get_products( array( 'average_rating' => 5.0 ) );

// Get products with 1 review.
$products = wc_get_products( array( 'review_count' => 1 ) );

Date

Date arguments receive values following the standard format described below, allowing for more flexible queries.

Parameter	Description
date_created	Matches product creation date. Accepts a string in standard format.
date_modified	Matches product modification date. Accepts a string in standard format.
date_on_sale_from	Matches sale start date. Accepts a string in standard format.
date_on_sale_to	Matches sale end date. Accepts a string in standard format.

Standard format

• YYYY-MM-DD - Matches on products during that one day in site timezone.
• >YYYY-MM-DD - Matches on products after that one day in site timezone.
• >=YYYY-MM-DD - Matches on products during or after that one day in site timezone.
• <YYYY-MM-DD - Matches on products before that one day in site timezone.
• <=YYYY-MM-DD - Matches on products during or before that one day in site timezone.
• YYYY-MM-DD...YYYY-MM-DD - Matches on products during or in between the days in site timezone.
• TIMESTAMP - Matches on products during that one second in UTC timezone.
• >TIMESTAMP - Matches on products after that one second in UTC timezone.
• >=TIMESTAMP - Matches on products during or after that one second in UTC timezone.
• <TIMESTAMP - Matches on products before that one second in UTC timezone.
• <=TIMESTAMP - Matches on products during or before that one second in UTC timezone.
• TIMESTAMP...TIMESTAMP - Matches on products during or in between the seconds in UTC timezone.

Examples

// Get downloadable products created in the year 2016.
$products = wc_get_products( array(
    'downloadable' => true,
    'date_created' => '2016-01-01...2016-12-31',
) );

Adding support for custom parameters

It is possible to add support for custom parameters in wc_get_products() or WC_Product_Query. To do this you need to filter the generated query.

/**
 * Handle a custom 'customvar' query var to get products with the 'customvar' meta.
 * @param array $query - Args for WP_Query.
 * @param array $query_vars - Query vars from WC_Product_Query.
 * @return array modified $query
 */
function handle_custom_query_var( $query, $query_vars ) {
	if ( ! empty( $query_vars['customvar'] ) ) {
		if ( ! isset( $query['meta_query'] ) ) {
			$query['meta_query'] = array();
		}
		$query['meta_query'][] = array(
			'key'   => 'customvar',
			'value' => sanitize_text_field( $query_vars['customvar'] ),
		);
	}

	return $query;
}
add_filter( 'woocommerce_product_data_store_cpt_get_products_query', 'handle_custom_query_var', 10, 2 );

Usage:

$products = wc_get_products( array( 'customvar' => 'somevalue' ) );