This API reference includes Medusa's Store APIs, which are REST APIs exposed by the Medusa backend. They are typically used to create a storefront for your commerce store, such as a webshop or a commerce mobile app.

All API Routes are prefixed with /store. So, during development, the API Routes will be available under the path http://localhost:9000/store. For production, replace http://localhost:9000 with your Medusa backend URL.

There are different ways you can send requests to these API Routes, including:

• Using Medusa's JavaScript Client
• Using the Medusa React library
• Using cURL

Aside from this API reference, check out the Commerce Modules section of the documentation for guides on how to use these APIs in different scenarios.

Authentication

There are two ways to send authenticated requests to the Medusa server: Using a JWT token or using a Cookie Session ID.

JWT Token

Use a JWT token to send authenticated requests. Authentication state is managed by the client, which is ideal for Jamstack applications and mobile applications.

How to Obtain the JWT Token

JWT tokens are obtained by sending a request to the Customer Login (JWT) API Route passing it the customer's email and password in the request body. For example:

1curl -X POST 'https://medusa-url.com/store/auth/token' \2-H 'Content-Type: application/json' \3--data-raw '{4  "email": "user@example.com",5  "password": "supersecret"6}'

If authenticated successfully, an object is returned in the response with the property access_token being the JWT token.

How to Use the JWT Token

The JWT token can be used for Bearer Authentication. It's passed in the Authorization header as the following:

Authorization: Bearer {jwt_token}

Cookie Session ID

Use a cookie session to send authenticated requests.

How to Obtain the Cookie Session

If you're sending requests through a browser, using Medusa's JS and Medusa React clients, or using tools like Postman, the cookie session should be automatically set when the customer is logged in.

If you're sending requests using cURL, you must set the Session ID in the cookie manually.

To do that, send a request to authenticate the customer and pass the cURL option -v:

1curl -v -X POST 'https://medusa-url.com/store/auth' \2-H 'Content-Type: application/json' \3--data-raw '{4  "email": "user@example.com",5  "password": "supersecret"6}'

The headers will be logged in the terminal as well as the response. You should find in the headers a Cookie header similar to this:

Set-Cookie: connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM;

Copy the value after connect.sid (without the ; at the end) and pass it as a cookie in subsequent requests as the following:

1curl 'https://medusa-url.com/store/customers/me/orders' \2-H 'Cookie: connect.sid={sid}'

Where {sid} is the value of connect.sid that you copied.

If you're sending requests using JavaScript's Fetch API, you must pass the credentials option with the value include to all the requests you're sending. For example:

1fetch(`<BACKEND_URL>/admin/products`, {2  credentials: "include",3})

Publishable API Key

Publishable API Keys allow you to send a request with a pre-defined scope. You can associate the publishable API key with one or more resources, such as sales channels, then include the publishable API key in the header of your requests.

The Medusa backend will infer the scope of the current request based on the publishable API key. At the moment, publishable API keys only work with sales channels.

It's highly recommended to create a publishable API key and pass it in the header of all your requests to the store APIs.

You can learn more about publishable API keys and how to use them in this documentation.

How to Create a Publishable API Key

You can create a publishable API key either using the admin REST APIs, or using the Medusa Admin.

How to Use a Publishable API Key

You can pass the publishable API key in the header x-publishable-api-key in all your requests to the store APIs:

x-publishable-api-key: {your_publishable_api_key}

If you're using Medusa's JS or Medusa React clients, you can pass the publishable API key when you first initialize either clients. Then, the publishable API key will be automatically included in all your requests:

HTTP Compression

If you've enabled HTTP Compression in your Medusa configurations, and you want to disable it for some requests, you can pass the x-no-compression header in your requests:

x-no-compression: true

If you're using the Medusa JS Client, you can pass custom headers in the last parameter of a method. For example:

1medusa.products.list({}, {2  "x-no-compression": true3})4.then(({ products, limit, offset, count }) => {5  console.log(products.length)6})

You can also pass the header when you first initialize the Medusa client:

1const medusa = new Medusa({2  maxRetries: 3,3  baseUrl: "https://api.example.com",4  customHeaders: {5    "x-no-compression": true6  }7})

For Medusa React, it's not possible to pass custom headers for a query or mutation, but you can pass the header to the MedusaProvider and it will be added to all subsequent requests:

