Skip to main content

Medusa Admin API (1.0.0)

License: MIT

API reference for Medusa's Admin endpoints. All endpoints are prefixed with /admin.

Authentication

There are two ways to send authenticated requests to the Medusa server: Using a user's API token, or using a Cookie Session ID.

API Token

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

How to Add API Token to a User

At the moment, there's no direct way of adding an API Token for a user. The only way it can be done is through directly editing the database.

If you're using a PostgreSQL database, you can run the following commands in your command line to add API token:

psql -d <DB_NAME> -U <DB_USER>
UPDATE public.user SET api_token='<API_TOKEN>' WHERE email='<USER_EMAIL>';

Where:

  • <DB_NAME> is the name of the database schema you use for the Medusa server.
  • <DB_USER> is the name of the user that has privileges over the database schema.
  • <API_TOKEN> is the API token you want to associate with the user. You can use this tool to generate a random token.
  • <USER_EMAIL> is the email address of the admin user you want to have this API token.

How to Use the API Token

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

Authorization: Bearer {api_token}

In this API reference, you'll find in the cURL request samples the use of {api_token}. This is where you must pass the API token.

If you're alternatively following along with the JS Client request samples, you must provide the apiKey option when creating the Medusa client:

const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3, apiKey: '{api_token}' })
Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer

Cookie Session ID

Use a cookie session to send authenticated requests.

If you're sending requests through a browser, using JS Client, or using tools like Postman, the cookie session should be automatically set when the admin user 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 user and pass the cURL option -v:

curl -v --location --request POST 'https://medusa-url.com/admin/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "user@example.com",
  "password": "supersecret"
}'

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:

curl --location --request GET 'https://medusa-url.com/admin/products' \
--header 'Cookie: connect.sid={sid}'

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

Security Scheme Type: API Key
Cookie parameter name: connect.sid

Expanding Fields

In many endpoints you'll find an expand query parameter that can be passed to the endpoint. You can use the expand query parameter to unpack an entity's relations and return them in the response.

For example, when you list customers you can also retrieve their groups by passing to the expand query parameter the value groups.

You can expand more than one relation by separating the relations in the expand query parameter with a comma. For example, to retrieve both the orders and the groups of a customer, pass to the expand query parameter the value groups,orders.

Please note that the parameters you pass to expand replace any relations that are expanded by default.

Selecting Fields

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

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

Only the fields you pass to field will be retrieved and returned in the response. Any fields that are returned by default will not be returned in this case. This does not affect relations.

For example, to only select the title and description fields of a product, pass to the fields query parameter the value title,description.

Pagination

Query Parameters

In listing endpoints, 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.

Response Fields

In listing fields, aside from the entities retrieved, there are three pagination-related fields returned: count, limit, and offset.

Similarly to the query parameters, limit is the maximum number of items that can be returned in the response, and field is the number of items that were skipped before the entities in the result.

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

App

App endpoints that allow handling apps in Medusa.

Generate Token for App

Generates a token for an application.

Authorizations:
API TokenCookie Session ID
Request Body schema: application/json
application_name
required
string

Name of the application for the token to be generated for.

state
required
string

State of the application.

code
required
string

The code for the generated token.

Responses

Response Schema: application/json
object (OAuth)

Represent an OAuth app

id
required
string
Example: "example_app"

The app's ID

display_name
required
string
Example: "Example app"

The app's display name

application_name
required
string
Example: "example"

The app's name

install_url
string <uri>

The URL to install the app

uninstall_url
string <uri>

The URL to uninstall the app

data
object
Example: {}

Any data necessary to the app.

Request samples

Content type
application/json
{
  • "application_name": "string",
  • "state": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{}

List Applications

Retrieve a list of applications.

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
Array of objects (OAuth)
Array
id
required
string
Example: "example_app"

The app's ID

display_name
required
string
Example: "Example app"

The app's display name

application_name
required
string
Example: "example"

The app's name

install_url
string <uri>

The URL to install the app

uninstall_url
string <uri>

The URL to uninstall the app

data
object
Example: {}

Any data necessary to the app.

Request samples

curl --location --request GET 'https://medusa-url.com/admin/apps' \
--header 'Authorization: Bearer {api_token}'

Response samples

Content type
application/json
{}

Auth

Auth endpoints that allow authorization of admin Users and manages their sessions.

User Login

Logs a User in and authorizes them to manage Store settings.

Request Body schema: application/json
email
required
string

The User's email.

password
required
string

The User's password.

Responses

Response Schema: application/json
object (User)

Represents a User who can manage store settings.

email
required
string <email>

The email of the User

id
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The user's ID

first_name
string
Example: "Levi"

The first name of the User

last_name
string
Example: "Bogan"

The last name of the User

api_token
string
Example: null

An API token associated with the user.

created_at
string <date-time>

The date with timezone at which the resource was created.

updated_at
string <date-time>

The date with timezone at which the resource was updated.

deleted_at
string <date-time>

The date with timezone at which the resource was deleted.

metadata
object
Example: {"car":"white"}

An optional key-value map with additional details

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "user": {
    }
}

