Products

Store API endpoints for browsing and retrieving product information in your storefront.

Overview

The Store Products API enables customers to browse your product catalog, view product details, and search for products. All endpoints are publicly accessible without authentication.

Base Path: /store/products

Source: packages/medusa/src/api/store/products/route.ts

List Products

Retrieve a list of published products available to customers.

GET /store/products

Query Parameters

fields · string

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

limit · number · default: "15"

Maximum number of products to return.

offset · number · default: "0"

Number of products to skip.

q · string

Search query for product title or description.

collection_id · string[]

Filter by collection IDs.

category_id · string[]

Filter by category IDs.

tags · string[]

Filter by product tag values.

type_id · string[]

Filter by product type IDs.

sales_channel_id · string

Filter products available in specific sales channel.

region_id · string

Region ID for pricing context.

currency_code · string

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

Request

curl -X GET http://localhost:9000/store/products \
  -G \
  --data-urlencode "limit=20" \
  --data-urlencode "region_id=reg_us" \
  --data-urlencode "currency_code=usd"

Response

{
  "products": [
    {
      "id": "prod_123",
      "title": "Premium T-Shirt",
      "subtitle": "Comfortable cotton tee",
      "description": "A high-quality cotton t-shirt perfect for everyday wear",
      "handle": "premium-t-shirt",
      "is_giftcard": false,
      "thumbnail": "https://example.com/images/tshirt.jpg",
      "collection": {
        "id": "pcol_123",
        "title": "Summer Collection",
        "handle": "summer-collection"
      },
      "categories": [
        {
          "id": "pcat_123",
          "name": "Clothing",
          "handle": "clothing"
        }
      ],
      "variants": [
        {
          "id": "variant_123",
          "title": "Small / Black",
          "sku": "SHIRT-SM-BLK",
          "inventory_quantity": 50,
          "manage_inventory": true,
          "allow_backorder": false,
          "calculated_price": {
            "calculated_amount": 2999,
            "is_calculated_price_tax_inclusive": false,
            "currency_code": "usd"
          },
          "options": [
            {
              "id": "optval_123",
              "value": "Small",
              "option": {
                "id": "opt_123",
                "title": "Size"
              }
            },
            {
              "id": "optval_456",
              "value": "Black",
              "option": {
                "id": "opt_456",
                "title": "Color"
              }
            }
          ]
        }
      ],
      "options": [
        {
          "id": "opt_123",
          "title": "Size",
          "values": [
            {"id": "optval_123", "value": "Small"},
            {"id": "optval_124", "value": "Medium"},
            {"id": "optval_125", "value": "Large"}
          ]
        },
        {
          "id": "opt_456",
          "title": "Color",
          "values": [
            {"id": "optval_456", "value": "Black"},
            {"id": "optval_457", "value": "White"}
          ]
        }
      ],
      "images": [
        {
          "id": "img_123",
          "url": "https://example.com/images/tshirt-front.jpg"
        },
        {
          "id": "img_124",
          "url": "https://example.com/images/tshirt-back.jpg"
        }
      ],
      "tags": [
        {
          "id": "tag_123",
          "value": "cotton"
        }
      ],
      "created_at": "2024-03-03T10:00:00.000Z",
      "updated_at": "2024-03-03T10:00:00.000Z"
    }
  ],
  "count": 150,
  "offset": 0,
  "limit": 20
}

products · Product[]

Array of product objects.

calculated_price · object

Calculated price based on region and currency context.

Show child attributes

calculated_amount · number

Price in smallest currency unit (cents).

currency_code · string

Currency code for the price.

Source: packages/medusa/src/api/store/products/route.ts:13

Only products with status: "published" are returned by the Store API. Products are automatically filtered by the current sales channel context.

Get Product

Retrieve a single product by ID or handle.

GET /store/products/{id}

Path Parameters

id · string · required

The product’s ID or handle.

Query Parameters

fields · string

Comma-separated list of fields to include.

region_id · string

Region ID for pricing context.

currency_code · string

Currency code for pricing.

Request

# By ID
curl -X GET http://localhost:9000/store/products/prod_123 \
  -G \
  --data-urlencode "region_id=reg_us" \
  --data-urlencode "currency_code=usd"

