Medusa
Store APIAdmin API
Store APIAdmin API
Discord
Twitter
Linkedin
Github
  1. Product Categories
  • Plugins
    • List Plugins
      GET
  • Auth
    • Refresh Authentication Token
      POST
    • Validate Authentication Callback
      POST
    • Generate Reset Password Token for Admin User
      POST
    • Retrieve Registration JWT Token
      POST
    • Authenticate User
      POST
    • Set Authentication Session
      POST
    • Delete Authentication Session
      DELETE
    • Reset an Admin User's Password
      POST
  • Draft Orders
    • Create a Draft Order Edit
      POST
    • Cancel Edit on Draft Order
      DELETE
    • Confirm an Edit on a Draft Order
      POST
    • Request Edit on Draft Order
      POST
    • Convert a Draft Order to an Order
      POST
    • Add Item to Draft Order Edit
      POST
    • Update Existing Item in Draft Order Edit
      POST
    • Remove Item from Draft Order Edit
      DELETE
    • Update New Item in Draft Order Edit
      POST
    • Add Promotions to Draft Order Edit
      POST
    • Remove Promotions from Draft Order Edit
      DELETE
    • Add Shipping Method to Draft Order Edit
      POST
    • Remove Shipping Method from Draft Order Edit
      DELETE
    • Update Existing Shipping Method in Draft Order Edit
      POST
    • Remove New Shipping Method from Draft Order
      DELETE
    • Update New Shipping Method in Draft Order Edit
      POST
    • Delete a Draft Order
      DELETE
    • Get a Draft Order
      GET
    • Update a Draft Order
      POST
    • Create Draft Order
      POST
    • List Draft Orders
      GET
  • Fulfillment Providers
    • List Fulfillment Options
    • List Fulfillment Providers
  • Fulfillment Sets
    • Delete Fulfillment Set
    • Add a Service Zone to a Fulfillment Set
    • Remove a Service Zone from Fulfillment Set
    • Get a Service Zone in a Fulfillment Set
    • Update the Service Zone of a Fulfillment Set
  • Inventory Items
    • Manage Inventory Levels
    • Manage Inventory Levels of Inventory Item
    • Create Inventory Level for Inventory Item
    • List Inventory Levels
    • Update an Inventory Level of an Inventory Item
    • Remove Inventory Level of Inventory Item
    • Create Inventory Item
    • List Inventory Items
    • Get a Inventory Item
    • Delete Inventory Item
    • Update an Inventory Item
  • Order Edits
    • Create Order Edit
    • Confirm Order Edit
    • Request Order Edit
    • Add Items to Order Edit
    • Update Order Item Quantity of Order Edit
    • Remove Item from Order Edit
    • Update an Item in an Order Edit
    • Add Shipping Method to Order Edit
    • Remove Shipping Method from Order Edit
    • Update Shipping Method of an Order Edit
    • Cancel Order Edit
  • Orders
    • List Changes on an Order
    • Mark a Fulfillment as Delivered.
    • Get Preview
    • Archive an Order
    • Cancel Order
    • Cancel Transfer Request
    • Create Credit Line for Order
    • Request Order Transfer
    • Complete Order
    • Update Order
    • Get an Order
    • List Line Items
    • Cancel Fulfillment
    • Create an Order Fulfillment
    • Create Shipment for an Order's Fulfillment
    • List Orders
  • Payment Collections
    • Delete a Payment Collection
    • Create Payment Collection
    • Mark a Payment Collection as Paid
  • Products
    • Create Product Import
    • Confirm Product Import
    • Export Products
    • Manage Products
    • Manage Variants in a Product
    • Associate Variant with Inventory Item
    • Remove Inventory Item Association with Product Variant
    • Update Product Variant's Inventory Details
    • Delete a Product
    • Get a Product
    • Update a Product
    • Create a Product Option
    • List a Product's Options
    • Get a Product's Option
    • Delete an Option from Product
    • Update a Product's Option
    • Get Variant of a Product
    • Delete Product Variant
    • Update a Product Variant
    • Manage Variants Inventory in a Product
    • Create a Product Variant
    • List Variants of a Product
    • Create Product
    • List Products
  • Claims
    • Get a Claim
    • Cancel a Claim
    • Add Inbound Items to a Claim
    • Remove an Inbound Item from Claim
    • Update Inbound Items of a Claim
    • Add an Inbound Shipping Method to a Claim
    • Cancel Claim Request
    • Confirm a Claim Request
    • Add Claim Items to a Claim
    • Remove a Claim Item from a Claim
    • Update a Claim Item
    • Remove Inbound Shipping Method from Claim
    • Update Inbound Shipping Method of a Claim
    • Add Outbound Items to a Claim
    • Remove an Outbound Item from Claim
    • Update Outbound Item of a Claim
    • Add Outbound Shipping Methods to a Claim
    • Remove Outbound Shipping Method from Claim
    • Update Outbound Shipping Method of a Claim
    • Create a Claim
    • List Claims
  • Currencies
    • Get a Currency
    • List Currencies
  • Exchanges
    • Get an Exchange
    • Cancel an Exchange
    • Add Inbound Items to an Exchange
    • Remove Inbound Item from Exchange
    • Update an Inbount Item of an Exchange
    • Add an Inbound Shipping Method to an Exchange
    • Cancel Exchange Request
    • Confirm an Exchange
    • Remove Inbound Shipping Method from Exchange
    • Update Inbound Shipping Method of an Exchange
    • Add Outbound Items to Exchange
    • Remove Outbound Item from Exchange
    • Update Outbound Item of an Exchange
    • Add Outbound Shipping Method to Exchange
    • Remove Outbound Shipping Method from Exchange
    • Update Outbound Shipping Method of Exchange
    • Create Exchange
    • List Exchanges
  • Fulfillments
    • Cancel a Fulfillment
    • Create Fulfillment
    • Create a Shipment for a Fulfillment
  • Invites
    • Refresh Invite Token
    • Get an Invite
    • Delete Invite
    • Accept Invite
    • Create Invite
    • List Invites
  • Notifications
    • Get a Notification
    • List Notifications
  • Payments
    • Get a Payment
    • Capture Payment
    • Refund Payment
    • List Payment Providers
    • List Payments
  • Returns
    • Cancel a return.
    • Get a Return
    • Update a Return
    • Add Damaged Items to Return
    • Remove Damaged Item from Return
    • Update Damaged Item of Return
    • Add Received Items to Return
    • Remove a Received Item from Return
    • Update a Received Item in a Return
    • Confirm Return Receival
    • Add Requested Items to Return
    • Remove Item from Return
    • Update Requested Item in Return
    • Add a Shipping Method to a Return
    • Remove Shipping Method from Return
    • Update a Shipping Method of a Return
    • Start Return Receival
    • Cancel Return Receival
    • Confirm Return Request
    • Cancel Return Request
    • Create Return
    • List Returns
  • Users
    • Get Logged-In User
    • Delete a User
    • Get a User
    • Update a User
    • List Users
  • Workflows Executions
    • Get a Workflows Execution
    • Subscribe to a Workflow's Execution
    • Get Workflow Execution's Details
    • Subscribe to Step of a Workflow's Execution
    • Fail a Step in a Workflow's Execution
    • Succeed a Step in a Workflow's Execution
    • List Workflows Executions
    • Execute a Workflow
  • Api Keys
    • Revoke API Key
    • Get API Key
    • Update an API Key
    • Delete an Api Key
    • Manage Sales Channels of a Publishable API Key
    • Create Api Key
    • List API Keys
  • Price Lists
    • Remove Products from Price List
    • Delete a Price List
    • Get a Price List
    • Update a Price List
    • Manage Prices in Price List
    • Create Price List
    • List Price Lists
  • Stores
    • Get a Store
    • Update a Store
    • List Stores
  • Tax Rates
    • Create Tax Rule for a Rate
    • Delete a Tax Rate
    • Get a Tax Rate
    • Update a Tax Rate
    • Remove Rule of Tax Rate
    • Create Tax Rate
    • List Tax Rates
  • Price Preferences
    • Delete a Price Preference
    • Get a Price Preference
    • Update a Price Preference
    • Create Price Preference
    • List Price Preferences
  • Return Reasons
    • Delete a Return Reason
    • Get a Return Reason
    • Update a Return Reason
    • Create Return Reason
    • List Return Reasons
  • Sales Channels
    • Delete a Sales Channel
    • Get a Sales Channel
    • Update a Sales Channel
    • Manage Products in Sales Channel
    • Create Sales Channel
    • List Sales Channels
  • Stock Locations
    • Delete a Stock Location
    • Get a Stock Location
    • Update a Stock Location
    • Add Fulfillment Set to Stock Location
    • Manage Fulfillment Providers of a Stock Location
    • Manage Sales Channels of a Stock Location
    • Create Stock Location
    • List Stock Locations
  • Tax Regions
    • Delete a Tax Region
    • Update a Tax Region
    • Get a Tax Region
    • Create Tax Region
    • List Tax Regions
  • Promotions
    • List Rule Attribute Options of a Rule Type
    • List Rules of a Promotion
    • List Rule Values Given a Rule Attribute
    • Manage the Buy Rules of a Promotion
    • Manage a Promotion's Rules
    • Manage Target Rules of a Promotion
    • Get a Promotion
    • Delete a Promotion
    • Update a Promotion
    • List Promotions
    • Create Promotion
  • Customer Groups
    • Get a Customer Group
    • Update a Customer Group
    • Delete a Customer Group
    • Manage Customers of a Customer Group
    • Create Customer Group
    • List Customer Groups
  • Product Tags
    • Delete a Product Tag
    • Get a Product Tag
    • Update a Product Tag
    • Create Product Tag
    • List Product Tags
  • Product Types
    • Delete a Product Type
    • Get a Product Type
    • Update a Product Type
    • Create Product Type
    • List Product Types
  • Refund Reasons
    • Get a Refund Reason
    • Update a Refund Reason
    • Delete a Refund Reason
    • Create Refund Reason
    • List Refund Reasons
  • Uploads
    • Get a File
    • Delete a File
    • Upload Files
  • Campaigns
    • Manage the Promotions of a Campaign
    • Get a Campaign
    • Delete a Campaign
    • Update a Campaign
    • List Campaigns
    • Create Campaign
  • Collections
    • Manage Products of a Collection
    • Delete a Collection
    • Get a Collection
    • Update a Collection
    • Create Collection
    • List Collections
  • Customers
    • Manage Customer Groups of Customer
    • Get a Customer
    • Delete a Customer
    • Update a Customer
    • List Addresses
    • Add a Customer Address
    • List Addresses
    • Remove an Address from Customer
    • Update a Customer's Address
    • Create Customer
    • List Customers
  • Product Categories
    • Manage Products in Product Category
      POST
    • Delete a Product Category
      DELETE
    • Get a Product Category
      GET
    • Update a Product Category
      POST
    • Create Product Category
      POST
    • List Product Categories
      GET
  • Reservations
    • Get a Reservation
    • Update a Reservation
    • Delete a Reservation
    • Create Reservation
    • List Reservations
  • Shipping Profiles
    • Delete a Shipping Profile
    • Get a Shipping Profile
    • Update a Shipping Profile
    • Create Shipping Profile
    • List Shipping Profiles
  • Regions
    • Get a Region
    • Delete a Region
    • Update a Region
    • Create Region
    • List Regions
  • Tax Providers
    • List Tax Providers
  • Shipping Options
    • Manage the Rules of a Shipping Option
    • Create Shipping Option
    • List Shipping Options
    • Delete a Shipping Option
    • Get a Shipping Option
    • Update a Shipping Option
  • Product Variants
    • List Product Variants
  1. Product Categories

