These calls need the Wix Stores app on the site (appDefId 215238eb-22a5-4c36-9e7b-e7c08025e04e); a 428, a 400 naming the app, or an empty result on a site that should have content means it is not there. List Installed Apps shows what the site has; Install Wix Apps adds it by that id.
Find products in a Wix store using the Catalog V3 Search Products and Query Products APIs. To change the products you find, continue with Update Product with Options (Catalog V3); to change their stock, with Update Product Stock and Pre-Order (Catalog V3).
Every call in this recipe is complete and was run as written: send it without looking up its schema first. Open a linked method page only for a field the recipe does not show.
Search Products lags behind new products. It reads a search index that can miss products created in the last seconds (and, on a site set up minutes ago, for longer). Query Products reads the catalog itself and returns new products at once. So:
cursorPaging.limit: 100. If pagingMetadata.hasNext is false, that page is the whole catalog: select in code (STEP 5). If hasNext is true, answer with the Search Products filter (STEP 1) instead, and do not page the catalog.productId with the STEP 7 code, which reports untracked variants as in stock, not as 0 units.Use Get Product for one product's variants, and Query Inventory Items for stock quantities.
| Need | Endpoint | Notes |
|---|---|---|
| One product by its exact name | Search Products with filter.name | Exact match, case-insensitive (STEP 1). |
| Products whose name contains a word ("all SA21 items") | Search Products with search.search | Free text over the fields you name (STEP 1). |
| A product by SKU | Search Products with variantsInfo.variants $matchItems | Free text on a SKU is unreliable (STEP 1). |
| Products that have an option choice ("every product with an Orange color") | Search Products with options.choicesSettings.choices.name | Case-insensitive (STEP 1). |
| List all products or page through the catalog | Query Products | Cursor paging only (STEP 5). |
| Products by price — "products under $20", "between $10 and $50" | One Query Products page; Search Products actualPriceRange filter when the catalog has more pages | Rule 1 above (STEP 1, STEP 5). |
| Out-of-stock products | One Query Products page; Search Products inventory.availabilityStatus filter when the catalog has more pages | Rule 1 above (STEP 1, STEP 5). |
Filter by id, slug, handle, dates, or visible | Query Products | STEP 4. |
| One product's variants, prices, SKUs, cost, description or categories | Get Product | Search and Query return no variants (STEP 6). |
| Stock quantity per variant, total stock per product, negative stock | Query Inventory Items | Products carry an availability status, not a quantity (STEP 7). |
The price and stock-status filters below are for catalogs of more than one Query Products page (rule 1 in STEP 0); they share the index lag described there.
Search Products is POST https://www.wixapis.com/stores/v3/products/search. Free text goes in search.search; exact and structured criteria go in search.filter. Send only the part you need.
Exact name ($eq, $in and $startsWith on name ignore case: "test eye serum" finds "Test Eye Serum". With $eq, part of a name finds nothing; $startsWith matches the start of a name):
A word in the name. The default mode is OR: "Blue Shirt" also returns every product with "Blue" or "Shirt" in its name. Send "mode": "AND" so that all words must be present, and still compare the returned names before you act on a product:
A SKU. A free-text search on variantsInfo.variants.sku splits the SKU at - and can return the whole catalog. Match the SKU exactly (case-insensitive):
An option choice name (case-insensitive), such as every product that sells an Orange color:
Stock status: { "search": { "filter": { "inventory.availabilityStatus": { "$in": ["OUT_OF_STOCK", "PARTIALLY_OUT_OF_STOCK"] } } } }. PARTIALLY_OUT_OF_STOCK means some of the product's variants are out of stock; leave it out when the user asks only about products that cannot be bought at all.
Price. actualPriceRange.minValue.amount is the price of the product's cheapest variant, and takes a number. "Products under $20" is this complete request:
Read each product's price from products[].actualPriceRange.minValue.amount (a string, such as "12"). A field takes one operator: for "between $10 and $50" send { "$and": [ { "actualPriceRange.minValue.amount": { "$gte": 10 } }, { "actualPriceRange.minValue.amount": { "$lte": 50 } } ] }; { "$gte": 10, "$lte": 50 } on one field returns 400 Filter must contain single operator. Add "search": { "expression": "Shirt", "fields": ["name"], "mode": "AND" } beside the filter to combine price with a word in the name.
The response puts the matches in products:
Query Products returns the same envelope. Search Products takes up to 100 results per page in search.cursorPaging.limit and pages like Query Products (STEP 5). Search Products drops a deleted product at once, but can miss a product created in the last few seconds, which Query Products already returns. So when a name lookup finds nothing, page Query Products (STEP 5) and match name in code, ignoring case, before you tell the user the product does not exist.
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 (first 100 products, default fields):
This returns products with their default fields, including inventory for product-level availability and variantSummary.variantCount.
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.
fields parameterThe fields array requests additional fields beyond the defaults. It does NOT accept property names like "name" or "id".
⚠️ CRITICAL: Valid fields enum values:
| Enum Value | Description |
|---|---|
URL | Product page URL |
CURRENCY | Currency information |
INFO_SECTION | Info sections (rich content) |
MERCHANT_DATA | Merchant-specific data |
PLAIN_DESCRIPTION | Plain text description |
INFO_SECTION_PLAIN_DESCRIPTION | Info section plain text |
SUBSCRIPTION_PRICES_INFO | Subscription pricing |
BREADCRUMBS_INFO | Category breadcrumbs |
WEIGHT_MEASUREMENT_UNIT_INFO | Weight unit info |
VARIANT_OPTION_CHOICE_NAMES | Variant option choice names |
MEDIA_ITEMS_INFO | Additional media items |
DESCRIPTION | Rich text description |
DIRECT_CATEGORIES_INFO | Direct category info |
ALL_CATEGORIES_INFO | All category info |
MIN_PRICE_VARIANT | Lowest-priced visible variant |
INFO_SECTION_DESCRIPTION | Info section rich content |
THUMBNAIL | Thumbnail image |
DIRECT_CATEGORY_IDS | Direct category IDs |
PRODUCT_CHOICES_MEDIA_REFERENCES | Choice-specific media |
WRONG – these are NOT valid field values:
CORRECT – use enum constants or leave empty for defaults:
CORRECT – requesting additional fields:
QueryProducts supports filters only on these fields. name and price are not among them (a name filter returns 400 Field 'name' is not declared as filterable), so find products by name or price with Search Products (STEP 1) rather than paging the whole catalog and comparing in your own code:
| Field | Supported Filters | Sortable |
|---|---|---|
id | $eq, $ne, $exists, $in, $startsWith | No |
handle | $eq, $ne, $exists, $in, $startsWith | No |
options.id | $isEmpty, $hasAll, $hasSome | No |
slug | $eq, $ne, $exists, $in, $startsWith | Yes |
createdDate | $eq, $ne, $exists, $in, $lt, $lte, $gt, $gte | Yes |
updatedDate | $eq, $ne, $exists, $in, $lt, $lte, $gt, $gte | Yes |
visible | $eq, $ne, $exists, $in | Yes |
Query with filter and sort:
Filter by product IDs:
Query Products and Search Products page with a cursor. Offset paging is silently ignored: "paging": { "limit": 5, "offset": 5 } returns the first page again, so a loop that raises offset never reaches the next products. Page like this:
cursorPaging: { "limit": 100 } (inside query, or inside search for Search Products) and any filter and sort.pagingMetadata.hasNext is true, send the cursor without filter or sort: { "query": { "cursorPaging": { "limit": 100, "cursor": "<pagingMetadata.cursors.next>" } } } for Query Products, { "search": { "cursorPaging": { ... } } } for Search Products. The cursor keeps the first request's filter and sort. Keep a top-level fields array on every page, or the later pages come back without those fields.Each product carries actualPriceRange.minValue.amount (the cheapest variant's price, a string such as "12") and inventory.availabilityStatus (IN_STOCK, OUT_OF_STOCK, PARTIALLY_OUT_OF_STOCK) by default. For a price or stock question, when the first page (limit: 100) has hasNext: false, select in the same execution; when it has hasNext: true, send the Search Products filter from STEP 1 instead of fetching more pages:
PARTIALLY_OUT_OF_STOCK means some of the product's variants are out of stock; leave it out when the user asks only about products that cannot be bought at all.
Search and Query do not return variantsInfo. For variants, prices, SKUs, cost, the description or categories of a product, call Get Product with the id from STEP 1, and add the fields the question needs (repeat fields once per value):
The response is { "product": { ... } }. The fields to read:
| Field | What it holds |
|---|---|
product.variantsInfo.variants[] | id, sku, price.actualPrice.amount, choices[].optionChoiceNames (with VARIANT_OPTION_CHOICE_NAMES), inventoryStatus.inStock |
product.options[].choicesSettings.choices[] | Each choice's name, colorCode, and its photos (request PRODUCT_CHOICES_MEDIA_REFERENCES) |
product.costRange, variants[].revenueDetails.cost | Cost, with MERCHANT_DATA. revenueDetails is absent when no cost was set |
product.plainDescription | Description as HTML, with PLAIN_DESCRIPTION |
product.directCategoriesInfo | Categories, with DIRECT_CATEGORIES_INFO |
inventoryStatus on a variant has inStock and preorderEnabled only, never a quantity. For quantities, use STEP 7.
Stock lives in inventory items, one per variant (and per location when the store has several). Query Inventory Items is POST https://www.wixapis.com/stores/v3/inventory-items/query, up to 1000 items per page:
Each item in inventoryItems[] has id, revision, productId, variantId, trackQuantity, availabilityStatus and product.name, product.variantName, product.variantSku. A tracked item (trackQuantity: true) has quantity; an untracked item has inStock (true or false) and no quantity. Other useful filters: { "quantity": { "$lt": 0 } } for negative stock, { "product.variantSku": "TEE-RED-L" } for one SKU (case-sensitive). product.name matching here is case-sensitive, so find products by name with Search Products first and filter inventory by productId.
Inventory paging returns no hasNext: request the next page while pagingMetadata.cursors.next is present.
To list every product with its variant count and total stock, take the product list from Query Products (STEP 5), with variantSummary.variantCount; not from Search Products, which can miss new products, and not from inventory items, which have no entry for a product created without inventory. Then page Query Inventory Items with no filter and sum per productId:
Take the stock from the inventory items, not from the product's inventory.availabilityStatus: right after a create or a stock change, that product status lags for a few seconds (a new product created in stock reads OUT_OF_STOCK), while its inventory items are already right. Right after a create the inventory query can also return fewer items than variantSummary.variantCount: when it does, wait 3 seconds and query again (up to 3 times) before you sum. Report untracked variants as "in stock, quantity not tracked" (or out of stock, when inStock is false) rather than adding them as 0 units. Only a product that still has no inventory items after those retries was created without inventory; report it from the product's inventory.availabilityStatus, which is OUT_OF_STOCK for such a product.
SCOPE.STORES.PRODUCT_READ_ADMIN permission.id, name, slug, visible, productType, inventory, media, variantSummary, createdDate, updatedDate.query.filter.fields parameter adds fields on top of the defaults — you never need to request id or name explicitly.To find specific products by name, SKU, option choice 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 with cursorPaging; for a price or stock question, select in code when the catalog fits in one page, and use the Search Products filters otherwise. For a product's variants, use GET https://www.wixapis.com/stores/v3/products/{productId}; for stock quantities, POST https://www.wixapis.com/stores/v3/inventory-items/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.
Last updated: 5 November 2026