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 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}' })

If you're using Medusa React, you can pass the apiKey prop to MedusaProvider:

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

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

Expanding One Relation

For example, when you retrieve products, you can retrieve their collection by passing to the expand query parameter the value collection:

curl "http://localhost:9000/admin/products?expand=collection" \
-H 'Authorization: Bearer {api_token}'

Expanding Multiple Relations

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 variants and the collection of products, pass to the expand query parameter the value variants,collection:

curl "http://localhost:9000/admin/products?expand=variants,collection" \
-H 'Authorization: Bearer {api_token}'

Prevent Expanding Relations

Some requests expand relations by default. You can prevent that by passing an empty expand value to retrieve an entity without any extra relations.

For example:

curl "http://localhost:9000/admin/products?expand" \
-H 'Authorization: Bearer {api_token}'

This would retrieve each product with only its properties, without any relations like collection.

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.

Please note that if you pass a fields query parameter, only the fields you pass in the value along with the id of the entity will be returned in the response.

Also, the fields query parameter does not affect the expanded relations. You'll have to use the expand parameter instead.

Selecting One Field

For example, when you retrieve a list of products, you can retrieve only the titles of the products by passing title as a value to the fields query parameter:

curl "http://localhost:9000/admin/products?fields=title" \
-H 'Authorization: Bearer {api_token}'

As mentioned above, the expanded relations such as variants will still be returned as they're not affected by the fields parameter.

You can ensure that only the title field is returned by passing an empty value to the expand query parameter. For example:

curl "http://localhost:9000/admin/products?fields=title&expand" \
-H 'Authorization: Bearer {api_token}'

Selecting Multiple Fields

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

For example, to select the title and handle of products:

curl "http://localhost:9000/admin/products?fields=title,handle" \
-H 'Authorization: Bearer {api_token}'

Retrieve Only the ID

You can pass an empty fields query parameter to return only the ID of an entity. For example:

curl "http://localhost:9000/admin/products?fields" \
-H 'Authorization: Bearer {api_token}'

You can also pair with an empty expand query parameter to ensure that the relations aren't retrieved as well. For example:

curl "http://localhost:9000/admin/products?fields&expand" \
-H 'Authorization: Bearer {api_token}'

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 endpoints and not using our JS Client. For example, when using cURL or Postman.

Strings

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

For example:

curl "http://localhost:9000/admin/products?title=Shirt" \
-H 'Authorization: Bearer {api_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:

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

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:

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

Boolean

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

For example:

curl "http://localhost:9000/admin/products?is_giftcard=true" \
-H 'Authorization: Bearer {api_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.

For example:

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

For example:

curl -g "http://localhost:9000/admin/products?created_at[lt]=2023-02-17T07:22:30Z" \
-H 'Authorization: Bearer {api_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>.

For example:

curl -g "http://localhost:9000/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7" \
-H 'Authorization: Bearer {api_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>.

For example:

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

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.

For example, to limit the number of products returned in the List Products endpoint:

curl "http://localhost:9000/admin/products?limit=5" \
-H 'Authorization: Bearer {api_token}'

Response Fields

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

Similar 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

application_name
required
string
Example: "example"

The app's name

data
required
object or null
Example: {}

Any data necessary to the app.

display_name
required
string
Example: "Example app"

The app's display name

id
required
string
Example: "example_app"

The app's ID

install_url
required
string or null <uri>

The URL to install the app

uninstall_url
required
string or null <uri>

The URL to uninstall 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
application_name
required
string
Example: "example"

The app's name

data
required
object or null
Example: {}

Any data necessary to the app.

display_name
required
string
Example: "Example app"

The app's display name

id
required
string
Example: "example_app"

The app's ID

install_url
required
string or null <uri>

The URL to install the app

uninstall_url
required
string or null <uri>

The URL to uninstall 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.

api_token
required
string or null
Example: null

An API token associated with the user.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The email of the User

first_name
required
string or null
Example: "Levi"

The first name of the User

id
required
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The user's ID

last_name
required
string or null
Example: "Bogan"

The last name of the User

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

role
required
string
Default: "member"
Enum: "admin" "member" "developer"

The user's role

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

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.

api_token
required
string or null
Example: null

An API token associated with the user.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The email of the User

first_name
required
string or null
Example: "Levi"

The first name of the User

id
required
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The user's ID

last_name
required
string or null
Example: "Bogan"

The last name of the User

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

role
required
string
Default: "member"
Enum: "admin" "member" "developer"

The user's role

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

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.

canceled_at
required
string or null <date-time>

The date of the concellation.

completed_at
required
string or null <date-time>

The date of the completion.

confirmed_at
required
string or null <date-time>

The date when the confirmation has been done.

context
required
object or null
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.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

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

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

dry_run
required
boolean
Default: false

Specify if the job must apply the modifications or not.

failed_at
required
string or null <date-time>

The date when the job failed.

id
required
string
Example: "batch_01G8T782965PYFG0751G0Z38B4"

The unique identifier for the batch job.

pre_processed_at
required
string or null <date-time>

The date from which the job has been pre-processed.

processing_at
required
string or null <date-time>

The date the job is processing at.

required
object or null
Example: {}

The result of the batch job.

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

The status of the batch job.

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

The type of batch job.

updated_at
required
string <date-time>

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

object (User)

Represents a User who can manage store settings.

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.

canceled_at
required
string or null <date-time>

The date of the concellation.

completed_at
required
string or null <date-time>

The date of the completion.

confirmed_at
required
string or null <date-time>

The date when the confirmation has been done.

context
required
object or null
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.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

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

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

dry_run
required
boolean
Default: false

Specify if the job must apply the modifications or not.

failed_at
required
string or null <date-time>

The date when the job failed.

id
required
string
Example: "batch_01G8T782965PYFG0751G0Z38B4"

The unique identifier for the batch job.

pre_processed_at
required
string or null <date-time>

The date from which the job has been pre-processed.

processing_at
required
string or null <date-time>

The date the job is processing at.

required
object or null
Example: {}

The result of the batch job.

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

The status of the batch job.

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

The type of batch job.

updated_at
required
string <date-time>

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

object (User)

Represents a User who can manage store settings.

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.

canceled_at
required
string or null <date-time>

The date of the concellation.

completed_at
required
string or null <date-time>

The date of the completion.

confirmed_at
required
string or null <date-time>

The date when the confirmation has been done.

context
required
object or null
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.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

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

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

dry_run
required
boolean
Default: false

Specify if the job must apply the modifications or not.

failed_at
required
string or null <date-time>

The date when the job failed.

id
required
string
Example: "batch_01G8T782965PYFG0751G0Z38B4"

The unique identifier for the batch job.

pre_processed_at
required
string or null <date-time>

The date from which the job has been pre-processed.

processing_at
required
string or null <date-time>

The date the job is processing at.

required
object or null
Example: {}

The result of the batch job.

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

The status of the batch job.

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

The type of batch job.

updated_at
required
string <date-time>

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

object (User)

Represents a User who can manage store settings.

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.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

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

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

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

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

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

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string or null
Example: "summer-collection"

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

id
required
string
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The product collection's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

title
required
string
Example: "Summer Collection"

The title that the Product Collection is identified by.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

products
Array of objects

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

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.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string or null
Example: "summer-collection"

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

id
required
string
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The product collection's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

title
required
string
Example: "Summer Collection"

The title that the Product Collection is identified by.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

products
Array of objects

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

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.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string or null
Example: "summer-collection"

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

id
required
string
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The product collection's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

title
required
string
Example: "Summer Collection"

The title that the Product Collection is identified by.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

products
Array of objects

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

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.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string or null
Example: "summer-collection"

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

id
required
string
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The product collection's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

title
required
string
Example: "Summer Collection"

The title that the Product Collection is identified by.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

products
Array of objects

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

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.

name
required
string
Example: "US Dollar"

The written name of 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.

includes_tax
boolean
Default: false

