Medusa
  1. Products
Medusa
  • Back to home
  • Store API
  • Carts
    • Auth
      • Customer Login (JWT)
      • Customer Login (JWT)
      • Check if Email Exists
      • Get Current Customer
      • Customer Log out
      • Customer Login
    • Create Payment Sessions
      POST
    • Refresh a Payment Session
      POST
    • Create a Cart
      POST
    • Complete a Cart
      POST
    • Select a Payment Session
      POST
    • Delete a Payment Session
      DELETE
    • Update a Payment Session
      POST
    • Get a Cart
      GET
    • Update a Cart
      POST
    • Add Shipping Method
      POST
    • Update a Line Item
      POST
    • Delete a Line Item
      DELETE
    • Add a Line Item
      POST
    • Calculate Cart Taxes
      POST
    • Remove Discount
      DELETE
  • Customers
    • Request Password Reset
      POST
    • Get Saved Payment Methods
      GET
    • Add a Shipping Address
      POST
    • Update Customer
      POST
    • Get a Customer
      GET
    • Update a Shipping Address
      POST
    • Delete an Address
      DELETE
    • Create a Customer
      POST
    • Reset Password
      POST
    • List Orders
      GET
  • Gift Cards
    • Get Gift Card by Code
  • Orders
    • 77
      • Claim Order
    • Verify Order Claim
    • Get an Order
    • Look Up an Order
    • Get by Cart ID
  • Order Edits
    • Complete an Order Edit
    • Retrieve an Order Edit
    • Decline an Order Edit
  • Payment Collections
    • Authorize Payment Session
    • Authorize Payment Sessions
    • Refresh a Payment Session
    • Get a PaymentCollection
    • Manage Payment Sessions
    • Create a Payment Session
  • Products
    • Search Products
      POST
    • List Products
      GET
    • Get a Product
      GET
  • Product Variants
    • Get a Product Variant
    • Get Product Variants
  • Product Tags
    • List Product Tags
  • Product Categories
    • List Product Categories
    • Get a Product Category
  • Product Collections
    • Get a Collection
    • List Collections
  • Product Types
    • List Product Types
  • Regions
    • List Regions
    • Get a Region
  • Returns
    • Create Return
  • Return Reasons
    • List Return Reasons
    • Get a Return Reason
  • Shipping Options
    • List for Cart
    • Get Shipping Options
  • Swaps
    • Get by Cart ID
    • Create a Swap
  1. Products

List Products

GET
/store/products
Store API/ProductsProducts
Retrieves a list of products. The products can be filtered by fields such as id or q. The products can also be sorted or paginated.
This API Route can also be used to retrieve a product by its handle.
For accurate and correct pricing of the products based on the customer's context, it's highly recommended to pass fields such as
region_id, currency_code, and cart_id when available.
Passing sales_channel_id ensures retrieving only products available in the specified sales channel.
You can alternatively use a publishable API key in the request header instead of passing a sales_channel_id.

Request

Query Params
q
string 
optional
term used to search products' title, description, variant's title, variant's sku, and collection's title.
id
string 
optional
Filter by IDs.
sales_channel_id
array[string]
optional
Filter by sales channel IDs. When provided, only products available in the selected sales channels are retrieved. Alternatively, you can pass a publishable API key in the request header and this will have the same effect.
collection_id
array[string]
optional
Filter by product collection IDs. When provided, only products that belong to the specified product collections are retrieved.
type_id
array[string]
optional
Filter by product type IDs. When provided, only products that belong to the specified product types are retrieved.
tags
array[string]
optional
Filter by product tag IDs. When provided, only products that belong to the specified product tags are retrieved.
title
string 
optional
Filter by title.
description
string 
optional
Filter by description
handle
string 
optional
Filter by handle.
is_giftcard
string 
optional
Whether to retrieve regular products or gift-card products.
lt
array[string]
optional
filter by dates less than this date
Example:
["",""]
gt
array[string]
optional
filter by dates greater than this date
Example:
["",""]
lte
array[string]
optional
filter by dates less than or equal to this date
Example:
["",""]
gte
array[string]
optional
filter by dates greater than or equal to this date
Example:
["",""]
category_id
array[string]
optional
Filter by product category IDs. When provided, only products that belong to the specified product categories are retrieved.
include_category_children
string 
optional
Whether to include child product categories when filtering using the category_id field.
offset
integer 
optional
The number of products to skip when retrieving the products.
limit
integer 
optional
Limit the number of products returned.
expand
string 
optional
Comma-separated relations that should be expanded in the returned products.
fields
string 
optional
Comma-separated fields that should be included in the returned products.
order
string 
optional
A product field to sort-order the retrieved products by.
cart_id
string 
optional
The ID of the cart. This is useful for accurate pricing based on the cart's context.
region_id
string 
optional
The ID of the region. This is useful for accurate pricing based on the selected region.
currency_code
string 
optional
A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request GET '/store/products'

