> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
GET /store/products
```

### Query Parameters

<ParamField query="fields" type="string">
  Comma-separated list of fields to include (e.g., `id,title,variants.prices`).
</ParamField>

<ParamField query="limit" type="number" default="15">
  Maximum number of products to return.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of products to skip.
</ParamField>

<ParamField query="q" type="string">
  Search query for product title or description.
</ParamField>

<ParamField query="collection_id" type="string[]">
  Filter by collection IDs.
</ParamField>

<ParamField query="category_id" type="string[]">
  Filter by category IDs.
</ParamField>

<ParamField query="tags" type="string[]">
  Filter by product tag values.
</ParamField>

<ParamField query="type_id" type="string[]">
  Filter by product type IDs.
</ParamField>

<ParamField query="sales_channel_id" type="string">
  Filter products available in specific sales channel.
</ParamField>

<ParamField query="region_id" type="string">
  Region ID for pricing context.
</ParamField>

<ParamField query="currency_code" type="string">
  Currency code for pricing (e.g., "usd").
</ParamField>

### Request

```bash theme={null}
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

```json theme={null}
{
  "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
}
```

<ResponseField name="products" type="Product[]">
  Array of product objects.
</ResponseField>

<ResponseField name="calculated_price" type="object">
  Calculated price based on region and currency context.

  <Expandable>
    <ResponseField name="calculated_amount" type="number">
      Price in smallest currency unit (cents).
    </ResponseField>

    <ResponseField name="currency_code" type="string">
      Currency code for the price.
    </ResponseField>
  </Expandable>
</ResponseField>

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

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

## Get Product

Retrieve a single product by ID or handle.

```bash theme={null}
GET /store/products/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The product's ID or handle.
</ParamField>

### Query Parameters

<ParamField query="fields" type="string">
  Comma-separated list of fields to include.
</ParamField>

<ParamField query="region_id" type="string">
  Region ID for pricing context.
</ParamField>

<ParamField query="currency_code" type="string">
  Currency code for pricing.
</ParamField>

### Request

```bash theme={null}
# 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

```json theme={null}
{
  "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.

```bash theme={null}
GET /store/product-variants
```

### Query Parameters

<ParamField query="id" type="string[]">
  Filter by variant IDs.
</ParamField>

<ParamField query="product_id" type="string[]">
  Filter by product IDs.
</ParamField>

<ParamField query="sku" type="string[]">
  Filter by SKU.
</ParamField>

<ParamField query="region_id" type="string">
  Region ID for pricing context.
</ParamField>

<ParamField query="currency_code" type="string">
  Currency code for pricing.
</ParamField>

### Request

```bash theme={null}
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.

```bash theme={null}
GET /store/product-variants/{id}
```

## Collections

### List Collections

Retrieve all product collections.

```bash theme={null}
GET /store/collections
```

### Query Parameters

<ParamField query="limit" type="number" default="15">
  Maximum number of collections to return.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of collections to skip.
</ParamField>

<ParamField query="handle" type="string[]">
  Filter by collection handles.
</ParamField>

### Request

```bash theme={null}
curl -X GET http://localhost:9000/store/collections
```

### Response

```json theme={null}
{
  "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.

```bash theme={null}
GET /store/collections/{id}
```

## Categories

### List Product Categories

Retrieve product categories in a hierarchical structure.

```bash theme={null}
GET /store/product-categories
```

### Query Parameters

<ParamField query="parent_category_id" type="string">
  Filter by parent category ID. Use `null` for top-level categories.
</ParamField>

<ParamField query="include_descendants_tree" type="boolean">
  Include nested child categories.
</ParamField>

### Request

```bash theme={null}
curl -X GET http://localhost:9000/store/product-categories \
  -G \
  --data-urlencode "include_descendants_tree=true"
```

### Response

```json theme={null}
{
  "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.

```bash theme={null}
GET /store/product-categories/{id}
```

## Search and Filtering

### Full-Text Search

Search products by title and description:

```bash theme={null}
curl -X GET http://localhost:9000/store/products \
  -G \
  --data-urlencode "q=cotton shirt"
```

### Filter by Collection

Get products in a specific collection:

```bash theme={null}
curl -X GET http://localhost:9000/store/products \
  -G \
  --data-urlencode "collection_id=pcol_123"
```

### Filter by Category

Get products in a category:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
curl -X GET http://localhost:9000/store/products \
  -G \
  --data-urlencode "fields=*,variants.inventory_quantity"
```

<Note>
  Inventory quantity calculation considers the current sales channel and stock location context.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Cart" icon="shopping-cart" href="/api/store/cart">
    Add products to cart
  </Card>

  <Card title="Checkout" icon="credit-card" href="/api/store/checkout">
    Complete the purchase
  </Card>
</CardGroup>