[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

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.customers.list()
.then(({ customers, limit, offset, count }) => {
  console.log(customers.length);
});

Response samples

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

Get a Customer

Retrieves a Customer.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Customer.

query Parameters
expand
string

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

fields
string

(Comma separated) Which fields should be included in the customer.

Responses

Response Schema: application/json
object (Customer)

Represents a customer

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The customer's billing address ID

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The customer's email

first_name
required
string or null
Example: "Arno"

The customer's first name

has_account
required
boolean
Default: false

Whether the customer has an account or not

id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The customer's ID

last_name
required
string or null
Example: "Willms"

The customer's last name

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

phone
required
string or null
Example: 16128234334802

The customer's phone number

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

Array of objects (Address)

Available if the relation shipping_addresses is expanded.

orders
Array of objects

Available if the relation orders is expanded.

Array of objects (Customer Group)

The customer groups the customer belongs to. Available if the relation groups is expanded.

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.customers.retrieve(customer_id)
.then(({ customer }) => {
  console.log(customer.id);
});

Response samples

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

Update a Customer

Updates a Customer.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Customer.

query Parameters
expand
string

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

fields
string

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

Request Body schema: application/json
email
string <email>

The Customer's email.

first_name
string

The Customer's first name.

last_name
string

The Customer's last name.

phone
string

The Customer's phone number.

password
string <password>

The Customer's password.

Array of objects

A list of customer groups to which the customer belongs.

metadata
object

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

Responses

Response Schema: application/json
object (Customer)

Represents a customer

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The customer's billing address ID

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The customer's email

first_name
required
string or null
Example: "Arno"

The customer's first name

has_account
required
boolean
Default: false

Whether the customer has an account or not

id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The customer's ID

last_name
required
string or null
Example: "Willms"

The customer's last name

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

phone
required
string or null
Example: 16128234334802

The customer's phone number

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

Array of objects (Address)

Available if the relation shipping_addresses is expanded.

orders
Array of objects

Available if the relation orders is expanded.

Array of objects (Customer Group)

The customer groups the customer belongs to. Available if the relation groups is expanded.

Request samples

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

Response samples

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

Customer Group

Customer Group endpoints that allow handling customer groups in Medusa.

Add Customers

Adds a list of customers, represented by id's, to a customer group.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the customer group.

Request Body schema: application/json
required
Array of objects

The ids of the customers to add

Array
id
required
string

ID of the customer

Responses

Response Schema: application/json
object (Customer Group)

Represents a customer group

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "cgrp_01G8ZH853Y6TFXWPG5EYE81X63"

The customer group's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "VIP"

The name of the customer group

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

customers
Array of objects

The customers that belong to the customer group. Available if the relation customers is expanded.

price_lists
Array of objects

The price lists that are associated with the customer group. Available if the relation price_lists is expanded.

Request samples

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

Response samples

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

Remove Customers

Removes a list of customers, represented by id's, from a customer group.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the customer group.

Request Body schema: application/json
required
Array of objects

The ids of the customers to remove

Array
id
required
string

ID of the customer

Responses

Response Schema: application/json
object (Customer Group)

Represents a customer group

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "cgrp_01G8ZH853Y6TFXWPG5EYE81X63"

The customer group's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "VIP"

The name of the customer group

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

customers
Array of objects

The customers that belong to the customer group. Available if the relation customers is expanded.

price_lists
Array of objects

The price lists that are associated with the customer group. Available if the relation price_lists is expanded.

Request samples

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

Response samples

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

Create a Customer Group

Creates a CustomerGroup.

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

Name of the customer group

metadata
object

Metadata for the customer.

Responses

Response Schema: application/json
object (Customer Group)

Represents a customer group

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "cgrp_01G8ZH853Y6TFXWPG5EYE81X63"

The customer group's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "VIP"

The name of the customer group

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

customers
Array of objects

The customers that belong to the customer group. Available if the relation customers is expanded.

price_lists
Array of objects

The price lists that are associated with the customer group. Available if the relation price_lists is expanded.

Request samples

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

Response samples

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

List Customer Groups

Retrieve a list of customer groups.

Authorizations:
API TokenCookie Session ID
query Parameters
q
string

Query used for searching customer group names.

offset
integer
Default: 0

How many groups to skip in the result.

order
string

the field used to order the customer groups.

discount_condition_id
string

The discount condition id on which to filter the customer groups.

string or Array of strings or object

Filter by the customer group ID

name
Array of strings

Filter by the customer group name

object

Date comparison for when resulting customer groups were created.

object

Date comparison for when resulting customer groups were updated.

limit
integer
Default: 10

Limit the number of customer groups returned.

expand
string

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

Responses

Response Schema: application/json
Array of objects (Customer Group)
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.customerGroups.list()
.then(({ customer_groups, limit, offset, count }) => {
  console.log(customer_groups.length);
});

Response samples

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

Delete a Customer Group

Deletes a CustomerGroup.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Customer Group

Responses

Response Schema: application/json
id
string

The ID of the deleted customer group.

object
string
Default: "customer_group"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether the customer group 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.customerGroups.delete(customer_group_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Customer Group

Retrieves a Customer Group.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Customer Group.

query Parameters
expand
string

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

fields
string

(Comma separated) Which fields should be included in the customer group.

Responses

Response Schema: application/json
object (Customer Group)

Represents a customer group

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "cgrp_01G8ZH853Y6TFXWPG5EYE81X63"

The customer group's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "VIP"

The name of the customer group

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

customers
Array of objects

The customers that belong to the customer group. Available if the relation customers is expanded.

price_lists
Array of objects

The price lists that are associated with the customer group. Available if the relation price_lists is expanded.

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.customerGroups.retrieve(customer_group_id)
.then(({ customer_group }) => {
  console.log(customer_group.id);
});

Response samples

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

Update a Customer Group

Update a CustomerGroup.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the customer group.

Request Body schema: application/json
name
string

Name of the customer group

metadata
object

Metadata for the customer.

Responses

Response Schema: application/json
object (Customer Group)

Represents a customer group

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "cgrp_01G8ZH853Y6TFXWPG5EYE81X63"

The customer group's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "VIP"

The name of the customer group

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

customers
Array of objects

The customers that belong to the customer group. Available if the relation customers is expanded.

price_lists
Array of objects

The price lists that are associated with the customer group. Available if the relation price_lists is expanded.

Request samples

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

Response samples

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

List Customers

Retrieves a list of customers in a customer group

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the customer group.

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

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.customerGroups.listCustomers(customer_group_id)
.then(({ customers }) => {
  console.log(customers.length);
});

Response samples

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

Discount

Discount endpoints that allow handling discounts in Medusa.

Add Region

Adds a Region to the list of Regions that a Discount can be used in.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Discount.

region_id
required
string

The ID of the Region.

Responses

Response Schema: application/json
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

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.discounts.addRegion(discount_id, region_id)
.then(({ discount }) => {
  console.log(discount.id);
});

Response samples

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

Remove Region

Removes a Region from the list of Regions that a Discount can be used in.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Discount.

region_id
required
string

The ID of the Region.

Responses

Response Schema: application/json
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

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.discounts.removeRegion(discount_id, region_id)
.then(({ discount }) => {
  console.log(discount.id);
});

Response samples

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

Creates a Discount

Creates a Discount with a given set of rules that define how the Discount behaves.

Authorizations:
API TokenCookie Session ID
query Parameters
expand
string

(Comma separated) Which fields should be expanded in the results.

fields
string

(Comma separated) Which fields should be retrieved in the results.

Request Body schema: application/json
code
required
string

A unique code that will be used to redeem the Discount

required
object

The Discount Rule that defines how Discounts are calculated

regions
required
Array of strings

A list of Region ids representing the Regions in which the Discount can be used.

is_dynamic
boolean
Default: false

Whether the Discount should have multiple instances of itself, each with a different code. This can be useful for automatically generated codes that all have to follow a common set of rules.

is_disabled
boolean
Default: false

Whether the Discount code is disabled on creation. You will have to enable it later to make it available to Customers.

starts_at
string <date-time>

The time at which the Discount should be available.

ends_at
string <date-time>

The time at which the Discount should no longer be available.

valid_duration
string
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

usage_limit
number

Maximum times the discount can be used

metadata
object

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

Responses

Response Schema: application/json
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

Request samples

Content type
application/json
{
  • "code": "string",
  • "is_dynamic": false,
  • "rule": {
    },
  • "is_disabled": false,
  • "starts_at": "2019-08-24T14:15:22Z",
  • "ends_at": "2019-08-24T14:15:22Z",
  • "valid_duration": "P3Y6M4DT12H30M5S",
  • "regions": [
    ],
  • "usage_limit": 0,
  • "metadata": { }
}

Response samples

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

List Discounts

Retrieves a list of Discounts

Authorizations:
API TokenCookie Session ID
query Parameters
q
string

Search query applied on the code field.

object

Discount Rules filters to apply on the search

is_dynamic
boolean

Return only dynamic discounts.

is_disabled
boolean

Return only disabled discounts.

limit
number
Default: "20"

The number of items in the response

offset
number
Default: "0"

The offset of items in response

expand
string

Comma separated list of relations to include in the results.

Responses

Response Schema: application/json
Array of objects (Discount)
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.discounts.list()
.then(({ discounts, limit, offset, count }) => {
  console.log(discounts.id);
});

Response samples

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

Create a Dynamic Code

Creates a dynamic unique code that can map to a parent Discount. This is useful if you want to automatically generate codes with the same behaviour.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Discount to create the dynamic code from."

Request Body schema: application/json
code
required
string

A unique code that will be used to redeem the Discount

usage_limit
number
Default: 1

Maximum times the discount can be used

metadata
object

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

Responses

Response Schema: application/json
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

Request samples

Content type
application/json
{
  • "code": "string",
  • "usage_limit": 1,
  • "metadata": { }
}

Response samples

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

Update a Condition

Updates a DiscountCondition. Only one of products, product_types, product_collections, product_tags, and customer_groups should be provided.

Authorizations:
API TokenCookie Session ID
path Parameters
discount_id
required
string

The ID of the Product.

condition_id
required
string

The ID of the DiscountCondition.

query Parameters
expand
string

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

fields
string

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

Request Body schema: application/json
products
Array of strings

list of product IDs if the condition is applied on products.

product_types
Array of strings

list of product type IDs if the condition is applied on product types.

product_collections
Array of strings

list of product collection IDs if the condition is applied on product collections.

product_tags
Array of strings

list of product tag IDs if the condition is applied on product tags.

customer_groups
Array of strings

list of customer group IDs if the condition is applied on customer groups.

Responses

Response Schema: application/json
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

Request samples

Content type
application/json
{
  • "products": [
    ],
  • "product_types": [
    ],
  • "product_collections": [
    ],
  • "product_tags": [
    ],
  • "customer_groups": [
    ]
}

Response samples

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

Delete a Discount

Deletes a Discount.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Discount

Responses

Response Schema: application/json
id
string

The ID of the deleted Discount

object
string
Default: "discount"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether the discount 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.discounts.delete(discount_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Discount

Retrieves a Discount

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Discount

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

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.discounts.retrieve(discount_id)
.then(({ discount }) => {
  console.log(discount.id);
});

Response samples

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

Update a Discount

Updates a Discount with a given set of rules that define how the Discount behaves.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Discount.

query Parameters
expand
string

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

fields
string

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

Request Body schema: application/json
code
string

A unique code that will be used to redeem the Discount

object

The Discount Rule that defines how Discounts are calculated

is_disabled
boolean

Whether the Discount code is disabled on creation. You will have to enable it later to make it available to Customers.

starts_at
string <date-time>

The time at which the Discount should be available.

ends_at
string <date-time>

The time at which the Discount should no longer be available.

valid_duration
string
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

usage_limit
number

Maximum times the discount can be used

regions
Array of strings

A list of Region ids representing the Regions in which the Discount can be used.

metadata
object

An object containing metadata of the discount

Responses

Response Schema: application/json
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

Request samples

Content type
application/json
{
  • "code": "string",
  • "rule": {
    },
  • "is_disabled": true,
  • "starts_at": "2019-08-24T14:15:22Z",
  • "ends_at": "2019-08-24T14:15:22Z",
  • "valid_duration": "P3Y6M4DT12H30M5S",
  • "usage_limit": 0,
  • "regions": [
    ],
  • "metadata": { }
}

Response samples

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

Delete a Dynamic Code

Deletes a dynamic code from a Discount.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Discount

code
required
string

The ID of the Discount

Responses

Response Schema: application/json
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

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.discounts.deleteDynamicCode(discount_id, code)
.then(({ discount }) => {
  console.log(discount.id);
});

Response samples

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

Get Discount by Code

Retrieves a Discount by its discount code

Authorizations:
API TokenCookie Session ID
path Parameters
code
required
string

The code of the Discount

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

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.discounts.retrieveByCode(code)
.then(({ discount }) => {
  console.log(discount.id);
});

Response samples

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

Discount Condition

Discount Condition endpoints that allow handling discount conditions in Medusa.

Add Batch Resources

Add a batch of resources to a discount condition.

Authorizations:
API TokenCookie Session ID
path Parameters
discount_id
required
string

The ID of the Product.

condition_id
required
string

The ID of the condition on which to add the item.

query Parameters
expand
string

(Comma separated) Which relations should be expanded in each discount of the result.

fields
string

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

Request Body schema: application/json
required
Array of objects

The resources to be added to the discount condition

Array
id
required
string

The id of the item

Responses

Response Schema: application/json
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

Request samples

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

Response samples

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

Delete Batch Resources

Delete a batch of resources from a discount condition.

Authorizations:
API TokenCookie Session ID
path Parameters
discount_id
required
string

The ID of the Product.

condition_id
required
string

The ID of the condition on which to add the item.

query Parameters
expand
string

(Comma separated) Which relations should be expanded in each discount of the result.

fields
string

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

Request Body schema: application/json
required
Array of objects

The resources to be deleted from the discount condition

Array
id
required
string

The id of the item

Responses

Response Schema: application/json
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

Request samples

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

Response samples

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

Create a Condition

Creates a DiscountCondition. Only one of products, product_types, product_collections, product_tags, and customer_groups should be provided.

Authorizations:
API TokenCookie Session ID
path Parameters
discount_id
required
string

The ID of the Product.

query Parameters
expand
string

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

fields
string

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

Request Body schema: application/json
operator
required
string
Enum: "in" "not_in"

Operator of the condition

products
Array of strings

list of product IDs if the condition is applied on products.

product_types
Array of strings

list of product type IDs if the condition is applied on product types.

product_collections
Array of strings

list of product collection IDs if the condition is applied on product collections.

product_tags
Array of strings

list of product tag IDs if the condition is applied on product tags.

customer_groups
Array of strings

list of customer group IDs if the condition is applied on customer groups.

Responses

Response Schema: application/json
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

Request samples

Content type
application/json
{
  • "operator": "in",
  • "products": [
    ],
  • "product_types": [
    ],
  • "product_collections": [
    ],
  • "product_tags": [
    ],
  • "customer_groups": [
    ]
}

Response samples

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

Delete a Condition

Deletes a DiscountCondition

Authorizations:
API TokenCookie Session ID
path Parameters
discount_id
required
string

The ID of the Discount

condition_id
required
string

The ID of the DiscountCondition

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
id
string

The ID of the deleted DiscountCondition

object
string
Default: "discount-condition"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether the discount condition was deleted successfully or not.

object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

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.discounts.deleteCondition(discount_id, condition_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Condition

Gets a DiscountCondition

Authorizations:
API TokenCookie Session ID
path Parameters
discount_id
required
string

The ID of the Discount.

condition_id
required
string

The ID of the DiscountCondition.

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
object (Discount Condition)

Holds rule conditions for when a discount is applicable

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

discount_rule_id
required
string
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The ID of the discount rule associated with the condition

id
required
string
Example: "discon_01G8X9A7ESKAJXG2H0E6F1MW7A"

The discount condition's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

operator
required
string
Enum: "in" "not_in"

The operator of the Condition

type
required
string
Enum: "products" "product_types" "product_collections" "product_tags" "customer_groups"

The type of the Condition

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

Array of objects (Product)

products associated with this condition if type = products. Available if the relation products is expanded.

Array of objects (Product Type)

Product types associated with this condition if type = product_types. Available if the relation product_types is expanded.

Array of objects (Product Tag)

Product tags associated with this condition if type = product_tags. Available if the relation product_tags is expanded.

Array of objects (Product Collection)

Product collections associated with this condition if type = product_collections. Available if the relation product_collections is expanded.

Array of objects (Customer Group)

Customer groups associated with this condition if type = customer_groups. Available if the relation customer_groups is expanded.

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.discounts.getCondition(discount_id, condition_id)
.then(({ discount_condition }) => {
  console.log(discount_condition.id);
});

Response samples

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

Draft Order

Draft Order endpoints that allow handling draft orders in Medusa.

Create a Draft Order

Creates a Draft Order

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

The email of the customer of the draft order

region_id
required
string

The ID of the region for the draft order

required
Array of objects

The shipping methods for the draft order

status
string
Enum: "open" "completed"

The status of the draft order

Address Fields (object) or string

The Address to be used for billing purposes.

Address Fields (object) or string

The Address to be used for shipping.

Array of objects

The Line Items that have been received.

Array of objects

The discounts to add on the draft order

customer_id
string

The ID of the customer to add on the draft order

no_notification_order
boolean

An optional flag passed to the resulting order to determine use of notifications.

metadata
object

The optional key-value map with additional details about the Draft Order.

Responses

Response Schema: application/json
object (DraftOrder)

Represents a draft order

canceled_at
required
string or null <date-time>

The date the draft order was canceled at.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the draft order.

completed_at
required
string or null <date-time>

The date the draft order was completed at.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

display_id
required
string
Example: 2

The draft order's display ID

id
required
string
Example: "dorder_01G8TJFKBG38YYFQ035MSVG03C"

The draft order's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of the cart associated with the draft order in case of failure.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification_order
required
boolean or null
Example: false

Whether to send the customer notifications regarding order updates.

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the order associated with the draft order.

status
required
string
Default: "open"
Enum: "open" "completed"

The status of the draft order

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

order
object or null

An order object. Available if the relation order is expanded.

Request samples

Content type
application/json
{
  • "status": "open",
  • "email": "user@example.com",
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "items": [
    ],
  • "region_id": "string",
  • "discounts": [
    ],
  • "customer_id": "string",
  • "no_notification_order": true,
  • "shipping_methods": [
    ],
  • "metadata": { }
}

Response samples

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

List Draft Orders

Retrieves an list of Draft Orders

Authorizations:
API TokenCookie Session ID
query Parameters
offset
number
Default: "0"

The number of items to skip before the results.

limit
number
Default: "50"

Limit the number of items returned.

q
string

a search term to search emails in carts associated with draft orders and display IDs of draft orders

Responses

Response Schema: application/json
Array of objects (DraftOrder)
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.draftOrders.list()
.then(({ draft_orders, limit, offset, count }) => {
  console.log(draft_orders.length);
});

Response samples

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

Create a Line Item

Creates a Line Item for the Draft Order

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Draft Order.

Request Body schema: application/json
quantity
required
integer

The quantity of the Line Item.

variant_id
string

The ID of the Product Variant to generate the Line Item from.

unit_price
integer

The potential custom price of the item.

title
string
Default: "Custom item"

The potential custom title of the item.

metadata
object

The optional key-value map with additional details about the Line Item.

Responses

Response Schema: application/json
object (DraftOrder)

Represents a draft order

canceled_at
required
string or null <date-time>

The date the draft order was canceled at.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the draft order.

completed_at
required
string or null <date-time>

The date the draft order was completed at.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

display_id
required
string
Example: 2

The draft order's display ID

id
required
string
Example: "dorder_01G8TJFKBG38YYFQ035MSVG03C"

The draft order's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of the cart associated with the draft order in case of failure.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification_order
required
boolean or null
Example: false

Whether to send the customer notifications regarding order updates.

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the order associated with the draft order.

status
required
string
Default: "open"
Enum: "open" "completed"

The status of the draft order

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

order
object or null

An order object. Available if the relation order is expanded.

Request samples

Content type
application/json
{
  • "variant_id": "string",
  • "unit_price": 0,
  • "title": "Custom item",
  • "quantity": 0,
  • "metadata": { }
}

Response samples

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

Delete a Draft Order

Deletes a Draft Order

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Draft Order.

Responses

Response Schema: application/json
id
string

The ID of the deleted Draft Order.

object
string
Default: "draft-order"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether the draft order 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.draftOrders.delete(draft_order_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Draft Order

Retrieves a Draft Order.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Draft Order.

Responses

Response Schema: application/json
object (DraftOrder)

Represents a draft order

canceled_at
required
string or null <date-time>

The date the draft order was canceled at.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the draft order.

completed_at
required
string or null <date-time>

The date the draft order was completed at.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

display_id
required
string
Example: 2

The draft order's display ID

id
required
string
Example: "dorder_01G8TJFKBG38YYFQ035MSVG03C"

The draft order's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of the cart associated with the draft order in case of failure.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification_order
required
boolean or null
Example: false

Whether to send the customer notifications regarding order updates.

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the order associated with the draft order.

status
required
string
Default: "open"
Enum: "open" "completed"

The status of the draft order

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

order
object or null

An order object. Available if the relation order is expanded.

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.draftOrders.retrieve(draft_order_id)
.then(({ draft_order }) => {
  console.log(draft_order.id);
});

Response samples

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

Delete a Line Item

Removes a Line Item from a Draft Order.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Draft Order.

line_id
required
string

The ID of the Draft Order.

Responses

Response Schema: application/json
object (DraftOrder)

Represents a draft order

canceled_at
required
string or null <date-time>

The date the draft order was canceled at.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the draft order.

completed_at
required
string or null <date-time>

The date the draft order was completed at.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

display_id
required
string
Example: 2

The draft order's display ID

id
required
string
Example: "dorder_01G8TJFKBG38YYFQ035MSVG03C"

The draft order's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of the cart associated with the draft order in case of failure.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification_order
required
boolean or null
Example: false

Whether to send the customer notifications regarding order updates.

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the order associated with the draft order.

status
required
string
Default: "open"
Enum: "open" "completed"

The status of the draft order

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

order
object or null

An order object. Available if the relation order is expanded.

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.draftOrders.removeLineItem(draft_order_id, item_id)
.then(({ draft_order }) => {
  console.log(draft_order.id);
});

Response samples

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

Update a Line Item

Updates a Line Item for a Draft Order

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Draft Order.

line_id
required
string

The ID of the Line Item.

Request Body schema: application/json
unit_price
integer

The potential custom price of the item.

title
string

The potential custom title of the item.

quantity
integer

The quantity of the Line Item.

metadata
object

The optional key-value map with additional details about the Line Item.

Responses

Response Schema: application/json
object (DraftOrder)

Represents a draft order

canceled_at
required
string or null <date-time>

The date the draft order was canceled at.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the draft order.

completed_at
required
string or null <date-time>

The date the draft order was completed at.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

display_id
required
string
Example: 2

The draft order's display ID

id
required
string
Example: "dorder_01G8TJFKBG38YYFQ035MSVG03C"

The draft order's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of the cart associated with the draft order in case of failure.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification_order
required
boolean or null
Example: false

Whether to send the customer notifications regarding order updates.

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the order associated with the draft order.

status
required
string
Default: "open"
Enum: "open" "completed"

The status of the draft order

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

order
object or null

An order object. Available if the relation order is expanded.

Request samples

Content type
application/json
{
  • "unit_price": 0,
  • "title": "string",
  • "quantity": 0,
  • "metadata": { }
}

Response samples

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

Registers a Payment

Registers a payment for a Draft Order.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The Draft Order id.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.draftOrders.markPaid(draft_order_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Update a Draft Order

Updates a Draft Order.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Draft Order.

Request Body schema: application/json
region_id
string

The ID of the Region to create the Draft Order in.

country_code
string

The 2 character ISO code for the Country.

email
string <email>

An email to be used on the Draft Order.

Address Fields (object) or string

The Address to be used for billing purposes.

Address Fields (object) or string

The Address to be used for shipping.

Array of objects

An array of Discount codes to add to the Draft Order.

no_notification_order
boolean

An optional flag passed to the resulting order to determine use of notifications.

customer_id
string

The ID of the Customer to associate the Draft Order with.

Responses

Response Schema: application/json
object (DraftOrder)

Represents a draft order

canceled_at
required
string or null <date-time>

The date the draft order was canceled at.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the draft order.

completed_at
required
string or null <date-time>

The date the draft order was completed at.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

display_id
required
string
Example: 2

The draft order's display ID

id
required
string
Example: "dorder_01G8TJFKBG38YYFQ035MSVG03C"

The draft order's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of the cart associated with the draft order in case of failure.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification_order
required
boolean or null
Example: false

Whether to send the customer notifications regarding order updates.

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the order associated with the draft order.

status
required
string
Default: "open"
Enum: "open" "completed"

The status of the draft order

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

order
object or null

An order object. Available if the relation order is expanded.

Request samples

Content type
application/json
{
  • "region_id": "string",
  • "country_code": "string",
  • "email": "user@example.com",
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "discounts": [
    ],
  • "no_notification_order": true,
  • "customer_id": "string"
}

Response samples

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

Fulfillment

Cancel Claim Fulfillment

Registers a claim's fulfillment as canceled.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order which the Claim relates to.

claim_id
required
string

The ID of the Claim which the Fulfillment relates to.

fulfillment_id
required
string

The ID of the Fulfillment.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.cancelClaimFulfillment(order_id, claim_id, fulfillment_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Cancel Swap's Fulfilmment

Registers a Swap's Fulfillment as canceled.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order which the Swap relates to.

swap_id
required
string

The ID of the Swap which the Fulfillment relates to.

fulfillment_id
required
string

The ID of the Fulfillment.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.cancelSwapFulfillment(order_id, swap_id, fulfillment_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Cancels a Fulfilmment

Registers a Fulfillment as canceled.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order which the Fulfillment relates to.

fulfillment_id
required
string

The ID of the Fulfillment

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.cancelFulfillment(order_id, fulfillment_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Create a Fulfillment

Creates a Fulfillment of an Order - will notify Fulfillment Providers to prepare a shipment.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Request Body schema: application/json
required
Array of objects

The Line Items to include in the Fulfillment.

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

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

Request samples

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

Response samples

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

Create Claim Fulfillment

Creates a Fulfillment for 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.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Request Body schema: application/json
metadata
object

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

no_notification
boolean

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

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

Request samples

Content type
application/json
{
  • "metadata": { },
  • "no_notification": true
}

Response samples

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

Create Swap Fulfillment

Creates a Fulfillment for a Swap.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

swap_id
required
string

The ID of the Swap.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Request Body schema: application/json
metadata
object

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

no_notification
boolean

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

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

Request samples

Content type
application/json
{
  • "metadata": { },
  • "no_notification": true
}

Response samples

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

Gift Card

Gift Card endpoints that allow handling gift cards in Medusa.

Create a Gift Card

Creates a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region.

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

The ID of the Region in which the Gift Card can be used.

value
integer

The value (excluding VAT) that the Gift Card should represent.

is_disabled
boolean

Whether the Gift Card is disabled on creation. You will have to enable it later to make it available to Customers.

ends_at
string <date-time>

The time at which the Gift Card should no longer be available.

metadata
object

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

Responses

Response Schema: application/json
object (Gift Card)

Gift Cards are redeemable and represent a value that can be used towards the payment of an Order.

balance
required
integer
Example: 10

The remaining value on the Gift Card.

code
required
string
Example: "3RFT-MH2C-Y4YZ-XMN4"

The unique code that identifies the Gift Card. This is used by the Customer to redeem the value of the Gift Card.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the Gift Card can no longer be used.

id
required
string
Example: "gift_01G8XKBPBQY2R7RBET4J7E0XQZ"

The gift card's ID

is_disabled
required
boolean
Default: false

Whether the Gift Card has been disabled. Disabled Gift Cards cannot be applied to carts.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The id of the Order that the Gift Card was purchased in.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The id of the Region in which the Gift Card is available.

tax_rate
required
number or null
Example: 0

The gift card's tax rate that will be applied on calculating totals

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

value
required
integer
Example: 10

The value that the Gift Card represents.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

order
object or null

An order object. Available if the relation order is expanded.

Request samples

Content type
application/json
{
  • "value": 0,
  • "is_disabled": true,
  • "ends_at": "2019-08-24T14:15:22Z",
  • "region_id": "string",
  • "metadata": { }
}

Response samples

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

List Gift Cards

Retrieves a list of Gift Cards.

Authorizations:
API TokenCookie Session ID
query Parameters
offset
number
Default: "0"

The number of items to skip before the results.

limit
number
Default: "50"

Limit the number of items returned.

q
string

a search term to search by code or display ID

Responses

Response Schema: application/json
Array of objects (Gift Card)
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.giftCards.list()
.then(({ gift_cards, limit, offset, count }) => {
  console.log(gift_cards.length);
});

Response samples

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

Delete a Gift Card

Deletes a Gift Card

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Gift Card to delete.

Responses

Response Schema: application/json
id
string

The ID of the deleted Gift Card

object
string
Default: "gift-card"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether the gift card 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.giftCards.delete(gift_card_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Gift Card

Retrieves a Gift Card.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Gift Card.

Responses

Response Schema: application/json
object (Gift Card)

Gift Cards are redeemable and represent a value that can be used towards the payment of an Order.

balance
required
integer
Example: 10

The remaining value on the Gift Card.

code
required
string
Example: "3RFT-MH2C-Y4YZ-XMN4"

The unique code that identifies the Gift Card. This is used by the Customer to redeem the value of the Gift Card.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the Gift Card can no longer be used.

id
required
string
Example: "gift_01G8XKBPBQY2R7RBET4J7E0XQZ"

The gift card's ID

is_disabled
required
boolean
Default: false

Whether the Gift Card has been disabled. Disabled Gift Cards cannot be applied to carts.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The id of the Order that the Gift Card was purchased in.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The id of the Region in which the Gift Card is available.

tax_rate
required
number or null
Example: 0

The gift card's tax rate that will be applied on calculating totals

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

value
required
integer
Example: 10

The value that the Gift Card represents.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

order
object or null

An order object. Available if the relation order is expanded.

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.giftCards.retrieve(gift_card_id)
.then(({ gift_card }) => {
  console.log(gift_card.id);
});

Response samples

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

Update a Gift Card

Update a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Gift Card.

Request Body schema: application/json
balance
integer

The value (excluding VAT) that the Gift Card should represent.

is_disabled
boolean

Whether the Gift Card is disabled on creation. You will have to enable it later to make it available to Customers.

ends_at
string <date-time>

The time at which the Gift Card should no longer be available.

region_id
string

The ID of the Region in which the Gift Card can be used.

metadata
object

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

Responses

Response Schema: application/json
object (Gift Card)

Gift Cards are redeemable and represent a value that can be used towards the payment of an Order.

balance
required
integer
Example: 10

The remaining value on the Gift Card.

code
required
string
Example: "3RFT-MH2C-Y4YZ-XMN4"

The unique code that identifies the Gift Card. This is used by the Customer to redeem the value of the Gift Card.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the Gift Card can no longer be used.

id
required
string
Example: "gift_01G8XKBPBQY2R7RBET4J7E0XQZ"

The gift card's ID

is_disabled
required
boolean
Default: false

Whether the Gift Card has been disabled. Disabled Gift Cards cannot be applied to carts.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The id of the Order that the Gift Card was purchased in.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The id of the Region in which the Gift Card is available.

tax_rate
required
number or null
Example: 0

The gift card's tax rate that will be applied on calculating totals

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

value
required
integer
Example: 10

The value that the Gift Card represents.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

order
object or null

An order object. Available if the relation order is expanded.

Request samples

Content type
application/json
{
  • "balance": 0,
  • "is_disabled": true,
  • "ends_at": "2019-08-24T14:15:22Z",
  • "region_id": "string",
  • "metadata": { }
}

Response samples

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

Inventory Items

Create an Inventory Location Level for a given Inventory Item.

Creates an Inventory Location Level for a given Inventory Item.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Inventory Item.

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Request Body schema: application/json
location_id
required
string

the item location ID

stocked_quantity
required
number

the stock quantity of an inventory item at the given location ID

incoming_quantity
number

the incoming stock quantity of an inventory item at the given location ID

Responses

Response Schema: application/json
object (InventoryItemDTO)
sku
required
string

The Stock Keeping Unit (SKU) code of the Inventory Item.

hs_code
string

The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
string

The country in which the Inventory Item was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

mid_code
string

The Manufacturers Identification code that identifies the manufacturer of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.

material
string

The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

weight
number

The weight of the Inventory Item. May be used in shipping rate calculations.

height
number

The height of the Inventory Item. May be used in shipping rate calculations.

width
number

The width of the Inventory Item. May be used in shipping rate calculations.

length
number

The length of the Inventory Item. May be used in shipping rate calculations.

requires_shipping
boolean

Whether the item requires shipping.

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

An optional key-value map with additional details

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.

Request samples

Content type
application/json
{
  • "location_id": "string",
  • "stocked_quantity": 0,
  • "incoming_quantity": 0
}

Response samples

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

List stock levels of a given location.

Lists stock levels of a given location.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Inventory Item.

query Parameters
offset
integer
Default: 0

How many stock locations levels to skip in the result.

limit
integer
Default: 20

Limit the number of stock locations levels returned.

expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
id
any

The id of the location

Array of objects (InventoryLevelDTO)

List of stock levels at a given location

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.inventoryItems.listLocationLevels(inventoryItemId)
.then(({ inventory_item }) => {
  console.log(inventory_item.location_levels);
});

Response samples

Content type
application/json
{
  • "id": null,
  • "location_levels": [
    ]
}

Retrive an Inventory Item.

Retrives an Inventory Item.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Inventory Item.

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
object (InventoryItemDTO)
sku
required
string

The Stock Keeping Unit (SKU) code of the Inventory Item.

hs_code
string

The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
string

The country in which the Inventory Item was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

mid_code
string

The Manufacturers Identification code that identifies the manufacturer of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.

material
string

The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

weight
number

The weight of the Inventory Item. May be used in shipping rate calculations.

height
number

The height of the Inventory Item. May be used in shipping rate calculations.

width
number

The width of the Inventory Item. May be used in shipping rate calculations.

length
number

The length of the Inventory Item. May be used in shipping rate calculations.

requires_shipping
boolean

Whether the item requires shipping.

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

An optional key-value map with additional details

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.

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.inventoryItems.retrieve(inventoryItemId)
.then(({ inventory_item }) => {
  console.log(inventory_item.id);
});

Response samples

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

Update an Inventory Item.

Updates an Inventory Item.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Inventory Item.

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Request Body schema: application/json
hs_code
string

The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
string

The country in which the Inventory Item was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

mid_code
string

The Manufacturers Identification code that identifies the manufacturer of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.

material
string

The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

weight
number

The weight of the Inventory Item. May be used in shipping rate calculations.

height
number

The height of the Inventory Item. May be used in shipping rate calculations.

width
number

The width of the Inventory Item. May be used in shipping rate calculations.

length
number

The length of the Inventory Item. May be used in shipping rate calculations.

requires_shipping
boolean

Whether the item requires shipping.

Responses

Response Schema: application/json
object (InventoryItemDTO)
sku
required
string

The Stock Keeping Unit (SKU) code of the Inventory Item.

hs_code
string

The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
string

The country in which the Inventory Item was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

mid_code
string

The Manufacturers Identification code that identifies the manufacturer of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.

material
string

The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

weight
number

The weight of the Inventory Item. May be used in shipping rate calculations.

height
number

The height of the Inventory Item. May be used in shipping rate calculations.

width
number

The width of the Inventory Item. May be used in shipping rate calculations.

length
number

The length of the Inventory Item. May be used in shipping rate calculations.

requires_shipping
boolean

Whether the item requires shipping.

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

An optional key-value map with additional details

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.

Request samples

Content type
application/json
{
  • "hs_code": "string",
  • "origin_country": "string",
  • "mid_code": "string",
  • "material": "string",
  • "weight": 0,
  • "height": 0,
  • "width": 0,
  • "length": 0,
  • "requires_shipping": true
}

Response samples

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

Delete a location level of an Inventory Item.

Delete a location level of an Inventory Item.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Inventory Item.

location_id
required
string

The ID of the location.

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
object (InventoryItemDTO)
sku
required
string

The Stock Keeping Unit (SKU) code of the Inventory Item.

hs_code
string

The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
string

The country in which the Inventory Item was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

mid_code
string

The Manufacturers Identification code that identifies the manufacturer of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.

material
string

The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

weight
number

The weight of the Inventory Item. May be used in shipping rate calculations.

height
number

The height of the Inventory Item. May be used in shipping rate calculations.

width
number

The width of the Inventory Item. May be used in shipping rate calculations.

length
number

The length of the Inventory Item. May be used in shipping rate calculations.

requires_shipping
boolean

Whether the item requires shipping.

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

An optional key-value map with additional details

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.

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.inventoryItems.deleteLocationLevel(inventoryItemId, locationId)
.then(({ inventory_item }) => {
  console.log(inventory_item.id);
});

Response samples

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

Update an Inventory Location Level for a given Inventory Item.

Updates an Inventory Location Level for a given Inventory Item.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Inventory Item.

location_id
required
string

The ID of the Location.

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Request Body schema: application/json
stocked_quantity
number

the total stock quantity of an inventory item at the given location ID

incoming_quantity
number

the incoming stock quantity of an inventory item at the given location ID

Responses

Response Schema: application/json
object (InventoryItemDTO)
sku
required
string

The Stock Keeping Unit (SKU) code of the Inventory Item.

hs_code
string

The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
string

The country in which the Inventory Item was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

mid_code
string

The Manufacturers Identification code that identifies the manufacturer of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.

material
string

The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

weight
number

The weight of the Inventory Item. May be used in shipping rate calculations.

height
number

The height of the Inventory Item. May be used in shipping rate calculations.

width
number

The width of the Inventory Item. May be used in shipping rate calculations.

length
number

The length of the Inventory Item. May be used in shipping rate calculations.

requires_shipping
boolean

Whether the item requires shipping.

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

An optional key-value map with additional details

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.

Request samples

Content type
application/json
{
  • "stocked_quantity": 0,
  • "incoming_quantity": 0
}

Response samples

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

List inventory items.

Lists inventory items.

Authorizations:
API TokenCookie Session ID
query Parameters
offset
integer
Default: 0

How many inventory items to skip in the result.

limit
integer
Default: 20

Limit the number of inventory items returned.

expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

q
string

Query used for searching product inventory items and their properties.

location_id
Array of strings

Locations ids to search for.

id
string

id to search for.

sku
string

sku to search for.

origin_country
string

origin_country to search for.

mid_code
string

mid_code to search for.

material
string

material to search for.

hs_code
string

hs_code to search for.

weight
string

weight to search for.

length
string

length to search for.

height
string

height to search for.

width
string

width to search for.

requires_shipping
string

requires_shipping to search for.

Responses

Response Schema: application/json
Array of objects
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.inventoryItems.list()
.then(({ inventory_items }) => {
  console.log(inventory_items.length);
});

Response samples

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

InventoryItem

Delete an Inventory Item

Delete an Inventory Item

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Inventory Item to delete.

Responses

Response Schema: application/json
id
string

The ID of the deleted Inventory Item.

object
string <inventory_item>

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the Inventory Item 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.inventoryItems.delete(inventoryItemId)
  .then(({ id, object, deleted }) => {
    console.log(id)
  })

Response samples

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

Invite

Invite endpoints that allow handling invites in Medusa.

Accept an Invite

Accepts an Invite and creates a corresponding user

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

The invite token provided by the admin.

required
object

The User to create.

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "user": {
    }
}

Response samples

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

Create an Invite

Creates an Invite and triggers an 'invite' created event

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

The email for the user to be created.

role
required
string
Enum: "admin" "member" "developer"

The role of the user to be created.

Responses

Request samples

Content type
application/json
{
  • "user": "user@example.com",
  • "role": "admin"
}

Response samples

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

Lists Invites

Lists all Invites

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
Array of objects (Invite)
Array
accepted
required
boolean
Default: false

Whether the invite was accepted or not.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

expires_at
required
string <date-time>

The date the invite expires at.

id
required
string
Example: "invite_01G8TKE4XYCTHSCK2GDEP47RE1"

The invite's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

role
required
string or null
Default: "member"
Enum: "admin" "member" "developer"

The user's role.

token
required
string

The token used to accept the invite.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

user_email
required
string <email>

The email of the user being invited.

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.invites.list()
.then(({ invites }) => {
  console.log(invites.length);
});

Response samples

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

Delete an Invite

Deletes an Invite

Authorizations:
API TokenCookie Session ID
path Parameters
invite_id
required
string

The ID of the Invite

Responses

Response Schema: application/json
id
string

The ID of the deleted Invite.

object
string
Default: "invite"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the Invite 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.invites.delete(invite_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Resend an Invite

Resends an Invite by triggering the 'invite' created event again

Authorizations:
API TokenCookie Session ID
path Parameters
invite_id
required
string

The ID of the Invite

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.invites.resend(invite_id)
.then(() => {
  // successful
})
.catch(() => {
  // an error occurred
});

Response samples

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

Note

Note endpoints that allow handling notes in Medusa.

Creates a Note

Creates a Note which can be associated with any resource as required.

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

The ID of the resource which the Note relates to.

resource_type
required
string

The type of resource which the Note relates to.

value
required
string

The content of the Note to create.

Responses

Response Schema: application/json
object (Note)

Notes are elements which we can use in association with different resources to allow users to describe additional information in relation to these.

author_id
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The ID of the author (user)

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "note_01G8TM8ENBMC7R90XRR1G6H26Q"

The note's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

resource_id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the resource that the Note refers to.

resource_type
required
string
Example: "order"

The type of resource that the Note refers to.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

value
required
string
Example: "This order must be fulfilled on Monday"

The contents of the note.

object (User)

Represents a User who can manage store settings.

Request samples

Content type
application/json
{
  • "resource_id": "string",
  • "resource_type": "string",
  • "value": "string"
}

Response samples

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

List Notes

Retrieves a list of notes

Authorizations:
API TokenCookie Session ID
query Parameters
limit
number
Default: "50"

The number of notes to get

offset
number
Default: "0"

The offset at which to get notes

resource_id
string

The ID which the notes belongs to

Responses

Response Schema: application/json
Array of objects (Note)
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.notes.list()
.then(({ notes, limit, offset, count }) => {
  console.log(notes.length);
});

Response samples

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

Delete a Note

Deletes a Note.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Note to delete.

Responses

Response Schema: application/json
id
string

The ID of the deleted Note.

object
string
Default: "note"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the Note 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.notes.delete(note_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Note

Retrieves a single note using its id

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the note to retrieve.

Responses

Response Schema: application/json
object (Note)

Notes are elements which we can use in association with different resources to allow users to describe additional information in relation to these.

author_id
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The ID of the author (user)

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "note_01G8TM8ENBMC7R90XRR1G6H26Q"

The note's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

resource_id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the resource that the Note refers to.

resource_type
required
string
Example: "order"

The type of resource that the Note refers to.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

value
required
string
Example: "This order must be fulfilled on Monday"

The contents of the note.

object (User)

Represents a User who can manage store settings.

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.notes.retrieve(note_id)
.then(({ note }) => {
  console.log(note.id);
});

Response samples

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

Update a Note

Updates a Note associated with some resource

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Note to update

Request Body schema: application/json
value
required
string

The updated description of the Note.

Responses

Response Schema: application/json
object (Note)

Notes are elements which we can use in association with different resources to allow users to describe additional information in relation to these.

author_id
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The ID of the author (user)

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "note_01G8TM8ENBMC7R90XRR1G6H26Q"

The note's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

resource_id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the resource that the Note refers to.

resource_type
required
string
Example: "order"

The type of resource that the Note refers to.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

value
required
string
Example: "This order must be fulfilled on Monday"

The contents of the note.

object (User)

Represents a User who can manage store settings.

Request samples

Content type
application/json
{
  • "value": "string"
}

Response samples

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

Notification

Notification endpoints that allow handling notifications in Medusa.

List Notifications

Retrieves a list of Notifications.

Authorizations:
API TokenCookie Session ID
query Parameters
offset
integer
Default: 0

The number of notifications to skip before starting to collect the notifications set

limit
integer
Default: 50

The number of notifications to return

fields
string

Comma separated fields to include in the result set

expand
string

Comma separated fields to populate

event_name
string

The name of the event that the notification was sent for.

resource_type
string

The type of resource that the Notification refers to.

resource_id
string

The ID of the resource that the Notification refers to.

to
string

The address that the Notification was sent to. This will usually be an email address, but represent other addresses such as a chat bot user id

include_resends
string

A boolean indicating whether the result set should include resent notifications or not

Responses

Response Schema: application/json
Array of objects (Notification)
Array
created_at
required
string <date-time>

The date with timezone at which the resource was created.

customer_id
required
string or null
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the Customer that the Notification was sent to.

data
required
object
Example: {}

The data that the Notification was sent with. This contains all the data necessary for the Notification Provider to initiate a resend.

event_name
required
string or null
Example: "order.placed"

The name of the event that the notification was sent for.

id
required
string
Example: "noti_01G53V9Y6CKMCGBM1P0X7C28RX"

The notification's ID

parent_id
required
string or null
Example: "noti_01G53V9Y6CKMCGBM1P0X7C28RX"

The notification's parent ID

provider_id
required
string or null
Example: "sengrid"

The id of the Notification Provider that handles the Notification.

resource_type
required
string
Example: "order"

The type of resource that the Notification refers to.

resource_id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the resource that the Notification refers to.

to
required
string
Example: "user@example.com"

The address that the Notification was sent to. This will usually be an email address, but represent other addresses such as a chat bot user id

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Customer)

Represents a customer

parent_notification
object or null

Available if the relation parent_notification is expanded.

resends
Array of objects

The resends that have been completed after the original Notification. Available if the relation resends is expanded.

object (Notification Provider)

Represents a notification provider plugin and holds its installation status.

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.notifications.list()
.then(({ notifications }) => {
  console.log(notifications.length);
});

Response samples

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

Resend Notification

Resends a previously sent notifications, with the same data but optionally to a different address

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Notification

Request Body schema: application/json
to
string

A new address or user identifier that the Notification should be sent to

Responses

Response Schema: application/json
object (Notification)

Notifications a communications sent via Notification Providers as a reaction to internal events such as order.placed. Notifications can be used to show a chronological timeline for communications sent to a Customer regarding an Order, and enables resends.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

customer_id
required
string or null
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the Customer that the Notification was sent to.

data
required
object
Example: {}

The data that the Notification was sent with. This contains all the data necessary for the Notification Provider to initiate a resend.

event_name
required
string or null
Example: "order.placed"

The name of the event that the notification was sent for.

id
required
string
Example: "noti_01G53V9Y6CKMCGBM1P0X7C28RX"

The notification's ID

parent_id
required
string or null
Example: "noti_01G53V9Y6CKMCGBM1P0X7C28RX"

The notification's parent ID

provider_id
required
string or null
Example: "sengrid"

The id of the Notification Provider that handles the Notification.

resource_type
required
string
Example: "order"

The type of resource that the Notification refers to.

resource_id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the resource that the Notification refers to.

to
required
string
Example: "user@example.com"

The address that the Notification was sent to. This will usually be an email address, but represent other addresses such as a chat bot user id

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Customer)

Represents a customer

parent_notification
object or null

Available if the relation parent_notification is expanded.

resends
Array of objects

The resends that have been completed after the original Notification. Available if the relation resends is expanded.

object (Notification Provider)

Represents a notification provider plugin and holds its installation status.

Request samples

Content type
application/json
{
  • "to": "string"
}

Response samples

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

Order

Order endpoints that allow handling orders in Medusa.

Add a Shipping Method

Adds a Shipping Method to an Order. If another Shipping Method exists with the same Shipping Profile, the previous Shipping Method will be replaced.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Request Body schema: application/json
price
required
number

The price (excluding VAT) that should be charged for the Shipping Method

option_id
required
string

The ID of the Shipping Option to create the Shipping Method from.

date
object

The data required for the Shipping Option to create a Shipping Method. This will depend on the Fulfillment Provider.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

Request samples

Content type
application/json
{
  • "price": 0,
  • "option_id": "string",
  • "date": { }
}

Response samples

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

Archive Order

Archives the order with the given id.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.archive(order_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Cancel an Order

Registers an Order as canceled. This triggers a flow that will cancel any created Fulfillments and Payments, may fail if the Payment or Fulfillment Provider is unable to cancel the Payment/Fulfillment.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.cancel(order_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Capture Order's Payment

Captures all the Payments associated with an Order.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.capturePayment(order_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Complete an Order

Completes an Order

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.complete(order_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Create a Reservation for a line item

Creates a Reservation for a line item at a specified location, optionally for a partial quantity.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

line_item_id
required
string

The ID of the Line item.

Request Body schema: application/json
location_id
required
string

The id of the location of the reservation

quantity
number

The quantity to reserve

Responses

Response Schema: application/json
required
object (Reservation item)

Represents a reservation of an inventory item at a stock location

id
required
string

The id of the reservation item

location_id
required
string

The id of the location of the reservation

inventory_item_id
required
string

The id of the inventory item the reservation relates to

quantity
required
number

The id of the reservation item

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

An optional key-value map with additional details

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.

Request samples

Content type
application/json
{
  • "location_id": "string",
  • "quantity": 0
}

Response samples

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

Create a Shipment

Registers a Fulfillment as shipped.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

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.

no_notification
boolean

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

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

Request samples

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

Response samples

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

Get an Order

Retrieves an Order

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.retrieve(order_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Update an Order

Updates and order

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Request Body schema: application/json
email
string

the email for the order

Address Fields (object)

Billing address

Address Fields (object)

Shipping address

Array of objects (Line Item)

The Line Items for the order

region
string

ID of the region where the order belongs

Array of objects (Discount)

Discounts applied to the order

customer_id
string

ID of the customer

object

payment method chosen for the order

object

The Shipping Method used for shipping the order.

no_notification
boolean

A flag to indicate if no notifications should be emitted related to the updated order.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

Request samples

Content type
application/json
{
  • "email": "string",
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "items": [
    ],
  • "region": "string",
  • "discounts": [
    ],
  • "customer_id": "string",
  • "payment_method": {
    },
  • "shipping_method": {
    },
  • "no_notification": true
}

Response samples

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

Get reservations for an Order

Retrieves reservations for an Order

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
offset
integer
Default: 0

How many reservations to skip before the results.

limit
integer
Default: 20

Limit the number of reservations returned.

Responses

Response Schema: application/json
Array of objects (Reservation item)
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.orders.retrieveReservations(order_id)
.then(({ reservations }) => {
  console.log(reservations[0].id);
});

Response samples

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

List Orders

Retrieves a list of Orders

Authorizations:
API TokenCookie Session ID
query Parameters
q
string

Query used for searching orders by shipping address first name, orders' email, and orders' display ID

id
string

ID of the order to search for.

status
Array of strings
Items Enum: "pending" "completed" "archived" "canceled" "requires_action"

Status to search for

fulfillment_status
Array of strings
Items Enum: "not_fulfilled" "fulfilled" "partially_fulfilled" "shipped" "partially_shipped" "canceled" "returned" "partially_returned" "requires_action"

Fulfillment status to search for.

payment_status
Array of strings
Items Enum: "captured" "awaiting" "not_paid" "refunded" "partially_refunded" "canceled" "requires_action"

Payment status to search for.

display_id
string

Display ID to search for.

cart_id
string

to search for.

customer_id
string

to search for.

email
string

to search for.

string or Array of strings

Regions to search orders by

currency_code
string

Currency code to search for

tax_rate
string

to search for.

object

Date comparison for when resulting orders were created.

object

Date comparison for when resulting orders were updated.

object

Date comparison for when resulting orders were canceled.

sales_channel_id
Array of strings

Filter by Sales Channels

offset
integer
Default: 0

How many orders to skip before the results.

limit
integer
Default: 50

Limit the number of orders returned.

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.

Responses

Response Schema: application/json
Array of objects (Order)
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.orders.list()
.then(({ orders, limit, offset, count }) => {
  console.log(orders.length);
});

Response samples

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

Create a Refund

Issues a Refund.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Request Body schema: application/json
amount
required
integer

The amount to refund.

reason
required
string

The reason for the Refund.

note
string

A note with additional details about the Refund.

no_notification
boolean

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

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

Request samples

Content type
application/json
{
  • "amount": 0,
  • "reason": "string",
  • "note": "string",
  • "no_notification": true
}

Response samples

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

Request a Return

Requests a Return. If applicable a return label will be created and other plugins notified.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Request Body schema: application/json
required
Array of objects

The Line Items that will be returned.

object

The Shipping Method to be used to handle the return shipment.

note
string

An optional note with information about the Return.

receive_now
boolean
Default: false

A flag to indicate if the Return should be registerd as received immediately.

no_notification
boolean

A flag to indicate if no notifications should be emitted related to the requested Return.

refund
integer

The amount to refund.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "return_shipping": {
    },
  • "note": "string",
  • "receive_now": false,
  • "no_notification": true,
  • "refund": 0
}

Response samples

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

OrderEdit

Add a Line Item

Create an OrderEdit LineItem.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order Edit.

Request Body schema: application/json
variant_id
required
string

The ID of the variant ID to add

quantity
required
number

The quantity to add

metadata
object

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

Responses

Response Schema: application/json
object (Order Edit)

Order edit keeps track of order items changes.

canceled_at
required
string or null <date-time>

The date with timezone at which the edit was cancelled.

canceled_by
required
string or null

The unique identifier of the user or customer who cancelled the order edit.

confirmed_by
required
string or null

The unique identifier of the user or customer who confirmed the order edit.

confirmed_at
required
string or null <date-time>

The date with timezone at which the edit was confirmed.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string

The unique identifier of the user or customer who created the order edit.

declined_at
required
string or null <date-time>

The date with timezone at which the edit was declined.

declined_by
required
string or null

The unique identifier of the user or customer who declined the order edit.

declined_reason
required
string or null

An optional note why the order edit is declined.

id
required
string
Example: "oe_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order edit's ID

internal_note
required
string or null
Example: "Included two more items B to the order."

An optional note with additional details about the order edit.

order_id
required
string
Example: "order_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the order that is edited

payment_collection_id
required
string or null
Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the payment collection

requested_at
required
string or null <date-time>

The date with timezone at which the edit was requested.

requested_by
required
string or null

The unique identifier of the user or customer who requested the order edit.

status
required
string
Enum: "confirmed" "declined" "requested" "created" "canceled"

The status of the order edit.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

order
object or null

Available if the relation order is expanded.

Array of objects (Order Item Change)

Available if the relation changes is expanded.

subtotal
integer
Example: 8000

The total of subtotal

discount_total
integer
Example: 800

The total of discount

shipping_total
integer
Example: 800

The total of the shipping amount

gift_card_total
integer
Example: 800

The total of the gift card amount

gift_card_tax_total
integer
Example: 800

The total of the gift card tax amount

tax_total
integer
Example: 0

The total of tax

total
integer
Example: 8200

The total amount of the edited order.

difference_due
integer
Example: 8200

The difference between the total amount of the order and total amount of edited order.

Array of objects (Line Item)

Available if the relation items is expanded.

object (Payment Collection)

Payment Collection

Request samples

Content type
application/json
{
  • "variant_id": "string",
  • "quantity": 0,
  • "metadata": { }
}

Response samples

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

Cancel an OrderEdit

Cancels an OrderEdit.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the OrderEdit.

Responses

Response Schema: application/json
object (Order Edit)

Order edit keeps track of order items changes.

canceled_at
required
string or null <date-time>

The date with timezone at which the edit was cancelled.

canceled_by
required
string or null

The unique identifier of the user or customer who cancelled the order edit.

confirmed_by
required
string or null

The unique identifier of the user or customer who confirmed the order edit.

confirmed_at
required
string or null <date-time>

The date with timezone at which the edit was confirmed.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string

The unique identifier of the user or customer who created the order edit.

declined_at
required
string or null <date-time>

The date with timezone at which the edit was declined.

declined_by
required
string or null

The unique identifier of the user or customer who declined the order edit.

declined_reason
required
string or null

An optional note why the order edit is declined.

id
required
string
Example: "oe_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order edit's ID

internal_note
required
string or null
Example: "Included two more items B to the order."

An optional note with additional details about the order edit.

order_id
required
string
Example: "order_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the order that is edited

payment_collection_id
required
string or null
Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the payment collection

requested_at
required
string or null <date-time>

The date with timezone at which the edit was requested.

requested_by
required
string or null

The unique identifier of the user or customer who requested the order edit.

status
required
string
Enum: "confirmed" "declined" "requested" "created" "canceled"

The status of the order edit.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

order
object or null

Available if the relation order is expanded.

Array of objects (Order Item Change)

Available if the relation changes is expanded.

subtotal
integer
Example: 8000

The total of subtotal

discount_total
integer
Example: 800

The total of discount

shipping_total
integer
Example: 800

The total of the shipping amount

gift_card_total
integer
Example: 800

The total of the gift card amount

gift_card_tax_total
integer
Example: 800

The total of the gift card tax amount

tax_total
integer
Example: 0

The total of tax

total
integer
Example: 8200

The total amount of the edited order.

difference_due
integer
Example: 8200

The difference between the total amount of the order and total amount of edited order.

Array of objects (Line Item)

Available if the relation items is expanded.

object (Payment Collection)

Payment Collection

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.orderEdits.cancel(order_edit_id)
  .then(({ order_edit }) => {
    console.log(order_edit.id)
  })

Response samples

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

Confirms an OrderEdit

Confirms an OrderEdit.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the order edit.

Responses

Response Schema: application/json
object (Order Edit)

Order edit keeps track of order items changes.

canceled_at
required
string or null <date-time>

The date with timezone at which the edit was cancelled.

canceled_by
required
string or null

The unique identifier of the user or customer who cancelled the order edit.

confirmed_by
required
string or null

The unique identifier of the user or customer who confirmed the order edit.

confirmed_at
required
string or null <date-time>

The date with timezone at which the edit was confirmed.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string

The unique identifier of the user or customer who created the order edit.

declined_at
required
string or null <date-time>

The date with timezone at which the edit was declined.

declined_by
required
string or null

The unique identifier of the user or customer who declined the order edit.

declined_reason
required
string or null

An optional note why the order edit is declined.

id
required
string
Example: "oe_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order edit's ID

internal_note
required
string or null
Example: "Included two more items B to the order."

An optional note with additional details about the order edit.

order_id
required
string
Example: "order_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the order that is edited

payment_collection_id
required
string or null
Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the payment collection

requested_at
required
string or null <date-time>

The date with timezone at which the edit was requested.

requested_by
required
string or null

The unique identifier of the user or customer who requested the order edit.

status
required
string
Enum: "confirmed" "declined" "requested" "created" "canceled"

The status of the order edit.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

order
object or null

Available if the relation order is expanded.

Array of objects (Order Item Change)

Available if the relation changes is expanded.

subtotal
integer
Example: 8000

The total of subtotal

discount_total
integer
Example: 800

The total of discount

shipping_total
integer
Example: 800

The total of the shipping amount

gift_card_total
integer
Example: 800

The total of the gift card amount

gift_card_tax_total
integer
Example: 800

The total of the gift card tax amount

tax_total
integer
Example: 0

The total of tax

total
integer
Example: 8200

The total amount of the edited order.

difference_due
integer
Example: 8200

The difference between the total amount of the order and total amount of edited order.

Array of objects (Line Item)

Available if the relation items is expanded.

object (Payment Collection)

Payment Collection

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.orderEdits.confirm(order_edit_id)
  .then(({ order_edit }) => {
    console.log(order_edit.id)
  })

Response samples

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

Create an OrderEdit

Creates an OrderEdit.

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

The ID of the order to create the edit for.

internal_note
string

An optional note to create for the order edit.

Responses

Response Schema: application/json
object (Order Edit)

Order edit keeps track of order items changes.

canceled_at
required
string or null <date-time>

The date with timezone at which the edit was cancelled.

canceled_by
required
string or null

The unique identifier of the user or customer who cancelled the order edit.

confirmed_by
required
string or null

The unique identifier of the user or customer who confirmed the order edit.

confirmed_at
required
string or null <date-time>

The date with timezone at which the edit was confirmed.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string

The unique identifier of the user or customer who created the order edit.

declined_at
required
string or null <date-time>

The date with timezone at which the edit was declined.

declined_by
required
string or null

The unique identifier of the user or customer who declined the order edit.

declined_reason
required
string or null

An optional note why the order edit is declined.

id
required
string
Example: "oe_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order edit's ID

internal_note
required
string or null
Example: "Included two more items B to the order."

An optional note with additional details about the order edit.

order_id
required
string
Example: "order_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the order that is edited

payment_collection_id
required
string or null
Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the payment collection

requested_at
required
string or null <date-time>

The date with timezone at which the edit was requested.

requested_by
required
string or null

The unique identifier of the user or customer who requested the order edit.

status
required
string
Enum: "confirmed" "declined" "requested" "created" "canceled"

The status of the order edit.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

order
object or null

Available if the relation order is expanded.

Array of objects (Order Item Change)

Available if the relation changes is expanded.

subtotal
integer
Example: 8000

The total of subtotal

discount_total
integer
Example: 800

The total of discount

shipping_total
integer
Example: 800

The total of the shipping amount

gift_card_total
integer
Example: 800

The total of the gift card amount

gift_card_tax_total
integer
Example: 800

The total of the gift card tax amount

tax_total
integer
Example: 0

The total of tax

total
integer
Example: 8200

The total amount of the edited order.

difference_due
integer
Example: 8200

The difference between the total amount of the order and total amount of edited order.

Array of objects (Line Item)

Available if the relation items is expanded.

object (Payment Collection)

Payment Collection

Request samples

Content type
application/json
{
  • "order_id": "string",
  • "internal_note": "string"
}

Response samples

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

List OrderEdits

List OrderEdits.

Authorizations:
API TokenCookie Session ID
query Parameters
q
string

Query used for searching order edit internal note.

order_id
string

List order edits by order id.

limit
number
Default: "20"

The number of items in the response

offset
number
Default: "0"

The offset of items in response

expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
Array of objects (Order Edit)
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.orderEdits.list()
  .then(({ order_edits, count, limit, offset }) => {
    console.log(order_edits.length)
  })

Response samples

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

Delete a Line Item

Delete line items from an order edit and create change item

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order Edit to delete from.

item_id
required
string

The ID of the order edit item to delete from order.

Responses

Response Schema: application/json
object (Order Edit)

Order edit keeps track of order items changes.

canceled_at
required
string or null <date-time>

The date with timezone at which the edit was cancelled.

canceled_by
required
string or null

The unique identifier of the user or customer who cancelled the order edit.

confirmed_by
required
string or null

The unique identifier of the user or customer who confirmed the order edit.

confirmed_at
required
string or null <date-time>

The date with timezone at which the edit was confirmed.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string

The unique identifier of the user or customer who created the order edit.

declined_at
required
string or null <date-time>

The date with timezone at which the edit was declined.

declined_by
required
string or null

The unique identifier of the user or customer who declined the order edit.

declined_reason
required
string or null

An optional note why the order edit is declined.

id
required
string
Example: "oe_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order edit's ID

internal_note
required
string or null
Example: "Included two more items B to the order."

An optional note with additional details about the order edit.

order_id
required
string
Example: "order_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the order that is edited

payment_collection_id
required
string or null
Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the payment collection

requested_at
required
string or null <date-time>

The date with timezone at which the edit was requested.

requested_by
required
string or null

The unique identifier of the user or customer who requested the order edit.

status
required
string
Enum: "confirmed" "declined" "requested" "created" "canceled"

The status of the order edit.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

order
object or null

Available if the relation order is expanded.

Array of objects (Order Item Change)

Available if the relation changes is expanded.

subtotal
integer
Example: 8000

The total of subtotal

discount_total
integer
Example: 800

The total of discount

shipping_total
integer
Example: 800

The total of the shipping amount

gift_card_total
integer
Example: 800

The total of the gift card amount

gift_card_tax_total
integer
Example: 800

The total of the gift card tax amount

tax_total
integer
Example: 0

The total of tax

total
integer
Example: 8200

The total amount of the edited order.

difference_due
integer
Example: 8200

The difference between the total amount of the order and total amount of edited order.

Array of objects (Line Item)

Available if the relation items is expanded.

object (Payment Collection)

Payment Collection

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.orderEdits.removeLineItem(order_edit_id, line_item_id)
  .then(({ order_edit }) => {
    console.log(order_edit.id)
  })

Response samples

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

Upsert Line Item Change

Create or update the order edit change holding the line item changes

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order Edit to update.

item_id
required
string

The ID of the order edit item to update.

Request Body schema: application/json
quantity
required
number

The quantity to update

Responses

Response Schema: application/json
object (Order Edit)

Order edit keeps track of order items changes.

canceled_at
required
string or null <date-time>

The date with timezone at which the edit was cancelled.

canceled_by
required
string or null

The unique identifier of the user or customer who cancelled the order edit.

confirmed_by
required
string or null

The unique identifier of the user or customer who confirmed the order edit.

confirmed_at
required
string or null <date-time>

The date with timezone at which the edit was confirmed.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string

The unique identifier of the user or customer who created the order edit.

declined_at
required
string or null <date-time>

The date with timezone at which the edit was declined.

declined_by
required
string or null

The unique identifier of the user or customer who declined the order edit.

declined_reason
required
string or null

An optional note why the order edit is declined.

id
required
string
Example: "oe_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order edit's ID

internal_note
required
string or null
Example: "Included two more items B to the order."

An optional note with additional details about the order edit.

order_id
required
string
Example: "order_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the order that is edited

payment_collection_id
required
string or null
Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the payment collection

requested_at
required
string or null <date-time>

The date with timezone at which the edit was requested.

requested_by
required
string or null

The unique identifier of the user or customer who requested the order edit.

status
required
string
Enum: "confirmed" "declined" "requested" "created" "canceled"

The status of the order edit.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

order
object or null

Available if the relation order is expanded.

Array of objects (Order Item Change)

Available if the relation changes is expanded.

subtotal
integer
Example: 8000

The total of subtotal

discount_total
integer
Example: 800

The total of discount

shipping_total
integer
Example: 800

The total of the shipping amount

gift_card_total
integer
Example: 800

The total of the gift card amount

gift_card_tax_total
integer
Example: 800

The total of the gift card tax amount

tax_total
integer
Example: 0

The total of tax

total
integer
Example: 8200

The total amount of the edited order.

difference_due
integer
Example: 8200

The difference between the total amount of the order and total amount of edited order.

Array of objects (Line Item)

Available if the relation items is expanded.

object (Payment Collection)

Payment Collection

Request samples

Content type
application/json
{
  • "quantity": 0
}

Response samples

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

Delete a Line Item Change

Deletes an Order Edit Item Change

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order Edit to delete.

change_id
required
string

The ID of the Order Edit Item Change to delete.

Responses

Response Schema: application/json
id
string

The ID of the deleted Order Edit Item Change.

object
string
Default: "item_change"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the Order Edit Item Change 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.orderEdits.deleteItemChange(order_edit_id, item_change_id)
  .then(({ id, object, deleted }) => {
    console.log(id)
  })

Response samples

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

Delete an Order Edit

Delete an Order Edit

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order Edit to delete.

Responses

Response Schema: application/json
id
string

The ID of the deleted Order Edit.

object
string
Default: "order_edit"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the Order Edit 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.orderEdits.delete(order_edit_id)
  .then(({ id, object, deleted }) => {
    console.log(id)
  })

Response samples

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

Get an OrderEdit

Retrieves a OrderEdit.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the OrderEdit.

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
object (Order Edit)

Order edit keeps track of order items changes.

canceled_at
required
string or null <date-time>

The date with timezone at which the edit was cancelled.

canceled_by
required
string or null

The unique identifier of the user or customer who cancelled the order edit.

confirmed_by
required
string or null

The unique identifier of the user or customer who confirmed the order edit.

confirmed_at
required
string or null <date-time>

The date with timezone at which the edit was confirmed.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string

The unique identifier of the user or customer who created the order edit.

declined_at
required
string or null <date-time>

The date with timezone at which the edit was declined.

declined_by
required
string or null

The unique identifier of the user or customer who declined the order edit.

declined_reason
required
string or null

An optional note why the order edit is declined.

id
required
string
Example: "oe_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order edit's ID

internal_note
required
string or null
Example: "Included two more items B to the order."

An optional note with additional details about the order edit.

order_id
required
string
Example: "order_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the order that is edited

payment_collection_id
required
string or null
Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the payment collection

requested_at
required
string or null <date-time>

The date with timezone at which the edit was requested.

requested_by
required
string or null

The unique identifier of the user or customer who requested the order edit.

status
required
string
Enum: "confirmed" "declined" "requested" "created" "canceled"

The status of the order edit.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

order
object or null

Available if the relation order is expanded.

Array of objects (Order Item Change)

Available if the relation changes is expanded.

subtotal
integer
Example: 8000

The total of subtotal

discount_total
integer
Example: 800

The total of discount

shipping_total
integer
Example: 800

The total of the shipping amount

gift_card_total
integer
Example: 800

The total of the gift card amount

gift_card_tax_total
integer
Example: 800

The total of the gift card tax amount

tax_total
integer
Example: 0

The total of tax

total
integer
Example: 8200

The total amount of the edited order.

difference_due
integer
Example: 8200

The difference between the total amount of the order and total amount of edited order.

Array of objects (Line Item)

Available if the relation items is expanded.

object (Payment Collection)

Payment Collection

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.orderEdits.retrieve(orderEditId)
  .then(({ order_edit }) => {
    console.log(order_edit.id)
  })

Response samples

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

Update an OrderEdit

Updates a OrderEdit.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the OrderEdit.

Request Body schema: application/json
internal_note
string

An optional note to create or update for the order edit.

Responses

Response Schema: application/json
object (Order Edit)

Order edit keeps track of order items changes.

canceled_at
required
string or null <date-time>

The date with timezone at which the edit was cancelled.

canceled_by
required
string or null

The unique identifier of the user or customer who cancelled the order edit.

confirmed_by
required
string or null

The unique identifier of the user or customer who confirmed the order edit.

confirmed_at
required
string or null <date-time>

The date with timezone at which the edit was confirmed.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string

The unique identifier of the user or customer who created the order edit.

declined_at
required
string or null <date-time>

The date with timezone at which the edit was declined.

declined_by
required
string or null

The unique identifier of the user or customer who declined the order edit.

declined_reason
required
string or null

An optional note why the order edit is declined.

id
required
string
Example: "oe_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order edit's ID

internal_note
required
string or null
Example: "Included two more items B to the order."

An optional note with additional details about the order edit.

order_id
required
string
Example: "order_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the order that is edited

payment_collection_id
required
string or null
Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the payment collection

requested_at
required
string or null <date-time>

The date with timezone at which the edit was requested.

requested_by
required
string or null

The unique identifier of the user or customer who requested the order edit.

status
required
string
Enum: "confirmed" "declined" "requested" "created" "canceled"

The status of the order edit.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

order
object or null

Available if the relation order is expanded.

Array of objects (Order Item Change)

Available if the relation changes is expanded.

subtotal
integer
Example: 8000

The total of subtotal

discount_total
integer
Example: 800

The total of discount

shipping_total
integer
Example: 800

The total of the shipping amount

gift_card_total
integer
Example: 800

The total of the gift card amount

gift_card_tax_total
integer
Example: 800

The total of the gift card tax amount

tax_total
integer
Example: 0

The total of tax

total
integer
Example: 8200

The total amount of the edited order.

difference_due
integer
Example: 8200

The difference between the total amount of the order and total amount of edited order.

Array of objects (Line Item)

Available if the relation items is expanded.

object (Payment Collection)

Payment Collection

Request samples

Content type
application/json
{
  • "internal_note": "string"
}

Response samples

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

Request Confirmation

Request customer confirmation of an Order Edit

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order Edit to request confirmation from.

Responses

Response Schema: application/json
object (Order Edit)

Order edit keeps track of order items changes.

canceled_at
required
string or null <date-time>

The date with timezone at which the edit was cancelled.

canceled_by
required
string or null

The unique identifier of the user or customer who cancelled the order edit.

confirmed_by
required
string or null

The unique identifier of the user or customer who confirmed the order edit.

confirmed_at
required
string or null <date-time>

The date with timezone at which the edit was confirmed.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string

The unique identifier of the user or customer who created the order edit.

declined_at
required
string or null <date-time>

The date with timezone at which the edit was declined.

declined_by
required
string or null

The unique identifier of the user or customer who declined the order edit.

declined_reason
required
string or null

An optional note why the order edit is declined.

id
required
string
Example: "oe_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order edit's ID

internal_note
required
string or null
Example: "Included two more items B to the order."

An optional note with additional details about the order edit.

order_id
required
string
Example: "order_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the order that is edited

payment_collection_id
required
string or null
Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the payment collection

requested_at
required
string or null <date-time>

The date with timezone at which the edit was requested.

requested_by
required
string or null

The unique identifier of the user or customer who requested the order edit.

status
required
string
Enum: "confirmed" "declined" "requested" "created" "canceled"

The status of the order edit.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

order
object or null

Available if the relation order is expanded.

Array of objects (Order Item Change)

Available if the relation changes is expanded.

subtotal
integer
Example: 8000

The total of subtotal

discount_total
integer
Example: 800

The total of discount

shipping_total
integer
Example: 800

The total of the shipping amount

gift_card_total
integer
Example: 800

The total of the gift card amount

gift_card_tax_total
integer
Example: 800

The total of the gift card tax amount

tax_total
integer
Example: 0

The total of tax

total
integer
Example: 8200

The total amount of the edited order.

difference_due
integer
Example: 8200

The difference between the total amount of the order and total amount of edited order.

Array of objects (Line Item)

Available if the relation items is expanded.

object (Payment Collection)

Payment Collection

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.orderEdits.requestConfirmation(order_edit_id)
  .then({ order_edit }) => {
    console.log(order_edit.id)
  })

Response samples

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

Payment

Capture a Payment

Captures a Payment.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Payment.

Responses

Response Schema: application/json
object (Payment)

Payments represent an amount authorized with a given payment method, Payments can be captured, canceled or refunded.

amount
required
integer
Example: 100

The amount that the Payment has been authorized for.

amount_refunded
required
integer
Default: 0
Example: 0

The amount of the original Payment amount that has been refunded back to the Customer.

canceled_at
required
string or null <date-time>

The date with timezone at which the Payment was canceled.

captured_at
required
string or null <date-time>

The date with timezone at which the Payment was captured.

cart_id
required
string or null

The id of the Cart that the Payment Session is created for.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character ISO currency code that the Payment is completed in.

data
required
object
Example: {}

The data required for the Payment Provider to identify, modify and process the Payment. Typically this will be an object that holds an id to the external payment session, but can be an empty object if the Payment Provider doesn't hold any state.

id
required
string
Example: "pay_01G2SJNT6DEEWDFNAJ4XWDTHKE"

The payment's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a payment in case of failure.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the Order that the Payment is used for.

provider_id
required
string
Example: "manual"

The id of the Payment Provider that is responsible for the Payment

swap_id
required
string or null
Example: null

The ID of the Swap that the Payment is used for.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

swap
object or null

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

cart
object or null

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

order
object or null

An order object. Available if the relation order is expanded.

object (Currency)

Currency

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.payments.capturePayment(payment_id)
.then(({ payment }) => {
  console.log(payment.id);
});

Response samples

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

Get Payment details

Retrieves the Payment details

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Payment.

Responses

Response Schema: application/json
object (Payment)

Payments represent an amount authorized with a given payment method, Payments can be captured, canceled or refunded.

amount
required
integer
Example: 100

The amount that the Payment has been authorized for.

amount_refunded
required
integer
Default: 0
Example: 0

The amount of the original Payment amount that has been refunded back to the Customer.

canceled_at
required
string or null <date-time>

The date with timezone at which the Payment was canceled.

captured_at
required
string or null <date-time>

The date with timezone at which the Payment was captured.

cart_id
required
string or null

The id of the Cart that the Payment Session is created for.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character ISO currency code that the Payment is completed in.

data
required
object
Example: {}

The data required for the Payment Provider to identify, modify and process the Payment. Typically this will be an object that holds an id to the external payment session, but can be an empty object if the Payment Provider doesn't hold any state.

id
required
string
Example: "pay_01G2SJNT6DEEWDFNAJ4XWDTHKE"

The payment's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a payment in case of failure.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the Order that the Payment is used for.

provider_id
required
string
Example: "manual"

The id of the Payment Provider that is responsible for the Payment

swap_id
required
string or null
Example: null

The ID of the Swap that the Payment is used for.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

swap
object or null

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

cart
object or null

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

order
object or null

An order object. Available if the relation order is expanded.

object (Currency)

Currency

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.payments.retrieve(payment_id)
.then(({ payment }) => {
  console.log(payment.id);
});

Response samples

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

Create a Refund

Issues a Refund.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Payment.

Request Body schema: application/json
amount
required
integer

The amount to refund.

reason
required
string

The reason for the Refund.

note
string

A note with additional details about the Refund.

Responses

Response Schema: application/json
object (Refund)

Refund represent an amount of money transfered back to the Customer for a given reason. Refunds may occur in relation to Returns, Swaps and Claims, but can also be initiated by a store operator.

amount
required
integer
Example: 1000

The amount that has be refunded to the Customer.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

id
required
string
Example: "ref_01G1G5V27GYX4QXNARRQCW1N8T"

The refund's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of the refund in case of failure.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

note
required
string or null
Example: "I didn't like it"

An optional note explaining why the amount was refunded.

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The id of the Order that the Refund is related to.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

reason
required
string
Enum: "discount" "return" "swap" "claim" "other"
Example: "return"

The reason given for the Refund, will automatically be set when processed as part of a Swap, Claim or Return.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

order
object or null

An order object. Available if the relation order is expanded.

payment
object or null

Available if the relation payment is expanded.

Request samples

Content type
application/json
{
  • "amount": 0,
  • "reason": "string",
  • "note": "string"
}

Response samples

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

PaymentCollection

Del a PaymentCollection

Deletes a Payment Collection

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Payment Collection to delete.

Responses

Response Schema: application/json
id
string

The ID of the deleted Payment Collection.

object
string
Default: "payment_collection"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the Payment Collection 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.paymentCollections.delete(payment_collection_id)
  .then(({ id, object, deleted }) => {
    console.log(id)
  })

Response samples

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

Get a PaymentCollection

Retrieves a PaymentCollection.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the PaymentCollection.

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
object (Payment Collection)

Payment Collection

amount
required
integer

Amount of the payment collection.

authorized_amount
required
integer or null

Authorized amount of the payment collection.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string

The ID of the user that created the payment collection.

currency_code
required
string
Example: "usd"

The 3 character ISO code for the currency.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null

Description of the payment collection

id
required
string
Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"

The payment collection's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

status
required
string
Enum: "not_paid" "awaiting" "authorized" "partially_authorized" "canceled"

The type of the payment collection

type
required
string
Value: "order_edit"

The type of the payment collection

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Payment Session)

Available if the relation payment_sessions is expanded.

Array of objects (Payment)

Available if the relation payments is expanded.

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.paymentCollections.retrieve(paymentCollectionId)
  .then(({ payment_collection }) => {
    console.log(payment_collection.id)
  })

Response samples

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

Update PaymentCollection

Updates a PaymentCollection.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the PaymentCollection.

Request Body schema: application/json
description
string

An optional description to create or update the payment collection.

metadata
object

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

Responses

Response Schema: application/json
object (Payment Collection)

Payment Collection

amount
required
integer

Amount of the payment collection.

authorized_amount
required
integer or null

Authorized amount of the payment collection.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string

The ID of the user that created the payment collection.

currency_code
required
string
Example: "usd"

The 3 character ISO code for the currency.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null

Description of the payment collection

id
required
string
Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"

The payment collection's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

status
required
string
Enum: "not_paid" "awaiting" "authorized" "partially_authorized" "canceled"

The type of the payment collection

type
required
string
Value: "order_edit"

The type of the payment collection

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Payment Session)

Available if the relation payment_sessions is expanded.

Array of objects (Payment)

Available if the relation payments is expanded.

Request samples

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

Response samples

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

Mark Authorized

Sets the status of PaymentCollection as Authorized.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the PaymentCollection.

Responses

Response Schema: application/json
object (Payment Collection)

Payment Collection

amount
required
integer

Amount of the payment collection.

authorized_amount
required
integer or null

Authorized amount of the payment collection.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string

The ID of the user that created the payment collection.

currency_code
required
string
Example: "usd"

The 3 character ISO code for the currency.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null

Description of the payment collection

id
required
string
Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK"

The payment collection's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

status
required
string
Enum: "not_paid" "awaiting" "authorized" "partially_authorized" "canceled"

The type of the payment collection

type
required
string
Value: "order_edit"

The type of the payment collection

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Payment Session)

Available if the relation payment_sessions is expanded.

Array of objects (Payment)

Available if the relation payments is expanded.

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.paymentCollections.markAsAuthorized(payment_collection_id)
  .then(({ payment_collection }) => {
    console.log(payment_collection.id)
  })

Response samples

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

Price List

Price List endpoints that allow handling price lists in Medusa.

Update Prices

Batch update prices for a Price List

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Price List to update prices for.

Request Body schema: application/json
Array of objects

The prices to update or add.

override
boolean

If true the prices will replace all existing prices associated with the Price List.

Responses

Response Schema: application/json
object (Price List)

Price Lists represents a set of prices that overrides the default price for one or more product variants.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string
Example: "Prices for VIP customers"

The price list's description

ends_at
required
string or null <date-time>

The date with timezone that the Price List stops being valid.

id
required
string
Example: "pl_01G8X3CKJXCG5VXVZ87H9KC09W"

The price list's ID

name
required
string
Example: "VIP Prices"

The price list's name

starts_at
required
string or null <date-time>

The date with timezone that the Price List starts being valid.

status
required
string
Default: "draft"
Enum: "active" "draft"

The status of the Price List

type
required
string
Default: "sale"
Enum: "sale" "override"

The type of Price List. This can be one of either sale or override.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Array of objects (Customer Group)

The Customer Groups that the Price List applies to. Available if the relation customer_groups is expanded.

Array of objects (Money Amount)

The Money Amounts that are associated with the Price List. Available if the relation prices is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the price list prices include tax

Request samples

Content type
application/json
{
  • "prices": [
    ],
  • "override": true
}

Response samples

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

Delete Prices

Batch delete prices that belong to a Price List

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Price List that the Money Amounts (Prices) that will be deleted belongs to.

Request Body schema: application/json
price_ids
Array of strings

The price id's of the Money Amounts to delete.

Responses

Response Schema: application/json
ids
Array of strings
object
string
Default: "money-amount"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were deleted.

Request samples

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

Response samples

Content type
application/json
{
  • "ids": [
    ],
  • "object": "money-amount",
  • "deleted": true
}

Create a Price List

Creates a Price List

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

The name of the Price List

description
required
string

A description of the Price List.

type
required
string
Enum: "sale" "override"

The type of the Price List.

required
Array of objects

The prices of the Price List.

starts_at
string <date>

The date with timezone that the Price List starts being valid.

ends_at
string <date>

The date with timezone that the Price List ends being valid.

status
string
Enum: "active" "draft"

The status of the Price List.

Array of objects

A list of customer groups that the Price List applies to.

includes_tax
boolean

[EXPERIMENTAL] Tax included in prices of price list

Responses

Response Schema: application/json
object (Price List)

Price Lists represents a set of prices that overrides the default price for one or more product variants.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string
Example: "Prices for VIP customers"

The price list's description

ends_at
required
string or null <date-time>

The date with timezone that the Price List stops being valid.

id
required
string
Example: "pl_01G8X3CKJXCG5VXVZ87H9KC09W"

The price list's ID

name
required
string
Example: "VIP Prices"

The price list's name

starts_at
required
string or null <date-time>

The date with timezone that the Price List starts being valid.

status
required
string
Default: "draft"
Enum: "active" "draft"

The status of the Price List

type
required
string
Default: "sale"
Enum: "sale" "override"

The type of Price List. This can be one of either sale or override.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Array of objects (Customer Group)

The Customer Groups that the Price List applies to. Available if the relation customer_groups is expanded.

Array of objects (Money Amount)

The Money Amounts that are associated with the Price List. Available if the relation prices is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the price list prices include tax

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "starts_at": "2019-08-24",
  • "ends_at": "2019-08-24",
  • "type": "sale",
  • "status": "active",
  • "prices": [
    ],
  • "customer_groups": [
    ],
  • "includes_tax": true
}

Response samples

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

List Price Lists

Retrieves a list of Price Lists.

Authorizations:
API TokenCookie Session ID
query Parameters
limit
number
Default: "10"

The number of items to get

offset
number
Default: "0"

The offset at which to get items

expand
string

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

order
string

field to order results by.

id
string

ID to search for.

q
string

query to search in price list description, price list name, and customer group name fields.

status
Array of strings
Items Enum: "active" "draft"

Status to search for.

name
string

price list name to search for.

customer_groups
Array of strings

Customer Group IDs to search for.

type
Array of strings
Items Enum: "sale" "override"

Type to search for.

object

Date comparison for when resulting price lists were created.

object

Date comparison for when resulting price lists were updated.

object

Date comparison for when resulting price lists were deleted.

Responses

Response Schema: application/json
Array of objects (Price List)
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.priceLists.list()
.then(({ price_lists, limit, offset, count }) => {
  console.log(price_lists.length);
});

Response samples

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

Delete a Price List

Deletes a Price List

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Price List to delete.

Responses

Response Schema: application/json
id
string

The ID of the deleted Price List.

object
string
Default: "price-list"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were 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.priceLists.delete(price_list_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Price List

Retrieves a Price List.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Price List.

Responses

Response Schema: application/json
object (Price List)

Price Lists represents a set of prices that overrides the default price for one or more product variants.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string
Example: "Prices for VIP customers"

The price list's description

ends_at
required
string or null <date-time>

The date with timezone that the Price List stops being valid.

id
required
string
Example: "pl_01G8X3CKJXCG5VXVZ87H9KC09W"

The price list's ID

name
required
string
Example: "VIP Prices"

The price list's name

starts_at
required
string or null <date-time>

The date with timezone that the Price List starts being valid.

status
required
string
Default: "draft"
Enum: "active" "draft"

The status of the Price List

type
required
string
Default: "sale"
Enum: "sale" "override"

The type of Price List. This can be one of either sale or override.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Array of objects (Customer Group)

The Customer Groups that the Price List applies to. Available if the relation customer_groups is expanded.

Array of objects (Money Amount)

The Money Amounts that are associated with the Price List. Available if the relation prices is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the price list prices include tax

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.priceLists.retrieve(price_list_id)
.then(({ price_list }) => {
  console.log(price_list.id);
});

Response samples

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

Update a Price List

Updates a Price List

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Price List.

Request Body schema: application/json
name
string

The name of the Price List

description
string

A description of the Price List.

starts_at
string <date>

The date with timezone that the Price List starts being valid.

ends_at
string <date>

The date with timezone that the Price List ends being valid.

type
string
Enum: "sale" "override"

The type of the Price List.

status
string
Enum: "active" "draft"

The status of the Price List.

Array of objects

The prices of the Price List.

Array of objects

A list of customer groups that the Price List applies to.

includes_tax
boolean

[EXPERIMENTAL] Tax included in prices of price list

Responses

Response Schema: application/json
object (Price List)

Price Lists represents a set of prices that overrides the default price for one or more product variants.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string
Example: "Prices for VIP customers"

The price list's description

ends_at
required
string or null <date-time>

The date with timezone that the Price List stops being valid.

id
required
string
Example: "pl_01G8X3CKJXCG5VXVZ87H9KC09W"

The price list's ID

name
required
string
Example: "VIP Prices"

The price list's name

starts_at
required
string or null <date-time>

The date with timezone that the Price List starts being valid.

status
required
string
Default: "draft"
Enum: "active" "draft"

The status of the Price List

type
required
string
Default: "sale"
Enum: "sale" "override"

The type of Price List. This can be one of either sale or override.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Array of objects (Customer Group)

The Customer Groups that the Price List applies to. Available if the relation customer_groups is expanded.

Array of objects (Money Amount)

The Money Amounts that are associated with the Price List. Available if the relation prices is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the price list prices include tax

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "starts_at": "2019-08-24",
  • "ends_at": "2019-08-24",
  • "type": "sale",
  • "status": "active",
  • "prices": [
    ],
  • "customer_groups": [
    ],
  • "includes_tax": true
}

Response samples

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

Delete Product's Prices

Delete all the prices related to a specific product in a price list

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Price List that the Money Amounts that will be deleted belongs to.

product_id
required
string

The ID of the product from which the money amount will be deleted.

Responses

Response Schema: application/json
ids
Array of strings

The price ids that have been deleted.

object
string
Default: "money-amount"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were 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.priceLists.deleteProductPrices(price_list_id, product_id)
.then(({ ids, object, deleted }) => {
  console.log(ids.length);
});

Response samples

Content type
application/json
{
  • "ids": [
    ],
  • "object": "money-amount",
  • "deleted": true
}

Delete Variant's Prices

Delete all the prices related to a specific variant in a price list

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Price List that the Money Amounts that will be deleted belongs to.

variant_id
required
string

The ID of the variant from which the money amount will be deleted.

Responses

Response Schema: application/json
ids
Array of strings

The price ids that have been deleted.

object
string
Default: "money-amount"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were 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.priceLists.deleteVariantPrices(price_list_id, variant_id)
.then(({ ids, object, deleted }) => {
  console.log(ids);
});

Response samples

Content type
application/json
{
  • "ids": [
    ],
  • "object": "money-amount",
  • "deleted": true
}

List Products

Retrieves a list of Product that are part of a Price List

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

ID of the price list.

query Parameters
q
string

Query used for searching product title and description, variant title and sku, and collection title.

id
string

ID of the product to search for.

status
Array of strings
Items Enum: "draft" "proposed" "published" "rejected"

Product status to search for

collection_id
Array of strings

Collection IDs to search for

tags
Array of strings

Tag IDs to search for

title
string

product title to search for.

description
string

product description to search for.

handle
string

product handle to search for.

is_giftcard
string

Search for giftcards using is_giftcard=true.

type
string

to search for.

order
string

field to sort results by.

object

Date comparison for when resulting products were created.

object

Date comparison for when resulting products were updated.

object

Date comparison for when resulting products were deleted.

offset
integer
Default: 0

How many products to skip in the result.

limit
integer
Default: 50

Limit the number of products returned.

expand
string

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

fields
string

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

Responses

Response Schema: application/json
Array of objects (Product)
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.priceLists.listProducts(price_list_id)
.then(({ products, limit, offset, count }) => {
  console.log(products.length);
});

Response samples

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

Product

Product endpoints that allow handling products in Medusa.

Add an Option

Adds a Product Option to a Product

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product.

Request Body schema: application/json
title
required
string

The title the Product Option will be identified by i.e. "Size"

Responses

Response Schema: application/json
object (Product)

Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.

collection_id
required
string or null
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The Product Collection that the Product belongs to

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Every programmer's best friend."

A short description of the Product.

discountable
required
boolean
Default: true

Whether the Product can be discounted. Discounts will not apply to Line Items of this Product when this flag is set to false.

external_id
required
string or null
Example: null

The external ID of the product

handle
required
string or null
Example: "coffee-mug"

A unique identifier for the Product (e.g. for slug structure).

height
required
number or null
Example: null

The height of the Product Variant. May be used in shipping rate calculations.

hs_code
required
string or null
Example: null

The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

id
required
string
Example: "prod_01G1G5V2MBA328390B5AXJ610F"

The product's ID

is_giftcard
required
boolean
Default: false

Whether the Product represents a Gift Card. Products that represent Gift Cards will automatically generate a redeemable Gift Card code once they are purchased.

length
required
number or null
Example: null

The length of the Product Variant. May be used in shipping rate calculations.

material
required
string or null
Example: null

The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

mid_code
required
string or null
Example: null

The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
required
string or null
Example: null

The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

profile_id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The ID of the Shipping Profile that the Product belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.

status
required
string
Default: "draft"
Enum: "draft" "proposed" "published" "rejected"

The status of the product

subtitle
required
string or null

An optional subtitle that can be used to further specify the Product.

type_id
required
string or null
Example: "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"

The Product type that the Product belongs to

thumbnail
required
string or null <uri>

A URL to an image file that can be used to identify the Product.

title
required
string
Example: "Medusa Coffee Mug"

A title that can be displayed for easy identification of the Product.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

weight
required
number or null
Example: null

The weight of the Product Variant. May be used in shipping rate calculations.

width
required
number or null
Example: null

The width of the Product Variant. May be used in shipping rate calculations.

Array of objects (Image)

Images of the Product. Available if the relation images is expanded.

Array of objects (Product Option)

The Product Options that are defined for the Product. Product Variants of the Product will have a unique combination of Product Option Values. Available if the relation options is expanded.

Array of objects (Product Variant)

The Product Variants that belong to the Product. Each will have a unique combination of Product Option Values. Available if the relation variants is expanded.

Array of objects (ProductCategory)

The product's associated categories. Available if the relation categories are expanded.

object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

object (Product Collection)

Product Collections represents a group of Products that are related.

object (Product Type)

Product Type can be added to Products for filtering and reporting purposes.

Array of objects (Product Tag)

The Product Tags assigned to the Product. Available if the relation tags is expanded.

Array of objects (Sales Channel)

The sales channels the product is associated with. Available if the relation sales_channels is expanded.

Request samples

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

Response samples

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

Create a Product

Creates a Product

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

The title of the Product

subtitle
string

The subtitle of the Product

description
string

A description of the Product.

is_giftcard
boolean
Default: false

A flag to indicate if the Product represents a Gift Card. Purchasing Products with this flag set to true will result in a Gift Card being created.

discountable
boolean
Default: true

A flag to indicate if discounts can be applied to the LineItems generated from this Product

images
Array of strings

Images of the Product.

thumbnail
string

The thumbnail to use for the Product.

handle
string

A unique handle to identify the Product by.

status
string
Default: "draft"
Enum: "draft" "proposed" "published" "rejected"

The status of the product.

object

The Product Type to associate the Product with.

collection_id
string

The ID of the Collection the Product should belong to.

Array of objects

Tags to associate the Product with.

Array of objects

[EXPERIMENTAL] Sales channels to associate the Product with.

Array of objects

Categories to add the Product to.

Array of objects

The Options that the Product should have. These define on which properties the Product's Product Variants will differ.

Array of objects

A list of Product Variants to create with the Product.

weight
number

The weight of the Product.

length
number

The length of the Product.

height
number

The height of the Product.

width
number

The width of the Product.

hs_code
string

The Harmonized System code for the Product Variant.

origin_country
string

The country of origin of the Product.

mid_code
string

The Manufacturer Identification code for the Product.

material
string

The material composition of the Product.

metadata
object

An optional set of key-value pairs with additional information.

Responses

Response Schema: application/json
object (Product)

Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.

collection_id
required
string or null
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The Product Collection that the Product belongs to

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Every programmer's best friend."

A short description of the Product.

discountable
required
boolean
Default: true

Whether the Product can be discounted. Discounts will not apply to Line Items of this Product when this flag is set to false.

external_id
required
string or null
Example: null

The external ID of the product

handle
required
string or null
Example: "coffee-mug"

A unique identifier for the Product (e.g. for slug structure).

height
required
number or null
Example: null

The height of the Product Variant. May be used in shipping rate calculations.

hs_code
required
string or null
Example: null

The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

id
required
string
Example: "prod_01G1G5V2MBA328390B5AXJ610F"

The product's ID

is_giftcard
required
boolean
Default: false

Whether the Product represents a Gift Card. Products that represent Gift Cards will automatically generate a redeemable Gift Card code once they are purchased.

length
required
number or null
Example: null

The length of the Product Variant. May be used in shipping rate calculations.

material
required
string or null
Example: null

The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

mid_code
required
string or null
Example: null

The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
required
string or null
Example: null

The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

profile_id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The ID of the Shipping Profile that the Product belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.

status
required
string
Default: "draft"
Enum: "draft" "proposed" "published" "rejected"

The status of the product

subtitle
required
string or null

An optional subtitle that can be used to further specify the Product.

type_id
required
string or null
Example: "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"

The Product type that the Product belongs to

thumbnail
required
string or null <uri>

A URL to an image file that can be used to identify the Product.

title
required
string
Example: "Medusa Coffee Mug"

A title that can be displayed for easy identification of the Product.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

weight
required
number or null
Example: null

The weight of the Product Variant. May be used in shipping rate calculations.

width
required
number or null
Example: null

The width of the Product Variant. May be used in shipping rate calculations.

Array of objects (Image)

Images of the Product. Available if the relation images is expanded.

Array of objects (Product Option)

The Product Options that are defined for the Product. Product Variants of the Product will have a unique combination of Product Option Values. Available if the relation options is expanded.

Array of objects (Product Variant)

The Product Variants that belong to the Product. Each will have a unique combination of Product Option Values. Available if the relation variants is expanded.

Array of objects (ProductCategory)

The product's associated categories. Available if the relation categories are expanded.

object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

object (Product Collection)

Product Collections represents a group of Products that are related.

object (Product Type)

Product Type can be added to Products for filtering and reporting purposes.

Array of objects (Product Tag)

The Product Tags assigned to the Product. Available if the relation tags is expanded.

Array of objects (Sales Channel)

The sales channels the product is associated with. Available if the relation sales_channels is expanded.

Request samples

Content type
application/json
{
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "is_giftcard": false,
  • "discountable": true,
  • "images": [
    ],
  • "thumbnail": "string",
  • "handle": "string",
  • "status": "draft",
  • "type": {
    },
  • "collection_id": "string",
  • "tags": [
    ],
  • "sales_channels": [
    ],
  • "categories": [
    ],
  • "options": [
    ],
  • "variants": [
    ],
  • "weight": 0,
  • "length": 0,
  • "height": 0,
  • "width": 0,
  • "hs_code": "string",
  • "origin_country": "string",
  • "mid_code": "string",
  • "material": "string",
  • "metadata": { }
}

Response samples

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

List Products

Retrieves a list of Product

Authorizations:
API TokenCookie Session ID
query Parameters
q
string

Query used for searching product title and description, variant title and sku, and collection title.

discount_condition_id
string

The discount condition id on which to filter the product.

string or Array of strings

Filter by product IDs.

status
Array of strings
Items Enum: "draft" "proposed" "published" "rejected"

Status to search for

collection_id
Array of strings

Collection ids to search for.

tags
Array of strings

Tag IDs to search for

price_list_id
Array of strings

Price List IDs to search for

sales_channel_id
Array of strings

Sales Channel IDs to filter products by

type_id
Array of strings

Type IDs to filter products by

category_id
Array of strings

Category IDs to filter products by

include_category_children
boolean

Include category children when filtering by category_id

title
string

title to search for.

description
string

description to search for.

handle
string

handle to search for.

is_giftcard
boolean

Search for giftcards using is_giftcard=true.

object

Date comparison for when resulting products were created.

object

Date comparison for when resulting products were updated.

object

Date comparison for when resulting products were deleted.

offset
integer
Default: 0

How many products to skip in the result.

limit
integer
Default: 50

Limit the number of products returned.

expand
string

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

fields
string

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

order
string

the field used to order the products.

Responses

Response Schema: application/json
Array of Product (object) or Priced Product (object)
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.products.list()
.then(({ products, limit, offset, count }) => {
  console.log(products.length);
});

Response samples

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

Create a Product Variant

Creates a Product Variant. Each Product Variant must have a unique combination of Product Option Values.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product.

Request Body schema: application/json
title
required
string

The title to identify the Product Variant by.

required
Array of objects
required
Array of objects
sku
string

The unique SKU for the Product Variant.

ean
string

The EAN number of the item.

upc
string

The UPC number of the item.

barcode
string

A generic GTIN field for the Product Variant.

hs_code
string

The Harmonized System code for the Product Variant.

inventory_quantity
integer
Default: 0

The amount of stock kept for the Product Variant.

allow_backorder
boolean

Whether the Product Variant can be purchased when out of stock.

manage_inventory
boolean
Default: true

Whether Medusa should keep track of the inventory for this Product Variant.

weight
number

The wieght of the Product Variant.

length
number

The length of the Product Variant.

height
number

The height of the Product Variant.

width
number

The width of the Product Variant.

origin_country
string

The country of origin of the Product Variant.

mid_code
string

The Manufacturer Identification code for the Product Variant.

material
string

The material composition of the Product Variant.

metadata
object

An optional set of key-value pairs with additional information.

Responses

Response Schema: application/json
object (Product)

Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.

collection_id
required
string or null
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The Product Collection that the Product belongs to

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Every programmer's best friend."

A short description of the Product.

discountable
required
boolean
Default: true

Whether the Product can be discounted. Discounts will not apply to Line Items of this Product when this flag is set to false.

external_id
required
string or null
Example: null

The external ID of the product

handle
required
string or null
Example: "coffee-mug"

A unique identifier for the Product (e.g. for slug structure).

height
required
number or null
Example: null

The height of the Product Variant. May be used in shipping rate calculations.

hs_code
required
string or null
Example: null

The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

id
required
string
Example: "prod_01G1G5V2MBA328390B5AXJ610F"

The product's ID

is_giftcard
required
boolean
Default: false

Whether the Product represents a Gift Card. Products that represent Gift Cards will automatically generate a redeemable Gift Card code once they are purchased.

length
required
number or null
Example: null

The length of the Product Variant. May be used in shipping rate calculations.

material
required
string or null
Example: null

The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

mid_code
required
string or null
Example: null

The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
required
string or null
Example: null

The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

profile_id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The ID of the Shipping Profile that the Product belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.

status
required
string
Default: "draft"
Enum: "draft" "proposed" "published" "rejected"

The status of the product

subtitle
required
string or null

An optional subtitle that can be used to further specify the Product.

type_id
required
string or null
Example: "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"

The Product type that the Product belongs to

thumbnail
required
string or null <uri>

A URL to an image file that can be used to identify the Product.

title
required
string
Example: "Medusa Coffee Mug"

A title that can be displayed for easy identification of the Product.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

weight
required
number or null
Example: null

The weight of the Product Variant. May be used in shipping rate calculations.

width
required
number or null
Example: null

The width of the Product Variant. May be used in shipping rate calculations.

Array of objects (Image)

Images of the Product. Available if the relation images is expanded.

Array of objects (Product Option)

The Product Options that are defined for the Product. Product Variants of the Product will have a unique combination of Product Option Values. Available if the relation options is expanded.

Array of objects (Product Variant)

The Product Variants that belong to the Product. Each will have a unique combination of Product Option Values. Available if the relation variants is expanded.

Array of objects (ProductCategory)

The product's associated categories. Available if the relation categories are expanded.

object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

object (Product Collection)

Product Collections represents a group of Products that are related.

object (Product Type)

Product Type can be added to Products for filtering and reporting purposes.

Array of objects (Product Tag)

The Product Tags assigned to the Product. Available if the relation tags is expanded.

Array of objects (Sales Channel)

The sales channels the product is associated with. Available if the relation sales_channels is expanded.

Request samples

Content type
application/json
{
  • "title": "string",
  • "sku": "string",
  • "ean": "string",
  • "upc": "string",
  • "barcode": "string",
  • "hs_code": "string",
  • "inventory_quantity": 0,
  • "allow_backorder": true,
  • "manage_inventory": true,
  • "weight": 0,
  • "length": 0,
  • "height": 0,
  • "width": 0,
  • "origin_country": "string",
  • "mid_code": "string",
  • "material": "string",
  • "metadata": { },
  • "prices": [
    ],
  • "options": [
    ]
}

Response samples

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

List a Product's Variants

Retrieves a list of the Product Variants associated with a Product.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

ID of the product to search for the variants.

query Parameters
fields
string

Comma separated string of the column to select.

expand
string

Comma separated string of the relations to include.

offset
integer
Default: 0

How many items to skip before the results.

limit
integer
Default: 100

Limit the number of items returned.

Responses

Response Schema: application/json
Array of objects (Product Variant)
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

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

Response samples

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

Delete a Product Option

Deletes a Product Option. Before a Product Option can be deleted all Option Values for the Product Option must be the same. You may, for example, have to delete some of your variants prior to deleting the Product Option

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product.

option_id
required
string

The ID of the Product Option.

Responses

Response Schema: application/json
option_id
string

The ID of the deleted Product Option

object
string
Default: "option"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were deleted.

object (Product)

Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.

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.products.deleteOption(product_id, option_id)
.then(({ option_id, object, delete, product }) => {
  console.log(product.id);
});

Response samples

Content type
application/json
{
  • "option_id": "string",
  • "object": "option",
  • "deleted": true,
  • "product": {
    }
}

Update a Product Option

Updates a Product Option

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product.

option_id
required
string

The ID of the Product Option.

Request Body schema: application/json
title
required
string

The title of the Product Option

Responses

Response Schema: application/json
object (Product)

Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.

collection_id
required
string or null
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The Product Collection that the Product belongs to

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Every programmer's best friend."

A short description of the Product.

discountable
required
boolean
Default: true

Whether the Product can be discounted. Discounts will not apply to Line Items of this Product when this flag is set to false.

external_id
required
string or null
Example: null

The external ID of the product

handle
required
string or null
Example: "coffee-mug"

A unique identifier for the Product (e.g. for slug structure).

height
required
number or null
Example: null

The height of the Product Variant. May be used in shipping rate calculations.

hs_code
required
string or null
Example: null

The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

id
required
string
Example: "prod_01G1G5V2MBA328390B5AXJ610F"

The product's ID

is_giftcard
required
boolean
Default: false

Whether the Product represents a Gift Card. Products that represent Gift Cards will automatically generate a redeemable Gift Card code once they are purchased.

length
required
number or null
Example: null

The length of the Product Variant. May be used in shipping rate calculations.

material
required
string or null
Example: null

The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

mid_code
required
string or null
Example: null

The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
required
string or null
Example: null

The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

profile_id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The ID of the Shipping Profile that the Product belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.

status
required
string
Default: "draft"
Enum: "draft" "proposed" "published" "rejected"

The status of the product

subtitle
required
string or null

An optional subtitle that can be used to further specify the Product.

type_id
required
string or null
Example: "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"

The Product type that the Product belongs to

thumbnail
required
string or null <uri>

A URL to an image file that can be used to identify the Product.

title
required
string
Example: "Medusa Coffee Mug"

A title that can be displayed for easy identification of the Product.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

weight
required
number or null
Example: null

The weight of the Product Variant. May be used in shipping rate calculations.

width
required
number or null
Example: null

The width of the Product Variant. May be used in shipping rate calculations.

Array of objects (Image)

Images of the Product. Available if the relation images is expanded.

Array of objects (Product Option)

The Product Options that are defined for the Product. Product Variants of the Product will have a unique combination of Product Option Values. Available if the relation options is expanded.

Array of objects (Product Variant)

The Product Variants that belong to the Product. Each will have a unique combination of Product Option Values. Available if the relation variants is expanded.

Array of objects (ProductCategory)

The product's associated categories. Available if the relation categories are expanded.

object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

object (Product Collection)

Product Collections represents a group of Products that are related.

object (Product Type)

Product Type can be added to Products for filtering and reporting purposes.

Array of objects (Product Tag)

The Product Tags assigned to the Product. Available if the relation tags is expanded.

Array of objects (Sales Channel)

The sales channels the product is associated with. Available if the relation sales_channels is expanded.

Request samples

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

Response samples

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

Delete a Product

Deletes a Product and it's associated Product Variants.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product.

Responses

Response Schema: application/json
id
string

The ID of the deleted Product.

object
string
Default: "product"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were 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.products.delete(product_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Product

Retrieves a Product.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product.

Responses

Response Schema: application/json
object (Product)

Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.

collection_id
required
string or null
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The Product Collection that the Product belongs to

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Every programmer's best friend."

A short description of the Product.

discountable
required
boolean
Default: true

Whether the Product can be discounted. Discounts will not apply to Line Items of this Product when this flag is set to false.

external_id
required
string or null
Example: null

The external ID of the product

handle
required
string or null
Example: "coffee-mug"

A unique identifier for the Product (e.g. for slug structure).

height
required
number or null
Example: null

The height of the Product Variant. May be used in shipping rate calculations.

hs_code
required
string or null
Example: null

The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

id
required
string
Example: "prod_01G1G5V2MBA328390B5AXJ610F"

The product's ID

is_giftcard
required
boolean
Default: false

Whether the Product represents a Gift Card. Products that represent Gift Cards will automatically generate a redeemable Gift Card code once they are purchased.

length
required
number or null
Example: null

The length of the Product Variant. May be used in shipping rate calculations.

material
required
string or null
Example: null

The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

mid_code
required
string or null
Example: null

The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
required
string or null
Example: null

The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

profile_id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The ID of the Shipping Profile that the Product belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.

status
required
string
Default: "draft"
Enum: "draft" "proposed" "published" "rejected"

The status of the product

subtitle
required
string or null

An optional subtitle that can be used to further specify the Product.

type_id
required
string or null
Example: "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"

The Product type that the Product belongs to

thumbnail
required
string or null <uri>

A URL to an image file that can be used to identify the Product.

title
required
string
Example: "Medusa Coffee Mug"

A title that can be displayed for easy identification of the Product.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

weight
required
number or null
Example: null

The weight of the Product Variant. May be used in shipping rate calculations.

width
required
number or null
Example: null

The width of the Product Variant. May be used in shipping rate calculations.

Array of objects (Image)

Images of the Product. Available if the relation images is expanded.

Array of objects (Product Option)

The Product Options that are defined for the Product. Product Variants of the Product will have a unique combination of Product Option Values. Available if the relation options is expanded.

Array of objects (Product Variant)

The Product Variants that belong to the Product. Each will have a unique combination of Product Option Values. Available if the relation variants is expanded.

Array of objects (ProductCategory)

The product's associated categories. Available if the relation categories are expanded.

object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

object (Product Collection)

Product Collections represents a group of Products that are related.

object (Product Type)

Product Type can be added to Products for filtering and reporting purposes.

Array of objects (Product Tag)

The Product Tags assigned to the Product. Available if the relation tags is expanded.

Array of objects (Sales Channel)

The sales channels the product is associated with. Available if the relation sales_channels is expanded.

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.products.retrieve(product_id)
.then(({ product }) => {
  console.log(product.id);
});

Response samples

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

Update a Product

Updates a Product

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product.

Request Body schema: application/json
title
string

The title of the Product

subtitle
string

The subtitle of the Product

description
string

A description of the Product.

discountable
boolean

A flag to indicate if discounts can be applied to the LineItems generated from this Product

images
Array of strings

Images of the Product.

thumbnail
string

The thumbnail to use for the Product.

handle
string

A unique handle to identify the Product by.

status
string
Enum: "draft" "proposed" "published" "rejected"

The status of the product.

object

The Product Type to associate the Product with.

collection_id
string

The ID of the Collection the Product should belong to.

Array of objects

Tags to associate the Product with.

Array of objects

[EXPERIMENTAL] Sales channels to associate the Product with.

Array of objects

Categories to add the Product to.

Array of objects

A list of Product Variants to create with the Product.

weight
number

The wieght of the Product.

length
number

The length of the Product.

height
number

The height of the Product.

width
number

The width of the Product.

origin_country
string

The country of origin of the Product.

mid_code
string

The Manufacturer Identification code for the Product.

material
string

The material composition of the Product.

metadata
object

An optional set of key-value pairs with additional information.

Responses

Response Schema: application/json
object (Product)

Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.

collection_id
required
string or null
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The Product Collection that the Product belongs to

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Every programmer's best friend."

A short description of the Product.

discountable
required
boolean
Default: true

Whether the Product can be discounted. Discounts will not apply to Line Items of this Product when this flag is set to false.

external_id
required
string or null
Example: null

The external ID of the product

handle
required
string or null
Example: "coffee-mug"

A unique identifier for the Product (e.g. for slug structure).

height
required
number or null
Example: null

The height of the Product Variant. May be used in shipping rate calculations.

hs_code
required
string or null
Example: null

The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

id
required
string
Example: "prod_01G1G5V2MBA328390B5AXJ610F"

The product's ID

is_giftcard
required
boolean
Default: false

Whether the Product represents a Gift Card. Products that represent Gift Cards will automatically generate a redeemable Gift Card code once they are purchased.

length
required
number or null
Example: null

The length of the Product Variant. May be used in shipping rate calculations.

material
required
string or null
Example: null

The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

mid_code
required
string or null
Example: null

The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
required
string or null
Example: null

The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

profile_id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The ID of the Shipping Profile that the Product belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.

status
required
string
Default: "draft"
Enum: "draft" "proposed" "published" "rejected"

The status of the product

subtitle
required
string or null

An optional subtitle that can be used to further specify the Product.

type_id
required
string or null
Example: "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"

The Product type that the Product belongs to

thumbnail
required
string or null <uri>

A URL to an image file that can be used to identify the Product.

title
required
string
Example: "Medusa Coffee Mug"

A title that can be displayed for easy identification of the Product.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

weight
required
number or null
Example: null

The weight of the Product Variant. May be used in shipping rate calculations.

width
required
number or null
Example: null

The width of the Product Variant. May be used in shipping rate calculations.

Array of objects (Image)

Images of the Product. Available if the relation images is expanded.

Array of objects (Product Option)

The Product Options that are defined for the Product. Product Variants of the Product will have a unique combination of Product Option Values. Available if the relation options is expanded.

Array of objects (Product Variant)

The Product Variants that belong to the Product. Each will have a unique combination of Product Option Values. Available if the relation variants is expanded.

Array of objects (ProductCategory)

The product's associated categories. Available if the relation categories are expanded.

object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

object (Product Collection)

Product Collections represents a group of Products that are related.

object (Product Type)

Product Type can be added to Products for filtering and reporting purposes.

Array of objects (Product Tag)

The Product Tags assigned to the Product. Available if the relation tags is expanded.

Array of objects (Sales Channel)

The sales channels the product is associated with. Available if the relation sales_channels is expanded.

Request samples

Content type
application/json
{
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "discountable": true,
  • "images": [
    ],
  • "thumbnail": "string",
  • "handle": "string",
  • "status": "draft",
  • "type": {
    },
  • "collection_id": "string",
  • "tags": [
    ],
  • "sales_channels": [
    ],
  • "categories": [
    ],
  • "variants": [
    ],
  • "weight": 0,
  • "length": 0,
  • "height": 0,
  • "width": 0,
  • "origin_country": "string",
  • "mid_code": "string",
  • "material": "string",
  • "metadata": { }
}

Response samples

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

Delete a Product Variant

Deletes a Product Variant.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product.

variant_id
required
string

The ID of the Product Variant.

Responses

Response Schema: application/json
variant_id
string

The ID of the deleted Product Variant.

object
string
Default: "product-variant"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were deleted.

object (Product)

Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.

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.products.deleteVariant(product_id, variant_id)
.then(({ variant_id, object, deleted, product }) => {
  console.log(product.id);
});

Response samples

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

Update a Product Variant

Update a Product Variant.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product.

variant_id
required
string

The ID of the Product Variant.

Request Body schema: application/json
required
Array of objects
title
string

The title to identify the Product Variant by.

sku
string

The unique SKU for the Product Variant.

ean
string

The EAN number of the item.

upc
string

The UPC number of the item.

barcode
string

A generic GTIN field for the Product Variant.

hs_code
string

The Harmonized System code for the Product Variant.

inventory_quantity
integer

The amount of stock kept for the Product Variant.

allow_backorder
boolean

Whether the Product Variant can be purchased when out of stock.

manage_inventory
boolean

Whether Medusa should keep track of the inventory for this Product Variant.

weight
number

The weight of the Product Variant.

length
number

The length of the Product Variant.

height
number

The height of the Product Variant.

width
number

The width of the Product Variant.

origin_country
string

The country of origin of the Product Variant.

mid_code
string

The Manufacturer Identification code for the Product Variant.

material
string

The material composition of the Product Variant.

metadata
object

An optional set of key-value pairs with additional information.

Array of objects

Responses

Response Schema: application/json
object (Product)

Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.

collection_id
required
string or null
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The Product Collection that the Product belongs to

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Every programmer's best friend."

A short description of the Product.

discountable
required
boolean
Default: true

Whether the Product can be discounted. Discounts will not apply to Line Items of this Product when this flag is set to false.

external_id
required
string or null
Example: null

The external ID of the product

handle
required
string or null
Example: "coffee-mug"

A unique identifier for the Product (e.g. for slug structure).

height
required
number or null
Example: null

The height of the Product Variant. May be used in shipping rate calculations.

hs_code
required
string or null
Example: null

The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

id
required
string
Example: "prod_01G1G5V2MBA328390B5AXJ610F"

The product's ID

is_giftcard
required
boolean
Default: false

Whether the Product represents a Gift Card. Products that represent Gift Cards will automatically generate a redeemable Gift Card code once they are purchased.

length
required
number or null
Example: null

The length of the Product Variant. May be used in shipping rate calculations.

material
required
string or null
Example: null

The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

mid_code
required
string or null
Example: null

The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
required
string or null
Example: null

The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

profile_id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The ID of the Shipping Profile that the Product belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.

status
required
string
Default: "draft"
Enum: "draft" "proposed" "published" "rejected"

The status of the product

subtitle
required
string or null

An optional subtitle that can be used to further specify the Product.

type_id
required
string or null
Example: "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"

The Product type that the Product belongs to

thumbnail
required
string or null <uri>

A URL to an image file that can be used to identify the Product.

title
required
string
Example: "Medusa Coffee Mug"

A title that can be displayed for easy identification of the Product.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

weight
required
number or null
Example: null

The weight of the Product Variant. May be used in shipping rate calculations.

width
required
number or null
Example: null

The width of the Product Variant. May be used in shipping rate calculations.

Array of objects (Image)

Images of the Product. Available if the relation images is expanded.

Array of objects (Product Option)

The Product Options that are defined for the Product. Product Variants of the Product will have a unique combination of Product Option Values. Available if the relation options is expanded.

Array of objects (Product Variant)

The Product Variants that belong to the Product. Each will have a unique combination of Product Option Values. Available if the relation variants is expanded.

Array of objects (ProductCategory)

The product's associated categories. Available if the relation categories are expanded.

object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

object (Product Collection)

Product Collections represents a group of Products that are related.

object (Product Type)

Product Type can be added to Products for filtering and reporting purposes.

Array of objects (Product Tag)

The Product Tags assigned to the Product. Available if the relation tags is expanded.

Array of objects (Sales Channel)

The sales channels the product is associated with. Available if the relation sales_channels is expanded.

Request samples

Content type
application/json
{
  • "title": "string",
  • "sku": "string",
  • "ean": "string",
  • "upc": "string",
  • "barcode": "string",
  • "hs_code": "string",
  • "inventory_quantity": 0,
  • "allow_backorder": true,
  • "manage_inventory": true,
  • "weight": 0,
  • "length": 0,
  • "height": 0,
  • "width": 0,
  • "origin_country": "string",
  • "mid_code": "string",
  • "material": "string",
  • "metadata": { },
  • "prices": [
    ],
  • "options": [
    ]
}

Response samples

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

List Product Types Deprecated

Retrieves a list of Product Types.

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
Array of objects (Product Type)
Array
created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"

The product type's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

value
required
string
Example: "Clothing"

The value that the Product Type represents.

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.products.listTypes()
.then(({ types }) => {
  console.log(types.length);
});

Response samples

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

Set Product Metadata

Set metadata key/value pair for Product

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product.

Request Body schema: application/json
key
required
string

The metadata key

value
required
string

The metadata value

Responses

Response Schema: application/json
object (Product)

Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.

collection_id
required
string or null
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The Product Collection that the Product belongs to

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Every programmer's best friend."

A short description of the Product.

discountable
required
boolean
Default: true

Whether the Product can be discounted. Discounts will not apply to Line Items of this Product when this flag is set to false.

external_id
required
string or null
Example: null

The external ID of the product

handle
required
string or null
Example: "coffee-mug"

A unique identifier for the Product (e.g. for slug structure).

height
required
number or null
Example: null

The height of the Product Variant. May be used in shipping rate calculations.

hs_code
required
string or null
Example: null

The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

id
required
string
Example: "prod_01G1G5V2MBA328390B5AXJ610F"

The product's ID

is_giftcard
required
boolean
Default: false

Whether the Product represents a Gift Card. Products that represent Gift Cards will automatically generate a redeemable Gift Card code once they are purchased.

length
required
number or null
Example: null

The length of the Product Variant. May be used in shipping rate calculations.

material
required
string or null
Example: null

The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

mid_code
required
string or null
Example: null

The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

origin_country
required
string or null
Example: null

The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

profile_id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The ID of the Shipping Profile that the Product belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.

status
required
string
Default: "draft"
Enum: "draft" "proposed" "published" "rejected"

The status of the product

subtitle
required
string or null

An optional subtitle that can be used to further specify the Product.

type_id
required
string or null
Example: "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A"

The Product type that the Product belongs to

thumbnail
required
string or null <uri>

A URL to an image file that can be used to identify the Product.

title
required
string
Example: "Medusa Coffee Mug"

A title that can be displayed for easy identification of the Product.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

weight
required
number or null
Example: null

The weight of the Product Variant. May be used in shipping rate calculations.

width
required
number or null
Example: null

The width of the Product Variant. May be used in shipping rate calculations.

Array of objects (Image)

Images of the Product. Available if the relation images is expanded.

Array of objects (Product Option)

The Product Options that are defined for the Product. Product Variants of the Product will have a unique combination of Product Option Values. Available if the relation options is expanded.

Array of objects (Product Variant)

The Product Variants that belong to the Product. Each will have a unique combination of Product Option Values. Available if the relation variants is expanded.

Array of objects (ProductCategory)

The product's associated categories. Available if the relation categories are expanded.

object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

object (Product Collection)

Product Collections represents a group of Products that are related.

object (Product Type)

Product Type can be added to Products for filtering and reporting purposes.

Array of objects (Product Tag)

The Product Tags assigned to the Product. Available if the relation tags is expanded.

Array of objects (Sales Channel)

The sales channels the product is associated with. Available if the relation sales_channels is expanded.

Request samples

Content type
application/json
{
  • "key": "string",
  • "value": "string"
}

Response samples

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

Product Category

Add Products to a category

Assign a batch of products to a product category.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product Category.

query Parameters
expand
string

(Comma separated) Category fields to be expanded in the response.

fields
string

(Comma separated) Category fields to be retrieved in the response.

Request Body schema: application/json
required
Array of objects

The IDs of the products to add to the Product Category

Array
id
required
string

The ID of the product

Responses

Response Schema: application/json
object (ProductCategory)

Represents a product category

category_children
required
Array of objects

Available if the relation category_children are expanded.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string
Example: "regular-fit"

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

id
required
string
Example: "pcat_01G2SG30J8C85S4A5CHM2S1NS2"

The product category's ID

is_active
required
boolean
Default: false

A flag to make product category visible/hidden in the store front

is_internal
required
boolean
Default: false

A flag to make product category an internal category for admins

mpath
required
string or null
Example: "pcat_id1.pcat_id2.pcat_id3"

A string for Materialized Paths - used for finding ancestors and descendents

name
required
string
Example: "Regular Fit"

The product category's name

parent_category_id
required
string or null
Default: null

The ID of the parent category.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

parent_category
object or null

A product category object. Available if the relation parent_category is expanded.

products
Array of objects

Products associated with category. Available if the relation products is expanded.

Request samples

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

Response samples

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

Delete Products

Remove a list of products from a product category.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product Category.

query Parameters
expand
string

(Comma separated) Category fields to be expanded in the response.

fields
string

(Comma separated) Category fields to be retrieved in the response.

Request Body schema: application/json
required
Array of objects

The IDs of the products to delete from the Product Category.

Array
id
required
string

The ID of a product

Responses

Response Schema: application/json
object (ProductCategory)

Represents a product category

category_children
required
Array of objects

Available if the relation category_children are expanded.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string
Example: "regular-fit"

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

id
required
string
Example: "pcat_01G2SG30J8C85S4A5CHM2S1NS2"

The product category's ID

is_active
required
boolean
Default: false

A flag to make product category visible/hidden in the store front

is_internal
required
boolean
Default: false

A flag to make product category an internal category for admins

mpath
required
string or null
Example: "pcat_id1.pcat_id2.pcat_id3"

A string for Materialized Paths - used for finding ancestors and descendents

name
required
string
Example: "Regular Fit"

The product category's name

parent_category_id
required
string or null
Default: null

The ID of the parent category.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

parent_category
object or null

A product category object. Available if the relation parent_category is expanded.

products
Array of objects

Products associated with category. Available if the relation products is expanded.

Request samples

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

Response samples

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

Create a Product Category

Creates a Product Category.

Authorizations:
API TokenCookie Session ID
query Parameters
expand
string

(Comma separated) Which fields should be expanded in the results.

fields
string

(Comma separated) Which fields should be retrieved in the results.

Request Body schema: application/json
name
required
string

The name to identify the Product Category by.

handle
string

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

is_internal
boolean

A flag to make product category an internal category for admins

is_active
boolean

A flag to make product category visible/hidden in the store front

parent_category_id
string

The ID of the parent product category

Responses

Response Schema: application/json
object (ProductCategory)

Represents a product category

category_children
required
Array of objects

Available if the relation category_children are expanded.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string
Example: "regular-fit"

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

id
required
string
Example: "pcat_01G2SG30J8C85S4A5CHM2S1NS2"

The product category's ID

is_active
required
boolean
Default: false

A flag to make product category visible/hidden in the store front

is_internal
required
boolean
Default: false

A flag to make product category an internal category for admins

mpath
required
string or null
Example: "pcat_id1.pcat_id2.pcat_id3"

A string for Materialized Paths - used for finding ancestors and descendents

name
required
string
Example: "Regular Fit"

The product category's name

parent_category_id
required
string or null
Default: null

The ID of the parent category.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

parent_category
object or null

A product category object. Available if the relation parent_category is expanded.

products
Array of objects

Products associated with category. Available if the relation products is expanded.

Request samples

Content type
application/json
{
  • "name": "string",
  • "handle": "string",
  • "is_internal": true,
  • "is_active": true,
  • "parent_category_id": "string"
}

Response samples

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

List Product Categories

Retrieve a list of product categories.

Authorizations:
API TokenCookie Session ID
query Parameters
q
string

Query used for searching product category names orhandles.

is_internal
boolean

Search for only internal categories.

is_active
boolean

Search for only active categories

parent_category_id
string

Returns categories scoped by parent

offset
integer
Default: 0

How many product categories to skip in the result.

limit
integer
Default: 100

Limit the number of product categories returned.

expand
string

(Comma separated) Which fields should be expanded in the product category.

fields
string

(Comma separated) Which fields should be included in the product category.

Responses

Response Schema: application/json
Array of objects (ProductCategory)
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.productCategories.list()
.then(({ product_categories, limit, offset, count }) => {
  console.log(product_categories.length);
});

Response samples

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

Delete a Product Category

Deletes a ProductCategory.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product Category

Responses

Response Schema: application/json
id
string

The ID of the deleted product category

object
string
Default: "product-category"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were 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.productCategories.delete(product_category_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Product Category

Retrieves a Product Category.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product Category

query Parameters
expand
string

(Comma separated) Which fields should be expanded in the results.

fields
string

(Comma separated) Which fields should be included in the results.

Responses

Response Schema: application/json
object (ProductCategory)

Represents a product category

category_children
required
Array of objects

Available if the relation category_children are expanded.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string
Example: "regular-fit"

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

id
required
string
Example: "pcat_01G2SG30J8C85S4A5CHM2S1NS2"

The product category's ID

is_active
required
boolean
Default: false

A flag to make product category visible/hidden in the store front

is_internal
required
boolean
Default: false

A flag to make product category an internal category for admins

mpath
required
string or null
Example: "pcat_id1.pcat_id2.pcat_id3"

A string for Materialized Paths - used for finding ancestors and descendents

name
required
string
Example: "Regular Fit"

The product category's name

parent_category_id
required
string or null
Default: null

The ID of the parent category.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

parent_category
object or null

A product category object. Available if the relation parent_category is expanded.

products
Array of objects

Products associated with category. Available if the relation products is expanded.

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.productCategories.retrieve(product_category_id)
.then(({ product_category }) => {
  console.log(product_category.id);
});

Response samples

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

Update a Product Category

Updates a Product Category.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product Category.

query Parameters
expand
string

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

fields
string

(Comma separated) Which fields should be retrieved in each product category.

Request Body schema: application/json
name
string

The name to identify the Product Category by.

handle
string

A handle to be used in slugs.

is_internal
boolean

A flag to make product category an internal category for admins

is_active
boolean

A flag to make product category visible/hidden in the store front

parent_category_id
string

The ID of the parent product category

Responses

Response Schema: application/json
object (ProductCategory)

Represents a product category

category_children
required
Array of objects

Available if the relation category_children are expanded.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string
Example: "regular-fit"

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

id
required
string
Example: "pcat_01G2SG30J8C85S4A5CHM2S1NS2"

The product category's ID

is_active
required
boolean
Default: false

A flag to make product category visible/hidden in the store front

is_internal
required
boolean
Default: false

A flag to make product category an internal category for admins

mpath
required
string or null
Example: "pcat_id1.pcat_id2.pcat_id3"

A string for Materialized Paths - used for finding ancestors and descendents

name
required
string
Example: "Regular Fit"

The product category's name

parent_category_id
required
string or null
Default: null

The ID of the parent category.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

parent_category
object or null

A product category object. Available if the relation parent_category is expanded.

products
Array of objects

Products associated with category. Available if the relation products is expanded.

Request samples

Content type
application/json
{
  • "name": "string",
  • "handle": "string",
  • "is_internal": true,
  • "is_active": true,
  • "parent_category_id": "string"
}

Response samples

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

List Reservations

Retrieve a list of Reservations.

Authorizations:
API TokenCookie Session ID
query Parameters
location_id
Array of strings

Location ids to search for.

inventory_item_id
Array of strings

Inventory Item ids to search for.

line_item_id
Array of strings

Line Item ids to search for.

object

Filter by reservation quantity

offset
integer
Default: 0

How many Reservations to skip in the result.

limit
integer
Default: 20

Limit the number of Reservations returned.

expand
string

(Comma separated) Which fields should be expanded in the product category.

fields
string

(Comma separated) Which fields should be included in the product category.

Responses

Response Schema: application/json
Array of objects (Reservation item)
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

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

Response samples

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

Product Tag

Product Tag endpoints that allow handling product tags in Medusa.

List Product Tags

Retrieve a list of Product Tags.

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

The number of tags to return.

offset
integer
Default: 0

The number of items to skip before the results.

order
string

The field to sort items by.

discount_condition_id
string

The discount condition id on which to filter the tags.

value
Array of strings

The tag values to search for

q
string

A query string to search values for

id
Array of strings

The tag IDs to search for

object

Date comparison for when resulting product tags were created.

object

Date comparison for when resulting product tags were updated.

Responses

Response Schema: application/json
Array of objects (Product Tag)
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.productTags.list()
.then(({ product_tags }) => {
  console.log(product_tags.length);
});

Response samples

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

List Tags Usage Number

Retrieves a list of Product Tags with how many times each is used.

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
Array of objects
Array
id
string

The ID of the tag.

usage_count
string

The number of products that use this tag.

value
string

The value of the tag.

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.products.listTags()
.then(({ tags }) => {
  console.log(tags.length);
});

Response samples

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

Product Type

Product Types endpoints that allow handling product types in Medusa.

List Product Types

Retrieve a list of Product Types.

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

The number of types to return.

offset
integer
Default: 0

The number of items to skip before the results.

order
string

The field to sort items by.

discount_condition_id
string

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

value
Array of strings

The type values to search for

id
Array of strings

The type IDs to search for

q
string

A query string to search values for

object

Date comparison for when resulting product types were created.

object

Date comparison for when resulting product types were updated.

Responses

Response Schema: application/json
Array of objects (Product Type)
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.productTypes.list()
.then(({ product_types }) => {
  console.log(product_types.length);
});

Response samples

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

Product Variant

Product Variant endpoints that allow handling product variants in Medusa.

Get inventory of Variant.

Returns the available inventory of a Variant.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The Product Variant id to get inventory for.

Responses

Response Schema: application/json
object (AdminGetVariantsVariantInventoryRes)
id
string

the id of the variant

inventory
string

the stock location address ID

object

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.variants.list()
  .then(({ variants, limit, offset, count }) => {
    console.log(variants.length)
  })

Response samples

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

List Product Variants

Retrieves a list of Product Variants

Authorizations:
API TokenCookie Session ID
query Parameters
id
string

A Product Variant id to filter by.

ids
string

A comma separated list of Product Variant ids to filter by.

expand
string

A comma separated list of Product Variant relations to load.

fields
string

A comma separated list of Product Variant fields to include.

offset
number
Default: "0"

How many product variants to skip in the result.

limit
number
Default: "100"

Maximum number of Product Variants to return.

cart_id
string

The id of the cart to use for price selection.

region_id
string

The id of the region to use for price selection.

currency_code
string

The currency code to use for price selection.

customer_id
string

The id of the customer to use for price selection.

string or Array of strings

product variant title to search for.

number or object

Filter by available inventory quantity

Responses

Response Schema: application/json
Array of objects (Product Variant)
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.variants.list()
.then(({ variants, limit, offset, count }) => {
  console.log(variants.length);
});

Response samples

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

PublishableApiKey

Add SalesChannels

Assign a batch of sales channels to a publishable api key.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Publishable Api Key.

Request Body schema: application/json
required
Array of objects

The IDs of the sales channels to add to the publishable api key

Array
id
required
string

The ID of the sales channel

Responses

Response Schema: application/json
object (Publishable API key)

Publishable API key defines scopes (i.e. resources) that are available within a request.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that created the key.

id
required
string
Example: "pk_01G1G5V27GYX4QXNARRQCW1N8T"

The key's ID

revoked_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that revoked the key.

revoked_at
required
string or null <date-time>

The date with timezone at which the key was revoked.

title
required
string

The key's title.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Request samples

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

Response samples

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

Delete SalesChannels

Remove a batch of sales channels from a publishable api key.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Publishable Api Key.

Request Body schema: application/json
required
Array of objects

The IDs of the sales channels to delete from the publishable api key

Array
id
required
string

The ID of the sales channel

Responses

Response Schema: application/json
object (Publishable API key)

Publishable API key defines scopes (i.e. resources) that are available within a request.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that created the key.

id
required
string
Example: "pk_01G1G5V27GYX4QXNARRQCW1N8T"

The key's ID

revoked_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that revoked the key.

revoked_at
required
string or null <date-time>

The date with timezone at which the key was revoked.

title
required
string

The key's title.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Request samples

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

Response samples

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

Create PublishableApiKey

Creates a PublishableApiKey.

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

A title for the publishable api key

Responses

Response Schema: application/json
object (Publishable API key)

Publishable API key defines scopes (i.e. resources) that are available within a request.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that created the key.

id
required
string
Example: "pk_01G1G5V27GYX4QXNARRQCW1N8T"

The key's ID

revoked_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that revoked the key.

revoked_at
required
string or null <date-time>

The date with timezone at which the key was revoked.

title
required
string

The key's title.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Request samples

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

Response samples

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

List PublishableApiKeys

List PublishableApiKeys.

Authorizations:
API TokenCookie Session ID
query Parameters
q
string

Query used for searching publishable api keys by title.

limit
number
Default: "20"

The number of items in the response

offset
number
Default: "0"

The offset of items in response

expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
Array of objects (Publishable API key)
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.publishableApiKeys.list()
  .then(({ publishable_api_keys, count, limit, offset }) => {
    console.log(publishable_api_keys)
  })

Response samples

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

Delete PublishableApiKey

Deletes a PublishableApiKeys

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the PublishableApiKeys to delete.

Responses

Response Schema: application/json
id
string

The ID of the deleted PublishableApiKey.

object
string
Default: "publishable_api_key"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether the PublishableApiKeys 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.publishableApiKeys.delete(publishableApiKeyId)
.then(({ id, object, deleted }) => {
  console.log(id)
})

Response samples

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

Get a PublishableApiKey

Retrieve the Publishable Api Key.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the PublishableApiKey.

Responses

Response Schema: application/json
object (Publishable API key)

Publishable API key defines scopes (i.e. resources) that are available within a request.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that created the key.

id
required
string
Example: "pk_01G1G5V27GYX4QXNARRQCW1N8T"

The key's ID

revoked_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that revoked the key.

revoked_at
required
string or null <date-time>

The date with timezone at which the key was revoked.

title
required
string

The key's title.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

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.publishableApiKeys.retrieve(publishableApiKeyId)
.then(({ publishable_api_key }) => {
  console.log(publishable_api_key.id)
})

Response samples

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

List SalesChannels

List PublishableApiKey's SalesChannels

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Publishable Api Key.

query Parameters
q
string

Query used for searching sales channels' names and descriptions.

Responses

Response Schema: application/json
Array of objects (Sales Channel)
Array
created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Multi-vendor market"

The description of the sales channel.

id
required
string
Example: "sc_01G8X9A7ESKAJXG2H0E6F1MW7A"

The sales channel's ID

is_disabled
required
boolean
Default: false

Specify if the sales channel is enabled or disabled.

name
required
string
Example: "Market"

The name of the sales channel.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Array of objects (Sales Channel Stock Location)

The Stock Locations related to the sales channel. Available if the relation locations is expanded.

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.publishableApiKeys.listSalesChannels()
  .then(({ sales_channels }) => {
    console.log(sales_channels.length)
  })

Response samples

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

Revoke PublishableApiKey

Revokes a PublishableApiKey.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the PublishableApiKey.

Responses

Response Schema: application/json
object (Publishable API key)

Publishable API key defines scopes (i.e. resources) that are available within a request.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that created the key.

id
required
string
Example: "pk_01G1G5V27GYX4QXNARRQCW1N8T"

The key's ID

revoked_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that revoked the key.

revoked_at
required
string or null <date-time>

The date with timezone at which the key was revoked.

title
required
string

The key's title.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

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.publishableApiKeys.revoke(publishableApiKeyId)
  .then(({ publishable_api_key }) => {
    console.log(publishable_api_key.id)
  })

Response samples

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

Update PublishableApiKey

Updates a PublishableApiKey.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the PublishableApiKey.

Request Body schema: application/json
title
string

A title to update for the key.

Responses

Response Schema: application/json
object (Publishable API key)

Publishable API key defines scopes (i.e. resources) that are available within a request.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that created the key.

id
required
string
Example: "pk_01G1G5V27GYX4QXNARRQCW1N8T"

The key's ID

revoked_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that revoked the key.

revoked_at
required
string or null <date-time>

The date with timezone at which the key was revoked.

title
required
string

The key's title.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Request samples

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

Response samples

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

Region

Region endpoints that allow handling regions in Medusa.

Add Country

Adds a Country to the list of Countries in a Region

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Region.

Request Body schema: application/json
country_code
required
string

The 2 character ISO code for the Country.

Responses

Response Schema: application/json
object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

automatic_taxes
required
boolean
Default: true

Whether taxes should be automated in this region.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that the Region uses.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

gift_cards_taxable
required
boolean
Default: true

Whether the gift cards are taxable or not in this region.

id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "EU"

The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.

tax_code
required
string or null
Example: null

The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.

tax_provider_id
required
string or null
Example: null

The ID of the tax provider used in this region

tax_rate
required
number
Example: 0

The tax rate that should be charged on purchases in the Region.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Tax Rate)

The tax rates that are included in the Region. Available if the relation tax_rates is expanded.

Array of objects (Country)

The countries that are included in the Region. Available if the relation countries is expanded.

object (Tax Provider)

The tax service used to calculate taxes

Array of objects (Payment Provider)

The Payment Providers that can be used to process Payments in the Region. Available if the relation payment_providers is expanded.

Array of objects (Fulfillment Provider)

The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation fulfillment_providers is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the prices for the region include tax

Request samples

Content type
application/json
{
  • "country_code": "string"
}

Response samples

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

Add Fulfillment Provider

Adds a Fulfillment Provider to a Region

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Region.

Request Body schema: application/json
provider_id
required
string

The ID of the Fulfillment Provider to add.

Responses

Response Schema: application/json
object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

automatic_taxes
required
boolean
Default: true

Whether taxes should be automated in this region.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that the Region uses.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

gift_cards_taxable
required
boolean
Default: true

Whether the gift cards are taxable or not in this region.

id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "EU"

The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.

tax_code
required
string or null
Example: null

The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.

tax_provider_id
required
string or null
Example: null

The ID of the tax provider used in this region

tax_rate
required
number
Example: 0

The tax rate that should be charged on purchases in the Region.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Tax Rate)

The tax rates that are included in the Region. Available if the relation tax_rates is expanded.

Array of objects (Country)

The countries that are included in the Region. Available if the relation countries is expanded.

object (Tax Provider)

The tax service used to calculate taxes

Array of objects (Payment Provider)

The Payment Providers that can be used to process Payments in the Region. Available if the relation payment_providers is expanded.

Array of objects (Fulfillment Provider)

The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation fulfillment_providers is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the prices for the region include tax

Request samples

Content type
application/json
{
  • "provider_id": "string"
}

Response samples

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

Add Payment Provider

Adds a Payment Provider to a Region

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Region.

Request Body schema: application/json
provider_id
required
string

The ID of the Payment Provider to add.

Responses

Response Schema: application/json
object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

automatic_taxes
required
boolean
Default: true

Whether taxes should be automated in this region.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that the Region uses.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

gift_cards_taxable
required
boolean
Default: true

Whether the gift cards are taxable or not in this region.

id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "EU"

The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.

tax_code
required
string or null
Example: null

The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.

tax_provider_id
required
string or null
Example: null

The ID of the tax provider used in this region

tax_rate
required
number
Example: 0

The tax rate that should be charged on purchases in the Region.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Tax Rate)

The tax rates that are included in the Region. Available if the relation tax_rates is expanded.

Array of objects (Country)

The countries that are included in the Region. Available if the relation countries is expanded.

object (Tax Provider)

The tax service used to calculate taxes

Array of objects (Payment Provider)

The Payment Providers that can be used to process Payments in the Region. Available if the relation payment_providers is expanded.

Array of objects (Fulfillment Provider)

The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation fulfillment_providers is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the prices for the region include tax

Request samples

Content type
application/json
{
  • "provider_id": "string"
}

Response samples

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

Create a Region

Creates a Region

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

The name of the Region

currency_code
required
string

The 3 character ISO currency code to use for the Region.

tax_rate
required
number

The tax rate to use on Orders in the Region.

payment_providers
required
Array of strings

A list of Payment Provider IDs that should be enabled for the Region

fulfillment_providers
required
Array of strings

A list of Fulfillment Provider IDs that should be enabled for the Region

countries
required
Array of strings
Example: ["US"]

A list of countries' 2 ISO Characters that should be included in the Region.

tax_code
string

An optional tax code the Region.

includes_tax
boolean

[EXPERIMENTAL] Tax included in prices of region

Responses

Response Schema: application/json
object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

automatic_taxes
required
boolean
Default: true

Whether taxes should be automated in this region.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that the Region uses.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

gift_cards_taxable
required
boolean
Default: true

Whether the gift cards are taxable or not in this region.

id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "EU"

The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.

tax_code
required
string or null
Example: null

The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.

tax_provider_id
required
string or null
Example: null

The ID of the tax provider used in this region

tax_rate
required
number
Example: 0

The tax rate that should be charged on purchases in the Region.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Tax Rate)

The tax rates that are included in the Region. Available if the relation tax_rates is expanded.

Array of objects (Country)

The countries that are included in the Region. Available if the relation countries is expanded.

object (Tax Provider)

The tax service used to calculate taxes

Array of objects (Payment Provider)

The Payment Providers that can be used to process Payments in the Region. Available if the relation payment_providers is expanded.

Array of objects (Fulfillment Provider)

The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation fulfillment_providers is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the prices for the region include tax

Request samples

Content type
application/json
{
  • "name": "string",
  • "currency_code": "string",
  • "tax_code": "string",
  • "tax_rate": 0,
  • "payment_providers": [
    ],
  • "fulfillment_providers": [
    ],
  • "countries": [
    ],
  • "includes_tax": true
}

Response samples

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

List Regions

Retrieves a list of Regions.

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

limit the number of regions in response

offset
integer
Default: 0

Offset of regions in response (used for pagination)

created_at
object

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

updated_at
object

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

deleted_at
object

Date comparison for when resulting region was deleted, i.e. less than, greater than etc.

Responses

Response Schema: application/json
Array of objects (Region)
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.regions.list()
.then(({ regions, limit, offset, count }) => {
  console.log(regions.length);
});

Response samples

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

Delete a Region

Deletes a Region.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Region.

Responses

Response Schema: application/json
id
string

The ID of the deleted Region.

object
string
Default: "region"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were 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.regions.delete(region_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Region

Retrieves a Region.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Region.

Responses

Response Schema: application/json
object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

automatic_taxes
required
boolean
Default: true

Whether taxes should be automated in this region.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that the Region uses.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

gift_cards_taxable
required
boolean
Default: true

Whether the gift cards are taxable or not in this region.

id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "EU"

The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.

tax_code
required
string or null
Example: null

The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.

tax_provider_id
required
string or null
Example: null

The ID of the tax provider used in this region

tax_rate
required
number
Example: 0

The tax rate that should be charged on purchases in the Region.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Tax Rate)

The tax rates that are included in the Region. Available if the relation tax_rates is expanded.

Array of objects (Country)

The countries that are included in the Region. Available if the relation countries is expanded.

object (Tax Provider)

The tax service used to calculate taxes

Array of objects (Payment Provider)

The Payment Providers that can be used to process Payments in the Region. Available if the relation payment_providers is expanded.

Array of objects (Fulfillment Provider)

The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation fulfillment_providers is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the prices for the region include tax

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.regions.retrieve(region_id)
.then(({ region }) => {
  console.log(region.id);
});

Response samples

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

Update a Region

Updates a Region

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Region.

Request Body schema: application/json
name
string

The name of the Region

currency_code
string

The 3 character ISO currency code to use for the Region.

automatic_taxes
boolean

If true Medusa will automatically calculate taxes for carts in this region. If false you have to manually call POST /carts/:id/taxes.

gift_cards_taxable
boolean

Whether gift cards in this region should be applied sales tax when purchasing a gift card

tax_provider_id
string

The ID of the tax provider to use; if null the system tax provider is used

tax_code
string

An optional tax code the Region.

tax_rate
number

The tax rate to use on Orders in the Region.

includes_tax
boolean

[EXPERIMENTAL] Tax included in prices of region

payment_providers
Array of strings

A list of Payment Provider IDs that should be enabled for the Region

fulfillment_providers
Array of strings

A list of Fulfillment Provider IDs that should be enabled for the Region

countries
Array of strings

A list of countries' 2 ISO Characters that should be included in the Region.

Responses

Response Schema: application/json
object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

automatic_taxes
required
boolean
Default: true

Whether taxes should be automated in this region.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that the Region uses.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

gift_cards_taxable
required
boolean
Default: true

Whether the gift cards are taxable or not in this region.

id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "EU"

The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.

tax_code
required
string or null
Example: null

The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.

tax_provider_id
required
string or null
Example: null

The ID of the tax provider used in this region

tax_rate
required
number
Example: 0

The tax rate that should be charged on purchases in the Region.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Tax Rate)

The tax rates that are included in the Region. Available if the relation tax_rates is expanded.

Array of objects (Country)

The countries that are included in the Region. Available if the relation countries is expanded.

object (Tax Provider)

The tax service used to calculate taxes

Array of objects (Payment Provider)

The Payment Providers that can be used to process Payments in the Region. Available if the relation payment_providers is expanded.

Array of objects (Fulfillment Provider)

The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation fulfillment_providers is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the prices for the region include tax

Request samples

Content type
application/json
{
  • "name": "string",
  • "currency_code": "string",
  • "automatic_taxes": true,
  • "gift_cards_taxable": true,
  • "tax_provider_id": "string",
  • "tax_code": "string",
  • "tax_rate": 0,
  • "includes_tax": true,
  • "payment_providers": [
    ],
  • "fulfillment_providers": [
    ],
  • "countries": [
    ]
}

Response samples

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

List Fulfillment Options

Gathers all the fulfillment options available to in the Region.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Region.

Responses

Response Schema: application/json
Array of objects
Array
provider_id
string

ID of the fulfillment provider

options
Array of arrays
Example: [{"id":"manual-fulfillment"},{"id":"manual-fulfillment-return","is_return":true}]

fulfillment provider options

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.regions.retrieveFulfillmentOptions(region_id)
.then(({ fulfillment_options }) => {
  console.log(fulfillment_options.length);
});

Response samples

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

Delete Country

Removes a Country from the list of Countries in a Region

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Region.

country_code
required
string

The 2 character ISO code for the Country.

Responses

Response Schema: application/json
object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

automatic_taxes
required
boolean
Default: true

Whether taxes should be automated in this region.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that the Region uses.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

gift_cards_taxable
required
boolean
Default: true

Whether the gift cards are taxable or not in this region.

id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "EU"

The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.

tax_code
required
string or null
Example: null

The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.

tax_provider_id
required
string or null
Example: null

The ID of the tax provider used in this region

tax_rate
required
number
Example: 0

The tax rate that should be charged on purchases in the Region.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Tax Rate)

The tax rates that are included in the Region. Available if the relation tax_rates is expanded.

Array of objects (Country)

The countries that are included in the Region. Available if the relation countries is expanded.

object (Tax Provider)

The tax service used to calculate taxes

Array of objects (Payment Provider)

The Payment Providers that can be used to process Payments in the Region. Available if the relation payment_providers is expanded.

Array of objects (Fulfillment Provider)

The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation fulfillment_providers is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the prices for the region include tax

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.regions.deleteCountry(region_id, 'dk')
.then(({ region }) => {
  console.log(region.id);
});

Response samples

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

Del. Fulfillment Provider

Removes a Fulfillment Provider.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Region.

provider_id
required
string

The ID of the Fulfillment Provider.

Responses

Response Schema: application/json
object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

automatic_taxes
required
boolean
Default: true

Whether taxes should be automated in this region.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that the Region uses.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

gift_cards_taxable
required
boolean
Default: true

Whether the gift cards are taxable or not in this region.

id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "EU"

The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.

tax_code
required
string or null
Example: null

The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.

tax_provider_id
required
string or null
Example: null

The ID of the tax provider used in this region

tax_rate
required
number
Example: 0

The tax rate that should be charged on purchases in the Region.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Tax Rate)

The tax rates that are included in the Region. Available if the relation tax_rates is expanded.

Array of objects (Country)

The countries that are included in the Region. Available if the relation countries is expanded.

object (Tax Provider)

The tax service used to calculate taxes

Array of objects (Payment Provider)

The Payment Providers that can be used to process Payments in the Region. Available if the relation payment_providers is expanded.

Array of objects (Fulfillment Provider)

The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation fulfillment_providers is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the prices for the region include tax

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.regions.deleteFulfillmentProvider(region_id, 'manual')
.then(({ region }) => {
  console.log(region.id);
});

Response samples

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

Delete Payment Provider

Removes a Payment Provider.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Region.

provider_id
required
string

The ID of the Payment Provider.

Responses

Response Schema: application/json
object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

automatic_taxes
required
boolean
Default: true

Whether taxes should be automated in this region.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that the Region uses.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

gift_cards_taxable
required
boolean
Default: true

Whether the gift cards are taxable or not in this region.

id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "EU"

The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.

tax_code
required
string or null
Example: null

The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.

tax_provider_id
required
string or null
Example: null

The ID of the tax provider used in this region

tax_rate
required
number
Example: 0

The tax rate that should be charged on purchases in the Region.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Tax Rate)

The tax rates that are included in the Region. Available if the relation tax_rates is expanded.

Array of objects (Country)

The countries that are included in the Region. Available if the relation countries is expanded.

object (Tax Provider)

The tax service used to calculate taxes

Array of objects (Payment Provider)

The Payment Providers that can be used to process Payments in the Region. Available if the relation payment_providers is expanded.

Array of objects (Fulfillment Provider)

The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation fulfillment_providers is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the prices for the region include tax

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.regions.deletePaymentProvider(region_id, 'manual')
.then(({ region }) => {
  console.log(region.id);
});

Response samples

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

Reservation

Creates a Reservation

Creates a Reservation which can be associated with any resource as required.

Authorizations:
API TokenCookie Session ID
Request Body schema: application/json
required
object (Reservation item)

Represents a reservation of an inventory item at a stock location

id
required
string

The id of the reservation item

location_id
required
string

The id of the location of the reservation

inventory_item_id
required
string

The id of the inventory item the reservation relates to

quantity
required
number

The id of the reservation item

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

An optional key-value map with additional details

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.

Responses

Response Schema: application/json
required
object (Reservation item)

Represents a reservation of an inventory item at a stock location

id
required
string

The id of the reservation item

location_id
required
string

The id of the location of the reservation

inventory_item_id
required
string

The id of the inventory item the reservation relates to

quantity
required
number

The id of the reservation item

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

An optional key-value map with additional details

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.

Request samples

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

Response samples

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

Delete a Reservation

Deletes a Reservation.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Reservation to delete.

Responses

Response Schema: application/json
id
string

The ID of the deleted Reservation.

object
string
Default: "reservation"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the Reservation 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.reservations.delete(reservation.id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Reservation

Retrieves a single reservation using its id

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the reservation to retrieve.

Responses

Response Schema: application/json
required
object (Reservation item)

Represents a reservation of an inventory item at a stock location

id
required
string

The id of the reservation item

location_id
required
string

The id of the location of the reservation

inventory_item_id
required
string

The id of the inventory item the reservation relates to

quantity
required
number

The id of the reservation item

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

An optional key-value map with additional details

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.

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.reservations.retrieve(reservation_id)
.then(({ reservation }) => {
  console.log(reservation.id);
});

Response samples

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

Updates a Reservation

Updates a Reservation which can be associated with any resource as required.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Reservation to update.

Request Body schema: application/json
location_id
string

The id of the location of the reservation

quantity
number

The id of the reservation item

metadata
object

An optional set of key-value pairs with additional information.

Responses

Response Schema: application/json
required
object (Reservation item)

Represents a reservation of an inventory item at a stock location

id
required
string

The id of the reservation item

location_id
required
string

The id of the location of the reservation

inventory_item_id
required
string

The id of the inventory item the reservation relates to

quantity
required
number

The id of the reservation item

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

An optional key-value map with additional details

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.

Request samples

Content type
application/json
{
  • "location_id": "string",
  • "quantity": 0,
  • "metadata": { }
}

Response samples

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

Return

Return endpoints that allow handling returns in Medusa.

Request a Return

Requests a Return. If applicable a return label will be created and other plugins notified.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Request Body schema: application/json
required
Array of objects

The Line Items that will be returned.

object

The Shipping Method to be used to handle the return shipment.

note
string

An optional note with information about the Return.

receive_now
boolean
Default: false

A flag to indicate if the Return should be registerd as received immediately.

no_notification
boolean

A flag to indicate if no notifications should be emitted related to the requested Return.

refund
integer

The amount to refund.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "return_shipping": {
    },
  • "note": "string",
  • "receive_now": false,
  • "no_notification": true,
  • "refund": 0
}

Response samples

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

Cancel a Return

Registers a Return as canceled.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Return.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.returns.cancel(return_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

List Returns

Retrieves a list of Returns

Authorizations:
API TokenCookie Session ID
query Parameters
limit
number
Default: "50"

The upper limit for the amount of responses returned.

offset
number
Default: "0"

The offset of the list returned.

Responses

Response Schema: application/json
Array of objects (Return)
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.returns.list()
.then(({ returns, limit, offset, count }) => {
  console.log(returns.length);
});

Response samples

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

Receive a Return

Registers a Return as received. Updates statuses on Orders and Swaps accordingly.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Return.

Request Body schema: application/json
required
Array of objects

The Line Items that have been received.

refund
number

The amount to refund.

Responses

Response Schema: application/json
object (Return)

Return orders hold information about Line Items that a Customer wishes to send back, along with how the items will be returned. Returns can be used as part of a Swap.

claim_order_id
required
string or null
Example: null

The ID of the Claim that the Return is a part of.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

id
required
string
Example: "ret_01F0YET7XPCMF8RZ0Y151NZV2V"

The return's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of the return in case of failure.

location_id
required
string or null
Example: "sloc_01G8TJSYT9M6AVS5N4EMNFS1EK"

The id of the stock location the return will be added back.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

When set to true, no notification will be sent related to this return.

order_id
required
string or null
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the Order that the Return is made from.

received_at
required
string or null <date-time>

The date with timezone at which the return was received.

refund_amount
required
integer
Example: 1000

The amount that should be refunded as a result of the return.

shipping_data
required
object or null
Example: {}

Data about the return shipment as provided by the Fulfilment Provider that handles the return shipment.

status
required
string
Default: "requested"
Enum: "requested" "received" "requires_action" "canceled"

Status of the Return.

swap_id
required
string or null
Example: null

The ID of the Swap that the Return is a part of.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Array of objects (Return Item)

The Return Items that will be shipped back to the warehouse. Available if the relation items is expanded.

swap
object or null

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

claim_order
object or null

A claim order object. Available if the relation claim_order is expanded.

order
object or null

An order object. Available if the relation order is expanded.

object (Shipping Method)

Shipping Methods represent a way in which an Order or Return can be shipped. Shipping Methods are built from a Shipping Option, but may contain additional details, that can be necessary for the Fulfillment Provider to handle the shipment.

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "refund": 0
}

Response samples

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

Return Reason

Return Reason endpoints that allow handling return reasons in Medusa.

Create a Return Reason

Creates a Return Reason

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

The label to display to the Customer.

value
required
string

The value that the Return Reason will be identified by. Must be unique.

parent_return_reason_id
string

The ID of the parent return reason.

description
string

An optional description to for the Reason.

metadata
object

An optional set of key-value pairs with additional information.

Responses

Response Schema: application/json
object (Return Reason)

A Reason for why a given product is returned. A Return Reason can be used on Return Items in order to indicate why a Line Item was returned.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Items that are damaged"

A description of the Reason.

id
required
string
Example: "rr_01G8X82GCCV2KSQHDBHSSAH5TQ"

The return reason's ID

label
required
string
Example: "Damaged goods"

A text that can be displayed to the Customer as a reason.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_return_reason_id
required
string or null
Example: null

The ID of the parent reason.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

value
required
string
Example: "damaged"

The value to identify the reason by.

parent_return_reason
object or null

Available if the relation parent_return_reason is expanded.

return_reason_children
object

Available if the relation return_reason_children is expanded.

Request samples

Content type
application/json
{
  • "label": "string",
  • "value": "string",
  • "parent_return_reason_id": "string",
  • "description": "string",
  • "metadata": { }
}

Response samples

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

List Return Reasons

Retrieves a list of Return Reasons.

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
Array of objects (Return Reason)
Array
created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Items that are damaged"

A description of the Reason.

id
required
string
Example: "rr_01G8X82GCCV2KSQHDBHSSAH5TQ"

The return reason's ID

label
required
string
Example: "Damaged goods"

A text that can be displayed to the Customer as a reason.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_return_reason_id
required
string or null
Example: null

The ID of the parent reason.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

value
required
string
Example: "damaged"

The value to identify the reason by.

parent_return_reason
object or null

Available if the relation parent_return_reason is expanded.

return_reason_children
object

Available if the relation return_reason_children is expanded.

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.returnReasons.list()
.then(({ return_reasons }) => {
  console.log(return_reasons.length);
});

Response samples

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

Delete a Return Reason

Deletes a return reason.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the return reason

Responses

Response Schema: application/json
id
string

The ID of the deleted return reason

object
string
Default: "return_reason"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were 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.returnReasons.delete(return_reason_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Return Reason

Retrieves a Return Reason.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Return Reason.

Responses

Response Schema: application/json
object (Return Reason)

A Reason for why a given product is returned. A Return Reason can be used on Return Items in order to indicate why a Line Item was returned.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Items that are damaged"

A description of the Reason.

id
required
string
Example: "rr_01G8X82GCCV2KSQHDBHSSAH5TQ"

The return reason's ID

label
required
string
Example: "Damaged goods"

A text that can be displayed to the Customer as a reason.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_return_reason_id
required
string or null
Example: null

The ID of the parent reason.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

value
required
string
Example: "damaged"

The value to identify the reason by.

parent_return_reason
object or null

Available if the relation parent_return_reason is expanded.

return_reason_children
object

Available if the relation return_reason_children is expanded.

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.returnReasons.retrieve(return_reason_id)
.then(({ return_reason }) => {
  console.log(return_reason.id);
});

Response samples

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

Update a Return Reason

Updates a Return Reason

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Return Reason.

Request Body schema: application/json
label
string

The label to display to the Customer.

value
string

The value that the Return Reason will be identified by. Must be unique.

description
string

An optional description to for the Reason.

metadata
object

An optional set of key-value pairs with additional information.

Responses

Response Schema: application/json
object (Return Reason)

A Reason for why a given product is returned. A Return Reason can be used on Return Items in order to indicate why a Line Item was returned.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Items that are damaged"

A description of the Reason.

id
required
string
Example: "rr_01G8X82GCCV2KSQHDBHSSAH5TQ"

The return reason's ID

label
required
string
Example: "Damaged goods"

A text that can be displayed to the Customer as a reason.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_return_reason_id
required
string or null
Example: null

The ID of the parent reason.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

value
required
string
Example: "damaged"

The value to identify the reason by.

parent_return_reason
object or null

Available if the relation parent_return_reason is expanded.

return_reason_children
object

Available if the relation return_reason_children is expanded.

Request samples

Content type
application/json
{
  • "label": "string",
  • "value": "string",
  • "description": "string",
  • "metadata": { }
}

Response samples

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

Sales Channel

Sales Channel endpoints that allow handling sales channels in Medusa.

Add Products

Assign a batch of product to a sales channel.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Sales channel.

Request Body schema: application/json
required
Array of objects

The IDs of the products to add to the Sales Channel

Array
id
required
string

The ID of the product

Responses

Response Schema: application/json
object (Sales Channel)

A Sales Channel

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Multi-vendor market"

The description of the sales channel.

id
required
string
Example: "sc_01G8X9A7ESKAJXG2H0E6F1MW7A"

The sales channel's ID

is_disabled
required
boolean
Default: false

Specify if the sales channel is enabled or disabled.

name
required
string
Example: "Market"

The name of the sales channel.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Array of objects (Sales Channel Stock Location)

The Stock Locations related to the sales channel. Available if the relation locations is expanded.

Request samples

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

Response samples

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

Delete Products

Remove a list of products from a sales channel.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Sales Channel

Request Body schema: application/json
required
Array of objects

The IDs of the products to delete from the Sales Channel.

Array
id
required
string

The ID of a product

Responses

Response Schema: application/json
object (Sales Channel)

A Sales Channel

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Multi-vendor market"

The description of the sales channel.

id
required
string
Example: "sc_01G8X9A7ESKAJXG2H0E6F1MW7A"

The sales channel's ID

is_disabled
required
boolean
Default: false

Specify if the sales channel is enabled or disabled.

name
required
string
Example: "Market"

The name of the sales channel.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Array of objects (Sales Channel Stock Location)

The Stock Locations related to the sales channel. Available if the relation locations is expanded.

Request samples

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

Response samples

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

Associate a stock location to a Sales Channel

Associates a stock location to a Sales Channel.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Sales Channel.

Request Body schema: application/json
location_id
required
string

The ID of the stock location

Responses

Response Schema: application/json
object (Sales Channel)

A Sales Channel

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Multi-vendor market"

The description of the sales channel.

id
required
string
Example: "sc_01G8X9A7ESKAJXG2H0E6F1MW7A"

The sales channel's ID

is_disabled
required
boolean
Default: false

Specify if the sales channel is enabled or disabled.

name
required
string
Example: "Market"

The name of the sales channel.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Array of objects (Sales Channel Stock Location)

The Stock Locations related to the sales channel. Available if the relation locations is expanded.

Request samples

Content type
application/json
{
  • "location_id": "string"
}

Response samples

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

Remove a stock location from a Sales Channel

Removes a stock location from a Sales Channel.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Sales Channel.

Request Body schema: application/json
location_id
required
string

The ID of the stock location

Responses

Response Schema: application/json
id
string

The ID of the removed stock location from a sales channel

object
string
Default: "stock-location"

The type of the object that was removed.

deleted
boolean
Default: true

Whether or not the items were deleted.

Request samples

Content type
application/json
{
  • "location_id": "string"
}

Response samples

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

Create a Sales Channel

Creates a Sales Channel.

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

The name of the Sales Channel

description
string

The description of the Sales Channel

is_disabled
boolean

Whether the Sales Channel is disabled or not.

Responses

Response Schema: application/json
object (Sales Channel)

A Sales Channel

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Multi-vendor market"

The description of the sales channel.

id
required
string
Example: "sc_01G8X9A7ESKAJXG2H0E6F1MW7A"

The sales channel's ID

is_disabled
required
boolean
Default: false

Specify if the sales channel is enabled or disabled.

name
required
string
Example: "Market"

The name of the sales channel.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Array of objects (Sales Channel Stock Location)

The Stock Locations related to the sales channel. Available if the relation locations is expanded.

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "is_disabled": true
}

Response samples

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

List Sales Channels

Retrieves a list of sales channels

Authorizations:
API TokenCookie Session ID
query Parameters
id
string

ID of the sales channel

name
string

Name of the sales channel

description
string

Description of the sales channel

q
string

Query used for searching sales channels' names and descriptions.

order
string

The field to order the results by.

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.

offset
integer
Default: 0

How many sales channels to skip in the result.

limit
integer
Default: 20

Limit the number of sales channels returned.

expand
string

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

fields
string

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

Responses

Response Schema: application/json
Array of objects (Sales Channel)
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.salesChannels.list()
.then(({ sales_channels, limit, offset, count }) => {
  console.log(sales_channels.length);
});

Response samples

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

Delete a Sales Channel

Deletes the sales channel.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Sales channel.

Responses

Response Schema: application/json
id
string

The ID of the deleted sales channel

object
string
Default: "sales-channel"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were 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.salesChannels.delete(sales_channel_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Sales Channel

Retrieves the sales channel.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Sales channel.

Responses

Response Schema: application/json
object (Sales Channel)

A Sales Channel

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Multi-vendor market"

The description of the sales channel.

id
required
string
Example: "sc_01G8X9A7ESKAJXG2H0E6F1MW7A"

The sales channel's ID

is_disabled
required
boolean
Default: false

Specify if the sales channel is enabled or disabled.

name
required
string
Example: "Market"

The name of the sales channel.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Array of objects (Sales Channel Stock Location)

The Stock Locations related to the sales channel. Available if the relation locations is expanded.

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.salesChannels.retrieve(sales_channel_id)
.then(({ sales_channel }) => {
  console.log(sales_channel.id);
});

Response samples

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

Update a Sales Channel

Updates a Sales Channel.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Sales Channel.

Request Body schema: application/json
name
string

Name of the sales channel.

description
string

Sales Channel description.

is_disabled
boolean

Indication of if the sales channel is active.

Responses

Response Schema: application/json
object (Sales Channel)

A Sales Channel

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

description
required
string or null
Example: "Multi-vendor market"

The description of the sales channel.

id
required
string
Example: "sc_01G8X9A7ESKAJXG2H0E6F1MW7A"

The sales channel's ID

is_disabled
required
boolean
Default: false

Specify if the sales channel is enabled or disabled.

name
required
string
Example: "Market"

The name of the sales channel.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Array of objects (Sales Channel Stock Location)

The Stock Locations related to the sales channel. Available if the relation locations is expanded.

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "is_disabled": true
}

Response samples

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

List Stock Locations

Retrieves a list of stock locations

Authorizations:
API TokenCookie Session ID
query Parameters
id
string

ID of the stock location

name
string

Name of the stock location

order
string

The field to order the results by.

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.

offset
integer
Default: 0

How many stock locations to skip in the result.

limit
integer
Default: 20

Limit the number of stock locations returned.

expand
string

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

fields
string

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

Responses

Response Schema: application/json
Array of objects (Stock Location)
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.stockLocations.list()
.then(({ stock_locations, limit, offset, count }) => {
  console.log(stock_locations.length);
});

Response samples

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

Shipping Option

Shipping Option endpoints that allow handling shipping options in Medusa.

Create Shipping Option

Creates a Shipping Option

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

The name of the Shipping Option

region_id
required
string

The ID of the Region in which the Shipping Option will be available.

provider_id
required
string

The ID of the Fulfillment Provider that handles the Shipping Option.

data
required
object

The data needed for the Fulfillment Provider to handle shipping with this Shipping Option.

price_type
required
string
Enum: "flat_rate" "calculated"

The type of the Shipping Option price.

profile_id
number

The ID of the Shipping Profile to add the Shipping Option to.

amount
integer

The amount to charge for the Shipping Option.

Array of objects

The requirements that must be satisfied for the Shipping Option to be available.

is_return
boolean
Default: false

Whether the Shipping Option defines a return shipment.

admin_only
boolean
Default: false

If true, the option can be used for draft orders

metadata
object

An optional set of key-value pairs with additional information.

includes_tax
boolean

[EXPERIMENTAL] Tax included in prices of shipping option

Responses

Response Schema: application/json
object (Shipping Option)

Shipping Options represent a way in which an Order or Return can be shipped. Shipping Options have an associated Fulfillment Provider that will be used when the fulfillment of an Order is initiated. Shipping Options themselves cannot be added to Carts, but serve as a template for Shipping Methods. This distinction makes it possible to customize individual Shipping Methods with additional information.

admin_only
required
boolean
Default: false

Flag to indicate if the Shipping Option usage is restricted to admin users.

amount
required
integer or null
Example: 200

The amount to charge for shipping when the Shipping Option price type is flat_rate.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

data
required
object
Example: {}

The data needed for the Fulfillment Provider to identify the Shipping Option.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "so_01G1G5V27GYX4QXNARRQCW1N8T"

The shipping option's ID

is_return
required
boolean
Default: false

Flag to indicate if the Shipping Option can be used for Return shipments.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "PostFake Standard"

The name given to the Shipping Option - this may be displayed to the Customer.

price_type
required
string
Enum: "flat_rate" "calculated"
Example: "flat_rate"

The type of pricing calculation that is used when creatin Shipping Methods from the Shipping Option. Can be flat_rate for fixed prices or calculated if the Fulfillment Provider can provide price calulations.

profile_id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The ID of the Shipping Profile that the shipping option belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.

provider_id
required
string
Example: "manual"

The id of the Fulfillment Provider, that will be used to process Fulfillments from the Shipping Option.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

region
object or null

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

object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

object (Fulfillment Provider)

Represents a fulfillment provider plugin and holds its installation status.

Array of objects (Shipping Option Requirement)

The requirements that must be satisfied for the Shipping Option to be available for a Cart. Available if the relation requirements is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the shipping option price include tax

Request samples

Content type
application/json
{
  • "name": "string",
  • "region_id": "string",
  • "provider_id": "string",
  • "profile_id": 0,
  • "data": { },
  • "price_type": "flat_rate",
  • "amount": 0,
  • "requirements": [
    ],
  • "is_return": false,
  • "admin_only": false,
  • "metadata": { },
  • "includes_tax": true
}

Response samples

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

List Shipping Options

Retrieves a list of Shipping Options.

Authorizations:
API TokenCookie Session ID
query Parameters
region_id
string

Region ID to fetch options from

is_return
boolean

Flag for fetching return options only

admin_only
boolean

Flag for fetching admin specific options

Responses

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

The total number of items available

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.shippingOptions.list()
.then(({ shipping_options, count }) => {
  console.log(shipping_options.length);
});

Response samples

Content type
application/json
{
  • "shipping_options": [
    ],
  • "count": 0
}

Delete a Shipping Option

Deletes a Shipping Option.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Shipping Option.

Responses

Response Schema: application/json
id
string

The ID of the deleted Shipping Option.

object
string
Default: "shipping-option"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were 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.shippingOptions.delete(option_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Shipping Option

Retrieves a Shipping Option.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Shipping Option.

Responses

Response Schema: application/json
object (Shipping Option)

Shipping Options represent a way in which an Order or Return can be shipped. Shipping Options have an associated Fulfillment Provider that will be used when the fulfillment of an Order is initiated. Shipping Options themselves cannot be added to Carts, but serve as a template for Shipping Methods. This distinction makes it possible to customize individual Shipping Methods with additional information.

admin_only
required
boolean
Default: false

Flag to indicate if the Shipping Option usage is restricted to admin users.

amount
required
integer or null
Example: 200

The amount to charge for shipping when the Shipping Option price type is flat_rate.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

data
required
object
Example: {}

The data needed for the Fulfillment Provider to identify the Shipping Option.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "so_01G1G5V27GYX4QXNARRQCW1N8T"

The shipping option's ID

is_return
required
boolean
Default: false

Flag to indicate if the Shipping Option can be used for Return shipments.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "PostFake Standard"

The name given to the Shipping Option - this may be displayed to the Customer.

price_type
required
string
Enum: "flat_rate" "calculated"
Example: "flat_rate"

The type of pricing calculation that is used when creatin Shipping Methods from the Shipping Option. Can be flat_rate for fixed prices or calculated if the Fulfillment Provider can provide price calulations.

profile_id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The ID of the Shipping Profile that the shipping option belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.

provider_id
required
string
Example: "manual"

The id of the Fulfillment Provider, that will be used to process Fulfillments from the Shipping Option.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

region
object or null

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

object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

object (Fulfillment Provider)

Represents a fulfillment provider plugin and holds its installation status.

Array of objects (Shipping Option Requirement)

The requirements that must be satisfied for the Shipping Option to be available for a Cart. Available if the relation requirements is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the shipping option price include tax

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.shippingOptions.retrieve(option_id)
.then(({ shipping_option }) => {
  console.log(shipping_option.id);
});

Response samples

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

Update Shipping Option

Updates a Shipping Option

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Shipping Option.

Request Body schema: application/json
required
Array of objects

The requirements that must be satisfied for the Shipping Option to be available.

name
string

The name of the Shipping Option

amount
integer

The amount to charge for the Shipping Option.

admin_only
boolean

If true, the option can be used for draft orders

metadata
object

An optional set of key-value pairs with additional information.

includes_tax
boolean

[EXPERIMENTAL] Tax included in prices of shipping option

Responses

Response Schema: application/json
object (Shipping Option)

Shipping Options represent a way in which an Order or Return can be shipped. Shipping Options have an associated Fulfillment Provider that will be used when the fulfillment of an Order is initiated. Shipping Options themselves cannot be added to Carts, but serve as a template for Shipping Methods. This distinction makes it possible to customize individual Shipping Methods with additional information.

admin_only
required
boolean
Default: false

Flag to indicate if the Shipping Option usage is restricted to admin users.

amount
required
integer or null
Example: 200

The amount to charge for shipping when the Shipping Option price type is flat_rate.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

data
required
object
Example: {}

The data needed for the Fulfillment Provider to identify the Shipping Option.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "so_01G1G5V27GYX4QXNARRQCW1N8T"

The shipping option's ID

is_return
required
boolean
Default: false

Flag to indicate if the Shipping Option can be used for Return shipments.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "PostFake Standard"

The name given to the Shipping Option - this may be displayed to the Customer.

price_type
required
string
Enum: "flat_rate" "calculated"
Example: "flat_rate"

The type of pricing calculation that is used when creatin Shipping Methods from the Shipping Option. Can be flat_rate for fixed prices or calculated if the Fulfillment Provider can provide price calulations.

profile_id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The ID of the Shipping Profile that the shipping option belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.

provider_id
required
string
Example: "manual"

The id of the Fulfillment Provider, that will be used to process Fulfillments from the Shipping Option.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

region
object or null

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

object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

object (Fulfillment Provider)

Represents a fulfillment provider plugin and holds its installation status.

Array of objects (Shipping Option Requirement)

The requirements that must be satisfied for the Shipping Option to be available for a Cart. Available if the relation requirements is expanded.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the shipping option price include tax

Request samples

Content type
application/json
{
  • "name": "string",
  • "amount": 0,
  • "admin_only": true,
  • "metadata": { },
  • "requirements": [
    ],
  • "includes_tax": true
}

Response samples

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

Shipping Profile

Shipping Profile endpoints that allow handling shipping profiles in Medusa.

Create a Shipping Profile

Creates a Shipping Profile

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

The name of the Shipping Profile

type
required
string
Enum: "default" "gift_card" "custom"

The type of the Shipping Profile

Responses

Response Schema: application/json
object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The shipping profile's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Default Shipping Profile"

The name given to the Shipping profile - this may be displayed to the Customer.

type
required
string
Enum: "default" "gift_card" "custom"
Example: "default"

The type of the Shipping Profile, may be default, gift_card or custom.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

products
Array of objects

The Products that the Shipping Profile defines Shipping Options for. Available if the relation products is expanded.

shipping_options
Array of objects

The Shipping Options that can be used to fulfill the Products in the Shipping Profile. Available if the relation shipping_options is expanded.

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "default"
}

Response samples

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

List Shipping Profiles

Retrieves a list of Shipping Profile.

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
Array of objects (Shipping Profile)
Array
created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The shipping profile's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Default Shipping Profile"

The name given to the Shipping profile - this may be displayed to the Customer.

type
required
string
Enum: "default" "gift_card" "custom"
Example: "default"

The type of the Shipping Profile, may be default, gift_card or custom.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

products
Array of objects

The Products that the Shipping Profile defines Shipping Options for. Available if the relation products is expanded.

shipping_options
Array of objects

The Shipping Options that can be used to fulfill the Products in the Shipping Profile. Available if the relation shipping_options is expanded.

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.shippingProfiles.list()
.then(({ shipping_profiles }) => {
  console.log(shipping_profiles.length);
});

Response samples

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

Delete a Shipping Profile

Deletes a Shipping Profile.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Shipping Profile.

Responses

Response Schema: application/json
id
string

The ID of the deleted Shipping Profile.

object
string
Default: "shipping_profile"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were 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.shippingProfiles.delete(profile_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Shipping Profile

Retrieves a Shipping Profile.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Shipping Profile.

Responses

Response Schema: application/json
object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The shipping profile's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Default Shipping Profile"

The name given to the Shipping profile - this may be displayed to the Customer.

type
required
string
Enum: "default" "gift_card" "custom"
Example: "default"

The type of the Shipping Profile, may be default, gift_card or custom.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

products
Array of objects

The Products that the Shipping Profile defines Shipping Options for. Available if the relation products is expanded.

shipping_options
Array of objects

The Shipping Options that can be used to fulfill the Products in the Shipping Profile. Available if the relation shipping_options is expanded.

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.shippingProfiles.retrieve(profile_id)
.then(({ shipping_profile }) => {
  console.log(shipping_profile.id);
});

Response samples

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

Update a Shipping Profile

Updates a Shipping Profile

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Shipping Profile.

Request Body schema: application/json
name
string

The name of the Shipping Profile

metadata
object

An optional set of key-value pairs with additional information.

type
string
Enum: "default" "gift_card" "custom"

The type of the Shipping Profile

products
Array of arrays

An optional array of product ids to associate with the Shipping Profile

shipping_options
Array of arrays

An optional array of shipping option ids to associate with the Shipping Profile

Responses

Response Schema: application/json
object (Shipping Profile)

Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "sp_01G1G5V239ENSZ5MV4JAR737BM"

The shipping profile's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Default Shipping Profile"

The name given to the Shipping profile - this may be displayed to the Customer.

type
required
string
Enum: "default" "gift_card" "custom"
Example: "default"

The type of the Shipping Profile, may be default, gift_card or custom.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

products
Array of objects

The Products that the Shipping Profile defines Shipping Options for. Available if the relation products is expanded.

shipping_options
Array of objects

The Shipping Options that can be used to fulfill the Products in the Shipping Profile. Available if the relation shipping_options is expanded.

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": { },
  • "type": "default",
  • "products": [ ],
  • "shipping_options": [ ]
}

Response samples

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

Stock Location

Create a Stock Location

Creates a Stock Location.

Authorizations:
API TokenCookie Session ID
query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Request Body schema: application/json
name
required
string

the name of the stock location

address_id
string

the stock location address ID

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

An optional key-value map with additional details

object (Stock Location Address Input)

Represents a Stock Location Address Input

Responses

Response Schema: application/json
object (Stock Location)

Represents a Stock Location

id
required
string
Example: "sloc_51G4ZW853Y6TFXWPG5ENJ81X42"

The stock location's ID

name
required
string
Example: "Main Warehouse"

The name of the stock location

address_id
required
string
Example: "laddr_05B2ZE853Y6FTXWPW85NJ81A44"

Stock location address' ID

created_at
required
string <date-time>

The date with timezone at which the resource was created.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Stock Location Address)

The Address of the Stock Location

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

An optional key-value map with additional details

deleted_at
string <date-time>

The date with timezone at which the resource was deleted.

Request samples

Content type
application/json
{
  • "name": "string",
  • "address_id": "string",
  • "metadata": {
    },
  • "address": {
    }
}

Response samples

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

Get a Stock Location

Retrieves the Stock Location.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Stock Location.

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Responses

Response Schema: application/json
object (Stock Location)

Represents a Stock Location

id
required
string
Example: "sloc_51G4ZW853Y6TFXWPG5ENJ81X42"

The stock location's ID

name
required
string
Example: "Main Warehouse"

The name of the stock location

address_id
required
string
Example: "laddr_05B2ZE853Y6FTXWPW85NJ81A44"

Stock location address' ID

created_at
required
string <date-time>

The date with timezone at which the resource was created.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Stock Location Address)

