Shop

The Shop REST API endpoint provides products, related terms and additional data for all products or those that match a specified set of search and filter constraints. Additional data includes stats about products on sale, stock status, price range data, ratings, stats on featured products and other relevant data.

GET /wp-json/wps/v1/shop

The endpoint allows to specify the parameters described below.

The taxonomy-data parameter is used to request matching taxonomy terms from the request. If the request does not place any constraints on the desired products, this would include all terms from relevant product taxonomies, including those from product categories, product tags and product attributes.

While a complete data set is likely the most appropriate for many components or for an App that renders a complete shop, this parameter provides the advantage of being able to request only certain taxonomies and their terms, matching all products or those products that match the current constraints of the search and filter request.

By default or when the parameter is set to true, the response will include terms from all eligible product taxonomies.

If it is set to false, no product taxonomy data is included in the response.

One or more data sets for specific taxonomies can be requested by indicating which taxonomies. Sub-parameters can be used to determine how the taxonomy data and its terms are provided. The parameters of the REST API – Terms can thus be used to have the terms sorted etc.

For example, to include relevant product categories sorted by name:

https://example.com/wp-json/wps/v1/shop?taxonomy-data=[{"taxonomy":"product_cat","orderby":"name","order":"asc"}]

Extending on the above, assume a color product attribute of which we also want to retrieve corresponding terms. We again request product categories but will also let categories which have no related products be included. In addition, we want to include the the color terms sorted by the number of related products in descending order:

https://example.com/wp-json/wps/v1/shop?taxonomy-data=[{"taxonomy":"product_cat","orderby":"name","order":"asc","hide_empty":false},{"taxonomy":"pa_color","orderby":"count","order":"desc"}]

The above will include two sets of entries under the "terms" key of the response, one for product categories and another for color attribute terms. For both, it will include which taxonomy the terms are related to, list the terms with their details and provide the count of related terms. Of course, the response to the request will also provide matching products and each of the other sets of data, including sale, stock, price, rating, featured and route data.

In general, the JSON format which takes a taxonomy sub-parameter for each entry is easily understood when we use a prettier representation than that of the URL parameter above:

taxonomy-data=[
    {
        "taxonomy"   : "product_cat",
        "orderby"    : "name",
        "order"      : "asc",
        "hide_empty" : false
    },
    {
        "taxonomy" : "pa_color",
        "orderby"  : "count",
        "order"    : "desc"
    }
]

An alternative but less flexible form that still uses the JSON format provides the taxonomy as a key:

https://example.com/wp-json/wps/v1/shop?taxonomy-data={"product_cat":{"orderby":"name","order":"asc"}}

The array-based simplest form requesting related terms of a particular taxonomy to be included:

https://example.com/wp-json/wps/v1/shop?taxonomy-data[product_cat]

The array-based form indicating sub-parameters:

https://example.com/wp-json/wps/v1/shop?taxonomy-data[product_cat][orderby]=name&taxonomy-data[product_cat][order]=desc

Among the different forms, we recommend to use the more versatile JSON format that provides the taxonomy parameter.

The response to a request to the shop endpoint will contain the data as requested by the parameters. The complete set of data is provided based on the default, specific data sets can be obtained by enabling or disabling the desired aspects using the endpoint’s parameters.

Here is an example response to a request /wp-json/wps/v1/shop based on the defaults. The product data and term data has been omitted for clarity. The data provided for products and for terms is that provided for the corresponding endpoints. See the sections REST API – Products and REST API – Terms for details in their examples.

{
  "products": {
    "products": [
      ... (product data omitted)
    ],
    "total": 53
  },
  "terms": [
    {
      "taxonomy": "product_cat",
      "terms": [
        ... (term data omitted)
      ],
      "total": 14
    },
    {
      "taxonomy": "product_tag",
      "terms": [
        ... (term data omitted)
      ],
      "total": 3
    },
    {
      "taxonomy": "pa_color",
      "terms": [
        ... (term data omitted)
      ],
      "total": 21
    },
    {
      "taxonomy": "pa_size",
      "terms": [
        ... (term data omitted)
      ],
      "total": 24
    }
  ],
  "sale": {
    "onsale": 10,
    "notonsale": 43
  },
  "stock": {
    "instock": 53,
    "outofstock": 1,
    "onbackorder": 1
  },
  "price": {
    "min_price": "26.0000",
    "max_price": "379.0000",
    "total": 53
  },
  "rating": {
    "min_average_rating": 1,
    "max_average_rating": 4.5,
    "ratings": [
      {
        "rounded_average_rating": 1,
        "count": 1
      },
      {
        "rounded_average_rating": 5,
        "count": 2
      },
      {
        "rounded_average_rating": 3,
        "count": 3
      }
    ],
    "total": 4
  },
  "featured": {
    "featured": 5,
    "notfeatured": 48
  },
  "route": {
    "route": "/wps/v1/shop",
    "params": {
      "context": "view",
      "status": "publish",
      "orderby": "menu_order",
      "order": "asc",
      "title": true,
      "excerpt": true,
      "content": true,
      "sku": true,
      "categories": true,
      "tags": true,
      "attributes": true,
      "variations": true,
      "page": 1,
      "per_page": 10,
      "include_variations": false,
      "product-data": true,
      "sale-data": true,
      "stock-data": true,
      "price-data": true,
      "rating-data": true,
      "featured-data": true,
      "route-data": true,
      "limit": null
    },
    "has_filters": false
  }
}