Responses

🟢200OK
application/json
Body
The list of products with pagination fields.
count
integer 
required
The total number of items available
offset
integer 
required
The number of products skipped when retrieving the products.
limit
integer 
required
The number of items per page
products
array[object (Priced Product) {35}] 
required
An array of products details.
id
string 
required
产品的ID。
Example:
prod_01G1G5V2MBA328390B5AXJ610F
title
string 
required
可以显示的标题，以便于识别产品。
Example:
Medusa Coffee Mug
subtitle
string  | null 
required
可用于进一步指定产品的可选副标题。
description
string  | null 
required
产品的简短描述。
Example:
Every programmer's best friend.
handle
string  | null 
required
产品的唯一标识符。
Example:
coffee-mug
is_giftcard
boolean 
required
产品是否代表礼品卡。代表礼品卡的产品在购买后将自动生成可兑换的礼品卡代码。
Default:
false
thumbnail
string <uri> | null 
required
可用于标识产品的图像文件的URL。
profile_id
string 
required
产品所属的装运配置文件的ID。装运配置文件有一组定义的装运选项，可用于完成产品。
Example:
sp_01G1G5V239ENSZ5MV4JAR737BM
weight
number  | null 
required
产品的重量。可用于运费计算。
Example:
null
length
number  | null 
required
产品的长度。可用于运费计算。
Example:
null
height
number  | null 
required
产品的高度。可用于运费计算。
Example:
null
width
number  | null 
required
产品的宽度。可用于运费计算。
Example:
null
hs_code
string  | null 
required
The 产品的协调制度代码。可由履行提供商用于将海关信息传递给运输承运人。 System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
Example:
null
origin_country
string  | null 
required
产品的生产国。可由履行提供商用于将海关信息传递给运输承运人。
Example:
null
mid_code
string  | null 
required
制造商识别码，用于识别产品的制造商。可由履行提供商用于将海关信息传递给运输承运人。
Example:
null
material
string  | null 
required
产品所用的材料和成分可由履行提供商用于将海关信息传递给运输承运人。
Example:
null
collection_id
string  | null 
required
产品所属的产品集合的ID。
Example:
pcol_01F0YESBFAZ0DV6V831JXWH0BG
type_id
string  | null 
required
产品所属的产品类型的ID。
Example:
ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
discountable
boolean 
required
产品是否可以打折。当此标志设置为“false”时，折扣将不适用于本产品的行项目。
Default:
true
external_id
string  | null 
required
产品的外部ID
Example:
null
created_at
string <date-time>
required
创建资源的日期和时区。
updated_at
string <date-time>
required
更新资源的日期和时区。
deleted_at
string <date-time> | null 
required
删除资源的日期和时区。
status
enum<string> 
required
产品的状态
Allowed values:
draftproposedpublishedrejected
Default:
draft
metadata
object  | null 
required
带有附加详细信息的可选键值映射
Example:
{"car":"white"}
categories
array[object (Product Category) {15}] 
optional
此产品所属的产品类别的详细信息。
profile
object 
Shipping Profile
optional
A Shipping Profile has a set of defined Shipping Options that can be used to fulfill a given set of Products. For example, gift cards are shipped differently than physical products, so a shipping profile with the type gift_card groups together the shipping options that can only be used for gift cards.
profiles
array[object (Shipping Profile) {9}]  | null 
optional
collection
object 
Product Collection
optional
A Product Collection allows grouping together products for promotional purposes. For example, an admin can create a Summer collection, add products to it, and showcase it on the storefront.
type
object 
Product Type
optional
A Product Type can be added to Products for filtering and reporting purposes.
tags
array[object (Product Tag) {6}] 
optional
此产品中使用的产品标签的详细信息。
images
array[object (Image) {6}] 
optional
options
array[object (Product Option) {9}] 
optional
为产品定义的产品选项的详细信息。产品将具有产品选项值的独特组合。
sales_channels
array[object (Sales Channel) {9}] 
optional
有关此产品销售渠道的详细信息
variants
array[object (Priced Product Variant) {35}] 
optional
The product variants and their prices.
Example
{
  "count": 0,
  "offset": 0,
  "limit": 0,
  "products": [
    {
      "id": "prod_01G1G5V2MBA328390B5AXJ610F",
      "title": "Medusa Coffee Mug",
      "subtitle": "string",
      "description": "Every programmer's best friend.",
      "handle": "coffee-mug",
      "is_giftcard": false,
      "thumbnail": "http://example.com",
      "profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
      "weight": null,
      "length": null,
      "height": null,
      "width": null,
      "hs_code": null,
      "origin_country": null,
      "mid_code": null,
      "material": null,
      "collection_id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
      "type_id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
      "discountable": true,
      "external_id": null,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "deleted_at": "2019-08-24T14:15:22Z",
      "status": "draft",
      "metadata": {
        "car": "white"
      },
      "categories": [
        {
          "id": "pcat_01G2SG30J8C85S4A5CHM2S1NS2",
          "name": "Regular Fit",
          "description": "",
          "handle": "regular-fit",
          "mpath": "pcat_id1.pcat_id2.pcat_id3",
          "is_internal": false,
          "is_active": false,
          "rank": 0,
          "parent_category_id": null,
          "parent_category": {},
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "category_children": [
            {}
          ],
          "products": [
            {}
          ],
          "metadata": {
            "car": "white"
          }
        }
      ],
      "profile": {
        "id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
        "name": "Default Shipping Profile",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "deleted_at": "2019-08-24T14:15:22Z",
        "type": "default",
        "products": [
          {}
        ],
        "shipping_options": [
          {}
        ],
        "metadata": {
          "car": "white"
        }
      },
      "profiles": [
        {
          "id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
          "name": "Default Shipping Profile",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "deleted_at": "2019-08-24T14:15:22Z",
          "type": "default",
          "products": [
            {}
          ],
          "shipping_options": [
            {}
          ],
          "metadata": {
            "car": "white"
          }
        }
      ],
      "collection": {
        "id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
        "title": "Summer Collection",
        "handle": "summer-collection",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "deleted_at": "2019-08-24T14:15:22Z",
        "products": [
          {}
        ],
        "metadata": {
          "car": "white"
        }
      },
      "type": {
        "id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
        "value": "Clothing",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "deleted_at": "2019-08-24T14:15:22Z",
        "metadata": {
          "car": "white"
        }
      },
      "tags": [
        {
          "id": "ptag_01G8K2MTMG9168F2B70S1TAVK3",
          "value": "Pants",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "deleted_at": "2019-08-24T14:15:22Z",
          "metadata": {
            "car": "white"
          }
        }
      ],
      "images": [
        {
          "id": "img_01G749BFYR6T8JTVW6SGW3K3E6",
          "url": "http://example.com",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "deleted_at": "2019-08-24T14:15:22Z",
          "metadata": {
            "car": "white"
          }
        }
      ],
      "options": [
        {
          "id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
          "title": "Size",
          "product_id": "prod_01G1G5V2MBA328390B5AXJ610F",
          "product": {},
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "deleted_at": "2019-08-24T14:15:22Z",
          "metadata": {
            "car": "white"
          },
          "values": [
            {
              "id": "optval_01F0YESHR7S6ECD03RF6W12DSJ",
              "value": "large",
              "option_id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
              "option": {},
              "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
              "variant": {},
              "created_at": "2019-08-24T14:15:22Z",
              "updated_at": "2019-08-24T14:15:22Z",
              "deleted_at": "2019-08-24T14:15:22Z",
              "metadata": {
                "car": "white"
              }
            }
          ]
        }
      ],
      "sales_channels": [
        {
          "id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
          "name": "Market",
          "description": "Multi-vendor market",
          "is_disabled": false,
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "deleted_at": "2019-08-24T14:15:22Z",
          "metadata": {
            "car": "white"
          },
          "locations": [
            {
              "id": "scloc_01G8X9A7ESKAJXG2H0E6F1MW7A",
              "sales_channel_id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
              "location_id": "string",
              "sales_channel": {},
              "created_at": "2019-08-24T14:15:22Z",
              "updated_at": "2019-08-24T14:15:22Z",
              "deleted_at": "2019-08-24T14:15:22Z"
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
          "title": "Small",
          "product_id": "prod_01G1G5V2MBA328390B5AXJ610F",
          "product": {},
          "sku": "shirt-123",
          "barcode": null,
          "ean": null,
          "upc": null,
          "variant_rank": 0,
          "inventory_quantity": 100,
          "allow_backorder": false,
          "manage_inventory": true,
          "hs_code": null,
          "origin_country": null,
          "mid_code": null,
          "material": null,
          "weight": null,
          "length": null,
          "height": null,
          "width": null,
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "deleted_at": "2019-08-24T14:15:22Z",
          "purchasable": true,
          "metadata": {
            "car": "white"
          },
          "options": [
            {
              "id": "optval_01F0YESHR7S6ECD03RF6W12DSJ",
              "value": "large",
              "option_id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
              "option": {},
              "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
              "variant": {},
              "created_at": "2019-08-24T14:15:22Z",
              "updated_at": "2019-08-24T14:15:22Z",
              "deleted_at": "2019-08-24T14:15:22Z",
              "metadata": {
                "car": "white"
              }
            }
          ],
          "inventory_items": [
            {
              "id": "pvitem_01G8X9A7ESKAJXG2H0E6F1MW7A",
              "inventory_item_id": "string",
              "variant_id": "string",
              "variant": {},
              "required_quantity": 1,
              "created_at": "2019-08-24T14:15:22Z",
              "updated_at": "2019-08-24T14:15:22Z",
              "deleted_at": "2019-08-24T14:15:22Z"
            }
          ],
          "prices": [
            {
              "id": "ma_01F0YESHRFQNH5S8Q0PK84YYZN",
              "amount": 100,
              "min_quantity": 1,
              "max_quantity": 1,
              "price_list_id": "pl_01G8X3CKJXCG5VXVZ87H9KC09W",
              "price_list": {},
              "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
              "variant": {},
              "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
              "region": {},
              "created_at": "2019-08-24T14:15:22Z",
              "updated_at": "2019-08-24T14:15:22Z",
              "deleted_at": "2019-08-24T14:15:22Z",
              "currency_code": "usd",
              "currency": {
                "symbol": "$",
                "symbol_native": "$",
                "name": "US Dollar",
                "includes_tax": false,
                "code": "usd"
              }
            }
          ],
          "original_price": 0,
          "calculated_price": 0,
          "original_price_incl_tax": 0,
          "calculated_price_incl_tax": 0,
          "original_tax": 0,
          "calculated_tax": 0,
          "tax_rates": [
            {
              "rate": 0,
              "name": "string",
              "code": "string"
            }
          ]
        }
      ]
    }
  ]
}
🟠400Client Error or Multiple Errors
🟠404Not Found Error
🟠409Invalid State Error
🟠422Invalid Request Error
🔴500Server Error
Modified at 2024-05-23 07:10:14
Previous
Search Products
Next
Get a Product
Built with