The Address of the Stock Location

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

An optional key-value map with additional details

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.stockLocations.retrieve(stock_location_id)
.then(({ stock_location }) => {
  console.log(stock_location.id);
});

Response samples

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

Update a Stock Location

Updates a Stock Location.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Stock Location.

query Parameters
expand
string

Comma separated list of relations to include in the results.

fields
string

Comma separated list of fields to include in the results.

Request Body schema: application/json
name
string

the name of the stock location

address_id
string

the stock location address ID

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

An optional key-value map with additional details

object (Stock Location Address Input)

Represents a Stock Location Address Input

Responses

Response Schema: application/json
object (Stock Location)

Represents a Stock Location

id
required
string
Example: "sloc_51G4ZW853Y6TFXWPG5ENJ81X42"

The stock location's ID

name
required
string
Example: "Main Warehouse"

The name of the stock location

address_id
required
string
Example: "laddr_05B2ZE853Y6FTXWPW85NJ81A44"

Stock location address' ID

created_at
required
string <date-time>

The date with timezone at which the resource was created.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Stock Location Address)

The Address of the Stock Location

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

An optional key-value map with additional details

deleted_at
string <date-time>

The date with timezone at which the resource was deleted.

Request samples

Content type
application/json
{
  • "name": "string",
  • "address_id": "string",
  • "metadata": {
    },
  • "address": {
    }
}

