- Get Started
- Product
- Resources
- Tools & SDKs
- Framework
- Reference
- Get Started
- Product
- Resources
- Tools & SDKs
- Framework
- Reference
Medusa V2 Store API Reference
This API reference includes Medusa v2's Store APIs, which are REST APIs exposed by the Medusa application. They are 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 application URL.
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):
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 two ways to send authenticated requests to the Medusa application: Using a JWT 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 customer's email and password in the request body.
If authenticated successfully, an object is returned in the response with the property token
being the JWT token.
How to Use the JWT Token
To use the JWT token, pass it in the authorization bearer header.
2. Cookie Session ID#
When you authenticate a customer 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.
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.
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.
Publishable API Key#
You must pass a publishable API key in the header of your requests to the store API routes.
Publishable API Keys sets the scope of your request to one or more sales channels. This ensures you only retrieve products available in the publishable API key's sales channels, retrieve correct inventory details, and associate placed orders with the specified sales channel.
How to Create a Publishable API Key#
Create a publishable API key either using the admin REST APIs, or using the Medusa Admin.
How to Use a Publishable API Key#
You pass the publishable API key in the header x-publishable-api-key
in all your requests to the store APIs.
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 ,
.
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 *
.
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.