Admin

import { CodeTabs, CodeTab, H1 } from "docs-ui" import { Feedback } from "@/components/Feedback" import SectionContainer from "@/components/Section/Container" import DividedMarkdownLayout from "@/layouts/DividedMarkdown" import { DividedMarkdownContent, DividedMarkdownCode } from "@/layouts/DividedMarkdown/Sections" import Section from "@/components/Section"

import ClientLibraries from "./client-libraries.mdx"

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.

<Feedback extraData={{ section: "introduction" }} question="Was this section helpful?" />

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.

token = await sdk.auth.login("user", "emailpass", {
  email,
  password
})

curl -X POST '{backend_url}/auth/user/emailpass' \
-H 'Content-Type: application/json' \
--data-raw '{
  "email": "[email protected]",
  "password": "supersecret"
}'

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

{
  "token": "123..."
}

How to Use the JWT Token

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

If you're using the JS SDK, the login method automatically sets the token for you and passes it to subsequent requests. You can also set the token manually using the client.setToken method.

Make sure you've set the auth.type configuration of the JS SDK to jwt to use the JWT token. Learn more in the JS SDK configurations.

Authorization: Bearer {jwt_token}

2. API Token

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

How to Create an API Token for a User

Create the API key token either from the Medusa Admin or using the Create API Key API Route.

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.

const { api_key } = await sdk.admin.apiKey.create({
  title: "My Token",
  type: "secret"
})

console.log(api_key.token)

curl -X POST 'localhost:9000/admin/api-keys' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {jwt_token}' \
--data '{
    "title": "my token",
    "type": "secret"
}'

How to Use the API Token

You pass the API Key token in the Authorization Basic header. For example:

Previous versions of Medusa required passing the API key token as base64. This is still supported for backwards compatibility, but you can pass the API token without encoding it as well.

import Medusa from "@medusajs/js-sdk"

export const sdk = new Medusa({
  // other options...
  apiKey: "{api_key_token}",
})

curl '{backend_url}/admin/products' \
-H '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, if you're using the JS SDK, make sure the auth.type configuration is set to session, as explained in the JS SDK configurations guide. The auth.login method will handle setting the session cookie and passing it in subsequent requests.

If you're not using the JS SDK, send a request to the session authentication API route. To view the cookie session ID, pass the -v option to the curl command.

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

If you send the cURL request, the headers will be logged in the terminal as well as the response. You should find in the headers a Cookie header.

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

How to Use the Cookie Session ID in cURL

If you're using the JS SDK, it will pass the cookie session with every request automatically after you use the auth.login method.

If you're not using the JS SDK, copy the value after connect.sid (without the ; at the end) and pass it as a cookie in subsequent requests.

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

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

<Feedback extraData={{ section: "authentication-cookie" }} question="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.

If you're using the JS SDK, every method accepts a headers parameter as the last parameter. You can pass in it custom headers, including the x-no-compression header.

sdk.store.product.list({
  limit,
  offset,
}, {
  "x-no-compression": "false",
})

x-no-compression: false

<Feedback extraData={{ section: "http-compression" }} question="Was this section helpful?" />

Manage Metadata

Many data models in Medusa, such as products and carts, have a metadata field that allows you to store custom information in key-value pairs.

When setting or updating the metadata field using the relevant API routes, Medusa will merge the new metadata with the existing metadata.

The instructions in this section apply to any JSON property in a data model.

Accepted Values in Metadata

The metadata is an object of key-value pairs, where the keys are strings and the values can be one of the following types:

• String
  • An empty string deletes the property from the metadata.
• Number
• Boolean
• Date
• Object
• Arrays of any of the above types

The metadata is not validated, so you can store any custom data in it.

{
  "metadata": {
    "category": "electronics",
    "views": 1500,
    "is_featured": true,
    "tags": ["new", "sale"],
    "details": {
      "warranty": "2 years",
      "origin": "USA"
    }
  }
}

Add or Update New Property in Metadata

To add or update a property in the metadata, pass the property in the request body as a key-value pair. This won't affect existing properties in the metadata.

sdk.admin.product.update("prod_123", {
  metadata: {
    new_property: "value"
  }
})

{
  "id": "prod_123",
  "metadata": {
    "new_property": "value",
    "old_property": "value"
  }
}

Update Nested Objects in Metadata

When updating a nested object in the metadata, you must pass the entire object in the request body.

Medusa doesn't merge nested objects, so if you pass a partial object, the existing properties in the nested object will be removed.