Response samples

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

StockLocation

Delete a Stock Location

Delete a Stock Location

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Stock Location to delete.

Responses

Response Schema: application/json
id
string

The ID of the deleted Stock Location.

object
string <stock_location>

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the Stock Location 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.stockLocations.delete(stock_location_id)
  .then(({ id, object, deleted }) => {
    console.log(id)
  })

Response samples

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

Store

Store endpoints that allow handling stores in Medusa.

Add a Currency Code

Adds a Currency Code to the available currencies.

Authorizations:
API TokenCookie Session ID
path Parameters
code
required
string

The 3 character ISO currency code.

Responses

Response Schema: application/json
object (Store)

Holds settings for the Store, such as name, currencies, etc.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

default_currency_code
required
string
Example: "usd"

The 3 character currency code that is the default of the store.

default_location_id
required
string or null
Example: null

The location ID the store is associated with.

id
required
string
Example: "store_01G1G5V21KADXNGH29BJMAJ4B4"

The store's ID

invite_link_template
required
string or null
Example: null

A template to generate Invite links from

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Medusa Store"

The name of the Store - this may be displayed to the Customer.

payment_link_template
required
string or null
Example: null

A template to generate Payment links from. Use {{cart_id}} to include the payment's cart_id in the link.

swap_link_template
required
string or null
Example: null

