Products - Medusa

Overview

The Products API allows you to create, update, retrieve, and manage products in your Medusa store. Products can have multiple variants, options, images, and be organized into collections and categories. Base Path: /admin/products Source: packages/medusa/src/api/admin/products/route.ts

List Products

Retrieve a list of products with filtering and pagination.

GET /admin/products

Query Parameters

string

Comma-separated list of fields to include (e.g., id,title,status,variants.sku).

number

default:"15"

Maximum number of products to return.

number

default:"0"

Number of products to skip.

string

Filter by product status: published, draft, or proposed.

string

Filter products by sales channel ID.

string

Filter products by collection ID.

string[]

Filter products by tag IDs.

string[]

Filter products by category IDs.

string

Search query for product title or description.

Request

curl -X GET http://localhost:9000/admin/products \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "status=published" \
  --data-urlencode "limit=20"

Response

{
  "products": [
    {
      "id": "prod_123",
      "title": "Premium T-Shirt",
      "subtitle": "Comfortable cotton tee",
      "status": "published",
      "description": "A high-quality cotton t-shirt",
      "handle": "premium-t-shirt",
      "is_giftcard": false,
      "discountable": true,
      "thumbnail": "https://example.com/image.jpg",
      "collection_id": "pcol_123",
      "type_id": "ptyp_123",
      "variants": [
        {
          "id": "variant_123",
          "title": "Small",
          "sku": "SHIRT-SM",
          "prices": [
            {
              "amount": 2999,
              "currency_code": "usd"
            }
          ]
        }
      ],
      "options": [
        {
          "id": "opt_123",
          "title": "Size",
          "values": ["Small", "Medium", "Large"]
        }
      ],
      "images": [
        {
          "id": "img_123",
          "url": "https://example.com/image.jpg"
        }
      ],
      "tags": [],
      "categories": [],
      "created_at": "2024-03-03T10:00:00.000Z",
      "updated_at": "2024-03-03T10:00:00.000Z"
    }
  ],
  "count": 100,
  "offset": 0,
  "limit": 20
}

Product[]

Array of product objects.

number

Total number of products matching the filters.

Source: packages/medusa/src/api/admin/products/route.ts:17

Create Product

Create a new product with variants and options.

POST /admin/products

Request Body

string

required

The product’s title.

string

The product’s subtitle.

string

The product’s description.

string

default:"draft"

Product status: published, draft, or proposed.

string

Unique URL-friendly identifier. Auto-generated from title if not provided.

boolean

default:"false"

Whether the product is a gift card.

boolean

default:"true"

Whether discounts can be applied to the product.

object[]

Product images.

Show child attributes

string

required

Image URL.

string

URL of the product’s thumbnail image.

string

ID of the collection the product belongs to.

string

ID of the product type.

object[]

Product categories.

Show child attributes

string

required

Category ID.

object[]

Product tags.

Show child attributes

string

required

Tag ID.

object[]

required

Product options (e.g., Size, Color).

Show child attributes

string

required

Option name.

string[]

required

Available option values.

object[]

Product variants.

Show child attributes

string

required

Variant title.

string

Stock keeping unit.

object[]

required

Variant prices.

Show child attributes

string

required

Currency code (e.g., “usd”).

number

required

Price amount in cents.

object

Option values for this variant (e.g., {"Size": "Small"}).

boolean

default:"true"

Whether Medusa manages inventory for this variant.

boolean

default:"false"

Allow orders when out of stock.

object[]

Sales channels where the product is available.

Show child attributes

string

required

Sales channel ID.

number

Product weight.

number

Product length.

number

Product height.

number

Product width.

object

Key-value pairs of custom metadata.

Request

curl -X POST http://localhost:9000/admin/products \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Premium T-Shirt",
    "description": "A comfortable cotton t-shirt",
    "status": "published",
    "options": [
      {
        "title": "Size",
        "values": ["Small", "Medium", "Large"]
      }
    ],
    "variants": [
      {
        "title": "Small",
        "sku": "SHIRT-SM",
        "options": {"Size": "Small"},
        "prices": [
          {
            "currency_code": "usd",
            "amount": 2999
          }
        ]
      }
    ]
  }'

Response

{
  "product": {
    "id": "prod_123",
    "title": "Premium T-Shirt",
    "status": "published",
    "variants": [...],
    "options": [...]
  }
}

Source: packages/medusa/src/api/admin/products/route.ts:94 Types: packages/core/types/src/http/product/admin/payloads.ts:159

Get Product

Retrieve a single product by ID.

GET /admin/products/{id}

Path Parameters

string

required

The product’s ID.

Request

curl -X GET http://localhost:9000/admin/products/prod_123 \
  -H "Authorization: Bearer {token}"

Response

{
  "product": {
    "id": "prod_123",
    "title": "Premium T-Shirt",
    "variants": [...],
    "options": [...]
  }
}

Update Product

Update an existing product.

POST /admin/products/{id}

Path Parameters

string

required

The product’s ID.

Request Body

Accepts the same fields as Create Product, all optional.

Request

curl -X POST http://localhost:9000/admin/products/prod_123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Product Title",
    "status": "published"
  }'

Response

{
  "product": {
    "id": "prod_123",
    "title": "Updated Product Title",
    "status": "published"
  }
}

Delete Product

Delete a product (soft delete).

DELETE /admin/products/{id}

Path Parameters

string

required

The product’s ID.

Request

curl -X DELETE http://localhost:9000/admin/products/prod_123 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "prod_123",
  "object": "product",
  "deleted": true
}

Product Variants

Create Variant

Add a new variant to an existing product.

POST /admin/products/{id}/variants

Update Variant

Update a product variant.

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

Delete Variant

Remove a variant from a product.

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

Product Options

Create Option

Add a new option to a product.

POST /admin/products/{id}/options

Update Option

Update a product option.

POST /admin/products/{id}/options/{option_id}

Delete Option

Remove an option from a product.

DELETE /admin/products/{id}/options/{option_id}

Batch Operations

Batch Create/Update Products

Create or update multiple products in a single request.

POST /admin/products/batch

Request Body

object[]

Products to create.

object[]

Products to update.

Show child attributes

string

required

Product ID to update.

Next Steps

Inventory

Manage product inventory

Pricing

Configure product pricing

​Overview

​List Products

​Query Parameters

​Request

​Response

​Create Product

​Request Body

​Request

​Response

​Get Product

​Path Parameters

​Request

​Response

​Update Product

​Path Parameters

​Request Body

​Request

​Response

​Delete Product

​Path Parameters

​Request

​Response

​Product Variants

​Create Variant

​Update Variant

​Delete Variant

​Product Options

​Create Option

​Update Option

​Delete Option

​Batch Operations

​Batch Create/Update Products

​Request Body

​Next Steps

Inventory

Pricing

Overview

List Products

Query Parameters

Request

Response

Create Product

Request Body

Request

Response

Get Product

Path Parameters

Request

Response

Update Product

Path Parameters

Request Body

Request

Response

Delete Product

Path Parameters

Request

Response

Product Variants

Create Variant

Update Variant

Delete Variant

Product Options

Create Option

Update Option

Delete Option

Batch Operations

Batch Create/Update Products

Request Body

Next Steps