# By handle
curl -X GET http://localhost:9000/store/products/premium-t-shirt \
  -G \
  --data-urlencode "region_id=reg_us"

Response

{
  "product": {
    "id": "prod_123",
    "title": "Premium T-Shirt",
    "description": "A high-quality cotton t-shirt",
    "variants": [...],
    "options": [...],
    "images": [...]
  }
}

Product Variants

List Product Variants

Retrieve variants for a specific product.

GET /store/product-variants

Query Parameters

id · string[]

Filter by variant IDs.

product_id · string[]

Filter by product IDs.

sku · string[]

Filter by SKU.

region_id · string

Region ID for pricing context.

currency_code · string

Currency code for pricing.

Request

curl -X GET http://localhost:9000/store/product-variants \
  -G \
  --data-urlencode "product_id=prod_123" \
  --data-urlencode "region_id=reg_us"

Source: packages/medusa/src/api/store/product-variants/route.ts

Get Product Variant

Retrieve a single variant by ID.

GET /store/product-variants/{id}

Collections

List Collections

Retrieve all product collections.

GET /store/collections

Query Parameters

limit · number · default: "15"

Maximum number of collections to return.

offset · number · default: "0"

Number of collections to skip.

handle · string[]

Filter by collection handles.

Request

curl -X GET http://localhost:9000/store/collections

Response

{
  "collections": [
    {
      "id": "pcol_123",
      "title": "Summer Collection",
      "handle": "summer-collection",
      "metadata": {}
    }
  ],
  "count": 5,
  "offset": 0,
  "limit": 15
}

Source: packages/medusa/src/api/store/collections/route.ts

Get Collection

Retrieve a single collection by ID or handle.

GET /store/collections/{id}

Categories

List Product Categories

Retrieve product categories in a hierarchical structure.

GET /store/product-categories

Query Parameters

parent_category_id · string

Filter by parent category ID. Use null for top-level categories.

include_descendants_tree · boolean

Include nested child categories.

Request

curl -X GET http://localhost:9000/store/product-categories \
  -G \
  --data-urlencode "include_descendants_tree=true"

Response

{
  "product_categories": [
    {
      "id": "pcat_123",
      "name": "Clothing",
      "handle": "clothing",
      "parent_category_id": null,
      "category_children": [
        {
          "id": "pcat_456",
          "name": "T-Shirts",
          "handle": "t-shirts",
          "parent_category_id": "pcat_123"
        }
      ]
    }
  ]
}

Source: packages/medusa/src/api/store/product-categories/route.ts

Get Product Category

Retrieve a single category by ID or handle.

GET /store/product-categories/{id}

Search and Filtering

Full-Text Search

Search products by title and description:

curl -X GET http://localhost:9000/store/products \
  -G \
  --data-urlencode "q=cotton shirt"

Filter by Collection

Get products in a specific collection:

curl -X GET http://localhost:9000/store/products \
  -G \
  --data-urlencode "collection_id=pcol_123"

Filter by Category

Get products in a category:

curl -X GET http://localhost:9000/store/products \
  -G \
  --data-urlencode "category_id=pcat_123" \
  --data-urlencode "category_id=pcat_456"

Filter by Tags

Get products with specific tags:

curl -X GET http://localhost:9000/store/products \
  -G \
  --data-urlencode "tags=cotton" \
  --data-urlencode "tags=organic"

Pricing Context

To get accurate pricing, always include region or currency context:

curl -X GET http://localhost:9000/store/products \
  -G \
  --data-urlencode "region_id=reg_us" \
  --data-urlencode "currency_code=usd"

The API calculates prices based on:

• Region-specific pricing rules
• Active price lists
• Currency conversion
• Tax rates (if applicable)
• Active promotions

Source: packages/medusa/src/api/store/products/helpers.ts (pricing calculation)

Inventory Information

Request inventory quantities by including the inventory field:

curl -X GET http://localhost:9000/store/products \
  -G \
  --data-urlencode "fields=*,variants.inventory_quantity"

Inventory quantity calculation considers the current sales channel and stock location context.

Next Steps

Cart

Add products to cart

Checkout

Complete the purchase