A template to generate Swap links from. Use {{cart_id}} to include the Swap's cart_id in the link.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Currency)

The currencies that are enabled for the Store. Available if the relation currencies is expanded.

default_sales_channel_id
string or null
Example: null

The sales channel ID the cart is associated with.

object (Sales Channel)

A Sales Channel

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.store.addCurrency('eur')
.then(({ store }) => {
  console.log(store.id);
});

Response samples

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

Delete a Currency Code

Removes a Currency Code from the available currencies.

Authorizations:
API TokenCookie Session ID
path Parameters
code
required
string

The 3 character ISO currency code.

Responses

Response Schema: application/json
object (Store)

Holds settings for the Store, such as name, currencies, etc.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

default_currency_code
required
string
Example: "usd"

The 3 character currency code that is the default of the store.

default_location_id
required
string or null
Example: null

The location ID the store is associated with.

id
required
string
Example: "store_01G1G5V21KADXNGH29BJMAJ4B4"

The store's ID

invite_link_template
required
string or null
Example: null

A template to generate Invite links from

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Medusa Store"

The name of the Store - this may be displayed to the Customer.

payment_link_template
required
string or null
Example: null

A template to generate Payment links from. Use {{cart_id}} to include the payment's cart_id in the link.

swap_link_template
required
string or null
Example: null