1import { MedusaProvider } from "medusa-react"2
3// define query client...4
5const App = () => {6  return (7    <MedusaProvider8      queryClientProviderProps={{ client: queryClient }}9      baseUrl="http://localhost:9000"10      // ...11      customHeaders={{12        "x-no-compression": true13      }}14    >15      <MyStorefront />16    </MedusaProvider>17  )18}

Expanding Relations

Many API Routes accept an expand that unpacks an entity's relations and return them in the response.

Expanding One Relation

For example, when you retrieve a list of products, retrieve their collections by passing to the expand query parameter the value collection:

Expanding Multiple Relations

Expand more than one relation by separating the relations in the expand query parameter with a comma.

For example, to retrieve both the variants and the collection of the products, pass to the expand query parameter the value variants,collection:

Expanding Nested Relations

Expand nested relations (the relations of a relation) using dot notation.

For example, to retrieve the variants of a product along with its option values, pass to the expand query parameter variants.options:

Prevent Expanding Relations

Some requests expand relations by default. You can prevent that by passing an empty expand value to retrieve an entity without any extra relations.

For example:

This would retrieve the products with only their properties, without any relations like collection.

Selecting Fields

In many API Routes you'll find a fields query parameter that can be passed to the API Route. You can use the fields query parameter to specify which fields in the entity should be returned in the response.

Please note that if you pass a fields query parameter, only the fields you pass in the value along with the id of the entity will be returned in the response.

Also, the fields query parameter does not affect the expanded relations. You'll have to use the expand parameter instead.

Selecting One Field

For example, when you retrieve a list of products, you can retrieve only the titles of the products by passing title as a value to the fields query parameter:

As mentioned above, the expanded relations such as variants will still be returned as they're not affected by the fields parameter.

You can ensure that only the title field is returned by passing an empty value to the expand query parameter. For example:

Selecting Multiple Fields

You can pass more than one field by seperating the field names in the fields query parameter with a comma.

For example, to select the title and handle of the products:

Retrieve Only the ID

You can pass an empty fields query parameter to return only the ID of an entity. For example:

You can also pair with an empty expand query parameter to ensure that the relations aren't retrieved as well. For example:

Query Parameter Types

This section covers how to pass some common data types as query parameters. This is useful if you're sending requests to the API Routes and not using our JS Client. For example, when using cURL or Postman.

Strings

You can pass a string value in the form of <parameter_name>=<value>.

For example:

curl "http://localhost:9000/store/products?title=Shirt"

If the string has any characters other than letters and numbers, you must encode them.

For example, if the string has spaces, you can encode the space with + or %20:

curl "http://localhost:9000/store/products?title=Blue%20Shirt"

You can use tools like this one to learn how a value can be encoded.

Integers

You can pass an integer value in the form of <parameter_name>=<value>.

For example:

curl "http://localhost:9000/store/products?offset=1"

Boolean

You can pass a boolean value in the form of <parameter_name>=<value>.

For example:

curl "http://localhost:9000/store/products?is_giftcard=true"

Date and DateTime

You can pass a date value in the form <parameter_name>=<value>. The date must be in the format YYYY-MM-DD.

For example:

curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17"

You can also pass the time using the format YYYY-MM-DDTHH:MM:SSZ. Please note that the T and Z here are fixed.

For example:

curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17T07:22:30Z"

Array

Each array value must be passed as a separate query parameter in the form <parameter_name>[]=<value>. You can also specify the index of each parameter in the brackets <parameter_name>[0]=<value>.

For example:

curl -g "http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7"

Note that the -g parameter passed to curl disables errors being thrown for using the brackets. Read more here.

Object

Object parameters must be passed as separate query parameters in the form <parameter_name>[<key>]=<value>.

For example:

curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17"

Pagination

Query Parameters

In listing API Routes, such as list customers or list products, you can control the pagination using the query parameters limit and offset.

limit is used to specify the maximum number of items that can be return in the response. offset is used to specify how many items to skip before returning the resulting entities.

You can use the offset query parameter to change between pages. For example, if the limit is 50, at page 1 the offset should be 0; at page 2 the offset should be 50, and so on.

For example, to limit the number of products returned in the List Products API Route:

Response Fields

In the response of listing API Routes, aside from the entities retrieved, there are three pagination-related fields returned:

• limit: the maximum number of items that can be returned in the response.
• offset: the number of items that were skipped before the entities in the result.
• count: the total number of available items of this entity. It can be used to determine how many pages are there.

For example, if the count is 100 and the limit is 50, you can divide the count by the limit to get the number of pages: 100/50 = 2 pages.

Sort Order

The order field available on API Routes supporting pagination allows you to sort the retrieved items by an attribute of that item. For example, you can sort products by their created_at attribute by setting order to created_at:

By default, the sort direction will be ascending. To change it to descending, pass a dash (-) before the attribute name. For example:

This sorts the products by their created_at attribute in the descending order.