Menu

Products API Routes

A product is a set of variants that the customer chooses from when making a purchase.

A product can be organized into categories or collections.

A product can have many options, and variants for each of these options' values.

These API routes allow admin users to manage products.

GET /admin/products#

List Products

Retrieve a list of products. The products can be filtered by fields such as id. The products can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
price_list_idstring | string[]Optional
Filter by a price list's ID to retrieve its associated products.
qstringOptional
Search term to filter a product's searchable properties.
status("draft")[] | ("proposed")[] | ("published")[] | ("rejected")[]Optional
Filter by product statuses.
sales_channel_idstring | string[]Optional
Filter by a sales channel's ID to retrieve its associated products.
titlestring | string[]Optional
Filter by a title.
handlestring | string[]Optional
Filter by a handle.
idstring | string[]Optional
Filter by a product ID.
is_giftcardbooleanOptional
Filter by whether a product is a gift card.
type_idstring | string[]Optional
Filter by a product type's ID to retrieve its associated products.
category_idstring | string[]Optional
Filter by a product category's ID to retrieve its associated products.
created_atobjectOptional
Filter by a product's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a product's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a product's deletion date. Accepts the filter operators.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
collection_idstring | string[]Optional
Filter by a product collection ID.
variantsobjectOptional
Filter the retrieved products' variants.
with_deletedbooleanOptional
Whether to include deleted products.
external_idstring | string[]Optional
Filter by the product's external ID.
tag_idstring | string[]Optional
Filter by the product's tag ID.
option_idstring | string[]Optional
Filter by an option ID to retrieve the products that have the option.
option_value_idstring | string[]Optional
Filter by an option value ID to retrieve the products that have the option value.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
productsobject[]
The list of products.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/products#

Create Product

Create a product.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

titlestring
The product's title.
subtitlestringOptional
The product's subtitle.
descriptionstringOptional
The product's description.
is_giftcardbooleanOptional
Whether the product is a gift card.
discountablebooleanOptional
Whether the product is discountable.
imagesobject[]Optional
The product's images.
thumbnailstringOptional
The URL of the product's thumbnail.
handlestringOptional
The product's handle.
status"draft" | "proposed" | "published" | "rejected"Optional
The product's status.
type_idstringOptional
The ID of the type the product belongs to.
collection_idstringOptional
The ID of the collection the product belongs to.
categoriesobject[]Optional
The categories the product belongs to.
tagsobject[]Optional
The product's tags.
optionsobject[]Optional
The product's options.
variantsobject[]Optional
The product's variants.
sales_channelsobject[]Optional
The sales channels the product is available in.
weightnumberOptional
The product's weight.
lengthnumberOptional
The product's length.
heightnumberOptional
The product's height.
widthnumberOptional
The product's width.
hs_codestringOptional
The product's HS code.
mid_codestringOptional
The product's MID code.
origin_countrystringOptional
The product's origin country.
materialstringOptional
The product's material.
metadataobjectOptional
The product's metadata, used to store custom key-value pairs. Learn more in the Manage Metadata section.
external_idstringOptional
The ID of the product in an external or third-party system.
shipping_profile_idstringOptional
The ID of the product's shipping profile.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

productobject
The product's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-variant.created: Emitted when product variants are created.
  • product.created: Emitted when products are created.
  • inventory-item.created: Emitted when inventory items are created.
  • inventory-level.created: Emitted when inventory levels are created.

POST /admin/products/batch#

Manage Products

Manage products to create, update, or delete them.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

createobject[]Optional
The products to create.
updateobject[]Optional
The products to update.
deletestring[]Optional
The products to delete.

Request examples

Responses

200 OK

createdobject[]
The created products
updatedobject[]
The updated products.
deletedobject
The deleted products' details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-variant.updated: Emitted when product variants are updated.
  • product-variant.created: Emitted when product variants are created.
  • product.updated: Emitted when products are updated.
  • product.created: Emitted when products are created.
  • product.deleted: Emitted when products are deleted.
  • product-option.deleted: Emitted when product options are deleted.
  • inventory-item.created: Emitted when inventory items are created.
  • inventory-item.deleted: Emitted when inventory items are deleted.
  • inventory-level.created: Emitted when inventory levels are created.