A template to generate Swap links from. Use {{cart_id}} to include the Swap's cart_id in the link.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Currency)

The currencies that are enabled for the Store. Available if the relation currencies is expanded.

default_sales_channel_id
string or null
Example: null

The sales channel ID the cart is associated with.

object (Sales Channel)

A Sales Channel

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.store.deleteCurrency('eur')
.then(({ store }) => {
  console.log(store.id);
});

Response samples

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

Get Store details

Retrieves the Store details

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
object (Store)

Holds settings for the Store, such as name, currencies, etc.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

default_currency_code
required
string
Example: "usd"

The 3 character currency code that is the default of the store.

default_location_id
required
string or null
Example: null

The location ID the store is associated with.

id
required
string
Example: "store_01G1G5V21KADXNGH29BJMAJ4B4"

The store's ID

invite_link_template
required
string or null
Example: null

A template to generate Invite links from

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Medusa Store"

The name of the Store - this may be displayed to the Customer.

payment_link_template
required
string or null
Example: null

A template to generate Payment links from. Use {{cart_id}} to include the payment's cart_id in the link.

swap_link_template
required
string or null
Example: null

A template to generate Swap links from. Use {{cart_id}} to include the Swap's cart_id in the link.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Currency)

The currencies that are enabled for the Store. Available if the relation currencies is expanded.