User Logout

Deletes the current session for the logged in user.

Authorizations:
API TokenCookie Session ID

Responses

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.auth.deleteSession()

Response samples

Content type
application/json
Example
{
  • "message": "Discount must be set to dynamic",
  • "type": "not_allowed"
}

Get Current User

Gets the currently logged in User.

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
object (User)

Represents a User who can manage store settings.

email
required
string <email>

The email of the User

id
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The user's ID

first_name
string
Example: "Levi"

The first name of the User

last_name
string
Example: "Bogan"

The last name of the User

api_token
string
Example: null

An API token associated with the user.

created_at
string <date-time>

The date with timezone at which the resource was created.

updated_at
string <date-time>

The date with timezone at which the resource was updated.

deleted_at
string <date-time>

The date with timezone at which the resource was deleted.

metadata
object
Example: {"car":"white"}

An optional key-value map with additional details

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.auth.getSession()
.then(({ user }) => {
  console.log(user.id);
});

Response samples

Content type
application/json
{
  • "user": {
    }
}

Batch Job

Batch Job endpoints that allow handling batch jobs in Medusa.

Cancel a Batch Job

Marks a batch job as canceled

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the batch job.

Responses

Response Schema: application/json
object (Batch Job)

A Batch Job.

type
required
string
Enum: "product-import" "product-export"

The type of batch job.

id
string
Example: "batch_01G8T782965PYFG0751G0Z38B4"

The unique identifier for the batch job.

status
string
Default: "created"
Enum: "created" "pre_processed" "confirmed" "processing" "completed" "canceled" "failed"

The status of the batch job.

created_by
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that created the batch job.

created_by_user
object

A user object. Available if the relation created_by_user is expanded.

context
object
Example: {"shape":{"prices":[{"region":null,"currency_code":"eur"}],"dynamicImageColumnCount":4,"dynamicOptionColumnCount":2},"list_config":{"skip":0,"take":50,"order":{"created_at":"DESC"},"relations":["variants","variant.prices","images"]}}

The context of the batch job, the type of the batch job determines what the context should contain.

dry_run
boolean
Default: false

Specify if the job must apply the modifications or not.

object
Example: {"errors":[{"err":[],"code":"unknown","message":"Method not implemented."}],"stat_descriptors":[{"key":"product-export-count","name":"Product count to export","message":"There will be 8 products exported by this action"}]}

The result of the batch job.

pre_processed_at
string <date-time>

The date from which the job has been pre processed.

processing_at
string <date-time>

The date the job is processing at.

confirmed_at
string <date-time>

The date when the confirmation has been done.

completed_at
string <date-time>

The date of the completion.

canceled_at
string <date-time>

The date of the concellation.

failed_at
string <date-time>

The date when the job failed.

created_at
string <date-time>

The date with timezone at which the resource was created.

updated_at
string <date-time>

The date with timezone at which the resource was last updated.

deleted_at
string <date-time>

The date with timezone at which the resource was deleted.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.batchJobs.cancel(batch_job_id)
.then(({ batch_job }) => {
  console.log(batch_job.id);
});

Response samples

Content type
application/json
{
  • "batch_job": {
    }
}

Confirm a Batch Job

Confirms that a previously requested batch job should be executed.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the batch job.

Responses

Response Schema: application/json
object (Batch Job)

A Batch Job.

type
required
string
Enum: "product-import" "product-export"

The type of batch job.

id
string
Example: "batch_01G8T782965PYFG0751G0Z38B4"

The unique identifier for the batch job.

status
string
Default: "created"
Enum: "created" "pre_processed" "confirmed" "processing" "completed" "canceled" "failed"

The status of the batch job.

created_by
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that created the batch job.

created_by_user
object

A user object. Available if the relation created_by_user is expanded.

context
object
Example: {"shape":{"prices":[{"region":null,"currency_code":"eur"}],"dynamicImageColumnCount":4,"dynamicOptionColumnCount":2},"list_config":{"skip":0,"take":50,"order":{"created_at":"DESC"},"relations":["variants","variant.prices","images"]}}

The context of the batch job, the type of the batch job determines what the context should contain.

dry_run
boolean
Default: false

Specify if the job must apply the modifications or not.

object
Example: {"errors":[{"err":[],"code":"unknown","message":"Method not implemented."}],"stat_descriptors":[{"key":"product-export-count","name":"Product count to export","message":"There will be 8 products exported by this action"}]}

