Menu

Medusa V2 Admin API Reference

Production Warning: Medusa v2.0 is in development and not suitable for production environments. As such, the API reference is incomplete and subject to change, so please use it with caution.

This API reference includes Medusa v2's Admin APIs, which are REST APIs exposed by the Medusa application. They are used to perform admin functionalities or create an admin dashboard to access and manipulate your commerce store's data.

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

Was this section helpful?

Just Getting Started?

Check out the Medusa v2 Documentation.

Medusa JS SDK

To use Medusa's JS SDK library, install the following packages in your project (not required for admin customizations):

Terminal
❯npm install @medusajs/js-sdk@rc @medusajs/types@rc

Learn more about the JS SDK in this documentation.

Download Full Reference#

Download this reference as an OpenApi YAML file. You can import this file to tools like Postman and start sending requests directly to your Medusa application.

Authentication#

There are three ways to send authenticated requests to the Medusa server: Using a JWT token in a bearer authorization header, using an admin user's API token, or using a cookie session ID.

1. Bearer Authorization with JWT Tokens#

Use a JWT token in a request's bearer authorization header 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

To obtain a JWT token, send a request to the authentication route passing it the user's email and password in the request body.

Obtain JWT token
1curl -X POST '{backend_url}/auth/user/emailpass' \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 token being the JWT token.

Example response
1{2  "token": "123..."3}

How to Use the JWT Token

To use the JWT token, pass it in the authorization bearer header.

Use JWT token
❯Authorization: Bearer {jwt_token}

2. API Token#

Use a user's API Token to send authenticated requests.

How to Create an API Token for a User

Use the Create API Key API Route to create an API token.

Note: You must be an authenticated user to create an API token.

An api_key object is returned in the response. You need its token property.

Create API token
1curl -X POST 'localhost:9000/admin/api-keys' \2-H 'Content-Type: application/json' \3-H 'Authorization: Bearer {jwt_token}' \4--data '{5    "title": "my token",6    "type": "secret"7}'

How to Use the API Token

Use the API token by passing it in a basic authorization header.

Use API token
❯Authorization: Basic {api_key_token}

3. Cookie Session ID#

When you authenticate a user and create a cookie session ID for them, the cookie session ID is passed automatically when sending the request from the browser, or with tools like Postman.

How to Obtain the Cookie Session#

To obtain a cookie session ID, you must have a JWT token for bearer authentication.

Then, send a request to the session authentication API route.

To view the cookie session ID, pass the -v option to the curl command.

Obtain cookie session
1curl -v -X POST '{backend_url}/auth/session' \2--header 'Authorization: Bearer {jwt_token}'

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

Logged cookie session
❯Set-Cookie: connect.sid=s%3A2Bu8B...;

How to Use the Cookie Session ID in cURL

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

Use cookie session
1curl '{backend_url}/admin/products' \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.

Include credentials in fetch
1fetch(`<BACKEND_URL>/admin/products`, {2  credentials: "include",3})
Was this section helpful?

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.

Enable HTTP compression
❯x-no-compression: true
Was this section helpful?

Select Fields and Relations#

Many API Routes accept a fields query that allows you to select which fields and relations should be returned in a record. Fields and relations are separated by a comma ,.

Select fields
1curl 'localhost:9000/admin/products?fields=title,handle' \2-H 'Authorization: Bearer {jwt_token}'

This returns only the title and handle fields of a product.

Fields Operator#

By default, only the selected fields and relations are returned in the response.

Before every field or relation, you can pass one of the following operators to change the default behavior:

  • +: Add the field to the fields returned by default. For example, +title returns the title field along with the fields returned by default.
  • -: Remove the field from the fields returned by default. For example, -title removes the title field from the fields returned by default.

Select Relations#

To select a relation, pass to fields the relation name prefixed by *.

Select relations
1curl 'localhost:9000/admin/products?fields=*variants' \2-H 'Authorization: Bearer {jwt_token}'

This returns the variants of each product.

Select Fields in a Relation#

The * prefix selects all fields of the relation's data model.

To select a specific field, pass a .<field> suffix instead of the * prefix. For example, variants.title.

To specify multiple fields, pass each of the fields with the <relation>.<field> format, separated by a comma.

Select relation's fields
1curl 'localhost:9000/admin/products?fields=variants.title,variants.sku' \2-H 'Authorization: Bearer {jwt_token}'

This returns the variants of each product, but the variants only have their id, title, and sku fields. The id is always included.

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 using cURL or Postman.

Strings#

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

String filter
1curl "http://localhost:9000/admin/products?title=Shirt" \2-H 'Authorization: Bearer {jwt_token}'

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.

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

Encoded string filter
1curl "http://localhost:9000/admin/products?title=Blue%20Shirt" \2-H 'Authorization: Bearer {jwt_token}'

Integers#

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

Integer filter
1curl "http://localhost:9000/admin/products?offset=1" \2-H 'Authorization: Bearer {jwt_token}'

Boolean#

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

Boolean filter
1curl "http://localhost:9000/admin/products?is_giftcard=true" \2-H 'Authorization: Bearer {jwt_token}'

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.

Date filter
1curl -g "http://localhost:9000/admin/products?created_at[$lt]=2023-02-17" \2-H 'Authorization: Bearer {jwt_token}'

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

Date and time filter
1curl -g "http://localhost:9000/admin/products?created_at[$lt]=2023-02-17T07:22:30Z" \2-H 'Authorization: Bearer {jwt_token}'

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>.

Array filter
1curl -g "http://localhost:9000/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7" \2-H 'Authorization: Bearer {jwt_token}'

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>.

Object filter
1curl -g "http://localhost:9000/admin/products?created_at[$lt]=2023-02-17&created_at[$gt]=2022-09-17" \2-H 'Authorization: Bearer {jwt_token}'
Was this section helpful?

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 to be returned in the response. offset is used to specify how many items to skip before returning the resulting records.

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.

Pagination query parameters
1curl "http://localhost:9000/admin/products?limit=5" \2-H 'Authorization: Bearer {jwt_token}'

Response Fields#

In the response of listing API Routes, aside from the records 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 records in the result.
  • count: the total number of available items of this data model. It can be used to determine how many pages are there.

For example, if the count is 100 and the limit is 50, 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 that support pagination) allows you to sort the retrieved items by a field of that item.

Ascending sort by a field
1curl "http://localhost:9000/admin/products?order=created_at" \2-H 'Authorization: Bearer {jwt_token}'

This sorts the products by their created_at field in the ascending order.

By default, the sort direction is ascending. To change it to descending, pass a dash (-) before the field name.

Descending sort by a field
1curl "http://localhost:9000/admin/products?order=-created_at" \2-H 'Authorization: Bearer {jwt_token}'

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

Was this section helpful?

Workflows#

While browsing this reference, you'll find some API routes mention what workflow is used in them.

If you click on the workflow, you'll view a reference of that workflow, including its hooks.

This is useful if you want to extend an API route and pass additional data or perform custom actions.

Refer to this guide to find an example of extending an API route.

Was this section helpful?