POST /admin/products/export#

Export Products

Start a product export process to retrieve a CSV of exported products.

You'll receive in the response the transaction ID of the workflow generating the CSV file. To check the status of the execution, send a GET request to /admin/workflows-executions/export-products/:transaction-id. Once the execution finishes successfully, a notification is created for the export. You can retrieve the notifications using the /admin/notification API route to retrieve the file's download URL.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
tagsobjectOptional
Filter products by their tags.
variantsobjectOptional
Filter the products' variants.
titlestring | string[]Optional
Filter products by their title.
status("draft")[] | ("proposed")[] | ("published")[] | ("rejected")[]Optional
Filter products by their statuses.
idstring | string[]Optional
Filter products by their ID.
sales_channel_idstring | string[]Optional
Filter products by their sales channel ID.
created_atobjectOptional
Filter by a product's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a product's update date. Accepts the filter operators.
handlestring | string[]Optional
Filter products by their handle.
is_giftcardbooleanOptional
Filter products by whether they are gift cards.
collection_idstring | string[]Optional
Filter products by their collection ID.
type_idstring | string[]Optional
Filter products by their type ID.
deleted_atobjectOptional
Filter by a product's deletion date. Accepts the filter operators.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
qstringOptional
The product's q.
category_idstring | string[]Optional
Filter products by their category ID.
limitnumberOptional
Limit the number of items returned in the list.
offsetnumberOptional
The number of items to skip when retrieving a list.
with_deletedbooleanOptional
The product's with deleted.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
price_list_idstring | string[]Optional
Filter products by the ID of a price list they belong to.
external_idstring | string[]Optional
Filter by the product's external ID.
tag_idstring | string[]Optional
Filter by the product's tag ID.
option_idstring | string[]Optional
Filter by an option ID to return products that have the option.
option_value_idstring | string[]Optional
Filter by an option value ID to return products that have the option value.

Request examples

Responses

202 OK

transaction_idstring
The ID of the workflow execution's transaction. Use it to check the status of the export by sending a GET request to /admin/workflows-executions/export-products/:transaction-id

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/products/import#

Create Product Import

Create a new product import process. The products aren't imported until the import is confirmed with the /admin/products/:transaction-id/import API route.

Deprecated: This API route is deprecated. use POST /admin/products/imports instead.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Request body (application/json)

fileobject
A File to upload.

Request examples

Responses

202 OK

transaction_idstring
The ID of the workflow execution's transaction. This is useful to confirm the import using the /admin/products/:transaction-id/import API route.
summaryobject
The import's summary.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-variant.updated: Emitted when product variants are updated.
  • product-variant.created: Emitted when product variants are created.
  • product.updated: Emitted when products are updated.
  • product.created: Emitted when products are created.
  • product.deleted: Emitted when products are deleted.
  • product-option.deleted: Emitted when product options are deleted.
  • inventory-item.created: Emitted when inventory items are created.
  • inventory-item.deleted: Emitted when inventory items are deleted.
  • inventory-level.created: Emitted when inventory levels are created.

POST /admin/products/import/{transaction_id}/confirm#

Confirm Product Import

Confirm that a created product import should start importing the products into Medusa.

Deprecated: This API route is deprecated. use POST /admin/products/imports/:transaction_id/confirm instead.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

transaction_idstring
The ID of the transaction returned when the product import was created.

Request examples

Responses

202 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/products/imports#

Create Product Import

Create a new product import process. The products aren't imported until the import is confirmed with the /admin/products/:transaction-id/imports API route.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Request body (application/json)

file_keystring
The name of the file as stored in the configured File Module Provider.
originalnamestring
The file's original name.
extensionstring
The file's extension.
Example: csv
sizenumber
The file's size in bytes.
mime_typestring
The file's mime type.
Example: text/csv

