RECIPE: Business Recipe – Find Products in a Wix Store (Query and Search, Catalog V3)

Find products in a Wix store using the Catalog V3 Search Products and Query Products APIs.

Article: How to Find Products

STEP 0: Choose the right product lookup method

Use Search Products for text search and name-based lookup. Use Query Products for structured filtering, sorting, paging, and listing products.

STEP 1: Search products by name, free text, or price

Use Search Products when the user gives a product name, keyword, or other text expression, and for price criteria, which Query Products cannot filter on. Free text goes in search.search; price and other structured criteria go in search.filter. Send only the part you need:

The response puts the matches in products:

Query Products returns the same envelope.

For exact name matching, search with the user-provided text and then compare the returned product.name values in your own code.

STEP 2: Query products with structured filters, sorting, or paging

Use the POST Query Products endpoint to query products. The endpoint returns up to 100 products per request.

Endpoint: POST https://www.wixapis.com/stores/v3/products/query

Basic query (all products, default fields):

This returns all products with their default fields, including inventory for product-level availability.

Take availability from inventory, and look up any other field you need in the Catalog V3 docs rather than carrying a name over from Catalog V1 — the two catalogs do not share a product shape. A name that isn't on the V3 product reads as undefined rather than raising, so the request still succeeds and a check against it quietly matches nothing: an availability question answered that way returns an empty list, which reads as "everything is in stock" instead of as a failure.

STEP 3: Understanding the fields parameter

The fields array requests additional fields beyond the defaults. It does NOT accept property names like "name" or "id".

⚠️ CRITICAL: Valid fields enum values:

WRONG – these are NOT valid field values:

CORRECT – use enum constants or leave empty for defaults:

CORRECT – requesting additional fields:

STEP 4: Filtering and sorting with Query Products

QueryProducts supports filters only on these fields. Price is not among them, so answer a price question with Search Products rather than paging the whole catalog and comparing amounts in your own code:

Query with filter and sort:

Filter by product IDs:

STEP 5: Handling pagination

When there are more products than the page limit, use cursor-based or offset-based paging:

Check the response pagingMetadata to determine if more pages exist.

Important Notes

• Variant data is NOT returned by Query Products. To get variant details, use Get Product for individual products.
• Non-visible products require the SCOPE.STORES.PRODUCT_READ_ADMIN permission.
• Default fields include: id, name, slug, visible, productType, inventory, media, createdDate, updatedDate.
• Availability is not in STEP 4's filterable set. To list out-of-stock products, query the catalog — paging until pagingMetadata reports no more results — and select on each returned product's inventory availability status in your own code, rather than putting it in query.filter.
• The fields parameter adds fields on top of the defaults — you never need to request id or name explicitly.

Conclusion

To find products by name or free text, use POST https://www.wixapis.com/stores/v3/products/search. To list, page, sort, or structurally filter products, use POST https://www.wixapis.com/stores/v3/products/query. Use fields: [] for defaults, or pass valid enum values like DESCRIPTION, URL, ALL_CATEGORIES_INFO for additional data. Never pass property names as field values.