Skip to main content
Skip to main content
You're viewing the documentation for v1, which isn't the latest Medusa version.Latest documentation

ProductVariantService

constructor​

Parameters​

__namedParametersobjectRequired
__namedParameters.productVariantRepositoryanyRequired
__namedParameters.productRepositoryanyRequired
__namedParameters.eventBusServiceanyRequired
__namedParameters.regionServiceanyRequired
__namedParameters.moneyAmountRepositoryanyRequired
__namedParameters.productOptionValueRepositoryanyRequired
__namedParameters.cartRepositoryanyRequired
__namedParameters.priceSelectionStrategyanyRequired

Properties​

manager_EntityManagerRequired
transactionManager_undefined | EntityManagerRequired
__container__anyRequired
EventsobjectRequired
Events.UPDATEDstringRequired

Default: "product-variant.updated"

Events.CREATEDstringRequired

Default: "product-variant.created"

Events.DELETEDstringRequired

Default: "product-variant.deleted"

productVariantRepository_Repository<ProductVariant>Required
productRepository_Repository<Product> & objectRequired
eventBus_EventBusServiceRequired
regionService_RegionServiceRequired
priceSelectionStrategy_IPriceSelectionStrategyRequired
moneyAmountRepository_Repository<MoneyAmount> & objectRequired
productOptionValueRepository_Repository<ProductOptionValue>Required
cartRepository_Repository<Cart> & objectRequired
__configModule__Record<string, unknown>
__moduleDeclaration__Record<string, unknown>

Accessors​

activeManager_​

Returns​

EntityManagerEntityManagerRequired

Methods​

withTransaction​

Parameters​

transactionManagerEntityManager

Returns​

thisthisRequired

shouldRetryTransaction_​

Parameters​

errRecord<string, unknown> | objectRequired

Returns​

booleanbooleanRequired

atomicPhase_​

Wraps some work within a transactional block. If the service already has a transaction manager attached this will be reused, otherwise a new transaction manager is created.

Type Parameters​

TResultobjectRequired
TErrorobjectRequired

Parameters​

work(transactionManager: EntityManager) => Promise<TResult>Required
the transactional work to be done
isolationOrErrorHandlerIsolationLevel | (error: TError) => Promise<void | TResult>
the isolation level to be used for the work.
maybeErrorHandlerOrDontFail(error: TError) => Promise<void | TResult>
Potential error handler

Returns​

PromisePromise<TResult>Required
the result of the transactional work

retrieve​

Gets a product variant by id.

Parameters​

variantIdstringRequired
the id of the product to get.
configFindConfig<ProductVariant> & PriceSelectionContextRequired
query config object for variant retrieval.

Returns​

PromisePromise<ProductVariant>Required
the product document.

retrieveBySKU​

Gets a product variant by id.

Parameters​

skustringRequired
The unique stock keeping unit used to identify the product variant.
configFindConfig<ProductVariant> & PriceSelectionContextRequired
query config object for variant retrieval.

Returns​

PromisePromise<ProductVariant>Required
the product document.

create​

Creates an unpublished product variant. Will validate against parent product to ensure that the variant can in fact be created.

Type Parameters​

TVariantsCreateProductVariantInput | CreateProductVariantInput[]Required
TOutputobjectRequired

Parameters​

productOrProductIdstring | ProductRequired
the product the variant will be added to
variantsCreateProductVariantInput | CreateProductVariantInput[]Required

Returns​

PromisePromise<TOutput>Required
resolves to the creation result.

update​

**update**(variantData): Promise&#60;[ProductVariant](../../entities/classes/entities.ProductVariant.mdx)[]&#62;

Updates a collection of variant.

Parameters​

variantDataobject[]Required
a collection of variant and the data to update.

Returns​

PromisePromise<ProductVariant[]>Required
resolves to the update result.

**update**(variantOrVariantId, update): Promise&#60;[ProductVariant](../../entities/classes/entities.ProductVariant.mdx)&#62;

Updates a variant. Price updates should use dedicated methods. The function will throw, if price updates are attempted.

Parameters​

variantOrVariantIdstring | Partial<ProductVariant>Required
variant or id of a variant.
updateUpdateProductVariantInputRequired
an object with the update values.

Returns​

PromisePromise<ProductVariant>Required
resolves to the update result.

**update**(variantOrVariantId, update): Promise&#60;[ProductVariant](../../entities/classes/entities.ProductVariant.mdx)&#62;

Parameters​

variantOrVariantIdstring | Partial<ProductVariant>Required
updateUpdateProductVariantInputRequired

Returns​

PromisePromise<ProductVariant>Required

updateBatch​

Parameters​

variantDataUpdateProductVariantData[]Required

Returns​