Request examples

Responses

202 OK

transaction_idstring
The ID of the workflow execution's transaction. This is useful to confirm the import using the /admin/products/:transaction-id/import API route.
summaryobject
The import's summary.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/products/imports/{transaction_id}/confirm#

Confirm Product Import

Confirm that a created product import should start importing the products into Medusa.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

transaction_idstring
The product's transaction id.

Request examples

Responses

202 OK

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/products/{id}#

Get a Product

Retrieve a product by its ID. You can expand the product's relations or select the fields that should be returned.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

productobject
The product's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/products/{id}#

Update a Product

Update a product's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

titlestringOptional
The product's title.
subtitlestringOptional
The product's subtitle.
descriptionstringOptional
The product's description.
is_giftcardbooleanOptional
Whether the product is a gift card.
discountablebooleanOptional
Whether discounts can be applied on the product.
imagesobject[]Optional
The product's images.
thumbnailstringOptional
The product's thumbnail URL.
handlestringOptional
The product's unique handle.
status"draft" | "proposed" | "published" | "rejected"Optional
The product's status.
type_idstringOptional
The ID of the product's type.
collection_idstringOptional
The ID of the product's collection.
categoriesobject[]Optional
The product's categories.
tagsobject[]Optional
The product's tags.
optionsobject[]Optional
The product's options.
variantsobject[]Optional
The product's variants. You can add new variants or update existing ones, passing their IDs in the object.
sales_channelsobject[]Optional
The sales channels that the product is available in.
weightnumberOptional
The product's weight.
lengthnumberOptional
The product's length.
heightnumberOptional
The product's height.
widthnumberOptional
The product's width.
hs_codestringOptional
The product's HS code.
mid_codestringOptional
The product's MID code.
origin_countrystringOptional
The product's origin country.
materialstringOptional
The product's material.
metadataobjectOptional
The product's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.
external_idstringOptional
The ID of the product in an external or third-party system.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

productobject
The product's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-variant.updated: Emitted when product variants are updated.
  • product.updated: Emitted when products are updated.

DELETE /admin/products/{id}#

Delete a Product

Delete a product.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.

Request examples

Responses

200 OK

idstring
The product's ID.
objectstring
The name of the deleted object.

Default: "product"

deletedboolean
Whether the product was deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product.deleted: Emitted when products are deleted.
  • product-option.deleted: Emitted when product options are deleted.
  • inventory-item.deleted: Emitted when inventory items are deleted.

POST /admin/products/{id}/images/{image_id}/variants/batch#

Manage Variants of Product Image

Manage the association between product variants and a product image. You can add or remove associations between variants and the image.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.
image_idstring
The product image's ID.

Request body (application/json)

addstring[]Optional
The IDs of product variants to add the image to.
removestring[]Optional
The IDs of product variants to remove the image from.

Request examples

Responses

200 OK

addedstring[]
The IDs of product variants added the image to.
removedstring[]
The IDs of product variants removed the image from.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-variant.updated: Emitted when product variants are updated.

GET /admin/products/{id}/options#

List a Product's Options

Retrieve a list of options of a product. The options can be filtered by fields like id. The options can also be paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
qstringOptional
Search term to filter the product option's searchable fields.
idstring | string[]Optional
Filter by the product option's ID.
titlestring | string[]Optional
Filter by a title.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
with_deletedbooleanOptional
Whether to include deleted records in the result.
is_exclusivebooleanOptional
Filter by whether the product option is global or exclusive to a product.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before the returned items.
countnumber
The total number of items.
product_optionsobject[]
The list of product options.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/products/{id}/options/batch#

Add Options to Product

Add a list of options to a product.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.

Request body (application/json)

addstring[] | object[]Optional
The options to add to the product.
removestring[]Optional
The IDs of the product options to remove from the product.
updateobject[]Optional
The product's update.