The result of the batch job.

pre_processed_at
string <date-time>

The date from which the job has been pre processed.

processing_at
string <date-time>

The date the job is processing at.

confirmed_at
string <date-time>

The date when the confirmation has been done.

completed_at
string <date-time>

The date of the completion.

canceled_at
string <date-time>

The date of the concellation.

failed_at
string <date-time>

The date when the job failed.

created_at
string <date-time>

The date with timezone at which the resource was created.

updated_at
string <date-time>

The date with timezone at which the resource was last updated.

deleted_at
string <date-time>

The date with timezone at which the resource was deleted.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.batchJobs.confirm(batch_job_id)
.then(({ batch_job }) => {
  console.log(batch_job.id);
});

Response samples

Content type
application/json
{
  • "batch_job": {
    }
}

Create a Batch Job

Creates a Batch Job.

Authorizations:
API TokenCookie Session ID
Request Body schema: application/json
type
required
string
Example: "product-export"

The type of batch job to start.

context
required
object
Example: {"shape":{"prices":[{"region":null,"currency_code":"eur"}],"dynamicImageColumnCount":4,"dynamicOptionColumnCount":2},"list_config":{"skip":0,"take":50,"order":{"created_at":"DESC"},"relations":["variants","variant.prices","images"]}}

Additional infomration regarding the batch to be used for processing.

dry_run
boolean
Default: false

Set a batch job in dry_run mode to get some information on what will be done without applying any modifications.

Responses

Request samples

Content type
application/json
{
  • "type": "product-export",
  • "context": {
    },
  • "dry_run": false
}

Response samples

Content type
application/json
{
  • "batch_job": {
    }
}

List Batch Jobs

Retrieve a list of Batch Jobs.

Authorizations:
API TokenCookie Session ID
query Parameters
limit
integer
Default: 10

The number of batch jobs to return.

offset
integer
Default: 0

The number of batch jobs to skip before results.

string or Array of strings

Filter by the batch ID

type
Array of strings

Filter by the batch type

object

Date comparison for when resulting collections was confirmed, i.e. less than, greater than etc.

object

Date comparison for when resulting collections was pre processed, i.e. less than, greater than etc.

object

Date comparison for when resulting collections was completed, i.e. less than, greater than etc.

object

Date comparison for when resulting collections was failed, i.e. less than, greater than etc.

object

Date comparison for when resulting collections was canceled, i.e. less than, greater than etc.

order
string

Field used to order retrieved batch jobs

expand
string

(Comma separated) Which fields should be expanded in each order of the result.

fields
string

(Comma separated) Which fields should be included in each order of the result.

object

Date comparison for when resulting collections was created, i.e. less than, greater than etc.

object

Date comparison for when resulting collections was updated, i.e. less than, greater than etc.

Responses

Response Schema: application/json
Array of objects (Batch Job)
count
integer

The total number of items available

offset
integer

The number of items skipped before these items

limit
integer

The number of items per page

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.batchJobs.list()
.then(({ batch_jobs, limit, offset, count }) => {
  console.log(batch_jobs.length);
});

Response samples

Content type
application/json
{
  • "batch_jobs": [
    ],
  • "count": 0,
  • "offset": 0,
  • "limit": 0
}

Get a Batch Job

Retrieves a Batch Job.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Batch Job

Responses

Response Schema: application/json
object (Batch Job)

A Batch Job.

type
required
string
Enum: "product-import" "product-export"

The type of batch job.

id
string
Example: "batch_01G8T782965PYFG0751G0Z38B4"

The unique identifier for the batch job.

status
string
Default: "created"
Enum: "created" "pre_processed" "confirmed" "processing" "completed" "canceled" "failed"

The status of the batch job.

created_by
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that created the batch job.

created_by_user
object

A user object. Available if the relation created_by_user is expanded.

context
object
Example: {"shape":{"prices":[{"region":null,"currency_code":"eur"}],"dynamicImageColumnCount":4,"dynamicOptionColumnCount":2},"list_config":{"skip":0,"take":50,"order":{"created_at":"DESC"},"relations":["variants","variant.prices","images"]}}

The context of the batch job, the type of the batch job determines what the context should contain.

dry_run
boolean
Default: false

Specify if the job must apply the modifications or not.

object
Example: {"errors":[{"err":[],"code":"unknown","message":"Method not implemented."}],"stat_descriptors":[{"key":"product-export-count","name":"Product count to export","message":"There will be 8 products exported by this action"}]}

The result of the batch job.

pre_processed_at
string <date-time>

The date from which the job has been pre processed.

processing_at
string <date-time>

The date the job is processing at.

confirmed_at
string <date-time>

The date when the confirmation has been done.

completed_at
string <date-time>