sdk.admin.product.update("prod_123", {
  metadata: {
    nested_object: {
      property1: "value1",
      property2: "value2"
    }
  }
})

{
  "id": "prod_123",
  "metadata": {
    "nested_object": {
      "property1": "value1",
      "property2": "value2"
    }
  }
}

Remove Property from Metadata

To remove a property from the metadata, pass the property in the request body with an empty string value. This will remove the property from the metadata without affecting other properties.

<Feedback extraData={{ section: "metadata" }} question="Was this section helpful?" />

sdk.admin.product.update("prod_123", {
  metadata: {
    property_to_remove: ""
  }
})

{
  "id": "prod_123",
  "metadata": {
    "other_property": "value"
  }
}

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

sdk.admin.product.list({
  fields: "title,handle"
})

curl 'localhost:9000/admin/products?fields=title,handle' \
-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, -handle removes the handle field from the fields returned by default.

sdk.admin.product.list({
  fields: "+title,-handle"
})

curl 'localhost:9000/admin/products?fields=+title,-handle'

This returns the products, each of them having their title field, but without the handle field.

Select Relations

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

sdk.admin.product.list({
  fields: "*variants"
})

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

This returns the variants of each product.

To select multiple relations, pass each of the relations with the * prefix, separated by a comma.

sdk.admin.product.list({
  fields: "*variants,*options"
})

curl 'localhost:9000/admin/products?fields=*variants,*options'

This returns the variants and options 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. You can do the same for multiple relations.

sdk.admin.product.list({
  fields: "variants.title,variants.sku,options.title"
})

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

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

Select Custom Linked Data Models

Most of the API routes that accept a fields query parameter allow you to specify custom linked data models. For example, if you linked a Brand to a Product, you can pass brand in the fields query parameter to retrieve the brand of each product.

However, some API routes restrict the fields and relations you can retrieve. To learn about those API routes and how to override the allowed fields and relations, refer to the Retrieve Custom Linked Data Models from Medusa's API routes documentation.

<Feedback extraData={{ section: "select-fields" }} question="Was this section helpful?" />

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

sdk.admin.product.list({
  title: "Shirt"
})

curl "http://localhost:9000/admin/products?title=Shirt" \
-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.

When using the JS SDK, you can pass the string directly to the query parameter. The JS SDK will encode the string for you.

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

sdk.admin.product.list({
  title: "Blue Shirt"
})

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

Integers

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

sdk.admin.product.list({
  offset: 1
})

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

Boolean

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

sdk.admin.product.list({
  is_giftcard: true
})

curl "http://localhost:9000/admin/products?is_giftcard=true" \
-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.

sdk.admin.product.list({
  created_at: { $lt: "2023-02-17" }
})

curl -g "http://localhost:9000/admin/products?created_at[$lt]=2023-02-17" \
-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.

sdk.admin.product.list({
  created_at: { $lt: "2023-02-17T07:22:30Z" }
})

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

Array

Array filters can be passed either as:

• <parameter_name>[]=<value1>,<value2>, separating the values by a comma.
• <parameter_name>[]=<value1>&<parameter_name>[]=<value2>, passing each value as a separate query parameter. You can also specify the index of each parameter in the brackets <parameter_name>[0]=<value>.

When using the JS SDK, you can pass the array directly to the query parameter. The JS SDK will handle the rest.

sdk.admin.product.list({
  sales_channel_id: ["sc_123", "sc_456"]
})

curl -g "http://localhost:9000/admin/products?sales_channel_id[]=sc_123,sc_456" \
-H 'Authorization: Bearer {jwt_token}'

curl -g "http://localhost:9000/admin/products?sales_channel_id[]=sc_123&sales_channel_id[]=sc_456" \
-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>.

When using the JS SDK, you can pass the object directly to the query parameter. The JS SDK will handle the rest.

sdk.admin.product.list({
  created_at: { $lt: "2023-02-17", $gt: "2022-09-17" }
})

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

<Feedback extraData={{ section: "query-parameters" }} question="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.

sdk.admin.product.list({
  limit: 5,
  offset: 0
})

curl "http://localhost:9000/admin/products?limit=5&offset=0" \
-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.

sdk.admin.product.list({
  order: "created_at"
})

curl "http://localhost:9000/admin/products?order=created_at" \
-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.

sdk.admin.product.list({
  order: "-created_at"
})

curl "http://localhost:9000/admin/products?order=-created_at" \
-H 'Authorization: Bearer {jwt_token}'

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

<Feedback extraData={{ section: "pagination" }} question="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.

<Feedback extraData={{ section: "workflows" }} question="Was this section helpful?" />