Skip to main content

​
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

​
fields
string
Comma-separated list of fields to include (e.g., id,title,status,variants.sku).
​
limit
number
default:"15"
Maximum number of products to return.
​
offset
number
default:"0"
Number of products to skip.
​
status
string
Filter by product status: published, draft, or proposed.
​
sales_channel_id
string
Filter products by sales channel ID.
​
collection_id
string
Filter products by collection ID.
​
tags
string[]
Filter products by tag IDs.
​
categories
string[]
Filter products by category IDs.
​
q
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
}
​
products
Product[]
Array of product objects.
​
count
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

​
title
string
required
The product’s title.
​
subtitle
string
The product’s subtitle.
​
description
string
The product’s description.
​
status
string
default:"draft"
Product status: published, draft, or proposed.
​
handle
string
Unique URL-friendly identifier. Auto-generated from title if not provided.
​
is_giftcard
boolean
default:"false"
Whether the product is a gift card.
​
discountable
boolean
default:"true"
Whether discounts can be applied to the product.
​
images
object[]
Product images.
​
thumbnail
string
URL of the product’s thumbnail image.
​
collection_id
string
ID of the collection the product belongs to.
​
type_id
string
ID of the product type.
​
categories
object[]
Product categories.
​
tags
object[]
Product tags.
​
options
object[]
required
Product options (e.g., Size, Color).
​
variants
object[]
Product variants.
​
sales_channels
object[]
Sales channels where the product is available.
​
weight
number
Product weight.
​
length
number
Product length.
​
height
number
Product height.
​
width
number
Product width.
​
metadata
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

​
id
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

​
id
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

​
id
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

​
create
object[]
Products to create.
​
update
object[]
Products to update.

​
Next Steps

Inventory

Manage product inventory

Pricing

Configure product pricing

Build docs developers (and LLMs) love

Get started for freeTalk to us