default_sales_channel_id
string or null
Example: null

The sales channel ID the cart is associated with.

object (Sales Channel)

A Sales Channel

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.store.retrieve()
.then(({ store }) => {
  console.log(store.id);
});

Response samples

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

Update Store Details

Updates the Store details

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

The name of the Store

swap_link_template
string

A template for Swap links - use {{cart_id}} to insert the Swap Cart id

payment_link_template
string

A template for payment links links - use {{cart_id}} to insert the Cart id

invite_link_template
string

A template for invite links - use {{invite_token}} to insert the invite token

default_currency_code
string

The default currency code for the Store.

currencies
Array of strings

Array of currencies in 2 character ISO code format.

metadata
object

An optional set of key-value pairs with additional information.

Responses

Response Schema: application/json
object (Store)

Holds settings for the Store, such as name, currencies, etc.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

default_currency_code
required
string
Example: "usd"

The 3 character currency code that is the default of the store.

default_location_id
required
string or null
Example: null

The location ID the store is associated with.

id
required
string
Example: "store_01G1G5V21KADXNGH29BJMAJ4B4"

The store's ID

invite_link_template
required
string or null
Example: null

A template to generate Invite links from

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Medusa Store"

The name of the Store - this may be displayed to the Customer.

payment_link_template
required
string or null
Example: null

