Medusa Getting Started: Setup and First API Call (2026)

Getting started overview

Medusa is an open-source headless commerce platform built with Node.js and TypeScript, designed to provide developers with a customizable backend for e-commerce applications. This guide outlines the process of initiating a Medusa project, configuring necessary credentials, and executing a foundational API request. Medusa's architecture separates the backend from the frontend, allowing for flexible storefront development using various frameworks such as React. The platform supports both self-hosted deployments and a managed cloud service, Medusa Cloud, which includes a free developer tier for initial exploration.

To begin with Medusa, developers typically undertake the following steps:

1. Backend Setup: Install the Medusa backend, either locally or by deploying to a cloud environment. This involves setting up a Medusa server and a database.
2. API Key Acquisition: For Medusa Cloud, or if using specific plugins/services, API keys may be required for authentication and access. Self-hosted instances generally manage access through direct database interaction or session-based authentication for the Admin panel.
3. Frontend Integration: Connect a storefront application to the Medusa backend using the Storefront API.
4. Initial Data Populate: Create products, collections, and other e-commerce entities to test the setup.

This page focuses on establishing a functional Medusa backend and making a basic API call to confirm the setup. For detailed instructions on deploying a production-ready environment or integrating advanced features, refer to the Medusa official documentation.

Here's a quick reference for the initial setup process:

Create an account and get keys

Medusa offers two primary deployment models: self-hosted open-source and Medusa Cloud. The process for obtaining API keys or credentials varies significantly based on this choice.

Self-Hosted Open-Source

For self-hosted Medusa instances, a direct account creation process on a central Medusa platform is generally not required for the core backend. Instead, you manage access and user accounts within your own deployed instance:

1. Backend Installation: Begin by installing the Medusa backend using the Medusa CLI. This typically involves running npx @medusajs/create-medusa-app and following the prompts to set up a new project with a database (e.g., PostgreSQL). Consult the Medusa backend setup documentation for detailed steps.
2. Admin User Creation: After the backend is set up and running, you'll create an administrator user for your Medusa Admin panel. This is often done via a CLI command, such as medusa user --email [email protected] --password supersecret --role admin, or through the initial setup wizard of the Medusa Admin storefront. This user provides access to the graphical interface for managing products, orders, and other e-commerce entities.
3. API Interaction: For public Storefront API endpoints (e.g., retrieving products), no specific key is typically required by default. For authenticated Admin API endpoints, you'll use the session generated by logging in via the Admin panel, or develop custom authentication flows.

Medusa Cloud

Medusa Cloud provides a managed environment for your Medusa instances, simplifying deployment and scaling. It includes a free developer tier:

1. Sign Up for Medusa Cloud: Navigate to the Medusa Cloud pricing page and select the Developer Free Tier or a suitable plan. Follow the registration process to create an account. This will typically involve providing an email address and setting a password.
2. Project Creation: Once logged into the Medusa Cloud dashboard, you can create a new project. This process provisions a Medusa backend instance for you.
3. API Key Retrieval: Within your Medusa Cloud project dashboard, you will find sections for API keys. Medusa Cloud typically provides different types of keys or tokens for accessing your Storefront API and potentially for administrative actions, depending on the scope. Look for sections labeled "API Keys" or "Credentials."
4. Configuration: Note down your API keys and the unique URL for your Medusa Cloud instance. These will be used to configure your storefront or any client application interacting with your Medusa backend.

Your first request

After setting up your Medusa backend, whether self-hosted or via Medusa Cloud, you can make a simple API request to confirm that the service is operational and accessible. This example focuses on fetching a list of products from the Storefront API, which is typically publicly accessible without specific API keys for read operations.

Prerequisites

• Your Medusa backend server must be running. If self-hosting, ensure you've started it (e.g., medusa develop). If using Medusa Cloud, your instance should be provisioned and active.
• You need a product in your Medusa instance to get a meaningful response. If you just set up a new instance, you can create a product via the Medusa Admin panel or use the seed data if your setup included it.
• The base URL for your Medusa Storefront API. For local development, this is typically http://localhost:9000. For Medusa Cloud, it will be a URL provided in your dashboard (e.g., https://your-project-id.medusajs.com).

Making the Request

We will use a simple HTTP GET request to the /store/products endpoint.

Using curl (Command Line)

Open your terminal or command prompt and execute the following command, replacing [YOUR_MEDUSA_BACKEND_URL] with your actual backend URL:

curl -X GET "[YOUR_MEDUSA_BACKEND_URL]/store/products"

For a local development setup, this would look like:

