Medusa
Store APIAdmin API
Store APIAdmin API
Discord
Twitter
Linkedin
Github
  1. Product Categories
  • Introduction
  • Authentication
  • HTTP Compression
  • Publishable API Key
  • Expanding Fields
  • Selecting Fields
  • Query Parameter Types
  • Pagination
  • Currencies
    • List Currencies
      GET
    • Get a Currency
      GET
  • Payment Providers
    • List Payment Providers
      GET
  • Return Reasons
    • List Return Reasons
      GET
    • Get a Return Reason
      GET
  • Auth
    • Retrieve Registration JWT Token
      POST
    • Authenticate Customer
      POST
    • Generate Reset Password Token for Customer
      POST
    • Refresh Authentication Token
      POST
    • Validate Authentication Callback
      POST
    • Delete Authentication Session
      DELETE
    • Set Authentication Session
      POST
    • Reset a Customer's Password
      POST
  • Collections
    • List Collections
      GET
    • Get a Collection
      GET
  • Regions
    • List Regions
    • Get a Region
  • Products
    • List Products
    • Get a Product
  • Customers
    • Get Logged-in Customer
    • Update Customer
    • Create Address for Logged-In Customer
    • List Customer's Addresses
    • Get Customer's Address
    • Update Customer's Address
    • Remove Customer's Address
    • Register Customer
  • Product Tags
    • List Product Tags
    • Get a Product Tag
  • Returns
    • Create Return
  • Product Types
    • Get a Product Type
    • List Product Types
  • Product Categories
    • List Product Categories
      GET
    • Get a Product Category
      GET
  • Carts
    • Create Cart
    • Set Cart's Customer
    • Add Shipping Method to Cart
    • Add Line Item to Cart
    • Calculate Cart Taxes
    • Get a Cart
    • Update a Cart
    • Update a Line Item in a Cart
    • Remove Line Item from Cart
    • Complete Cart
    • Add Promotions to Cart
    • Remove Promotions from Cart
  • Orders
    • List Logged-in Customer's Orders
    • Request Order Transfer
    • Get an Order
    • Cancel Order Transfer
    • Decline Order Transfer
    • Accept Order Transfer
  • Payment Collections
    • Initialize Payment Session of a Payment Collection
    • Create Payment Collection
  • Shipping Options
    • Calculate Shipping Option Price
    • List Shipping Options for Cart
  1. Product Categories

List Product Categories