PromisePromise<ProductVariant[]>Required

updateVariantPrices​

**updateVariantPrices**(data): Promise&#60;void&#62;

Updates variant/prices collection. Deletes any prices that are not in the update object, and is not associated with a price list.

Parameters​

dataUpdateVariantPricesData[]Required

Returns​

PromisePromise<void>Required
empty promise

**updateVariantPrices**(variantId, prices): Promise&#60;void&#62;

Updates a variant's prices. Deletes any prices that are not in the update object, and is not associated with a price list.

Parameters​

variantIdstringRequired
the id of variant
pricesProductVariantPrice[]Required
the update prices

Returns​

PromisePromise<void>Required
empty promise

updateVariantPricesBatch​

Parameters​

dataUpdateVariantPricesData[]Required

Returns​

PromisePromise<void>Required

upsertRegionPrices​

Parameters​

dataUpdateVariantRegionPriceData[]Required

Returns​

PromisePromise<void>Required

upsertCurrencyPrices​

Parameters​

dataobject[]Required

Returns​

PromisePromise<void>Required

getRegionPrice​

Gets the price specific to a region. If no region specific money amount exists the function will try to use a currency price. If no default currency price exists the function will throw an error.

Parameters​

variantIdstringRequired
the id of the variant to get price from
contextGetRegionPriceContextRequired
context for getting region price

Returns​

PromisePromise<null | number>Required
the price specific to the region

setRegionPrice​

Parameters​

variantIdstringRequired
the id of the variant to update
priceProductVariantPriceRequired
the price for the variant.

Returns​

PromisePromise<MoneyAmount>Required
the result of the update operation

Deprecated​

use addOrUpdateRegionPrices instead Sets the default price of a specific region

setCurrencyPrice​

Parameters​

variantIdstringRequired
the id of the variant to set prices for
priceProductVariantPriceRequired
the price for the variant

Returns​

PromisePromise<MoneyAmount>Required
the result of the update operation

Deprecated​

use addOrUpdateCurrencyPrices instead Sets the default price for the given currency.

updateOptionValue​

Updates variant's option value. Option value must be of type string or number.

Parameters​

variantIdstringRequired
the variant to decorate.
optionIdstringRequired
the option from product.
optionValuestringRequired
option value to add.

Returns​

PromisePromise<ProductOptionValue>Required
the result of the update operation.

addOptionValue​

Adds option value to a variant. Fails when product with variant does not exist or if that product does not have an option with the given option id. Fails if given variant is not found. Option value must be of type string or number.

Parameters​

variantIdstringRequired
the variant to decorate.
optionIdstringRequired
the option from product.
optionValuestringRequired
option value to add.

Returns​

PromisePromise<ProductOptionValue>Required
the result of the update operation.

deleteOptionValue​

Deletes option value from given variant. Will never fail due to delete being idempotent.

Parameters​

variantIdstringRequired
the variant to decorate.
optionIdstringRequired
the option from product.

Returns​

PromisePromise<void>Required
empty promise

listAndCount​

Parameters​

selectorFilterableProductVariantPropsRequired
the query object for find
configFindConfig<ProductVariant> & PriceSelectionContextRequired
query config object for variant retrieval

Returns​

PromisePromise<[ProductVariant[], number]>Required
the result of the find operation

list​

Parameters​

selectorFilterableProductVariantPropsRequired
the query object for find
configFindConfig<ProductVariant> & PriceSelectionContextRequired
query config object for variant retrieval

Returns​

PromisePromise<ProductVariant[]>Required
the result of the find operation

delete​

Deletes variant or variants. Will never fail due to delete being idempotent.

Parameters​

variantIdsstring | string[]Required
the id of the variant to delete. Must be castable as an ObjectId

Returns​

PromisePromise<void>Required
empty promise

isVariantInSalesChannels​

Check if the variant is assigned to at least one of the provided sales channels.

Parameters​

idstringRequired
product variant id
salesChannelIdsstring[]Required
an array of sales channel ids

Returns​

PromisePromise<boolean>Required
Check if the variant is assigned to at least one of the provided sales channels.

getFreeTextQueryBuilder_​

Lists variants based on the provided parameters and includes the count of variants that match the query.

Parameters​

variantRepoRepository<ProductVariant>Required
the variant repository
queryFindWithRelationsOptionsRequired
object that defines the scope for what should be returned
qstring
free text query

Returns​

SelectQueryBuilderSelectQueryBuilder<ProductVariant>Required
an array containing the products as the first element and the total count of products that matches the query as the second element.

validateVariantsToCreate_​

Parameters​

productProductRequired
variantsCreateProductVariantInput[]Required

Returns​

voidvoidRequired
Was this section helpful?
© 2026 Medusa, Inc. All rights reserved.