The date of the completion.

canceled_at
string <date-time>

The date of the concellation.

failed_at
string <date-time>

The date when the job failed.

created_at
string <date-time>

The date with timezone at which the resource was created.

updated_at
string <date-time>

The date with timezone at which the resource was last updated.

deleted_at
string <date-time>

The date with timezone at which the resource was deleted.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.batchJobs.retrieve(batch_job_id)
.then(({ batch_job }) => {
  console.log(batch_job.id);
});

Response samples

Content type
application/json
{
  • "batch_job": {
    }
}

Claim

Claim endpoints that allow handling claims in Medusa.

Cancel a Claim

Cancels a Claim

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

claim_id
required
string

The ID of the Claim.

Responses

Response Schema: application/json
object (Order)

Represents an order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

email
required
string <email>

The email associated with the order

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

id
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

status
string
Default: "pending"
Enum: "pending" "completed" "archived" "canceled" "requires_action"

The order's status

fulfillment_status
string
Default: "not_fulfilled"
Enum: "not_fulfilled" "partially_fulfilled" "fulfilled" "partially_shipped" "shipped" "partially_returned" "returned" "canceled" "requires_action"

The order's fulfillment status

payment_status
string
Default: "not_paid"
Enum: "not_paid" "awaiting" "captured" "partially_refunded" "refuneded" "canceled" "requires_action"

The order's payment status

display_id
integer
Example: 2

The order's display ID

cart_id
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

cart
object

A cart object. Available if the relation cart is expanded.

customer
object

A customer object. Available if the relation customer is expanded.

billing_address_id
string
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

object (Address)

An address.

shipping_address_id
string
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

object (Address)

An address.

region
object

A region object. Available if the relation region is expanded.

object (Currency)

Currency

tax_rate
number
Example: 0

The order's tax rate

discounts
Array of objects

The discounts used in the order. Available if the relation discounts is expanded.

gift_cards
Array of objects

The gift cards used in the order. Available if the relation gift_cards is expanded.

Array of objects (Shipping Method)

The shipping methods used in the order. Available if the relation shipping_methods is expanded.

Array of objects (Payment)

The payments used in the order. Available if the relation payments is expanded.

Array of objects (Fulfillment)

The fulfillments used in the order. Available if the relation fulfillments is expanded.

returns
Array of objects

The returns associated with the order. Available if the relation returns is expanded.

claims
Array of objects

The claims associated with the order. Available if the relation claims is expanded.

refunds
Array of objects

The refunds associated with the order. Available if the relation refunds is expanded.

swaps
Array of objects

The swaps associated with the order. Available if the relation swaps is expanded.

draft_order_id
string
Example: null

The ID of the draft order this order is associated with.

draft_order
object

A draft order object. Available if the relation draft_order is expanded.

Array of objects (Line Item)

The line items that belong to the order. Available if the relation items is expanded.

Array of objects (Order Edit)

[EXPERIMENTAL] Order edits done on the order. Available if the relation edits is expanded.

Array of objects (Gift Card Transaction)

The gift card transactions used in the order. Available if the relation gift_card_transactions is expanded.

canceled_at
string <date-time>

The date the order was canceled on.

no_notification
boolean
Example: false

Flag for describing whether or not notifications related to this should be send.

idempotency_key
string

Randomly generated key used to continue the processing of the order in case of failure.

external_id
string
Example: null

The ID of an external order.

sales_channel_id
string
Example: null

The ID of the sales channel this order is associated with.

sales_channel
object

A sales channel object. Available if the relation sales_channel is expanded.

shipping_total
integer
Example: 1000

The total of shipping

discount_total
integer
Example: 800

The total of discount

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order is returned.

total
integer
Example: 8200

The total amount of the order

subtotal
integer
Example: 8000

The subtotal of the order

paid_total
integer
Example: 8000