curl -X GET "http://localhost:9000/store/products"

Expected Response

A successful response (HTTP status code 200 OK) will return a JSON object containing an array of products:

{
  "products": [
    {
      "id": "prod_01G3K123456789ABCDEFHIJKL",
      "title": "Medusa T-Shirt",
      "handle": "medusa-t-shirt",
      "status": "published",
      "description": "A comfortable t-shirt from Medusa.",
      "thumbnail": null,
      "profile_id": "sp_01G3K123456789ABCDEFHIJKL",
      "collection_id": null,
      "type_id": null,
      "weight": null,
      "length": null,
      "height": null,
      "width": null,
      // ... other product details
    }
  ],
  "count": 1,
  "offset": 0,
  "limit": 100
}

If you receive an empty products array, it likely means no products have been added to your Medusa instance yet. If you encounter connectivity issues, refer to the Troubleshooting the first call section.

Using JavaScript (Browser or Node.js with fetch)

You can also make this request programmatically. In a browser's developer console or a Node.js environment:

fetch('[YOUR_MEDUSA_BACKEND_URL]/store/products')
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error('Error fetching products:', error));

Remember to replace [YOUR_MEDUSA_BACKEND_URL] with your specific URL.

Common next steps

Once you've successfully made your first API call, you've established basic connectivity with your Medusa backend. The next steps typically involve extending your e-commerce functionality:

1. Build a Storefront: Integrate a frontend application with your Medusa backend. Medusa provides starter templates for Next.js and Gatsby, which can accelerate development.
2. Explore the Admin Panel: Set up and use the Medusa Admin dashboard to manage products, orders, customers, and other store settings. This provides a user interface for non-developers to manage the store.
3. Add Plugins and Integrations: Medusa's modular architecture allows for the addition of plugins for payment gateways (e.g., Stripe, PayPal), shipping providers, notification services, and more. Explore the Medusa plugin documentation for a list of available integrations.
4. Implement Advanced Features: Develop custom functionalities such as wishlists, product comparisons, or loyalty programs using Medusa's extensive API and event system.
5. Authentication and User Management: Implement user authentication for your storefront, allowing customers to create accounts, manage their orders, and save preferences. The Medusa Storefront API reference provides details on authentication endpoints.
6. Deployment and Scaling: Plan for deploying your Medusa backend and storefront to a production environment. Consider hosting options and scaling strategies as your store grows. For platform-as-a-service options, services like Render or Heroku, or more robust cloud providers like Amazon Web Services or Google Cloud, can host your Medusa components.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some frequent problems and their solutions:

• "Connection refused" or "Failed to fetch":
  • Backend not running: Ensure your Medusa backend server is actively running. If self-hosting, navigate to your backend project directory in the terminal and run medusa develop. For Medusa Cloud, verify your instance status in the dashboard.
  • Incorrect URL: Double-check the base URL for your Medusa backend. For local development, it's typically http://localhost:9000. For Medusa Cloud, confirm the URL provided in your project dashboard.
  • Port conflict: If self-hosting, another application might be using port 9000. Check your system's port usage or configure Medusa to run on a different port.
• Empty products array in response:
  • No products created: Your Medusa instance might not have any products yet. Use the Medusa Admin panel to create a test product, or use Medusa's seeding capabilities to populate initial data.
  • Product status: Ensure any created products are set to 'published' status so they are visible via the Storefront API.
• CORS Policy Error (Cross-Origin Resource Sharing):
  • This typically occurs when your frontend application is trying to access a Medusa backend on a different domain or port. For self-hosted instances, you need to configure the MEDUSA_CORS_ORIGINS environment variable in your medusa-config.js file to include the domain(s) of your frontend application. For example: MEDUSA_CORS_ORIGINS=http://localhost:8000,https://your-storefront-domain.com. Refer to the Medusa CORS configuration guide.
  • On Medusa Cloud, CORS settings are usually managed through the platform's dashboard or configuration options.
• 404 Not Found:
  • Incorrect endpoint: Verify that the API endpoint you are calling (e.g., /store/products) is correct and matches the Medusa Storefront API reference.
  • Backend routing issue: Ensure all necessary Medusa modules and plugins are correctly installed and loaded, as they define API routes.
• Authentication Errors (e.g., 401 Unauthorized):
  • While /store/products doesn't usually require authentication, other endpoints (especially in the Admin API) do. If you're experimenting with authenticated endpoints, ensure you're providing valid authentication tokens or session cookies.

For more in-depth troubleshooting or specific error messages, the Medusa documentation and community forums are valuable resources.