Medusa V2 Admin API Reference
This API reference includes Medusa'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.
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.
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
JWT tokens are obtained by sending a request to the authentication route passing it the user's email and password in the request body.
For example:
If authenticated successfully, an object is returned in the response with the property token
being the JWT token.
Learn more about the authentication route here
How to Use the JWT Token
Pass the JWT token in the authorization bearer header:
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:
An api_key
object is returned in the response. You need its token
property.
How to Use the API Token
The API token can be used by providing it in a basic authorization header:
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:
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:
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 as the following:
Where {sid}
is the value of connect.sid
that you copied.
Including Credentials in the Fetch API
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:
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:
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 ,
.
For example:
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 thetitle
field along with the fields returned by default.-
: Remove the field from the fields returned by default. For example,-title
removes thetitle
field from the fields returned by default.
Select Relations
To select a relation, pass to fields
the relation name prefixed by *
. For example:
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.
For example:
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.
Strings
You can pass a string value in the form of <parameter_name>=<value>
.
For example:
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.
Integers
You can pass an integer value in the form of <parameter_name>=<value>
.
For example:
Boolean
You can pass a boolean value in the form of <parameter_name>=<value>
.
For example:
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:
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:
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:
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:
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.
For example:
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.
For example, pass the query parameter order=created_at
to sort products by their created_at
field:
By default, the sort direction is ascending. To change it to
descending, pass a dash (-
) before the field name.
For example:
This sorts the products by their created_at
field in the descending order.
Just Getting Started?
Check out the quickstart guide.
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 backend.