> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # SearchInventoryItems # Package: catalogV3 # Namespace: InventoryService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/inventory-items-v3/search-inventory-items.md ## Permission Scopes: Read inventory in v3 catalog: SCOPE.STORES.INVENTORY_ITEM_READ ## Introduction Retrieves a list of inventory items, given the provided filtering, sorting, and cursor paging. Search Inventory Items runs with these defaults, which you can override: - `createdDate` is sorted in `DESC` order - `cursorPaging.limit` is `100` To learn about working with _Search_ endpoints, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), and [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md). Learn more about the differences between [_Query_ and _Search_](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-search-query-and-list-methods.md) methods. --- ## REST API ### Schema ``` Method: searchInventoryItems Description: Retrieves a list of inventory items, given the provided filtering, sorting, and cursor paging. Search Inventory Items runs with these defaults, which you can override: - `createdDate` is sorted in `DESC` order - `cursorPaging.limit` is `100` To learn about working with _Search_ endpoints, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), and [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md). Learn more about the differences between [_Query_ and _Search_](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-search-query-and-list-methods.md) methods. URL: https://www.wixapis.com/stores/v3/inventory-items/search Method: POST Method parameters: param name: search | type: CursorSearch - name: cursorPaging | type: CursorPaging | description: Cursor paging options. Learn more about [cursor paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md#cursor-paging). - name: limit | type: integer | description: Maximum number of items to return in the results. - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. - name: filter | type: object | description: Filter object. Learn more about [filtering](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md#filters). - name: sort | type: array | description: List of sort objects. Learn more about [sorting](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md#sorting). - name: fieldName | type: string | description: Name of the field to sort by. - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: aggregations | type: array | description: Logical groupings of data into facets, with summaries for each facet. For example, use aggregations to allow site visitors to narrow down their search results by selecting specific categories. - ONE-OF: - name: value | type: ValueAggregation | description: A value aggregation calculates metrics such as count for specific fields within a dataset, providing insights into the overall distribution and key statistics of those values. For example, use a value aggregation to get the number (count) of products for each price listed in the store. - ONE-OF: - name: includeOptions | type: IncludeMissingValuesOptions | description: Options for including missing values in results. - name: addToBucket | type: string | description: Specify a custom name for the bucket containing the missing values. Defaults are `"N/A"` for strings, `0` for integers, and `false` for booleans. - name: sortType | type: SortType | description: Sort type. - enum: - COUNT: Number of matches in the results. - VALUE: Alphabetically by the field value. - name: sortDirection | type: SortDirection | description: Sort direction. - enum: - DESC: Descending order. - ASC: Ascending order. - name: limit | type: integer | description: Number of aggregation results to return. Min: `1` Max: `250` Default: `10` - name: missingValues | type: MissingValues | description: Whether to include or exclude missing values in the aggregation results. Default: `EXCLUDE`. - enum: - EXCLUDE: Exclude missing values from the aggregation results. - INCLUDE: Include missing values in the aggregation results. - name: range | type: RangeAggregation | description: A range aggregation calculates the count of the values from the specified field in the dataset that fall within the range of each bucket you define. For example, use a range aggregation to compare the number of reservations made for parties of 4 or less to the number of reservations made for parties with 5 or more. - name: buckets | type: array | description: List of range buckets, where during aggregation each entity will be placed in the first bucket its value falls into, based on the provided range bounds. - name: from | type: number | description: Inclusive lower bound of the range. Required if `to` is not provided. - name: to | type: number | description: Exclusive upper bound of the range. Required if `from` is not provided. - name: scalar | type: ScalarAggregation | description: A scalar aggregation calculates a single numerical value from a dataset, summarizing the dataset into one key metric: `COUNT_DISTINCT`, `SUM`, `AVG`, `MIN`, or `MAX`. - name: type | type: ScalarType | description: Operator type for the scalar aggregation. - enum: - COUNT_DISTINCT: Total number of distinct values. - MIN: Minimum value. - MAX: Maximum value. - name: dateHistogram | type: DateHistogramAggregation | description: A date histogram calculates the count of time values from the specified field in the dataset that fall within each time interval you define (hour, day, week, etc.) For example, use a date histogram to find how many reservations have been made at a restaurant each week. - name: interval | type: Interval | description: Interval for date histogram aggregation. - enum: - YEAR: Yearly interval - MONTH: Monthly interval - WEEK: Weekly interval - DAY: Daily interval - HOUR: Hourly interval - MINUTE: Minute interval - SECOND: Second interval - name: nested | type: NestedAggregation | description: A nested aggregation is applied within the results of another aggregation. Rather than aggregating directly on the primary dataset, first group data using one aggregation and then apply another aggregation within each group. It allows for more complex analyses where you can summarize data at different levels of detail or hierarchy. For example, to get the number of products that are in stock and out of stock for each price listed, first perform a value aggregation on `discountedPriceNumeric`, and a second value aggregation on `inStock`. - name: nestedAggregations | type: array | description: Flattened list of aggregations, where each next aggregation is nested within previous one. - ONE-OF: - name: value | type: ValueAggregation | description: A value aggregation calculates the distribution of a specific field's values within a dataset, providing insights into the overall distribution and key statistics of those values. For example, use a value aggregation to get the number (count) of orders for each order status. - name: range | type: RangeAggregation | description: A range aggregation calculates the count of the values from the specified field in the dataset that fall within the range of each bucket you define. For example, use a range aggregation to compare the number of reservations made for parties of 4 or less to the number of reservations made for parties with 5 or more. If ranges overlap, a record that fits more than one range will only be counted in the first range that matches the criteria. - name: scalar | type: ScalarAggregation | description: A scalar aggregation calculates a single numerical value from a dataset, summarizing the dataset into one key metric: `COUNT_DISTINCT`, `SUM`, `AVG`, `MIN`, or `MAX`. - name: dateHistogram | type: DateHistogramAggregation | description: A date histogram calculates the count of time values from the specified field in the dataset that fall within each time interval you define (hour, day, week, etc.). For example, use a date histogram to determine how many reservations have been made at a restaurant each week. If ranges overlap, a record that fits more than one range will only be counted in the first range that matches the criteria. - name: name | type: string | description: Unique, caller-defined aggregation name, returned in `aggregations.results`. - name: type | type: NestedAggregationType | description: Type of aggregation to perform. The matching aggregation field must be passed. - enum: - VALUE: Calculates the distribution of a specific field's values within a dataset, providing insights into the overall distribution and key statistics of those values. - RANGE: Calculates the count of the values from the specified field in the dataset that fall within the range of each bucket you define. - SCALAR: Calculates a single numerical value from a dataset, summarizing the dataset into one key metric: `COUNT_DISTINCT`, `SUM`, `AVG`, `MIN`, or `MAX`. - DATE_HISTOGRAM: Calculates the count of time values from the specified field in the dataset that fall within each time interval you define (hour, day, week, etc.). - name: fieldPath | type: string | description: Field to aggregate by. Use dot notation to specify a JSON path. For example, `order.address.streetName`. - name: name | type: string | description: Aggregation name, returned in `aggregations.results.name`. - name: type | type: AggregationType | description: Type of aggregation to perform. Must align with the corresponding aggregation field. - enum: - VALUE: Calculates the distribution of a specific field's values within a dataset, providing insights into the overall distribution and key statistics of those values. - RANGE: Calculates the count of the values from the specified field in the dataset that fall within the range of each bucket you define. - SCALAR: Calculates a single numerical value from a dataset, summarizing the dataset into one key metric: `COUNT_DISTINCT`, `SUM`, `AVG`, `MIN`, or `MAX`. - DATE_HISTOGRAM: Calculates the count of time values from the specified field in the dataset that fall within each time interval you define (hour, day, week, etc.). - NESTED: Flattened list of aggregations, where each aggregation is nested within previous one. - name: fieldPath | type: string | description: Field to aggregate by. Use dot notation to specify a JSON path. For example, `order.address.streetName`. - name: search | type: SearchDetails | description: Free text to match in searchable fields. - name: mode | type: Mode | description: Search mode. Defines the search logic for combining multiple terms in the `expression`. - enum: - OR: At least one of the search terms must be present. - AND: All search terms must be present. - name: expression | type: string | description: Search term or expression. - name: fields | type: array | description: Fields to search in. If the array is empty, all searchable fields are searched. Use dot notation to specify a JSON path. For example, `order.address.streetName`. - name: fuzzy | type: boolean | description: Whether to enable the search function to use an algorithm to automatically find results that are close to the search expression, such as typos and declensions. - name: timeZone | type: string | description: Time zone to adjust date-time-based filters and aggregations, in ISO 8601 (including offsets) or IANA time zone database (including time zone GUIDs) format. Applies to all relevant filters and aggregations, unless overridden by providing timestamps including time zone. For example, "2023-12-20T10:52:34.795Z". Return type: SearchInventoryItemsResponse - name: inventoryItems | type: array | description: List of inventory items. - ONE-OF: - name: inStock | type: boolean | description: Indicates that inventory is tracked by status rather than quantity. When set to `true`, the item is marked as available for sale without tracking exact quantities. When set to `false`, the item is marked as out of stock. This tracking method is useful for made-to-order products or items with unlimited inventory. When using this tracking method, `trackQuantity` is `false` and preorder limits aren't supported. - name: quantity | type: integer | description: Indicates that inventory is tracked by quantity. Set this field to the number of items currently in stock. This tracking method is useful when you need to know exactly how many items are available. When using this tracking method, `trackQuantity` is `true`. Quantity can be negative when inventory is decremented for an order that has already been paid. - name: id | type: string | description: Inventory item GUID. - name: revision | type: string | description: Revision number, which increments by 1 each time the inventory item is updated. To prevent conflicting changes, the current revision must be passed when updating the inventory item. Ignored when creating an inventory item. - name: createdDate | type: string | description: Date and time the inventory item was created. - name: updatedDate | type: string | description: Date and time the inventory item was last updated. - name: variantId | type: string | description: Variant GUID. - name: locationId | type: string | description: Stores location GUID. If not specified when creating an inventory item, the store's default location is used. - name: productId | type: string | description: Product GUID. - name: trackQuantity | type: boolean | description: Whether the quantity is being tracked. - name: availabilityStatus | type: AvailabilityStatus | description: Inventory item availability status. - enum: - OUT_OF_STOCK: Item is out of stock. For tracked inventory, `quantity` is zero or negative and preorder isn't available. - IN_STOCK: Item is in stock and available for purchase. For tracked inventory, see the `quantity` field for the exact amount in stock. - PREORDER: Item is available for preorder only. Stock is zero or negative, but preorder is enabled with remaining capacity. - name: preorderInfo | type: PreorderInfo | description: Item preorder info. Preorder settings are configured per inventory item, so each variant-location combination can have its own preorder configuration. > **Note:** The product entity's `inventory.preorderStatus` and `inventory.preorderAvailability` fields reflect only the default location's preorder state. - name: enabled | type: boolean | description: Whether preorder is enabled for this inventory item. > **Note:** Preorder can't be enabled for digital products or products with subscriptions. Default: `false` - name: message | type: string | description: Message displayed to customers when the item is out of stock and preorder is enabled. - name: limit | type: integer | description: Maximum number of items that can be preordered after stock reaches zero. Supported only for inventory items with `trackQuantity = true`. Default: `100000` - name: counter | type: integer | description: Number of times this item has been preordered. Supported only for inventory items with `trackQuantity = true`. - name: quantity | type: integer | description: Remaining quantity available for preorder. Supported only for items with `trackQuantity` set to `true`. - name: product | type: Product | description: Associated product and variant details. - name: name | type: string | description: Product name. - name: directCategoryIds | type: array | description: List of category GUIDs that this product is included in directly. - name: variantName | type: string | description: Variant name. - name: variantSku | type: string | description: Variant SKU (stock keeping unit). - name: variantVisible | type: boolean | description: Whether the variant is visible in the store. - name: extendedFields | type: ExtendedFields | description: Custom field data for the inventory item object. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata. - name: count | type: integer | description: Number of items returned in current page. - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both. - name: next | type: string | description: Cursor string pointing to the next page in the list of results. - name: prev | type: string | description: Cursor pointing to the previous page in the list of results. - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page. + `true`: Another page of results can be retrieved. + `false`: This is the last page. - name: aggregationData | type: AggregationData | description: Aggregation data. - name: results | type: array | description: List of the aggregated data results. - ONE-OF: - name: values | type: ValueResults | description: Value aggregation results. - name: results | type: array | description: List of value aggregations. - name: value | type: string | description: Value of the field. - name: count | type: integer | description: Number of entities with this value. - name: ranges | type: RangeResults | description: Range aggregation results. - name: results | type: array | description: List of ranges returned in same order as requested. - name: from | type: number | description: Inclusive lower bound of the range. - name: to | type: number | description: Exclusive upper bound of the range. - name: count | type: integer | description: Total number of entities in this range. - name: scalar | type: ScalarResult | description: Scalar aggregation results. - name: type | type: ScalarType | description: Type of scalar aggregation. - enum: - COUNT_DISTINCT: Total number of distinct values. - MIN: Minimum value. - MAX: Maximum value. - name: value | type: number | description: Value of the scalar aggregation. - name: groupedByValue | type: GroupByValueResults | description: Group by value aggregation results. - name: results | type: array | description: List of value aggregations. - name: value | type: string | description: Value of the field. - name: nestedResults | type: NestedAggregationResults | description: Nested aggregations. - ONE-OF: - name: values | type: ValueResults | description: Value aggregation results. - name: ranges | type: RangeResults | description: Range aggregation results. - name: scalar | type: ScalarResult | description: Scalar aggregation results. - name: name | type: string | description: Unique, caller-defined aggregation name, identifiable by the requested aggregation `name`. - name: type | type: AggregationType | description: Aggregation type. - enum: - VALUE: Calculates the distribution of a specific field's values within a dataset, providing insights into the overall distribution and key statistics of those values. - RANGE: Calculates the count of the values from the specified field in the dataset that fall within the range of each bucket you define. - SCALAR: Calculates a single numerical value from a dataset, summarizing the dataset into one key metric: `COUNT_DISTINCT`, `SUM`, `AVG`, `MIN`, or `MAX`. - DATE_HISTOGRAM: Calculates the count of time values from the specified field in the dataset that fall within each time interval you define (hour, day, week, etc.). - NESTED: Flattened list of aggregations, where each aggregation is nested within previous one. - name: fieldPath | type: string | description: Field which the data was aggregated by. - name: dateHistogram | type: DateHistogramResults | description: Date histogram aggregation results. - name: results | type: array | description: List of date histogram aggregations. - name: value | type: string | description: Date in ISO 8601 format. - name: count | type: integer | description: Count of documents in the bucket. - name: nested | type: NestedResults | description: Nested aggregation results. - name: results | type: array | description: List of nested aggregations. - name: results | type: Map | description: List of nested aggregations. - ONE-OF: - name: value | type: ValueResult | description: Value aggregation result. - name: value | type: string | description: Value of the field. - name: count | type: integer | description: Number of entities with this value. - name: range | type: RangeResult | description: Range aggregation result. - name: from | type: number | description: Inclusive lower bound of the range. - name: to | type: number | description: Exclusive upper bound of the range. - name: count | type: integer | description: Total number of entities in this range. - name: scalar | type: ScalarResult | description: Scalar aggregation result. - name: value | type: number | description: Value of the scalar aggregation. - name: dateHistogram | type: ValueResult | description: Date histogram aggregation result. - name: name | type: string | description: Aggregation name, returned in `aggregations.results.name`. - name: type | type: AggregationType | description: Aggregation type. Must align with the corresponding aggregation field. - name: fieldPath | type: string | description: Field to aggregate by. Use dot notation to specify a JSON path. For example, `order.address.streetName`. ``` ### Examples ### Search available items in a specific location ```curl curl -X POST 'https://www.wixapis.com/stores/v3/inventory-items/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "search": { "filter": { "$and": [ { "availabilityStatus": { "$eq": "IN_STOCK" } }, { "locationId": { "$eq": "4c7b5c73-d7b4-4ab3-8dbf-410776df8008" } } ] } } }' ``` ### SearchInventoryItems filter and sort by createdDate ```curl curl -X POST 'https://www.wixapis.com/stores/v3/inventory-items/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "search": { "sort": [ { "fieldName": "createdDate", "order": "DESC" } ], "filter": { "createdDate": { "$gt": "2024-04-24T10:22:53" } }, "cursorPaging": { "limit": 2 } } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.catalogV3.InventoryService.searchInventoryItems(search) Description: Retrieves a list of inventory items, given the provided filtering, sorting, and cursor paging. Search Inventory Items runs with these defaults, which you can override: - `createdDate` is sorted in `DESC` order - `cursorPaging.limit` is `100` To learn about working with _Search_ endpoints, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), and [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md). Learn more about the differences between [_Query_ and _Search_](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-search-query-and-list-methods.md) methods. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: search Method parameters: param name: search | type: CursorSearch | required: true - name: cursorPaging | type: CursorPaging | description: Cursor paging options. Learn more about [cursor paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md#cursor-paging). - name: limit | type: integer | description: Maximum number of items to return in the results. - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. - name: filter | type: object | description: Filter object. Learn more about [filtering](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md#filters). - name: sort | type: array | description: List of sort objects. Learn more about [sorting](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md#sorting). - name: fieldName | type: string | description: Name of the field to sort by. - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: aggregations | type: array | description: Logical groupings of data into facets, with summaries for each facet. For example, use aggregations to allow site visitors to narrow down their search results by selecting specific categories. - ONE-OF: - name: value | type: ValueAggregation | description: A value aggregation calculates metrics such as count for specific fields within a dataset, providing insights into the overall distribution and key statistics of those values. For example, use a value aggregation to get the number (count) of products for each price listed in the store. - ONE-OF: - name: includeOptions | type: IncludeMissingValuesOptions | description: Options for including missing values in results. - name: addToBucket | type: string | description: Specify a custom name for the bucket containing the missing values. Defaults are `"N/A"` for strings, `0` for integers, and `false` for booleans. - name: sortType | type: SortType | description: Sort type. - enum: - COUNT: Number of matches in the results. - VALUE: Alphabetically by the field value. - name: sortDirection | type: SortDirection | description: Sort direction. - enum: - DESC: Descending order. - ASC: Ascending order. - name: limit | type: integer | description: Number of aggregation results to return. Min: `1` Max: `250` Default: `10` - name: missingValues | type: MissingValues | description: Whether to include or exclude missing values in the aggregation results. Default: `EXCLUDE`. - enum: - EXCLUDE: Exclude missing values from the aggregation results. - INCLUDE: Include missing values in the aggregation results. - name: range | type: RangeAggregation | description: A range aggregation calculates the count of the values from the specified field in the dataset that fall within the range of each bucket you define. For example, use a range aggregation to compare the number of reservations made for parties of 4 or less to the number of reservations made for parties with 5 or more. - name: buckets | type: array | description: List of range buckets, where during aggregation each entity will be placed in the first bucket its value falls into, based on the provided range bounds. - name: from | type: number | description: Inclusive lower bound of the range. Required if `to` is not provided. - name: to | type: number | description: Exclusive upper bound of the range. Required if `from` is not provided. - name: scalar | type: ScalarAggregation | description: A scalar aggregation calculates a single numerical value from a dataset, summarizing the dataset into one key metric: `COUNT_DISTINCT`, `SUM`, `AVG`, `MIN`, or `MAX`. - name: type | type: ScalarType | description: Operator type for the scalar aggregation. - enum: - COUNT_DISTINCT: Total number of distinct values. - MIN: Minimum value. - MAX: Maximum value. - name: dateHistogram | type: DateHistogramAggregation | description: A date histogram calculates the count of time values from the specified field in the dataset that fall within each time interval you define (hour, day, week, etc.) For example, use a date histogram to find how many reservations have been made at a restaurant each week. - name: interval | type: Interval | description: Interval for date histogram aggregation. - enum: - YEAR: Yearly interval - MONTH: Monthly interval - WEEK: Weekly interval - DAY: Daily interval - HOUR: Hourly interval - MINUTE: Minute interval - SECOND: Second interval - name: nested | type: NestedAggregation | description: A nested aggregation is applied within the results of another aggregation. Rather than aggregating directly on the primary dataset, first group data using one aggregation and then apply another aggregation within each group. It allows for more complex analyses where you can summarize data at different levels of detail or hierarchy. For example, to get the number of products that are in stock and out of stock for each price listed, first perform a value aggregation on `discountedPriceNumeric`, and a second value aggregation on `inStock`. - name: nestedAggregations | type: array | description: Flattened list of aggregations, where each next aggregation is nested within previous one. - ONE-OF: - name: value | type: ValueAggregation | description: A value aggregation calculates the distribution of a specific field's values within a dataset, providing insights into the overall distribution and key statistics of those values. For example, use a value aggregation to get the number (count) of orders for each order status. - name: range | type: RangeAggregation | description: A range aggregation calculates the count of the values from the specified field in the dataset that fall within the range of each bucket you define. For example, use a range aggregation to compare the number of reservations made for parties of 4 or less to the number of reservations made for parties with 5 or more. If ranges overlap, a record that fits more than one range will only be counted in the first range that matches the criteria. - name: scalar | type: ScalarAggregation | description: A scalar aggregation calculates a single numerical value from a dataset, summarizing the dataset into one key metric: `COUNT_DISTINCT`, `SUM`, `AVG`, `MIN`, or `MAX`. - name: dateHistogram | type: DateHistogramAggregation | description: A date histogram calculates the count of time values from the specified field in the dataset that fall within each time interval you define (hour, day, week, etc.). For example, use a date histogram to determine how many reservations have been made at a restaurant each week. If ranges overlap, a record that fits more than one range will only be counted in the first range that matches the criteria. - name: name | type: string | description: Unique, caller-defined aggregation name, returned in `aggregations.results`. - name: type | type: NestedAggregationType | description: Type of aggregation to perform. The matching aggregation field must be passed. - enum: - VALUE: Calculates the distribution of a specific field's values within a dataset, providing insights into the overall distribution and key statistics of those values. - RANGE: Calculates the count of the values from the specified field in the dataset that fall within the range of each bucket you define. - SCALAR: Calculates a single numerical value from a dataset, summarizing the dataset into one key metric: `COUNT_DISTINCT`, `SUM`, `AVG`, `MIN`, or `MAX`. - DATE_HISTOGRAM: Calculates the count of time values from the specified field in the dataset that fall within each time interval you define (hour, day, week, etc.). - name: fieldPath | type: string | description: Field to aggregate by. Use dot notation to specify a JSON path. For example, `order.address.streetName`. - name: name | type: string | description: Aggregation name, returned in `aggregations.results.name`. - name: type | type: AggregationType | description: Type of aggregation to perform. Must align with the corresponding aggregation field. - enum: - VALUE: Calculates the distribution of a specific field's values within a dataset, providing insights into the overall distribution and key statistics of those values. - RANGE: Calculates the count of the values from the specified field in the dataset that fall within the range of each bucket you define. - SCALAR: Calculates a single numerical value from a dataset, summarizing the dataset into one key metric: `COUNT_DISTINCT`, `SUM`, `AVG`, `MIN`, or `MAX`. - DATE_HISTOGRAM: Calculates the count of time values from the specified field in the dataset that fall within each time interval you define (hour, day, week, etc.). - NESTED: Flattened list of aggregations, where each aggregation is nested within previous one. - name: fieldPath | type: string | description: Field to aggregate by. Use dot notation to specify a JSON path. For example, `order.address.streetName`. - name: search | type: SearchDetails | description: Free text to match in searchable fields. - name: mode | type: Mode | description: Search mode. Defines the search logic for combining multiple terms in the `expression`. - enum: - OR: At least one of the search terms must be present. - AND: All search terms must be present. - name: expression | type: string | description: Search term or expression. - name: fields | type: array | description: Fields to search in. If the array is empty, all searchable fields are searched. Use dot notation to specify a JSON path. For example, `order.address.streetName`. - name: fuzzy | type: boolean | description: Whether to enable the search function to use an algorithm to automatically find results that are close to the search expression, such as typos and declensions. - name: timeZone | type: string | description: Time zone to adjust date-time-based filters and aggregations, in ISO 8601 (including offsets) or IANA time zone database (including time zone GUIDs) format. Applies to all relevant filters and aggregations, unless overridden by providing timestamps including time zone. For example, "2023-12-20T10:52:34.795Z". Return type: PROMISE - name: inventoryItems | type: array | description: List of inventory items. - ONE-OF: - name: inStock | type: boolean | description: Indicates that inventory is tracked by status rather than quantity. When set to `true`, the item is marked as available for sale without tracking exact quantities. When set to `false`, the item is marked as out of stock. This tracking method is useful for made-to-order products or items with unlimited inventory. When using this tracking method, `trackQuantity` is `false` and preorder limits aren't supported. - name: quantity | type: integer | description: Indicates that inventory is tracked by quantity. Set this field to the number of items currently in stock. This tracking method is useful when you need to know exactly how many items are available. When using this tracking method, `trackQuantity` is `true`. Quantity can be negative when inventory is decremented for an order that has already been paid. - name: _id | type: string | description: Inventory item GUID. - name: revision | type: string | description: Revision number, which increments by 1 each time the inventory item is updated. To prevent conflicting changes, the current revision must be passed when updating the inventory item. Ignored when creating an inventory item. - name: _createdDate | type: Date | description: Date and time the inventory item was created. - name: _updatedDate | type: Date | description: Date and time the inventory item was last updated. - name: variantId | type: string | description: Variant GUID. - name: locationId | type: string | description: Stores location GUID. If not specified when creating an inventory item, the store's default location is used. - name: productId | type: string | description: Product GUID. - name: trackQuantity | type: boolean | description: Whether the quantity is being tracked. - name: availabilityStatus | type: AvailabilityStatus | description: Inventory item availability status. - enum: - OUT_OF_STOCK: Item is out of stock. For tracked inventory, `quantity` is zero or negative and preorder isn't available. - IN_STOCK: Item is in stock and available for purchase. For tracked inventory, see the `quantity` field for the exact amount in stock. - PREORDER: Item is available for preorder only. Stock is zero or negative, but preorder is enabled with remaining capacity. - name: preorderInfo | type: PreorderInfo | description: Item preorder info. Preorder settings are configured per inventory item, so each variant-location combination can have its own preorder configuration. > **Note:** The product entity's `inventory.preorderStatus` and `inventory.preorderAvailability` fields reflect only the default location's preorder state. - name: enabled | type: boolean | description: Whether preorder is enabled for this inventory item. > **Note:** Preorder can't be enabled for digital products or products with subscriptions. Default: `false` - name: message | type: string | description: Message displayed to customers when the item is out of stock and preorder is enabled. - name: limit | type: integer | description: Maximum number of items that can be preordered after stock reaches zero. Supported only for inventory items with `trackQuantity = true`. Default: `100000` - name: counter | type: integer | description: Number of times this item has been preordered. Supported only for inventory items with `trackQuantity = true`. - name: quantity | type: integer | description: Remaining quantity available for preorder. Supported only for items with `trackQuantity` set to `true`. - name: product | type: Product | description: Associated product and variant details. - name: name | type: string | description: Product name. - name: directCategoryIds | type: array | description: List of category GUIDs that this product is included in directly. - name: variantName | type: string | description: Variant name. - name: variantSku | type: string | description: Variant SKU (stock keeping unit). - name: variantVisible | type: boolean | description: Whether the variant is visible in the store. - name: extendedFields | type: ExtendedFields | description: Custom field data for the inventory item object. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata. - name: count | type: integer | description: Number of items returned in current page. - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both. - name: next | type: string | description: Cursor string pointing to the next page in the list of results. - name: prev | type: string | description: Cursor pointing to the previous page in the list of results. - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page. + `true`: Another page of results can be retrieved. + `false`: This is the last page. - name: aggregationData | type: AggregationData | description: Aggregation data. - name: results | type: array | description: List of the aggregated data results. - ONE-OF: - name: values | type: ValueResults | description: Value aggregation results. - name: results | type: array | description: List of value aggregations. - name: value | type: string | description: Value of the field. - name: count | type: integer | description: Number of entities with this value. - name: ranges | type: RangeResults | description: Range aggregation results. - name: results | type: array | description: List of ranges returned in same order as requested. - name: from | type: number | description: Inclusive lower bound of the range. - name: to | type: number | description: Exclusive upper bound of the range. - name: count | type: integer | description: Total number of entities in this range. - name: scalar | type: ScalarResult | description: Scalar aggregation results. - name: type | type: ScalarType | description: Type of scalar aggregation. - enum: - COUNT_DISTINCT: Total number of distinct values. - MIN: Minimum value. - MAX: Maximum value. - name: value | type: number | description: Value of the scalar aggregation. - name: groupedByValue | type: GroupByValueResults | description: Group by value aggregation results. - name: results | type: array | description: List of value aggregations. - name: value | type: string | description: Value of the field. - name: nestedResults | type: NestedAggregationResults | description: Nested aggregations. - ONE-OF: - name: values | type: ValueResults | description: Value aggregation results. - name: ranges | type: RangeResults | description: Range aggregation results. - name: scalar | type: ScalarResult | description: Scalar aggregation results. - name: name | type: string | description: Unique, caller-defined aggregation name, identifiable by the requested aggregation `name`. - name: type | type: AggregationType | description: Aggregation type. - enum: - VALUE: Calculates the distribution of a specific field's values within a dataset, providing insights into the overall distribution and key statistics of those values. - RANGE: Calculates the count of the values from the specified field in the dataset that fall within the range of each bucket you define. - SCALAR: Calculates a single numerical value from a dataset, summarizing the dataset into one key metric: `COUNT_DISTINCT`, `SUM`, `AVG`, `MIN`, or `MAX`. - DATE_HISTOGRAM: Calculates the count of time values from the specified field in the dataset that fall within each time interval you define (hour, day, week, etc.). - NESTED: Flattened list of aggregations, where each aggregation is nested within previous one. - name: fieldPath | type: string | description: Field which the data was aggregated by. - name: dateHistogram | type: DateHistogramResults | description: Date histogram aggregation results. - name: results | type: array | description: List of date histogram aggregations. - name: value | type: string | description: Date in ISO 8601 format. - name: count | type: integer | description: Count of documents in the bucket. - name: nested | type: NestedResults | description: Nested aggregation results. - name: results | type: array | description: List of nested aggregations. - name: results | type: Map | description: List of nested aggregations. - ONE-OF: - name: value | type: ValueResult | description: Value aggregation result. - name: value | type: string | description: Value of the field. - name: count | type: integer | description: Number of entities with this value. - name: range | type: RangeResult | description: Range aggregation result. - name: from | type: number | description: Inclusive lower bound of the range. - name: to | type: number | description: Exclusive upper bound of the range. - name: count | type: integer | description: Total number of entities in this range. - name: scalar | type: ScalarResult | description: Scalar aggregation result. - name: value | type: number | description: Value of the scalar aggregation. - name: dateHistogram | type: ValueResult | description: Date histogram aggregation result. - name: name | type: string | description: Aggregation name, returned in `aggregations.results.name`. - name: type | type: AggregationType | description: Aggregation type. Must align with the corresponding aggregation field. - name: fieldPath | type: string | description: Field to aggregate by. Use dot notation to specify a JSON path. For example, `order.address.streetName`. ``` ### Examples ### Search inventory items by location and availability ```javascript import { inventoryItemsV3 } from "@wix/stores"; const options = { search: { filter: { $and: [ { availabilityStatus: { $eq: "IN_STOCK" } }, { locationId: { $eq: "4c7b5c73-d7b4-4ab3-8dbf-410776df8008" } } ] } } }; async function searchInventoryItems() { const response = await inventoryItemsV3.searchInventoryItems(options); } /* Promise resolves to: * { * "inventoryItems": [ * { * "_id": "item-1", * "revision": "1", * "variantId": "variant-1", * "productId": "product-1", * "locationId": "4c7b5c73-d7b4-4ab3-8dbf-410776df8008", * "availabilityStatus": "IN_STOCK", * "quantity": 25 * } * ], * "pagingMetadata": { "count": 1, "cursors": {}, "hasNext": false, "total": 1 } * } */ ``` ### Search inventory items by creation date ```javascript import { inventoryItemsV3 } from "@wix/stores"; const options = { search: { sort: [ { fieldName: "createdDate", order: "DESC" } ], filter: { createdDate: { $gt: "2024-04-24T10:22:53" } }, cursorPaging: { limit: 2 } } }; async function searchInventoryItems() { const response = await inventoryItemsV3.searchInventoryItems(options); } /* Promise resolves to: * { * "inventoryItems": [ * { * "_id": "item-1", * "revision": "1", * "variantId": "variant-1", * "productId": "product-1", * "inStock": true, * "quantity": 50, * "createdDate": "2024-05-01T10:00:00.000Z" * } * ], * "pagingMetadata": { "count": 1, "cursors": {}, "hasNext": false, "total": 1 } * } */ ``` ### searchInventoryItems (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { inventoryItemsV3 } from '@wix/stores'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { inventoryItemsV3 }, // Include the auth strategy and host as relevant }); async function searchInventoryItems(search) { const response = await myWixClient.inventoryItemsV3.searchInventoryItems(search); }; ``` ---