A template to generate Payment links from. Use {{cart_id}} to include the payment's cart_id in the link.

swap_link_template
required
string or null
Example: null

A template to generate Swap links from. Use {{cart_id}} to include the Swap's cart_id in the link.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Currency)

Currency

Array of objects (Currency)

The currencies that are enabled for the Store. Available if the relation currencies is expanded.

default_sales_channel_id
string or null
Example: null

The sales channel ID the cart is associated with.

object (Sales Channel)

A Sales Channel

Request samples

Content type
application/json
{
  • "name": "string",
  • "swap_link_template": "string",
  • "payment_link_template": "string",
  • "invite_link_template": "string",
  • "default_currency_code": "string",
  • "currencies": [
    ],
  • "metadata": { }
}

Response samples

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

List Payment Providers

Retrieves the configured Payment Providers

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
Array of objects (Payment Provider)
Array
id
required
string
Example: "manual"

The id of the payment provider as given by the plugin.

is_installed
required
boolean
Default: true

Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to false.

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.store.listPaymentProviders()
.then(({ payment_providers }) => {
  console.log(payment_providers.length);
});

Response samples

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

List Tax Providers

Retrieves the configured Tax Providers

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
Array of objects (Tax Provider)
Array
id
required
string
Example: "manual"

The id of the tax provider as given by the plugin.

is_installed
required
boolean
Default: true

Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to false.

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.store.listTaxProviders()
.then(({ tax_providers }) => {
  console.log(tax_providers.length);
});

Response samples

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

Swap

Swap endpoints that allow handling swaps in Medusa.

Cancels a Swap

Cancels a Swap

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

swap_id
required
string

The ID of the Swap.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.cancelSwap(order_id, swap_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Create Swap Shipment

Registers a Swap Fulfillment as shipped.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

swap_id
required
string

The ID of the Swap.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

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.

no_notification
boolean

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

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

Request samples

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

Response samples

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

Create a Swap

Creates a Swap. Swaps are used to handle Return of previously purchased goods and Fulfillment of replacements simultaneously.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

query Parameters
expand
string

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

fields
string

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

Request Body schema: application/json
required
Array of objects

The Line Items to return as part of the Swap.

object

How the Swap will be returned.

Array of objects

The new items to send to the Customer.

Array of objects

The custom shipping options to potentially create a Shipping Method from.

no_notification
boolean

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

allow_backorder
boolean
Default: true

If true, swaps can be completed with items out of stock

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

Request samples

Content type
application/json
{
  • "return_items": [
    ],
  • "return_shipping": {
    },
  • "additional_items": [
    ],
  • "custom_shipping_options": [
    ],
  • "no_notification": true,
  • "allow_backorder": true
}

Response samples

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

Process Swap Payment

When there are differences between the returned and shipped Products in a Swap, the difference must be processed. Either a Refund will be issued or a Payment will be captured.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Order.

swap_id
required
string

The ID of the Swap.

query Parameters
expand
string

Comma separated list of relations to include in the result.

fields
string

Comma separated list of fields to include in the result.

Responses

Response Schema: application/json
object (Order)

Represents an order

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the billing address associated with the order

canceled_at
required
string or null <date-time>

The date the order was canceled on.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The ID of the cart associated with the order

created_at
required
string <date-time>

The date with timezone at which the resource was created.

currency_code
required
string
Example: "usd"

The 3 character currency code that is used in the order

customer_id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The ID of the customer associated with the order

draft_order_id
required
string or null
Example: null

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

display_id
required
integer
Example: 2

The order's display ID

email
required
string <email>

The email associated with the order

external_id
required
string or null
Example: null

The ID of an external order.

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

The order's fulfillment status

id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The order's ID

idempotency_key
required
string or null

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

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

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

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

The order's payment status

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The ID of the shipping address associated with the order

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

The order's status

tax_rate
required
number or null
Example: 0

The order's tax rate

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

cart
object or null

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

customer
object or null

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

object (Address)

An address.

object (Address)

An address.

object (Region)

Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.

object (Currency)

Currency

Array of objects (Discount)

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

Array of objects (Gift Card)

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.

payments
Array of objects

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

fulfillments
Array of objects

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
object or null

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.

edits
Array of objects

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.

sales_channel_id
string or null
Example: null

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

object (Sales Channel)

A Sales Channel

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

Array of objects (Line Item)

The items that are returnable as part of the order, order swaps or order claims

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.processSwapPayment(order_id, swap_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Get a Swap

Retrieves a Swap.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Swap.

Responses

Response Schema: application/json
object (Swap)

Swaps can be created when a Customer wishes to exchange Products that they have purchased to different Products. Swaps consist of a Return of previously purchased Products and a Fulfillment of new Products, the amount paid for the Products being returned will be used towards payment for the new Products. In the case where the amount paid for the the Products being returned exceed the amount to be paid for the new Products, a Refund will be issued for the difference.

allow_backorder
required
boolean
Default: false

If true, swaps can be completed with items out of stock

canceled_at
required
string or null <date-time>

The date with timezone at which the Swap was canceled.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The id of the Cart that the Customer will use to confirm the Swap.

confirmed_at
required
string or null <date-time>

The date with timezone at which the Swap was confirmed by the Customer.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

difference_due
required
integer or null
Example: 0

The difference that is paid or refunded as a result of the Swap. May be negative when the amount paid for the returned items exceed the total of the new Products.

fulfillment_status
required
string
Enum: "not_fulfilled" "fulfilled" "shipped" "partially_shipped" "canceled" "requires_action"
Example: "not_fulfilled"

The status of the Fulfillment of the Swap.

id
required
string
Example: "swap_01F0YET86Y9G92D3YDR9Y6V676"

The swap's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of the swap in case of failure.

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

no_notification
required
boolean or null
Example: false

If set to true, no notification will be sent related to this swap

order_id
required
string
Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK"

The ID of the Order where the Line Items to be returned where purchased.

payment_status
required
string
Enum: "not_paid" "awaiting" "captured" "confirmed" "canceled" "difference_refunded" "partially_refunded" "refunded" "requires_action"
Example: "not_paid"

The status of the Payment of the Swap. The payment may either refer to the refund of an amount or the authorization of a new amount.

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The Address to send the new Line Items to - in most cases this will be the same as the shipping address on the Order.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

order
object or null

An order object. Available if the relation order is expanded.

Array of objects (Line Item)

The new Line Items to ship to the Customer. Available if the relation additional_items is expanded.

return_order
object or null

A return order object. The Return that is issued for the return part of the Swap. Available if the relation return_order is expanded.

fulfillments
Array of objects

The Fulfillments used to send the new Line Items. Available if the relation fulfillments is expanded.

payment
object or null

The Payment authorized when the Swap requires an additional amount to be charged from the Customer. Available if the relation payment is expanded.

object (Address)

An address.

Array of objects (Shipping Method)

The Shipping Methods used to fulfill the additional items purchased. Available if the relation shipping_methods is expanded.

cart
object or null

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

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.swaps.retrieve(swap_id)
.then(({ swap }) => {
  console.log(swap.id);
});

Response samples

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

List Swaps

Retrieves a list of Swaps.

Authorizations:
API TokenCookie Session ID
query Parameters
limit
number
Default: "50"

The upper limit for the amount of responses returned.

offset
number
Default: "0"

The offset of the list returned.

Responses

Response Schema: application/json
Array of objects (Swap)
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.swaps.list()
.then(({ swaps }) => {
  console.log(swaps.length);
});

Response samples

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

Tax Rate

Tax Rate endpoints that allow handling tax rates in Medusa.

Add to Product Types

Associates a Tax Rate with a list of Product Types

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

ID of the tax rate.

query Parameters
fields
Array of strings

Which fields should be included in the result.

expand
Array of strings

Which fields should be expanded and retrieved in the result.

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

The IDs of the types of products to associate with this tax rate

Responses

Response Schema: application/json
object (Tax Rate)

A Tax Rate can be used to associate a certain rate to charge on products within a given Region

code
required
string or null
Example: "tax01"

A code to identify the tax type by

created_at
required
string <date-time>

The date with timezone at which the resource was created.

id
required
string
Example: "txr_01G8XDBAWKBHHJRKH0AV02KXBR"

The tax rate's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Tax Example"

A human friendly name for the tax

rate
required
number or null
Example: 10

The numeric rate to charge

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The id of the Region that the rate belongs to

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

region
object or null

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

Array of objects (Product)

The products that belong to this tax rate. Available if the relation products is expanded.

Array of objects (Product Type)

The product types that belong to this tax rate. Available if the relation product_types is expanded.

Array of objects (Shipping Option)

The shipping options that belong to this tax rate. Available if the relation shipping_options is expanded.

product_count
integer
Example: 10

The count of products

product_type_count
integer
Example: 2

The count of product types

shipping_option_count
integer
Example: 1

The count of shipping options

Request samples

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

Response samples

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

Delete from Product Types

Removes a Tax Rate from a list of Product Types

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

ID of the tax rate.

query Parameters
fields
Array of strings

Which fields should be included in the result.

expand
Array of strings

Which fields should be expanded and retrieved in the result.

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

The IDs of the types of products to remove association with this tax rate

Responses

Response Schema: application/json
object (Tax Rate)

A Tax Rate can be used to associate a certain rate to charge on products within a given Region

code
required
string or null
Example: "tax01"

A code to identify the tax type by

created_at
required
string <date-time>

The date with timezone at which the resource was created.

id
required
string
Example: "txr_01G8XDBAWKBHHJRKH0AV02KXBR"

The tax rate's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Tax Example"

A human friendly name for the tax

rate
required
number or null
Example: 10

The numeric rate to charge

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The id of the Region that the rate belongs to

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

region
object or null

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

Array of objects (Product)

The products that belong to this tax rate. Available if the relation products is expanded.

Array of objects (Product Type)

The product types that belong to this tax rate. Available if the relation product_types is expanded.

Array of objects (Shipping Option)

The shipping options that belong to this tax rate. Available if the relation shipping_options is expanded.

product_count
integer
Example: 10

The count of products

product_type_count
integer
Example: 2

The count of product types

shipping_option_count
integer
Example: 1

The count of shipping options

Request samples

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

Response samples

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

Add to Products

Associates a Tax Rate with a list of Products

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

ID of the tax rate.

query Parameters
fields
Array of strings

Which fields should be included in the result.

expand
Array of strings

Which fields should be expanded and retrieved in the result.

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

The IDs of the products to associate with this tax rate

Responses

Response Schema: application/json
object (Tax Rate)

A Tax Rate can be used to associate a certain rate to charge on products within a given Region

code
required
string or null
Example: "tax01"

A code to identify the tax type by

created_at
required
string <date-time>

The date with timezone at which the resource was created.

id
required
string
Example: "txr_01G8XDBAWKBHHJRKH0AV02KXBR"

The tax rate's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Tax Example"

A human friendly name for the tax

rate
required
number or null
Example: 10

The numeric rate to charge

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The id of the Region that the rate belongs to

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

region
object or null

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

Array of objects (Product)

The products that belong to this tax rate. Available if the relation products is expanded.

Array of objects (Product Type)

The product types that belong to this tax rate. Available if the relation product_types is expanded.

Array of objects (Shipping Option)

The shipping options that belong to this tax rate. Available if the relation shipping_options is expanded.

product_count
integer
Example: 10

The count of products

product_type_count
integer
Example: 2

The count of product types

shipping_option_count
integer
Example: 1

The count of shipping options

Request samples

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

Response samples

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

Delete from Products

Removes a Tax Rate from a list of Products

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

ID of the tax rate.

query Parameters
fields
Array of strings

Which fields should be included in the result.

expand
Array of strings

Which fields should be expanded and retrieved in the result.

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

The IDs of the products to remove association with this tax rate

Responses

Response Schema: application/json
object (Tax Rate)

A Tax Rate can be used to associate a certain rate to charge on products within a given Region

code
required
string or null
Example: "tax01"

A code to identify the tax type by

created_at
required
string <date-time>

The date with timezone at which the resource was created.

id
required
string
Example: "txr_01G8XDBAWKBHHJRKH0AV02KXBR"

The tax rate's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Tax Example"

A human friendly name for the tax

rate
required
number or null
Example: 10

The numeric rate to charge

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The id of the Region that the rate belongs to

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

region
object or null

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

Array of objects (Product)

The products that belong to this tax rate. Available if the relation products is expanded.

Array of objects (Product Type)

The product types that belong to this tax rate. Available if the relation product_types is expanded.

Array of objects (Shipping Option)

The shipping options that belong to this tax rate. Available if the relation shipping_options is expanded.

product_count
integer
Example: 10

The count of products

product_type_count
integer
Example: 2

The count of product types

shipping_option_count
integer
Example: 1

The count of shipping options

Request samples

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

Response samples

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

Add to Shipping Options

Associates a Tax Rate with a list of Shipping Options

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

ID of the tax rate.

query Parameters
fields
Array of strings

Which fields should be included in the result.

expand
Array of strings

Which fields should be expanded and retrieved in the result.

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

The IDs of the shipping options to associate with this tax rate

Responses

Response Schema: application/json
object (Tax Rate)

A Tax Rate can be used to associate a certain rate to charge on products within a given Region

code
required
string or null
Example: "tax01"

A code to identify the tax type by

created_at
required
string <date-time>

The date with timezone at which the resource was created.

id
required
string
Example: "txr_01G8XDBAWKBHHJRKH0AV02KXBR"

The tax rate's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Tax Example"

A human friendly name for the tax

rate
required
number or null
Example: 10

The numeric rate to charge

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The id of the Region that the rate belongs to

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

region
object or null

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

Array of objects (Product)

The products that belong to this tax rate. Available if the relation products is expanded.

Array of objects (Product Type)

The product types that belong to this tax rate. Available if the relation product_types is expanded.

Array of objects (Shipping Option)

The shipping options that belong to this tax rate. Available if the relation shipping_options is expanded.

product_count
integer
Example: 10

The count of products

product_type_count
integer
Example: 2

The count of product types

shipping_option_count
integer
Example: 1

The count of shipping options

Request samples

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

Response samples

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

Del. for Shipping Options

Removes a Tax Rate from a list of Shipping Options

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

ID of the tax rate.

query Parameters
fields
Array of strings

Which fields should be included in the result.

expand
Array of strings

Which fields should be expanded and retrieved in the result.

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

The IDs of the shipping options to remove association with this tax rate

Responses

Response Schema: application/json
object (Tax Rate)

A Tax Rate can be used to associate a certain rate to charge on products within a given Region

code
required
string or null
Example: "tax01"

A code to identify the tax type by

created_at
required
string <date-time>

The date with timezone at which the resource was created.

id
required
string
Example: "txr_01G8XDBAWKBHHJRKH0AV02KXBR"

The tax rate's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Tax Example"

A human friendly name for the tax

rate
required
number or null
Example: 10

The numeric rate to charge

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The id of the Region that the rate belongs to

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

region
object or null

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

Array of objects (Product)

The products that belong to this tax rate. Available if the relation products is expanded.

Array of objects (Product Type)

The product types that belong to this tax rate. Available if the relation product_types is expanded.

Array of objects (Shipping Option)

The shipping options that belong to this tax rate. Available if the relation shipping_options is expanded.

product_count
integer
Example: 10

The count of products

product_type_count
integer
Example: 2

The count of product types

shipping_option_count
integer
Example: 1

The count of shipping options

Request samples

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

Response samples

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

Create a Tax Rate

Creates a Tax Rate

Authorizations:
API TokenCookie Session ID
query Parameters
fields
Array of strings

Which fields should be included in the result.

expand
Array of strings

Which fields should be expanded and retrieved in the result.

Request Body schema: application/json
code
required
string

A code to identify the tax type by

name
required
string

A human friendly name for the tax

region_id
required
string

The ID of the Region that the rate belongs to

rate
number

The numeric rate to charge

products
Array of strings

The IDs of the products associated with this tax rate

shipping_options
Array of strings

The IDs of the shipping options associated with this tax rate

product_types
Array of strings

The IDs of the types of products associated with this tax rate

Responses

Response Schema: application/json
object (Tax Rate)

A Tax Rate can be used to associate a certain rate to charge on products within a given Region

code
required
string or null
Example: "tax01"

A code to identify the tax type by

created_at
required
string <date-time>

The date with timezone at which the resource was created.

id
required
string
Example: "txr_01G8XDBAWKBHHJRKH0AV02KXBR"

The tax rate's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Tax Example"

A human friendly name for the tax

rate
required
number or null
Example: 10

The numeric rate to charge

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The id of the Region that the rate belongs to

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

region
object or null

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

Array of objects (Product)

The products that belong to this tax rate. Available if the relation products is expanded.

Array of objects (Product Type)

The product types that belong to this tax rate. Available if the relation product_types is expanded.

Array of objects (Shipping Option)

The shipping options that belong to this tax rate. Available if the relation shipping_options is expanded.

product_count
integer
Example: 10

The count of products

product_type_count
integer
Example: 2

The count of product types

shipping_option_count
integer
Example: 1

The count of shipping options

Request samples

Content type
application/json
{
  • "code": "string",
  • "name": "string",
  • "region_id": "string",
  • "rate": 0,
  • "products": [
    ],
  • "shipping_options": [
    ],
  • "product_types": [
    ]
}

Response samples

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

List Tax Rates

Retrieves a list of TaxRates

Authorizations:
API TokenCookie Session ID
query Parameters
name
string

Name of tax rate to retrieve

string or Array of strings

Filter by Region ID

code
string

code to search for.

number or object

Filter by Rate

offset
integer
Default: 0

How many tax rates to skip before retrieving the result.

limit
integer
Default: 50

Limit the number of tax rates returned.

fields
Array of strings

Which fields should be included in each item.

expand
Array of strings

Which fields should be expanded and retrieved for each item.

Responses

Response Schema: application/json
Array of objects (Tax Rate)
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.taxRates.list()
.then(({ tax_rates, limit, offset, count }) => {
  console.log(tax_rates.length);
});

Response samples

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

Delete a Tax Rate

Deletes a Tax Rate

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Shipping Option.

Responses

Response Schema: application/json
id
string

The ID of the deleted Shipping Option.

object
string
Default: "tax-rate"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were 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.taxRates.delete(tax_rate_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a Tax Rate

Retrieves a TaxRate

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

ID of the tax rate.

query Parameters
fields
Array of strings

Which fields should be included in the result.

expand
Array of strings

Which fields should be expanded and retrieved in the result.

Responses

Response Schema: application/json
object (Tax Rate)

A Tax Rate can be used to associate a certain rate to charge on products within a given Region

code
required
string or null
Example: "tax01"

A code to identify the tax type by

created_at
required
string <date-time>

The date with timezone at which the resource was created.

id
required
string
Example: "txr_01G8XDBAWKBHHJRKH0AV02KXBR"

The tax rate's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Tax Example"

A human friendly name for the tax

rate
required
number or null
Example: 10

The numeric rate to charge

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The id of the Region that the rate belongs to

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

region
object or null

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

Array of objects (Product)

The products that belong to this tax rate. Available if the relation products is expanded.

Array of objects (Product Type)

The product types that belong to this tax rate. Available if the relation product_types is expanded.

Array of objects (Shipping Option)

The shipping options that belong to this tax rate. Available if the relation shipping_options is expanded.

product_count
integer
Example: 10

The count of products

product_type_count
integer
Example: 2

The count of product types

shipping_option_count
integer
Example: 1

The count of shipping options

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.taxRates.retrieve(tax_rate_id)
.then(({ tax_rate }) => {
  console.log(tax_rate.id);
});

Response samples

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

Update a Tax Rate

Updates a Tax Rate

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

ID of the tax rate.

query Parameters
fields
Array of strings

Which fields should be included in the result.

expand
Array of strings

Which fields should be expanded and retrieved in the result.

Request Body schema: application/json
code
string

A code to identify the tax type by

name
string

A human friendly name for the tax

region_id
string

The ID of the Region that the rate belongs to

rate
number

The numeric rate to charge

products
Array of strings

The IDs of the products associated with this tax rate

shipping_options
Array of strings

The IDs of the shipping options associated with this tax rate

product_types
Array of strings

The IDs of the types of products associated with this tax rate

Responses

Response Schema: application/json
object (Tax Rate)

A Tax Rate can be used to associate a certain rate to charge on products within a given Region

code
required
string or null
Example: "tax01"

A code to identify the tax type by

created_at
required
string <date-time>

The date with timezone at which the resource was created.

id
required
string
Example: "txr_01G8XDBAWKBHHJRKH0AV02KXBR"

The tax rate's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "Tax Example"

A human friendly name for the tax

rate
required
number or null
Example: 10

The numeric rate to charge

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The id of the Region that the rate belongs to

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

region
object or null

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

Array of objects (Product)

The products that belong to this tax rate. Available if the relation products is expanded.

Array of objects (Product Type)

The product types that belong to this tax rate. Available if the relation product_types is expanded.

Array of objects (Shipping Option)

The shipping options that belong to this tax rate. Available if the relation shipping_options is expanded.

product_count
integer
Example: 10

The count of products

product_type_count
integer
Example: 2

The count of product types

shipping_option_count
integer
Example: 1

The count of shipping options

Request samples

Content type
application/json
{
  • "code": "string",
  • "name": "string",
  • "region_id": "string",
  • "rate": 0,
  • "products": [
    ],
  • "shipping_options": [
    ],
  • "product_types": [
    ]
}

Response samples

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

Upload

Upload endpoints that allow handling uploads in Medusa.

Protected File Upload

Uploads at least one file with ACL or a non-public bucket to the specific fileservice that is installed in Medusa.

Authorizations:
API TokenCookie Session ID
Request Body schema: multipart/form-data
files
string <binary>

Responses

Response Schema: application/json
Array of objects
Array
url
string <uri>

The URL of the uploaded file.

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.uploads.createProtected(file)
.then(({ uploads }) => {
  console.log(uploads.length);
});

Response samples

Content type
application/json
{}

Upload files

Uploads at least one file to the specific fileservice that is installed in Medusa.

Authorizations:
API TokenCookie Session ID
Request Body schema: multipart/form-data
files
string <binary>

Responses

Response Schema: application/json
Array of objects
Array
url
string <uri>

The URL of the uploaded file.

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.uploads.create(file)
.then(({ uploads }) => {
  console.log(uploads.length);
});

Response samples

Content type
application/json
{}

Delete an Uploaded File

Removes an uploaded file using the installed fileservice

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

key of the file to delete

Responses

Response Schema: application/json
id
string

The file key of the upload deleted

object
string
Default: "file"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were deleted.

Request samples

Content type
application/json
{
  • "file_key": "string"
}

Response samples

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

Get a File's Download URL

Creates a presigned download url for a file

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

key of the file to obtain the download link for

Responses

Response Schema: application/json
download_url
string

The Download URL of the file

Request samples

Content type
application/json
{
  • "file_key": "string"
}

Response samples

Content type
application/json
{
  • "download_url": "string"
}

User

User endpoints that allow handling users in Medusa.

Create a User

Creates a User

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

The Users email.

password
required
string <password>

The Users password.

first_name
string

The name of the User.

last_name
string

The name of the User.

role
string
Enum: "admin" "member" "developer"

Userrole assigned to the user.

Responses

Response Schema: application/json
object (User)

Represents a User who can manage store settings.

api_token
required
string or null
Example: null

An API token associated with the user.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The email of the User

first_name
required
string or null
Example: "Levi"

The first name of the User

id
required
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The user's ID

last_name
required
string or null
Example: "Bogan"

The last name of the User

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

role
required
string
Default: "member"
Enum: "admin" "member" "developer"

The user's role

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Request samples

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

Response samples

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

List Users

Retrieves all users.

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
Array of objects (User)
Array
api_token
required
string or null
Example: null

An API token associated with the user.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The email of the User

first_name
required
string or null
Example: "Levi"

The first name of the User

id
required
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The user's ID

last_name
required
string or null
Example: "Bogan"

The last name of the User

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

role
required
string
Default: "member"
Enum: "admin" "member" "developer"

The user's role

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

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.users.list()
.then(({ users }) => {
  console.log(users.length);
});

Response samples

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

Delete a User

Deletes a User

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the User.

Responses

Response Schema: application/json
id
string

The ID of the deleted user.

object
string
Default: "user"

The type of the object that was deleted.

deleted
boolean
Default: true

Whether or not the items were 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.users.delete(user_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

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

Get a User

Retrieves a User.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the User.

Responses

Response Schema: application/json
object (User)

Represents a User who can manage store settings.

api_token
required
string or null
Example: null

An API token associated with the user.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The email of the User

first_name
required
string or null
Example: "Levi"

The first name of the User

id
required
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The user's ID

last_name
required
string or null
Example: "Bogan"

The last name of the User

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

role
required
string
Default: "member"
Enum: "admin" "member" "developer"

The user's role

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

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.users.retrieve(user_id)
.then(({ user }) => {
  console.log(user.id);
});

Response samples

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

Update a User

Updates a User

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the User.

Request Body schema: application/json
first_name
string

The name of the User.

last_name
string

The name of the User.

role
string
Enum: "admin" "member" "developer"

Userrole assigned to the user.

api_token
string

The api token of the User.

metadata
object

An optional set of key-value pairs with additional information.

Responses

Response Schema: application/json
object (User)

Represents a User who can manage store settings.

api_token
required
string or null
Example: null

An API token associated with the user.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The email of the User

first_name
required
string or null
Example: "Levi"

The first name of the User

id
required
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The user's ID

last_name
required
string or null
Example: "Bogan"

The last name of the User

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

role
required
string
Default: "member"
Enum: "admin" "member" "developer"

The user's role

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "role": "admin",
  • "api_token": "string",
  • "metadata": { }
}

Response samples

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

Request Password Reset

Generates a password token for a User with a given email.

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

The Users email.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

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

Reset Password

Sets the password for a User given the correct token.

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

The token generated from the 'password-token' endpoint.

password
required
string <password>

The Users new password.

email
string <email>

The Users email.

Responses

Response Schema: application/json
object (User)

Represents a User who can manage store settings.

api_token
required
string or null
Example: null

An API token associated with the user.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The email of the User

first_name
required
string or null
Example: "Levi"

The first name of the User

id
required
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The user's ID

last_name
required
string or null
Example: "Bogan"

The last name of the User

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

role
required
string
Default: "member"
Enum: "admin" "member" "developer"

The user's role

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Request samples

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

Response samples

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