searchVariants( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Search product variants using free-text search with advanced query capabilities.

Use this endpoint for complex queries that include free-text search, aggregations, or when you need faceted search results. For simple filtering, use Query Variants instead.

Supports Wix Query Language (WQL) for structured filtering combined with free-text search.

Note: Non-visible variants, and variants related to non-visible products are filtered from results if you don't have permissions to read hidden products.

Property	Capabilities	Filters
`optionChoices.optionChoiceIds.choiceId`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$hasAll`, `$hasSome`
`optionChoices.optionChoiceIds.optionId`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$hasAll`, `$hasSome`
`barcode`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`
`internalMetadata.rowState`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`
`inventoryStatus.inStock`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`
`inventoryStatus.preorderEnabled`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`
`price.actualPrice.amount`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`
`price.compareAtPrice.amount`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`
`productData.directCategoryIds`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$all`
`productData.name`	Search: ✓ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`
`productData.productId`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`
`productData.productType`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`
`productData.slug`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`
`productData.visible`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`
`productData.visibleInPos`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`
`sku`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`
`visible`	Search: ✗ Aggregate: ✓ Sort: `ASC`, `DESC`	`$eq`, `$ne`, `$exists`, `$in`, `$any`

Authentication

When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user's permissions.
When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.

Permissions

Learn more about app permissions.

Method Declaration

Copy

Method Parameters

searchCursorSearchRequired

WQL expression for searching variants.

optionsSearchVariantsOptions

Returns

Return Type:Promise<SearchVariantsResponse>

Errors

This method doesn't return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?