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

AdminProductsResource

This class is used to send requests to Admin Product API Routes. All its method are available in the JS Client under the medusa.admin.products property.

All methods in this class require user authentication.

Products are saleable items in a store. This also includes saleable gift cards in a store.

Related Guide: How to manage products.

Methods​

create​

Create a new Product. This API Route can also be used to create a gift card if the is_giftcard field is set to true.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.create({
  title: "Shirt",
  is_giftcard: false,
  discountable: true
})
.then(({ product }) => {
  console.log(product.id);
})

Parameters​

payloadAdminPostProductsReqRequired
The product to create.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminProductsRes>Required
Resolves to the product's details.

retrieve​

Retrieve a product's details.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.retrieve(productId)
.then(({ product }) => {
  console.log(product.id);
})

Parameters​

idstringRequired
The product's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminProductsRes>Required
Resolves to the product's details.

update​

Update a Product's details.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.update(productId, {
  title: "Shirt",
})
.then(({ product }) => {
  console.log(product.id);
})

Parameters​

idstringRequired
The product's ID.
payloadAdminPostProductsProductReqRequired
The attributes to update in a product.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminProductsRes>Required
Resolves to the product's details.

delete​

Delete a product and its associated product variants and options.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.delete(productId)
.then(({ id, object, deleted }) => {
  console.log(id);
})

Parameters​

idstringRequired
The product's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminProductsDeleteRes>Required
Resolves to the deletion operation's details.

list​

Retrieve a list of products. The products can be filtered by fields such as q or status passed in the query parameter. The products can also be sorted or paginated.

Example​

To list products:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.list()
.then(({ products, limit, offset, count }) => {
  console.log(products.length);
})

To specify relations that should be retrieved within the products:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.list({
  expand: "images"
})
.then(({ products, limit, offset, count }) => {
  console.log(products.length);
})

By default, only the first 50 records are retrieved. You can control pagination by specifying the limit and offset properties:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.list({
  expand: "images",
  limit,
  offset
})
.then(({ products, limit, offset, count }) => {
  console.log(products.length);
})

Parameters​

customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

queryAdminGetProductsParams
Filters and pagination configurations to apply on the retrieved products.

Returns​

ResponsePromiseResponsePromise<AdminProductsListRes>Required
Resolves to the list of products with pagination fields.

listTags​

Retrieve a list of Product Tags with how many times each is used in products.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.listTags()
.then(({ tags }) => {
  console.log(tags.length);
})

Parameters​

customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminProductsListTagsRes>Required
Resolves to the list of tags.

setMetadata​

Set the metadata of a product. It can be any key-value pair, which allows adding custom data to a product. Learn about how you can update and delete the metadata attribute here.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.setMetadata(productId, {
  key: "test",
  value: "true"
})
.then(({ product }) => {
  console.log(product.id);
})

Parameters​

idstringRequired
The product's ID.
payloadAdminPostProductsProductMetadataReqRequired
The metadata details to add, update, or delete.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminProductsRes>Required
Resolves to the product's details.

createVariant​

Create a product variant associated with a product. Each product variant must have a unique combination of product option values.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.createVariant(productId, {
  title: "Color",
  prices: [
    {
      amount: 1000,
      currency_code: "eur"
    }
  ],
  options: [
    {
      option_id,
      value: "S"
    }
  ],
  inventory_quantity: 100
})
.then(({ product }) => {
  console.log(product.id);
})

Parameters​

idstringRequired
The ID of the product that the variant belongs to.
payloadAdminPostProductsProductVariantsReqRequired
The product variant to create.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminProductsRes>Required
Resolves to the product's details. You can access the variant under the variants property.

updateVariant​

Update a product variant's details.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.updateVariant(productId, variantId, {
  title: "Color",
  prices: [
    {
      amount: 1000,
      currency_code: "eur"
    }
  ],
  options: [
    {
      option_id,
      value: "S"
    }
  ],
  inventory_quantity: 100
})
.then(({ product }) => {
  console.log(product.id);
})

Parameters​

idstringRequired
The ID of the product that the variant belongs to.
variantIdstringRequired
The ID of the product variant.
payloadAdminPostProductsProductVariantsVariantReqRequired
The attributes to update in the product variant.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminProductsRes>Required
Resolves to the product's details. You can access the variant under the variants property.

deleteVariant​

Delete a product variant.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.deleteVariant(productId, variantId)
.then(({ variant_id, object, deleted, product }) => {
  console.log(product.id);
})

Parameters​

idstringRequired
The ID of the product that the variant belongs to.
variantIdstringRequired
The ID of the product variant.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminProductsDeleteVariantRes>Required
Resolves to the deletion operation's details.

listVariants​

List the product variants associated with a product. The product variants can be filtered by fields such as q or manage_inventory passed in the query parameter. The product variants can also be sorted or paginated.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.listVariants(productId, {
  limit: 10,
})
.then(({ variants, limit, offset, count }) => {
 console.log(variants.length);
})

Parameters​

idstringRequired
The ID of the product that the variants belongs to.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

queryAdminGetProductsVariantsParams
Filters and pagination configurations to apply on the retrieved product variants. If undefined, the first 100 records are retrieved.

Returns​

ResponsePromiseResponsePromise<AdminProductsListVariantsRes>Required
Resolves to the list of product variants with pagination fields.

addOption​

Add a product option to a product.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.addOption(productId, {
  title: "Size"
})
.then(({ product }) => {
  console.log(product.id);
})

Parameters​

idstringRequired
The product's ID.
payloadAdminPostProductsProductOptionsReqRequired
The option to add.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminProductsRes>Required
Resolves to the product's details. You can access the variant under the options property.

updateOption​

Update a product option's details.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.products.updateOption(productId, optionId, {
  title: "Size"
})
.then(({ product }) => {
  console.log(product.id);
})

Parameters​

idstringRequired
The ID of the product that the option belongs to.
optionIdstringRequired
The ID of the product option.
payloadAdminPostProductsProductOptionsOptionRequired
The attributes to update in the product option.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminProductsRes>Required
Resolves to the product's details. You can access the variant under the options property.

deleteOption​

Delete a product option. If there are product variants that use this product option, they must be deleted before deleting the product option.

Parameters​

idstringRequired
The ID of the product that the option belongs to.
optionIdstringRequired
The ID of the product option.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminProductsDeleteOptionRes>Required
Resolves to the deletion operation's details.
Was this section helpful?
© 2026 Medusa, Inc. All rights reserved.