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/productsSource: packages/medusa/src/api/store/products/route.tsList Products Retrieve a list of published products available to customers.
Query Parameters Comma-separated list of fields to include (e.g., id,title,variants.prices).
Maximum number of products to return.
Number of products to skip.
Search query for product title or description.
Filter by collection IDs.
Filter by product tag values.
Filter by product type IDs.
Filter products available in specific sales channel.
Region ID for pricing context.
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 }
Array of product objects.
Calculated price based on region and currency context. Price in smallest currency unit (cents).
Currency code for the price.
Source: packages/medusa/src/api/store/products/route.ts:13Only 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.
Path Parameters The product’s ID or handle.
Query Parameters Comma-separated list of fields to include.
Region ID for pricing context.
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 Region ID for pricing context.
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.tsGet Product Variant Retrieve a single variant by ID.
GET /store/product-variants/{id}
Collections List Collections Retrieve all product collections.
Query Parameters Maximum number of collections to return.
Number of collections to skip.
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.tsGet 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 Filter by parent category ID. Use null for top-level categories.
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.tsGet 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"
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)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
Checkout Complete the purchase