Request examples

Responses

200 OK

productobject
The product's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product.updated: Emitted when products are updated.

GET /admin/products/{id}/variants#

List Variants of a Product

Retrieve a list of variants in a product. The variants can be filtered by fields like FILTER FIELDS. The variants can also be paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
qstringOptional
Search term to filter the variant's search attributes.
idstring | string[]Optional
Filter by a variant's ID.
manage_inventorybooleanOptional
Filter by whether a variant's manage_inventory property is enabled.
allow_backorderbooleanOptional
Filter by whether backorders are allowed for the variant.
created_atobjectOptional
Filter by the product's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the product's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by the product's deletion date. Accepts the filter operators.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
with_deletedbooleanOptional
Whether to include deleted records in the result.
eanstring | string[]Optional
The product's ean.
upcstring | string[]Optional
The product's upc.
barcodestring | string[]Optional
The product's barcode.
skustring | string[]Optional
Filter by an SKU.

Request examples

Responses

200 OK

limitnumber
The maximum number of returned items.
offsetnumber
The number of items skipped before the returned item.
countnumber
The total number of items.
variantsobject[]
The list of product variants.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/products/{id}/variants#

Create a Product Variant

Create a variant for a product.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

titlestring
The variant's title.
skustringOptional
The variant's SKU.
eanstringOptional
The variant's EAN.
upcstringOptional
The variant's UPC.
barcodestringOptional
The variant's barcode.
hs_codestringOptional
The variant's HS code.
mid_codestringOptional
The variant's MID code.
allow_backorderbooleanOptional
Whether it's allowed to order this variant when it's out of stock.
manage_inventorybooleanOptional
Whether Medusa manages the variant's inventory quantity. If disabled, the product variant is always considered in stock.
variant_ranknumberOptional
The sorting order of the variant among other variants in the product.
weightnumberOptional
The variant's weight.
lengthnumberOptional
The variant's length.
heightnumberOptional
The variant's height.
widthnumberOptional
The variant's width.
origin_countrystringOptional
The variant's origin country.
materialstringOptional
The variant's material.
metadataobjectOptional
The variant's metadata, used to store custom key-value pairs. Learn more in the Manage Metadata section.
pricesobject[]
The variant's prices.
optionsobjectOptional
The variant's options, where the key is an option's name, and the value is the option's value.
inventory_itemsobject[]Optional
The variant's inventory items to create.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

productobject
The product's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-variant.created: Emitted when product variants are created.
  • inventory-item.created: Emitted when inventory items are created.
  • inventory-level.created: Emitted when inventory levels are created.

POST /admin/products/{id}/variants/batch#

Manage Variants in a Product

Manage variants in a product to create, update, or delete them.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

createobject[]Optional
The product variants to create.
updateobject[]Optional
The product variants to update.
deletestring[]Optional
The product variants to delete.

Request examples

Responses

200 OK

createdobject[]
The created product variants.
updatedobject[]
The updated product variants.
deletedobject
The details of the deleted product variants.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-variant.updated: Emitted when product variants are updated.
  • product-variant.created: Emitted when product variants are created.
  • product-variant.deleted: Emitted when product variants are deleted.
  • inventory-item.created: Emitted when inventory items are created.
  • inventory-item.deleted: Emitted when inventory items are deleted.
  • inventory-level.created: Emitted when inventory levels are created.

POST /admin/products/{id}/variants/inventory-items/batch#

Manage Variants Inventory in a Product

Manage a product's variant's inventoris to associate them with inventory items, update their inventory items, or delete their association with inventory items.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.

Request body (application/json)

createobject[]Optional
The associations to create between product variants and inventory items.
updateobject[]Optional
The product variants to update their association with inventory items.
deleteobject[]Optional
The product variants to delete their association with inventory items.

Request examples

Responses

200 OK

createdobject | object[]
A created association between a product variant and an inventory item.
updatedobject | object[]
A created association between a product variant and an inventory item.
deletedobject | object[]
A created association between a product variant and an inventory item.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/products/{id}/variants/{variant_id}#

