Skip to main content

​
Introduction

The Medusa API is a RESTful API that provides programmatic access to your commerce backend. It consists of two main sections:
  • Admin API: For managing your store’s products, orders, customers, and other resources
  • Store API: For building storefronts and customer-facing applications

​
Base URLs

The API is accessible through the following base URLs: 
Admin API: http://localhost:9000/admin
Store API: http://localhost:9000/store
Auth API:  http://localhost:9000/auth
Replace localhost:9000 with your Medusa backend URL in production.

​
Request Format

All API requests should include the following headers: 
Content-Type: application/json
Accept: application/json

​
Request Body

For POST, PUT, and PATCH requests, the request body should be formatted as JSON: 
{
  "title": "My Product",
  "description": "A great product",
  "status": "published"
}

​
Query Parameters

Most list endpoints support the following query parameters:
​
fields
string
Comma-separated list of fields to include in the response. Use dot notation for nested fields (e.g., id,title,variants.sku).
​
limit
number
default:"15"
Maximum number of items to return.
​
offset
number
default:"0"
Number of items to skip before starting to return results.
​
order
string
Sort order for results (e.g., created_at or -created_at for descending).

​
Response Format

All API responses are returned in JSON format with a consistent structure.

​
Successful Response

Single resource responses: 
{
  "product": {
    "id": "prod_123",
    "title": "My Product",
    "status": "published"
  }
}
List responses include pagination metadata: 
{
  "products": [
    {
      "id": "prod_123",
      "title": "Product 1"
    },
    {
      "id": "prod_124",
      "title": "Product 2"
    }
  ],
  "count": 100,
  "offset": 0,
  "limit": 15
}
​
count
number
Total number of items matching the query.
​
offset
number
Number of items skipped.
​
limit
number
Maximum number of items returned.

​
Error Response

When an error occurs, the API returns an error response: 
{
  "type": "not_found",
  "message": "Product with id: prod_123 was not found"
}
​
type
string
The error type. Common types include:
  • not_found - Resource not found
  • invalid_data - Invalid request data
  • not_allowed - Operation not permitted
  • unauthorized - Authentication required
​
message
string
Human-readable error message.

​
HTTP Status Codes

The API uses standard HTTP status codes:
Status CodeDescription
200Success
201Resource created
400Bad request - Invalid parameters
401Unauthorized - Authentication required
403Forbidden - Insufficient permissions
404Not found - Resource doesn’t exist
409Conflict - Resource already exists
500Internal server error
Many list endpoints support filtering using query parameters: 
# Filter products by status
GET /admin/products?status=published

# Filter by multiple values
GET /admin/products?status[]=published&status[]=draft

# Filter orders by date range
GET /admin/orders?created_at[gte]=2024-01-01

​
Field Selection

Use the fields parameter to optimize responses by requesting only needed fields: 
# Request specific fields
GET /admin/products?fields=id,title,status

# Request nested fields
GET /admin/products?fields=id,title,variants.id,variants.sku

​
Rate Limiting

Rate limits may apply depending on your Medusa deployment configuration. When rate limited, the API returns a 429 Too Many Requests status code.

​
Next Steps

Authentication

Learn how to authenticate API requests

Admin API

Explore the Admin API endpoints

Store API

Explore the Store API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us