The total amount paid

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.orders.cancelClaim(order_id, claim_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

Content type
application/json
{
  • "order": {
    }
}

Create Claim Shipment

Registers a Claim Fulfillment as shipped.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

claim_id
required
string

The ID of the Claim.

Request Body schema: application/json
fulfillment_id
required
string

The ID of the Fulfillment.

tracking_numbers
Array of strings

The tracking numbers for the shipment.

Responses

Response Schema: application/json
object (Order)

Represents an order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

email
required
string <email>

The email associated with the order

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

id
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

status
string
Default: "pending"
Enum: "pending" "completed" "archived" "canceled" "requires_action"

The order's status

fulfillment_status
string
Default: "not_fulfilled"
Enum: "not_fulfilled" "partially_fulfilled" "fulfilled" "partially_shipped" "shipped" "partially_returned" "returned" "canceled" "requires_action"

The order's fulfillment status

payment_status
string
Default: "not_paid"
Enum: "not_paid" "awaiting" "captured" "partially_refunded" "refuneded" "canceled" "requires_action"

The order's payment status

display_id
integer
Example: 2

The order's display ID

cart_id
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

cart
object

A cart object. Available if the relation cart is expanded.

customer
object

A customer object. Available if the relation customer is expanded.

billing_address_id
string
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

object (Address)

An address.

shipping_address_id
string
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

object (Address)

An address.

region
object

A region object. Available if the relation region is expanded.

object (Currency)

Currency

tax_rate
number
Example: 0

The order's tax rate

discounts
Array of objects

The discounts used in the order. Available if the relation discounts is expanded.

gift_cards
Array of objects

The gift cards used in the order. Available if the relation gift_cards is expanded.

Array of objects (Shipping Method)

The shipping methods used in the order. Available if the relation shipping_methods is expanded.

Array of objects (Payment)

The payments used in the order. Available if the relation payments is expanded.

Array of objects (Fulfillment)

The fulfillments used in the order. Available if the relation fulfillments is expanded.

returns
Array of objects

The returns associated with the order. Available if the relation returns is expanded.

claims
Array of objects

The claims associated with the order. Available if the relation claims is expanded.

refunds
Array of objects

The refunds associated with the order. Available if the relation refunds is expanded.

swaps
Array of objects

The swaps associated with the order. Available if the relation swaps is expanded.

draft_order_id
string
Example: null

The ID of the draft order this order is associated with.

draft_order
object

A draft order object. Available if the relation draft_order is expanded.

Array of objects (Line Item)

The line items that belong to the order. Available if the relation items is expanded.

Array of objects (Order Edit)

[EXPERIMENTAL] Order edits done on the order. Available if the relation edits is expanded.

Array of objects (Gift Card Transaction)

The gift card transactions used in the order. Available if the relation gift_card_transactions is expanded.

canceled_at
string <date-time>

The date the order was canceled on.

no_notification
boolean
Example: false

Flag for describing whether or not notifications related to this should be send.

idempotency_key
string

Randomly generated key used to continue the processing of the order in case of failure.

external_id
string
Example: null

The ID of an external order.

sales_channel_id
string
Example: null

The ID of the sales channel this order is associated with.

sales_channel
object

A sales channel object. Available if the relation sales_channel is expanded.

shipping_total
integer
Example: 1000

The total of shipping

discount_total
integer
Example: 800

The total of discount

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order is returned.

total
integer
Example: 8200

The total amount of the order

subtotal
integer
Example: 8000

The subtotal of the order

paid_total
integer
Example: 8000

The total amount paid

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

Content type
application/json
{
  • "fulfillment_id": "string",
  • "tracking_numbers": [
    ]
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

Create a Claim

Creates a Claim.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

Request Body schema: application/json
type
required
string
Enum: "replace" "refund"

The type of the Claim. This will determine how the Claim is treated: replace Claims will result in a Fulfillment with new items being created, while a refund Claim will refund the amount paid for the claimed items.

required
Array of objects

The Claim Items that the Claim will consist of.

object

Optional details for the Return Shipping Method, if the items are to be sent back.

Array of objects

The new items to send to the Customer when the Claim type is Replace.

Array of objects

The Shipping Methods to send the additional Line Items with.

object (Address)

An address.

refund_amount
integer

The amount to refund the Customer when the Claim type is refund.

no_notification
boolean

If set to true no notification will be send related to this Claim.

metadata
object

An optional set of key-value pairs to hold additional information.

Responses

Response Schema: application/json
object (Order)

Represents an order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

email
required
string <email>

The email associated with the order

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

id
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

status
string
Default: "pending"
Enum: "pending" "completed" "archived" "canceled" "requires_action"

The order's status

fulfillment_status
string
Default: "not_fulfilled"
Enum: "not_fulfilled" "partially_fulfilled" "fulfilled" "partially_shipped" "shipped" "partially_returned" "returned" "canceled" "requires_action"

The order's fulfillment status

payment_status
string
Default: "not_paid"
Enum: "not_paid" "awaiting" "captured" "partially_refunded" "refuneded" "canceled" "requires_action"

The order's payment status

display_id
integer
Example: 2

The order's display ID

cart_id
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

cart
object

A cart object. Available if the relation cart is expanded.

customer
object

A customer object. Available if the relation customer is expanded.

billing_address_id
string
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

object (Address)

An address.

shipping_address_id
string
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

object (Address)

An address.

region
object

A region object. Available if the relation region is expanded.

object (Currency)

Currency

tax_rate
number
Example: 0

The order's tax rate

discounts
Array of objects

The discounts used in the order. Available if the relation discounts is expanded.

gift_cards
Array of objects

The gift cards used in the order. Available if the relation gift_cards is expanded.

Array of objects (Shipping Method)

The shipping methods used in the order. Available if the relation shipping_methods is expanded.

Array of objects (Payment)

The payments used in the order. Available if the relation payments is expanded.

Array of objects (Fulfillment)

The fulfillments used in the order. Available if the relation fulfillments is expanded.

returns
Array of objects

The returns associated with the order. Available if the relation returns is expanded.

claims
Array of objects

The claims associated with the order. Available if the relation claims is expanded.

refunds
Array of objects

The refunds associated with the order. Available if the relation refunds is expanded.

swaps
Array of objects

The swaps associated with the order. Available if the relation swaps is expanded.

draft_order_id
string
Example: null

The ID of the draft order this order is associated with.

draft_order
object

A draft order object. Available if the relation draft_order is expanded.

Array of objects (Line Item)

The line items that belong to the order. Available if the relation items is expanded.

Array of objects (Order Edit)

[EXPERIMENTAL] Order edits done on the order. Available if the relation edits is expanded.

Array of objects (Gift Card Transaction)

The gift card transactions used in the order. Available if the relation gift_card_transactions is expanded.

canceled_at
string <date-time>

The date the order was canceled on.

no_notification
boolean
Example: false

Flag for describing whether or not notifications related to this should be send.

idempotency_key
string

Randomly generated key used to continue the processing of the order in case of failure.

external_id
string
Example: null

The ID of an external order.

sales_channel_id
string
Example: null

The ID of the sales channel this order is associated with.

sales_channel
object

A sales channel object. Available if the relation sales_channel is expanded.

shipping_total
integer
Example: 1000

The total of shipping

discount_total
integer
Example: 800

The total of discount

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order is returned.

total
integer
Example: 8200

The total amount of the order

subtotal
integer
Example: 8000

The subtotal of the order

paid_total
integer
Example: 8000

The total amount paid

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

Content type
application/json
{
  • "type": "replace",
  • "claim_items": [
    ],
  • "return_shipping": {
    },
  • "additional_items": [
    ],
  • "shipping_methods": [
    ],
  • "shipping_address": {
    },
  • "refund_amount": 0,
  • "no_notification": true,
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

Update a Claim

Updates a Claim.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

claim_id
required
string

The ID of the Claim.

Request Body schema: application/json
Array of objects

The Claim Items that the Claim will consist of.

Array of objects

The Shipping Methods to send the additional Line Items with.

no_notification
boolean

If set to true no notification will be send related to this Swap.

metadata
object

An optional set of key-value pairs to hold additional information.

Responses

Response Schema: application/json
object (Order)

Represents an order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

email
required
string <email>

The email associated with the order

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

id
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

status
string
Default: "pending"
Enum: "pending" "completed" "archived" "canceled" "requires_action"

The order's status

fulfillment_status
string
Default: "not_fulfilled"
Enum: "not_fulfilled" "partially_fulfilled" "fulfilled" "partially_shipped" "shipped" "partially_returned" "returned" "canceled" "requires_action"

The order's fulfillment status

payment_status
string
Default: "not_paid"
Enum: "not_paid" "awaiting" "captured" "partially_refunded" "refuneded" "canceled" "requires_action"

The order's payment status

display_id
integer
Example: 2

The order's display ID

cart_id
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

cart
object

A cart object. Available if the relation cart is expanded.

customer
object

A customer object. Available if the relation customer is expanded.

billing_address_id
string
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

object (Address)

An address.

shipping_address_id
string
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

object (Address)

An address.

region
object

A region object. Available if the relation region is expanded.

object (Currency)

Currency

tax_rate
number
Example: 0

The order's tax rate

discounts
Array of objects

The discounts used in the order. Available if the relation discounts is expanded.

gift_cards
Array of objects

The gift cards used in the order. Available if the relation gift_cards is expanded.

Array of objects (Shipping Method)

The shipping methods used in the order. Available if the relation shipping_methods is expanded.

Array of objects (Payment)

The payments used in the order. Available if the relation payments is expanded.

Array of objects (Fulfillment)

The fulfillments used in the order. Available if the relation fulfillments is expanded.

returns
Array of objects

The returns associated with the order. Available if the relation returns is expanded.

claims
Array of objects

The claims associated with the order. Available if the relation claims is expanded.

refunds
Array of objects

The refunds associated with the order. Available if the relation refunds is expanded.

swaps
Array of objects

The swaps associated with the order. Available if the relation swaps is expanded.

draft_order_id
string
Example: null

The ID of the draft order this order is associated with.

draft_order
object

A draft order object. Available if the relation draft_order is expanded.

Array of objects (Line Item)

The line items that belong to the order. Available if the relation items is expanded.

Array of objects (Order Edit)

[EXPERIMENTAL] Order edits done on the order. Available if the relation edits is expanded.

Array of objects (Gift Card Transaction)

The gift card transactions used in the order. Available if the relation gift_card_transactions is expanded.

canceled_at
string <date-time>

The date the order was canceled on.

no_notification
boolean
Example: false

Flag for describing whether or not notifications related to this should be send.

idempotency_key
string

Randomly generated key used to continue the processing of the order in case of failure.

external_id
string
Example: null

The ID of an external order.

sales_channel_id
string
Example: null

The ID of the sales channel this order is associated with.

sales_channel
object

A sales channel object. Available if the relation sales_channel is expanded.

shipping_total
integer
Example: 1000

The total of shipping

discount_total
integer
Example: 800

The total of discount

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order is returned.

total
integer
Example: 8200

The total amount of the order

subtotal
integer
Example: 8000

The subtotal of the order

paid_total
integer
Example: 8000

The total amount paid

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

Content type
application/json
{
  • "claim_items": [
    ],
  • "shipping_methods": [
    ],
  • "no_notification": true,
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

Collection

Collection endpoints that allow handling collections in Medusa.

Update Products

Updates products associated with a Product Collection

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Collection.

Request Body schema: application/json
product_ids
required
Array of strings

An array of Product IDs to add to the Product Collection.

Responses

Response Schema: application/json
object (Product Collection)

Product Collections represents a group of Products that are related.

title
required
string
Example: "Summer Collection"

The title that the Product Collection is identified by.

id
string
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The product collection's ID

handle
string
Example: "summer-collection"

A unique string that identifies the Product Collection - can for example be used in slug structures.

products
Array of objects

The Products contained in the Product Collection. Available if the relation products is expanded.

created_at
string <date-time>

The date with timezone at which the resource was created.

updated_at
string <date-time>

The date with timezone at which the resource was updated.

deleted_at
string <date-time>

The date with timezone at which the resource was deleted.

metadata
object
Example: {"car":"white"}

An optional key-value map with additional details

Request samples

Content type
application/json
{
  • "product_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "collection": {
    }
}

Remove Product

Removes products associated with a Product Collection

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Collection.

Request Body schema: application/json
product_ids
required
Array of strings

An array of Product IDs to remove from the Product Collection.

Responses

Response Schema: application/json
id
string

The ID of the collection

object
string
Default: "product-collection"

The type of object the removal was executed on

removed_products
Array of strings

The IDs of the products removed from the collection

Request samples

Content type
application/json
{
  • "product_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "product-collection",
  • "removed_products": [
    ]
}

Create a Collection

Creates a Product Collection.

Authorizations:
API TokenCookie Session ID
Request Body schema: application/json
title
required
string

The title to identify the Collection by.

handle
string

An optional handle to be used in slugs, if none is provided we will kebab-case the title.

metadata
object

An optional set of key-value pairs to hold additional information.

Responses

Response Schema: application/json
object (Product Collection)

Product Collections represents a group of Products that are related.

title
required
string
Example: "Summer Collection"

The title that the Product Collection is identified by.

id
string
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The product collection's ID

handle
string
Example: "summer-collection"

A unique string that identifies the Product Collection - can for example be used in slug structures.

products
Array of objects

The Products contained in the Product Collection. Available if the relation products is expanded.

created_at
string <date-time>

The date with timezone at which the resource was created.

updated_at
string <date-time>

The date with timezone at which the resource was updated.

deleted_at
string <date-time>

The date with timezone at which the resource was deleted.

metadata
object
Example: {"car":"white"}

An optional key-value map with additional details

Request samples

Content type
application/json
{
  • "title": "string",
  • "handle": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "collection": {
    }
}

List Collections

Retrieve a list of Product Collection.

Authorizations:
API TokenCookie Session ID
query Parameters
limit
integer
Default: 10

The number of collections to return.

offset
integer
Default: 0

The number of collections to skip before the results.

title
string

The title of collections to return.

handle
string

The handle of collections to return.

q
string

a search term to search titles and handles.

discount_condition_id
string

The discount condition id on which to filter the product collections.

object

Date comparison for when resulting collections were created.

object

Date comparison for when resulting collections were updated.

object

Date comparison for when resulting collections were deleted.

Responses

Response Schema: application/json
Array of objects (Product Collection)
count
integer

The total number of items available

offset
integer

The number of items skipped before these items

limit
integer

The number of items per page

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.collections.list()
.then(({ collections, limit, offset, count }) => {
  console.log(collections.length);
});

Response samples

Content type
application/json
{
  • "collections": [
    ],
  • "count": 0,
  • "offset": 0,
  • "limit": 0
}

Delete a Collection

Deletes a Product Collection.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Collection.

Responses

Response Schema: application/json
id
string

The ID of the deleted Collection

object
string
Default: "product-collection"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether the collection was deleted successfully or not.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.collections.delete(collection_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "product-collection",
  • "deleted": true
}

Get a Collection

Retrieves a Product Collection.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product Collection

Responses

Response Schema: application/json
object (Product Collection)

Product Collections represents a group of Products that are related.

title
required
string
Example: "Summer Collection"

The title that the Product Collection is identified by.

id
string
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The product collection's ID

handle
string
Example: "summer-collection"

A unique string that identifies the Product Collection - can for example be used in slug structures.

products
Array of objects

The Products contained in the Product Collection. Available if the relation products is expanded.

created_at
string <date-time>

The date with timezone at which the resource was created.

updated_at
string <date-time>

The date with timezone at which the resource was updated.

deleted_at
string <date-time>

The date with timezone at which the resource was deleted.

metadata
object
Example: {"car":"white"}

An optional key-value map with additional details

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.collections.retrieve(collection_id)
.then(({ collection }) => {
  console.log(collection.id);
});

Response samples

Content type
application/json
{
  • "collection": {
    }
}

Update a Collection

Updates a Product Collection.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Collection.

Request Body schema: application/json
title
string

The title to identify the Collection by.

handle
string

An optional handle to be used in slugs, if none is provided we will kebab-case the title.

metadata
object

An optional set of key-value pairs to hold additional information.

Responses

Response Schema: application/json
object (Product Collection)

Product Collections represents a group of Products that are related.

title
required
string
Example: "Summer Collection"

The title that the Product Collection is identified by.

id
string
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The product collection's ID

handle
string
Example: "summer-collection"

A unique string that identifies the Product Collection - can for example be used in slug structures.

products
Array of objects

The Products contained in the Product Collection. Available if the relation products is expanded.

created_at
string <date-time>

The date with timezone at which the resource was created.

updated_at
string <date-time>

The date with timezone at which the resource was updated.

deleted_at
string <date-time>

The date with timezone at which the resource was deleted.

metadata
object
Example: {"car":"white"}

An optional key-value map with additional details

Request samples

Content type
application/json
{
  • "title": "string",
  • "handle": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "collection": {
    }
}

Currency

List Currency

Retrieves a list of Currency

query Parameters
code
string

Code of the currency to search for.

includes_tax
boolean

Search for tax inclusive currencies.

order
string

order to retrieve products in.

offset
number
Default: "0"

How many products to skip in the result.

limit
number
Default: "20"

Limit the number of products returned.

Responses

Response Schema: application/json
Array of objects (Currency)
count
integer

The total number of items available

offset
integer

The number of items skipped before these items

limit
integer

The number of items per page

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.currencies.list()
.then(({ currencies, count, offset, limit }) => {
  console.log(currencies.length);
});

Response samples

Content type
application/json
{
  • "currencies": [
    ],
  • "count": 0,
  • "offset": 0,
  • "limit": 0
}

Update a Currency

Update a Currency

path Parameters
code
required
string

The code of the Currency.

Request Body schema: application/json
includes_tax
boolean

[EXPERIMENTAL] Tax included in prices of currency.

Responses

Response Schema: application/json
object (Currency)

Currency

code
required
string
Example: "usd"

The 3 character ISO code for the currency.

symbol
required
string
Example: "$"

The symbol used to indicate the currency.

symbol_native
required
string
Example: "$"

The native symbol used to indicate the currency.

name
required
string
Example: "US Dollar"

The written name of the currency

includes_tax
boolean

[EXPERIMENTAL] Does the currency prices include tax

Request samples

Content type
application/json
{
  • "includes_tax": true
}

Response samples

Content type
application/json
{
  • "currency": {
    }
}

Customer

Customer endpoints that allow handling customers in Medusa.

Create a Customer

Creates a Customer.

Authorizations:
API TokenCookie Session ID
Request Body schema: application/json
email
required
string <email>

The customer's email.

first_name
required
string

The customer's first name.

last_name
required
string

The customer's last name.

password
required
string <password>

The customer's password.

phone
string

The customer's phone number.

metadata
object

An optional set of key-value pairs to hold additional information.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "password": "pa$$word",
  • "phone": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "customer": {
    }
}

List Customers

Retrieves a list of Customers.

Authorizations:
API TokenCookie Session ID
query Parameters
limit
integer
Default: 50

The number of items to return.

offset
integer
Default: 0

The items to skip before result.

expand
string

(Comma separated) Which fields should be expanded in each customer.

q
string

a search term to search email, first_name, and last_name.

Responses

Response Schema: application/json
Array of objects (Customer)
count
integer

The total number of items available

offset
integer

The number of items skipped before these items