Get Variant of a Product

Retrieve a product's variant by its ID.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.
variant_idstring
The variant's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

variantobject
The product variant's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/products/{id}/variants/{variant_id}#

Update a Product Variant

Update a variant's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.
variant_idstring
The product's variant id.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

titlestringOptional
The product variant's title.
skustringOptional
The product variant's SKU.
eanstringOptional
The product variant's EAN.
upcstringOptional
The product variant's UPC.
barcodestringOptional
The product variant's barcode.
hs_codestringOptional
The product variant's HS code.
mid_codestringOptional
The product variant's MID code.
allow_backorderbooleanOptional
Whether customers can order the variant even if it's not in stock.
manage_inventorybooleanOptional
Whether the MedusaGo application manages the variant's inventory. If disabled, the product variant is always considered in stock.
variant_ranknumberOptional
The product variant's rank among its siblings.
weightnumberOptional
The product variant's weight.
lengthnumberOptional
The product variant's length.
heightnumberOptional
The product variant's height.
widthnumberOptional
The product variant's width.
origin_countrystringOptional
The product variant's origin country.
materialstringOptional
The product variant's material.
metadataobjectOptional
The product variant's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.
pricesobject[]Optional
The product variant's prices.
optionsobjectOptional
The product variant's options.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

productobject
The product's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-variant.updated: Emitted when product variants are updated.

DELETE /admin/products/{id}/variants/{variant_id}#

Delete Product Variant

Delete a variant of a product.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.
variant_idstring
The product variant's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

idstring
The product variant's ID.
objectstring
The name of the deleted object.
deletedboolean
Whether the product variant was deleted.

Default: "variant"

parentobjectOptional
The product's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-variant.deleted: Emitted when product variants are deleted.
  • inventory-item.deleted: Emitted when inventory items are deleted.

POST /admin/products/{id}/variants/{variant_id}/images/batch#

Manage Images of Product Variant

Manage the association between product images and a product variant. You can add or remove associations between images and the variant.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.
variant_idstring
The product variant's ID.

Request body (application/json)

addstring[]Optional
The IDs of product images to add to the variant.
removestring[]Optional
The IDs of product images to remove from the variant.

Request examples

Responses

200 OK

addedstring[]
The IDs of product images added to the variant.
removedstring[]
The IDs of product images removed from the variant.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-variant.updated: Emitted when product variants are updated.

POST /admin/products/{id}/variants/{variant_id}/inventory-items#

Associate Variant with Inventory Item

Associate with a product variant an inventory item that manages its inventory details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.
variant_idstring
The variant's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

required_quantitynumber
The quantity of the variant in the inventory item.
inventory_item_idstring
The inventory item's ID.

Request examples

Responses

200 OK

variantobject
The product variant's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/products/{id}/variants/{variant_id}/inventory-items/{inventory_item_id}#

Update Product Variant's Inventory Details

Update the inventory item that manages the inventory details of a product variant.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.
variant_idstring
The variant's ID.
inventory_item_idstring
The inventory item's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

required_quantitynumber
The number of units a single quantity is equivalent to. For example, if a customer orders one quantity of the variant, Medusa checks the availability of the quantity multiplied by the value set for required_quantity. When the customer orders the quantity, Medusa reserves the ordered quantity multiplied by the value set for required_quantity.

Request examples

Responses

200 OK

variantobject
The product variant's details.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/products/{id}/variants/{variant_id}/inventory-items/{inventory_item_id}#

Remove Inventory Item Association with Product Variant

Remove the association between an inventory item and its product variant.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product's ID.
variant_idstring
The products variant's ID.
inventory_item_idstring
The inventory item's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

idobject
A created association between a product variant and an inventory item.
objectstring
The name of the deleted object.

Default: "variant-inventory-item-link"

deletedboolean
Whether the association was deleted.
parentobject
The product variant's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page