List Product Categories

GET
/admin/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}}/admin/product-categories'
Response Response Example
200 - Example 1
{
    "limit": 0,
    "offset": 0,
    "count": 0,
    "product_categories": [
        {
            "parent_category": {},
            "name": "string",
            "description": "string",
            "id": "string",
            "metadata": {},
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2019-08-24T14:15:22Z",
            "handle": "string",
            "deleted_at": "2019-08-24T14:15:22Z",
            "is_active": true,
            "is_internal": true,
            "rank": 0,
            "parent_category_id": "string",
            "category_children": [
                {}
            ],
            "products": [
                {}
            ]
        }
    ],
    "estimate_count": 0
}

Request

Authorization
or
or
or
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. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
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 on the product category's searchable properties.
id
optional
One of
Filter by a product category's ID.
description
optional
One of
Filter by the category's description. This performs a full-text search. To do keyword search, use the q parameter instead.
handle
optional
One of
Filter by a category's handle.
parent_category_id
optional
One of
Filter by a parent category's ID to retrieve its child categories.
include_ancestors_tree
boolean 
include_ancestors_tree
optional
Whether to include the parent category of each category. 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 include the child categories of each category. If you enable this, add to the fields query parameter category_children to set the children 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.
is_internal
boolean 
is_internal
optional
Filter by whether the category is internal.
is_active
boolean 
is_active
optional
Filter by whether the category is active.
$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
The product category's name.

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.
product_categories
array[object (AdminProductCategory) {15}] 
required
The list of product categories.
parent_category
object 
required
name
string 
name
required
The category's name.
description
string 
description
required
The category's description.
id
string 
id
required
The category's ID.
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.
handle
string 
handle
required
The category's unique handle.
deleted_at
string <date-time>
deleted_at
required
The date the category was deleted.
is_active
boolean 
is_active
required
Whether the category is active. If disabled, the category isn't shown in the storefront.
is_internal
boolean 
is_internal
required
Whether the category is internal. If enabled, the category is only seen by admin users.
rank
number 
rank
required
The category's rank among sibling categories.
parent_category_id
string 
parent_category_id
required
The ID of the category's parent.
category_children
array [object] 
required
The category's children.
products
array [object] 
optional
The category's products.
estimate_count
number 
estimate_count
optional
The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.
🟠400Bad Request
🟠401Unauthorized
🟠404Record Not Found
🟠409409
🟠422Parameter Error
🔴500Server Error
Modified at 2025-06-17 04:10:32
Previous
Create Product Category
Next
Get a Reservation
Built with