GET
/store/product-categories
Product Categories
Retrieve a list of product categories. The product categories can be filtered by fields such as id. The product categories can also be sorted or paginated.
Request Request Example
JavaScript
Shell
Java
Swift
curl --location -g --request GET '{{BASE_URL}}/store/product-categories' \
--header 'x-publishable-api-key;'
Response Response Example
200 - Example 1
{
    "limit": 0,
    "offset": 0,
    "count": 0,
    "estimate_count": 0,
    "product_categories": [
        {
            "id": "string",
            "name": "string",
            "description": "string",
            "handle": "string",
            "rank": 0,
            "parent_category_id": "string",
            "parent_category": {},
            "metadata": {},
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2019-08-24T14:15:22Z",
            "deleted_at": "2019-08-24T14:15:22Z",
            "category_children": [
                {}
            ],
            "products": [
                {
                    "length": 0,
                    "title": "string",
                    "description": "string",
                    "id": "string",
                    "metadata": {},
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "handle": "string",
                    "subtitle": "string",
                    "is_giftcard": true,
                    "thumbnail": "string",
                    "width": 0,
                    "weight": 0,
                    "height": 0,
                    "origin_country": "string",
                    "hs_code": "string",
                    "mid_code": "string",
                    "material": "string",
                    "collection_id": "string",
                    "type_id": "string",
                    "discountable": true,
                    "external_id": "string",
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "categories": [
                        {}
                    ],
                    "status": "draft",
                    "images": [
                        {
                            "id": "string",
                            "url": "string",
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z",
                            "metadata": {},
                            "rank": 0
                        }
                    ],
                    "tags": [
                        {
                            "id": "string",
                            "value": "string",
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z",
                            "metadata": {}
                        }
                    ],
                    "collection": {
                        "id": "string",
                        "title": "string",
                        "handle": "string",
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "deleted_at": "2019-08-24T14:15:22Z",
                        "metadata": {},
                        "products": [
                            {}
                        ]
                    },
                    "type": {
                        "id": "string",
                        "metadata": {},
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "deleted_at": "2019-08-24T14:15:22Z",
                        "value": "string"
                    },
                    "options": [
                        {
                            "id": "string",
                            "title": "string",
                            "product": {},
                            "product_id": "string",
                            "metadata": {},
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z",
                            "values": [
                                {
                                    "id": "string",
                                    "value": "string",
                                    "option": {},
                                    "option_id": "string",
                                    "metadata": {},
                                    "created_at": "2019-08-24T14:15:22Z",
                                    "updated_at": "2019-08-24T14:15:22Z",
                                    "deleted_at": "2019-08-24T14:15:22Z"
                                }
                            ]
                        }
                    ],
                    "variants": [
                        {
                            "product": {},
                            "length": 0,
                            "title": "string",
                            "metadata": {},
                            "id": "string",
                            "width": 0,
                            "weight": 0,
                            "height": 0,
                            "origin_country": "string",
                            "hs_code": "string",
                            "mid_code": "string",
                            "material": "string",
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z",
                            "product_id": "string",
                            "sku": "string",
                            "barcode": "string",
                            "ean": "string",
                            "upc": "string",
                            "allow_backorder": true,
                            "variant_rank": 0,
                            "manage_inventory": true,
                            "inventory_quantity": 0,
                            "options": [
                                {
                                    "id": "string",
                                    "value": "string",
                                    "option": {},
                                    "option_id": "string",
                                    "metadata": {},
                                    "created_at": "2019-08-24T14:15:22Z",
                                    "updated_at": "2019-08-24T14:15:22Z",
                                    "deleted_at": "2019-08-24T14:15:22Z"
                                }
                            ],
                            "calculated_price": {
                                "id": "string",
                                "is_calculated_price_price_list": true,
                                "is_calculated_price_tax_inclusive": true,
                                "calculated_amount": 0,
                                "calculated_amount_with_tax": 0,
                                "calculated_amount_without_tax": 0,
                                "is_original_price_price_list": true,
                                "is_original_price_tax_inclusive": true,
                                "original_amount": 0,
                                "currency_code": "usd",
                                "calculated_price": {},
                                "original_price": {},
                                "original_amount_with_tax": 0,
                                "original_amount_without_tax": 0
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Request

Query Params
fields
string 
fields
optional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offset
number 
offset
optional
The number of items to skip when retrieving a list.
limit
number 
limit
optional
Limit the number of items returned in the list.
order
string 
order
optional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
q
string 
q
optional
Search term to filter the product category's properties.
id
optional
One of
Filter by a product category's ID.
description
optional
One of
Filter by a description. This only matches categories with the exact description. To search by a term or keyword, use the q query parameter instead.
handle
optional
One of
Filter by a category's handle.
parent_category_id
optional
One of
The ID of a category to retrieve its child categories.
include_ancestors_tree
boolean 
include_ancestors_tree
optional
Whether to retrieve the category's parent. If you enable this, add to the fields query parameter parent_category to set the parent of a category in this field. You can either pass *parent_category to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, fields=parent_category.id,parent_category.name.
include_descendants_tree
boolean 
include_descendants_tree
optional
Whether to retrieve a list of child categories. If you enable this, add to the fields query parameter category_children to set the child of a category in this field. You can either pass *category_children to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, fields=category_children.id,category_children.name.
$ne
array[string]
optional
Filter by values not equal to this parameter.
Example:
["",""]
$gt
array[string]
optional
Filter by values greater than this parameter. Useful for numbers and dates only.
Example:
["",""]
$gte
array[string]
optional
Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
Example:
["",""]
$lt
array[string]
optional
Filter by values less than this parameter. Useful for numbers and dates only.
Example:
["",""]
$lte
array[string]
optional
Filter by values less than or equal to this parameter. Useful for numbers and dates only.
Example:
["",""]
$like
array[string]
optional
Apply a like filter. Useful for strings only.
Example:
["",""]
$re
array[string]
optional
Apply a regex filter. Useful for strings only.
Example:
["",""]
$ilike
array[string]
optional
Apply a case-insensitive like filter. Useful for strings only.
Example:
["",""]
$fulltext
array[string]
optional
Filter to apply on full-text properties.
Example:
["",""]
$exists
array[string]
optional
Filter by whether a value for this parameter exists (not null).
Example:
["",""]
$and
array [object] 
$and
optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
Example:
["",""]
$or
array [object] 
$or
optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
Example:
["",""]
$in
array[string]
optional
Filter by values in this array.
Example:
["",""]
$nin
array[string]
optional
Filter by values not in this array.
Example:
["",""]
$overlap
array[string]
optional
Filter arrays that have overlapping values with this parameter.
Example:
["",""]
$contains
array[string]
optional
Filter arrays that contain some of the values of this parameter.
Example:
["",""]
$contained
array[string]
optional
Filter arrays that contain all values of this parameter.
Example:
["",""]
$eq
array[string]
optional
Example:
["",""]
$not
array[string]
optional
Example:
["",""]
name
optional
One of
Filter by a product category name.
Header Params
x-publishable-api-key
string 
required
Publishable API Key created in the Medusa Admin.

Responses

🟢200OK
application/json
OK
Body
The paginated list of product categories.
limit
number 
limit
required
The maximum number of items returned.
offset
number 
offset
required
The number of items skipped before retrieving the returned items.
count
number 
count
required
The total number of items.
estimate_count
number 
estimate_count
optional
The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.
product_categories
array[object (StoreProductCategory) {13}] 
required
The list of product categories.
id
string 
id
required
The category's ID.
name
string 
name
required
The category's name.
description
string 
description
required
The category's description.
handle
string 
handle
required
The category's handle.
rank
number 
rank
required
The category's rank.
parent_category_id
string 
parent_category_id
required
The ID of the category's parent.
parent_category
object 
required
metadata
object 
optional
The category's metadata, can hold custom key-value pairs.
created_at
string <date-time>
created_at
required
The date the category was created.
updated_at
string <date-time>
updated_at
required
The date the category was updated.
deleted_at
string <date-time>
deleted_at
required
The date the category was deleted.
category_children
array [object] 
required
The category's children.
products
array[object (StoreProduct) {31}] 
optional
The category's products.
🟠400Bad Request
🟠401Unauthorized
🟠404Record Not Found
🟠409409
🟠422Parameter Error
🔴500Server Error
Modified at 2025-06-17 04:21:30
Previous
List Product Types
Next
Get a Product Category
Built with