Skip to main content

Medusa Storefront API (1.0.0)

License: MIT

API reference for Medusa's Storefront endpoints. All endpoints are prefixed with /store.

Authentication

To send requests as an authenticated customer, you must use the Cookie Session ID.

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 customer 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 customer and pass the cURL option -v:

curl -v --location --request POST 'https://medusa-url.com/store/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/store/customers/me/orders' \
--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 a product, you can retrieve its collection by passing to the expand query parameter the value collection:

curl "http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=collection"

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 a product, pass to the expand query parameter the value variants,collection:

curl "http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=variants,collection"

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/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand"

This would retrieve the 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/store/products?fields=title"

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/store/products?fields=title&expand"

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 a product:

curl "http://localhost:9000/store/products?fields=title,handle"

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/store/products?fields"

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/store/products?fields&expand"

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/store/products?title=Shirt"

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/store/products?title=Blue%20Shirt"

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/store/products?offset=1"

Boolean

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

For example:

curl "http://localhost:9000/store/products?is_giftcard=true"

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/store/products?created_at[lt]=2023-02-17"

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/store/products?created_at[lt]=2023-02-17T07:22:30Z"

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/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7"

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/store/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17"

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/store/products?limit=5"

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.

Auth

Auth endpoints that allow authorization of customers and manages their sessions.

Customer Login

Logs a Customer in and authorizes them to view their details. Successful authentication will set a session cookie in the Customer's browser.

Request Body schema: application/json
email
required
string

The Customer's email.

password
required
string

The Customer's password.

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": "string",
  • "password": "string"
}

Response samples

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

Customer Log out

Destroys a Customer's authenticated session.

Authorizations:
Cookie Session ID

Responses

Request samples

curl --location --request DELETE 'https://medusa-url.com/store/auth' \
--header 'Cookie: connect.sid={sid}'

Response samples

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

Get Current Customer

Gets the currently logged in Customer.

Authorizations:
Cookie Session ID

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
medusa.auth.getSession()
.then(({ customer }) => {
  console.log(customer.id);
});

Response samples

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

Check if email exists

Checks if a Customer with the given email has signed up.

path Parameters
email
required
string <email>

The email to check if exists.

Responses

Response Schema: application/json
exists
boolean

Whether email exists or not.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.auth.exists('user@example.com')

Response samples

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

Cart

Cart endpoints that allow handling carts in Medusa.

Add a Shipping Method

Adds a Shipping Method to the Cart.

path Parameters
id
required
string

The cart ID.

Request Body schema: application/json
option_id
required
string

ID of the shipping option to create the method from

data
object

Used to hold any data that the shipping method may need to process the fulfillment of the order. Look at the documentation for your installed fulfillment providers to find out what to send.

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

Content type
application/json
{
  • "option_id": "string",
  • "data": { }
}

Response samples

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

Calculate Cart Taxes

Calculates taxes for a cart. Depending on the cart's region this may involve making 3rd party API calls to a Tax Provider service.

path Parameters
id
required
string

The Cart ID.

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

curl --location --request POST 'https://medusa-url.com/store/carts/{id}/taxes'

Response samples

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

Complete a Cart

Completes a cart. The following steps will be performed. Payment authorization is attempted and if more work is required, we simply return the cart for further updates. If payment is authorized and order is not yet created, we make sure to do so. The completion of a cart can be performed idempotently with a provided header Idempotency-Key. If not provided, we will generate one for the request.

path Parameters
id
required
string

The Cart id.

Responses

Response Schema: application/json
type
string
Enum: "order" "cart" "swap"

The type of the data property.

Order (object) or Cart (object) or Swap (object)

The data of the result object. Its type depends on the type field.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.complete(cart_id)
.then(({ cart }) => {
  console.log(cart.id);
});

Response samples

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

Create a Cart

Creates a Cart within the given region and with the initial items. If no region_id is provided the cart will be associated with the first Region available. If no items are provided the cart will be empty after creation. If a user is logged in the cart's customer id and email will be set.

Request Body schema: application/json
region_id
string

The ID of the Region to create the Cart in.

sales_channel_id
string

[EXPERIMENTAL] The ID of the Sales channel to create the Cart in.

country_code
string

The 2 character ISO country code to create the Cart in.

Array of objects

An optional array of variant_id, quantity pairs to generate Line Items from.

context
object
Example: {"ip":"::1","user_agent":"Chrome"}

An optional object to provide context to the Cart. The context field is automatically populated with ip and user_agent

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

Content type
application/json
{
  • "region_id": "string",
  • "sales_channel_id": "string",
  • "country_code": "string",
  • "items": [
    ],
  • "context": {
    }
}

Response samples

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

Create Payment Sessions

Creates Payment Sessions for each of the available Payment Providers in the Cart's Region.

path Parameters
id
required
string

The id of the Cart.

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.createPaymentSessions(cart_id)
.then(({ cart }) => {
  console.log(cart.id);
});

Response samples

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

Remove Discount

Removes a Discount from a Cart.

path Parameters
id
required
string

The id of the Cart.

code
required
string

The unique Discount code.

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.deleteDiscount(cart_id, code)
.then(({ cart }) => {
  console.log(cart.id);
});

Response samples

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

Delete a Line Item

Removes a Line Item from a Cart.

path Parameters
id
required
string

The id of the Cart.

line_id
required
string

The id of the Line Item.

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.lineItems.delete(cart_id, line_id)
.then(({ cart }) => {
  console.log(cart.id);
});

Response samples

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

Update a Line Item

Updates a Line Item if the desired quantity can be fulfilled.

path Parameters
id
required
string

The id of the Cart.

line_id
required
string

The id of the Line Item.

Request Body schema: application/json
quantity
required
number

The quantity to set the Line Item to.

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

Content type
application/json
{
  • "quantity": 0
}

Response samples

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

Delete a Payment Session

Deletes a Payment Session on a Cart. May be useful if a payment has failed.

path Parameters
id
required
string

The id of the Cart.

provider_id
required
string

The id of the Payment Provider used to create the Payment Session to be deleted.

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.deletePaymentSession(cart_id, 'manual')
.then(({ cart }) => {
  console.log(cart.id);
});

Response samples

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

Update a Payment Session

Updates a Payment Session with additional data.

path Parameters
id
required
string

The id of the Cart.

provider_id
required
string

The id of the payment provider.

Request Body schema: application/json
data
required
object

The data to update the payment session with.

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

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

Response samples

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

Get a Cart

Retrieves a Cart.

path Parameters
id
required
string

The id of the Cart.

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.retrieve(cart_id)
.then(({ cart }) => {
  console.log(cart.id);
});

Response samples

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

Update a Cart

Updates a Cart.

path Parameters
id
required
string

The id of the Cart.

Request Body schema: application/json
region_id
string

The id of the Region to create the Cart in.

country_code
string

The 2 character ISO country code to create the Cart in.

email
string <email>

An email to be used on the Cart.

sales_channel_id
string

The ID of the Sales channel to update the Cart with.

Address (object) or string

The Address to be used for billing purposes.

Address (object) or string

The Address to be used for shipping.

Array of objects

An array of Gift Card codes to add to the Cart.

Array of objects

An array of Discount codes to add to the Cart.

customer_id
string

The ID of the Customer to associate the Cart with.

context
object
Example: {"ip":"::1","user_agent":"Chrome"}

An optional object to provide context to the Cart.

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

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

Response samples

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

Refresh a Payment Session

Refreshes a Payment Session to ensure that it is in sync with the Cart - this is usually not necessary.

path Parameters
id
required
string

The id of the Cart.

provider_id
required
string

The id of the Payment Provider that created the Payment Session to be refreshed.

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.refreshPaymentSession(cart_id, 'manual')
.then(({ cart }) => {
  console.log(cart.id);
});

Response samples

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

Select a Payment Session

Selects a Payment Session as the session intended to be used towards the completion of the Cart.

path Parameters
id
required
string

The ID of the Cart.

Request Body schema: application/json
provider_id
required
string

The ID of the Payment Provider.

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

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

Response samples

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

Add a Line Item

Generates a Line Item with a given Product Variant and adds it to the Cart

path Parameters
id
required
string

The id of the Cart to add the Line Item to.

Request Body schema: application/json
variant_id
required
string

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

quantity
required
number

The quantity of the Product Variant to add to the Line Item.

metadata
object

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

Responses

Response Schema: application/json
object (Cart)

Represents a user cart

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The billing address's ID

completed_at
required
string or null <date-time>

The date with timezone at which the cart was completed.

context
required
object or null
Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

The context of the cart which can include info like IP or user agent.

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 customer's ID

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string or null <email>

The email associated with the cart

id
required
string
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

The cart's ID

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

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

An optional key-value map with additional details

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the payment was authorized.

payment_id
required
string or null
Example: "pay_01G8ZCC5W42ZNY842124G7P5R9"

The payment's ID if available

payment_session
required
object or null

The selected payment session in the cart.

region_id
required
string
Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G"

The region's ID

shipping_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The shipping address's ID

type
required
string
Default: "default"
Enum: "default" "swap" "draft_order" "payment_link" "claim"

The cart's type.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

object (Address)

An address.

Array of objects (Line Item)

Available if the relation items is expanded.

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.

Array of objects (Discount)

Available if the relation discounts is expanded.

Array of objects (Gift Card)

Available if the relation gift_cards is expanded.

customer
object or null

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

payment_sessions
Array of objects

The payment sessions created on the cart.

payment
object or null

Available if the relation payment is expanded.

Array of objects (Shipping Method)

The shipping methods added to the cart.

sales_channel_id
string or null
Example: null

The sales channel ID the cart 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

item_tax_total
integer
Example: 8000

The total of items with taxes

shipping_tax_total
integer
Example: 1000

The total of shipping with taxes

tax_total
integer
Example: 0

The total of tax

refunded_total
integer
Example: 0

The total amount refunded if the order associated with this cart is returned.

total
integer
Example: 8200

The total amount of the cart

subtotal
integer
Example: 8000

The subtotal of the cart

refundable_amount
integer
Example: 8200

The amount that can be refunded

gift_card_total
integer
Example: 0

The total of gift cards

gift_card_tax_total
integer
Example: 0

The total of gift cards with taxes

Request samples

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

Response samples

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

Collection

Collection endpoints that allow handling collections in Medusa.

Get a Collection

Retrieves a Product Collection.

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 })
medusa.collections.retrieve(collection_id)
.then(({ collection }) => {
  console.log(collection.id);
});

Response samples

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

List Collections

Retrieve a list of Product Collection.

query Parameters
offset
integer
Default: 0

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

limit
integer
Default: 10

The number of collections to return

object

Date comparison for when resulting collections were created.

object

Date comparison for when resulting collections were updated.

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

Response samples

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

Customer

Customer endpoints that allow handling customers in Medusa.

Add a Shipping Address

Adds a Shipping Address to a Customer's saved addresses.

Authorizations:
Cookie Session ID
Request Body schema: application/json
required
object (Address Fields)

The Address to add to the Customer.

first_name
required
string
Example: "Arno"

First name

last_name
required
string
Example: "Willms"

Last name

address_1
required
string
Example: "14433 Kemmer Court"

Address line 1

city
required
string
Example: "South Geoffreyview"

City

country_code
required
string
Example: "st"

The 2 character ISO code of the country in lower case

postal_code
required
string
Example: 72093

Postal Code

company
string
Example: "Acme"

Company name

address_2
string
Example: "Suite 369"

Address line 2

province
string
Example: "Kentucky"

Province

phone
string
Example: 16128234334802

Phone Number

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

An optional key-value map with additional details

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
{
  • "address": {
    }
}

Response samples

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

Create a Customer

Creates a Customer account.

Request Body schema: application/json
first_name
required
string

The Customer's first name.

last_name
required
string

The Customer's last name.

email
required
string <email>

The email of the customer.

password
required
string <password>

The Customer's password.

phone
string

The Customer's phone number.

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
{
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "password": "pa$$word",
  • "phone": "string"
}

Response samples

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

Delete an Address

Removes an Address from the Customer's saved addresses.

Authorizations:
Cookie Session ID
path Parameters
address_id
required
string

The id of the Address to remove.

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
medusa.customers.addresses.deleteAddress(address_id)
.then(({ customer }) => {
  console.log(customer.id);
});

Response samples

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

Update a Shipping Address

Updates a Customer's saved Shipping Address.

Authorizations:
Cookie Session ID
path Parameters
address_id
required
string

The id of the Address to update.

Request Body schema: application/json
Any of
company
string
Example: "Acme"

Company name

first_name
string
Example: "Arno"

First name

last_name
string
Example: "Willms"

Last name

address_1
string
Example: "14433 Kemmer Court"

Address line 1

address_2
string
Example: "Suite 369"

Address line 2

city
string
Example: "South Geoffreyview"

City

country_code
string
Example: "st"

The 2 character ISO code of the country in lower case

province
string
Example: "Kentucky"

Province

postal_code
string
Example: 72093

Postal Code

phone
string
Example: 16128234334802

Phone Number

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

An optional key-value map with additional details

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
{
  • "company": "Acme",
  • "first_name": "Arno",
  • "last_name": "Willms",
  • "address_1": "14433 Kemmer Court",
  • "address_2": "Suite 369",
  • "city": "South Geoffreyview",
  • "country_code": "st",
  • "province": "Kentucky",
  • "postal_code": 72093,
  • "phone": 16128234334802,
  • "metadata": {
    }
}

Response samples

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

Get a Customer

Retrieves a Customer - the Customer must be logged in to retrieve their details.

Authorizations:
Cookie Session ID

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

Response samples

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

Update Customer

Updates a Customer's saved details.

Authorizations:
Cookie Session ID
Request Body schema: application/json
first_name
string

The Customer's first name.

last_name
string

The Customer's last name.

Address Fields (object) or string

The Address to be used for billing purposes.

password
string

The Customer's password.

phone
string

The Customer's phone number.

email
string

The email of the customer.

metadata
object

Metadata about 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

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "billing_address": {
    },
  • "password": "string",
  • "phone": "string",
  • "email": "string",
  • "metadata": { }
}

Response samples

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

Get Payment Methods

Retrieves a list of a Customer's saved payment methods. Payment methods are saved with Payment Providers and it is their responsibility to fetch saved methods.

Authorizations:
Cookie Session ID

Responses

Response Schema: application/json
Array of objects
Array
provider_id
string

The id of the Payment Provider where the payment method is saved.

data
object

The data needed for the Payment Provider to use the saved payment method.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged
medusa.customers.paymentMethods.list()
.then(({ payment_methods }) => {
  console.log(payment_methods.length);
});

Response samples

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

List Orders

Retrieves a list of a Customer's Orders.

Authorizations:
Cookie Session ID
query Parameters
q
string

Query used for searching orders.

id
string

Id of the order to search for.

status
Array of strings

Status to search for.

fulfillment_status
Array of strings

Fulfillment status to search for.

payment_status
Array of strings

Payment status to search for.

display_id
string

Display id to search for.

cart_id
string

to search for.

email
string

to search for.

region_id
string

to search for.

currency_code
string

The 3 character ISO currency code to set prices based on.

tax_rate
string

to search for.

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

limit
integer
Default: 10

How many orders to return.

offset
integer
Default: 0

The offset in the resulting orders.

fields
string

(Comma separated string) Which fields should be included in the resulting orders.

expand
string

(Comma separated string) Which relations should be expanded in the resulting orders.

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

Response samples

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

Request Password Reset

Creates a reset password token to be used in a subsequent /reset-password request. The password token should be sent out of band e.g. via email and will not be returned.

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

The email of the customer.

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

Resets a Customer's password using a password token created by a previous /password-token request.

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

The email of the customer.

password
required
string <password>

The Customer's password.

token
required
string

The reset password token

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",
  • "password": "pa$$word",
  • "token": "string"
}

Response samples

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

Gift Card

Gift Card endpoints that allow handling gift cards in Medusa.

Get Gift Card by Code

Retrieves a Gift Card by its associated unique code.

path Parameters
code
required
string

The unique Gift Card code.

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

Response samples

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

Invite

Claim an Order

Sends an email to emails registered to orders provided with link to transfer order ownership

Authorizations:
NoneCookie Session ID
Request Body schema: application/json
order_ids
required
Array of strings

The ids of the orders to claim

Responses

Request samples

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

Response samples

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

Order

Order endpoints that allow handling orders in Medusa.

Verify an Order Claim

Verifies the claim order token provided to the customer upon request of order ownership

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

The invite token provided by the admin.

Responses

Request samples

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

Response samples

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

Get by Cart ID

Retrieves an Order by the id of the Cart that was used to create the Order.

path Parameters
cart_id
required
string

The ID of Cart.

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 })
medusa.orders.retrieveByCartId(cart_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Get an Order

Retrieves an Order

path Parameters
id
required
string

The id of the Order.

query Parameters
fields
string

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

expand
string

(Comma separated) Which fields should be expanded 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 })
medusa.orders.retrieve(order_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

Look Up an Order

Look up an order using filters.

query Parameters
display_id
required
number

The display id given to the Order.

email
required
string <email>

The email associated with this order.

fields
string

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

expand
string

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

object

The shipping address associated with this 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

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.orders.lookupOrder({
  display_id: 1,
  email: 'user@example.com'
})
.then(({ order }) => {
  console.log(order.id);
});

Response samples

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

OrderEdit

Completes an OrderEdit

Completes an OrderEdit.

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 })
medusa.orderEdits.complete(order_edit_id)
  .then(({ order_edit }) => {
    console.log(order_edit.id)
  })

Response samples

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

Decline an OrderEdit

Declines an OrderEdit.

path Parameters
id
required
string

The ID of the OrderEdit.

Request Body schema: application/json
declined_reason
string

The reason for declining 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

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

Response samples

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

Retrieve an OrderEdit

Retrieves a OrderEdit.

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 })
medusa.orderEdits.retrieve(order_edit_id)
.then(({ order_edit }) => {
  console.log(order_edit.id);
});

Response samples

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

PaymentCollection

Authorize PaymentSessions

Authorizes Payment Sessions of a Payment Collection.

Authorizations:
NoneCookie Session ID
path Parameters
id
required
string

The ID of the Payment Collections.

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

List of Payment Session IDs to authorize.

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
{
  • "session_ids": [
    ]
}

Response samples

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

Authorize Payment Session

Authorizes a Payment Session of a Payment Collection.

Authorizations:
NoneCookie Session ID
path Parameters
id
required
string

The ID of the Payment Collections.

session_id
required
string

The ID of the Payment Session.

Responses

Response Schema: application/json
object (Payment Session)

Payment Sessions are created when a Customer initilizes the checkout flow, and can be used to hold the state of a payment flow. Each Payment Session is controlled by a Payment Provider, who is responsible for the communication with external payment services. Authorized Payment Sessions will eventually get promoted to Payments to indicate that they are authorized for capture/refunds/etc.

amount
required
integer or null
Example: 100

The amount that the Payment Session has been authorized for.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

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.

data
required
object
Example: {}

The data required for the Payment Provider to identify, modify and process the Payment Session. 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: "ps_01G901XNSRM2YS3ASN9H5KG3FZ"

The payment session's ID

is_initiated
required
boolean
Default: false
Example: true

A flag to indicate if a communication with the third party provider has been initiated.

is_selected
required
boolean or null
Example: true

A flag to indicate if the Payment Session has been selected as the method that will be used to complete the purchase.

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the Payment Session was authorized.

provider_id
required
string
Example: "manual"

The id of the Payment Provider that is responsible for the Payment Session

status
required
string
Enum: "authorized" "pending" "requires_more" "error" "canceled"
Example: "pending"

Indicates the status of the Payment Session. Will default to pending, and will eventually become authorized. Payment Sessions may have the status of requires_more to indicate that further actions are to be completed by the Customer.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Cart)

Represents a user cart

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.paymentCollections.authorize(payment_id, session_id)
.then(({ payment_collection }) => {
  console.log(payment_collection.id);
});

Response samples

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

Get a PaymentCollection

Get a Payment Collection

Authorizations:
NoneCookie 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.paymentCollections.retrieve(paymentCollectionId)
  .then(({ payment_collection }) => {
    console.log(payment_collection.id)
  })

Response samples

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

Manage Payment Sessions

Manages Multiple Payment Sessions from Payment Collections.

Authorizations:
NoneCookie Session ID
path Parameters
id
required
string

The ID of the Payment Collections.

Request Body schema: application/json
required
Array of objects

An array of payment sessions related to the Payment Collection. If the session_id is not provided, existing sessions not present will be deleted and the provided ones will be created.

Array
provider_id
required
string

The ID of the Payment Provider.

amount
required
integer

The amount .

session_id
string

The ID of the Payment Session to be updated.

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
{
  • "sessions": [
    ]
}

Response samples

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

Manage a Payment Session

Manages Payment Sessions from Payment Collections.

Authorizations:
NoneCookie Session ID
path Parameters
id
required
string

The ID of the Payment Collection.

Request Body schema: application/json
provider_id
required
string

The ID of the Payment Provider.

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
{
  • "provider_id": "string"
}

Response samples

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

Refresh a Payment Session

Refreshes a Payment Session to ensure that it is in sync with the Payment Collection.

path Parameters
id
required
string

The id of the PaymentCollection.

session_id
required
string

The id of the Payment Session to be refreshed.

Responses

Response Schema: application/json
object (Payment Session)

Payment Sessions are created when a Customer initilizes the checkout flow, and can be used to hold the state of a payment flow. Each Payment Session is controlled by a Payment Provider, who is responsible for the communication with external payment services. Authorized Payment Sessions will eventually get promoted to Payments to indicate that they are authorized for capture/refunds/etc.

amount
required
integer or null
Example: 100

The amount that the Payment Session has been authorized for.

cart_id
required
string or null
Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63"

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.

data
required
object
Example: {}

The data required for the Payment Provider to identify, modify and process the Payment Session. 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: "ps_01G901XNSRM2YS3ASN9H5KG3FZ"

The payment session's ID

is_initiated
required
boolean
Default: false
Example: true

A flag to indicate if a communication with the third party provider has been initiated.

is_selected
required
boolean or null
Example: true

A flag to indicate if the Payment Session has been selected as the method that will be used to complete the purchase.

idempotency_key
required
string or null

Randomly generated key used to continue the completion of a cart in case of failure.

payment_authorized_at
required
string or null <date-time>

The date with timezone at which the Payment Session was authorized.

provider_id
required
string
Example: "manual"

The id of the Payment Provider that is responsible for the Payment Session

status
required
string
Enum: "authorized" "pending" "requires_more" "error" "canceled"
Example: "pending"

Indicates the status of the Payment Session. Will default to pending, and will eventually become authorized. Payment Sessions may have the status of requires_more to indicate that further actions are to be completed by the Customer.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Cart)

Represents a user cart

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.paymentCollections.refreshPaymentSession(payment_collection_id, session_id)
.then(({ payment_session }) => {
  console.log(payment_session.id);
});

Response samples

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

Product

Product endpoints that allow handling products in Medusa.

Get a Product

Retrieves a Product.

path Parameters
id
required
string

The id of the Product.

query Parameters
sales_channel_id
string

The sales channel used when fetching the product.

cart_id
string

The ID of the customer's cart.

region_id
string

The ID of the region the customer is using. This is helpful to ensure correct prices are retrieved for a region.

fields
string

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

expand
string

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

currency_code
string

The 3 character ISO currency code to set prices based on. This is helpful to ensure correct prices are retrieved for a currency.

Responses

Response Schema: application/json
object (Priced 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 })
medusa.products.retrieve(product_id)
.then(({ product }) => {
  console.log(product.id);
});

Response samples

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

List Products

Retrieves a list of Products.

query Parameters
q
string

Query used for searching products by title, description, variant's title, variant's sku, and collection's title

string or Array of strings

product IDs to search for.

sales_channel_id
Array of strings

an array of sales channel IDs to filter the retrieved products by.

collection_id
Array of strings

Collection IDs to search for

type_id
Array of strings

Type IDs to search for

tags
Array of strings

Tag IDs to search for

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.

category_id
Array of strings

Category ids to filter by.

include_category_children
boolean

Include category children when filtering by category_id.

offset
integer
Default: 0

How many products to skip in the result.

limit
integer
Default: 100

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.

cart_id
string

The id of the Cart to set prices based on.

region_id
string

The id of the Region to set prices based on.

currency_code
string

The currency code to use for price selection.

Responses

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

Response samples

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

Search Products

Run a search query on products using the search engine installed on Medusa

query Parameters
q
required
string

The query to run the search with.

offset
integer

How many products to skip in the result.

limit
integer

Limit the number of products returned.

Responses

Response Schema: application/json
hits
Array of arrays

Array of results. The format of the items depends on the search engine installed on the server.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.products.search({
  q: 'Shirt'
})
.then(({ hits }) => {
  console.log(hits.length);
});

Response samples

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

Product Category

Get a Product Category

Retrieves a Product Category.

Authorizations:
NoneCookie 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.

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.productCategories.retrieve(product_category_id)
  .then(({ product_category }) => {
    console.log(product_category.id);
  });

Response samples

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

List Product Categories

Retrieve a list of product categories.

Authorizations:
NoneCookie Session ID
query Parameters
q
string

Query used for searching product category names orhandles.

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.

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 })
medusa.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
}

Product Tag

List Product Tags

Retrieve a list of Product Tags.

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

value
Array of strings

The tag values to search for

id
Array of strings

The tag IDs to search for

q
string

A query string to search values 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
object (Product Tag)

Product Tags can be added to Products for easy filtering and grouping.

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

Response samples

Content type
application/json
{
  • "product_tags": {
    },
  • "count": 0,
  • "offset": 0,
  • "limit": 0
}

Product Type

List Product Types

Retrieve a list of Product Types.

Authorizations:
NoneCookie 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.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 a Product Variant

Retrieves a Product Variant by id

path Parameters
variant_id
required
string

The id of the Product Variant.

query Parameters
cart_id
string

The id of the Cart to set prices based on.

sales_channel_id
string

A sales channel id for result configuration.

region_id
string

The id of the Region to set prices based on.

currency_code
string

The 3 character ISO currency code to set prices based on.

Responses

Response Schema: application/json
object (Priced Product Variant)

Product Variants represent a Product with a specific set of Product Option configurations. The maximum number of Product Variants that a Product can have is given by the number of available Product Option combinations.

allow_backorder
required
boolean
Default: false

Whether the Product Variant should be purchasable when inventory_quantity is 0.

barcode
required
string or null
Example: null

A generic field for a GTIN number that can be used to identify the Product Variant.

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.

ean
required
string or null
Example: null

An EAN barcode number that can be used to identify the Product Variant.

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: "variant_01G1G5V2MRX2V3PVSR2WXYPFB6"

The product variant's ID

inventory_quantity
required
integer
Example: 100

The current quantity of the item that is stocked.

length
required
number or null
Example: null

The length of the Product Variant. May be used in shipping rate calculations.

manage_inventory
required
boolean
Default: true

Whether Medusa should manage inventory for the Product Variant.

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.

product_id
required
string
Example: "prod_01G1G5V2MBA328390B5AXJ610F"

The ID of the Product that the Product Variant belongs to.

sku
required
string or null
Example: "shirt-123"

The unique stock keeping unit used to identify the Product Variant. This will usually be a unqiue identifer for the item that is to be shipped, and can be referenced across multiple systems.

title
required
string
Example: "Small"

A title that can be displayed for easy identification of the Product Variant.

upc
required
string or null
Example: null

A UPC barcode number that can be used to identify the Product Variant.

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.

product
object or null

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

Array of objects (Money Amount)

The Money Amounts defined for the Product Variant. Each Money Amount represents a price in a given currency or a price in a specific Region. Available if the relation prices is expanded.

variant_rank
number or null
Default: 0

The ranking of this variant

Array of objects (Product Option Value)

The Product Option Values specified for the Product Variant. Available if the relation options is expanded.

Array of objects (Product Variant Inventory Item)

The Inventory Items related to the product variant. Available if the relation inventory_items is expanded.

original_price
number

The original price of the variant without any discounted prices applied.

calculated_price
number

The calculated price of the variant. Can be a discounted price.

original_price_incl_tax
number

The original price of the variant including taxes.

calculated_price_incl_tax
number

The calculated price of the variant including taxes.

original_tax
number

The taxes applied on the original price.

calculated_tax
number

The taxes applied on the calculated price.

Array of objects

An array of applied tax rates

Request samples

curl --location --request GET 'https://medusa-url.com/store/variants/{id}'

Response samples

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

Get Product Variants

Retrieves a list of Product Variants

query Parameters
ids
string

A comma separated list of Product Variant ids to filter by.

sales_channel_id
string

A sales channel id for result configuration.

expand
string

A comma separated list of Product Variant relations to load.

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 set prices based on.

region_id
string

The id of the Region to set prices based on.

currency_code
string

The currency code 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 (Priced Product Variant)
Array
allow_backorder
required
boolean
Default: false

Whether the Product Variant should be purchasable when inventory_quantity is 0.

barcode
required
string or null
Example: null

A generic field for a GTIN number that can be used to identify the Product Variant.

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.

ean
required
string or null
Example: null

An EAN barcode number that can be used to identify the Product Variant.

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: "variant_01G1G5V2MRX2V3PVSR2WXYPFB6"

The product variant's ID

inventory_quantity
required
integer
Example: 100

The current quantity of the item that is stocked.

length
required
number or null
Example: null

The length of the Product Variant. May be used in shipping rate calculations.

manage_inventory
required
boolean
Default: true

Whether Medusa should manage inventory for the Product Variant.

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.

product_id
required
string
Example: "prod_01G1G5V2MBA328390B5AXJ610F"

The ID of the Product that the Product Variant belongs to.

sku
required
string or null
Example: "shirt-123"

The unique stock keeping unit used to identify the Product Variant. This will usually be a unqiue identifer for the item that is to be shipped, and can be referenced across multiple systems.

title
required
string
Example: "Small"

A title that can be displayed for easy identification of the Product Variant.

upc
required
string or null
Example: null

A UPC barcode number that can be used to identify the Product Variant.

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.

product
object or null

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

Array of objects (Money Amount)

The Money Amounts defined for the Product Variant. Each Money Amount represents a price in a given currency or a price in a specific Region. Available if the relation prices is expanded.

variant_rank
number or null
Default: 0

The ranking of this variant

Array of objects (Product Option Value)

The Product Option Values specified for the Product Variant. Available if the relation options is expanded.

Array of objects (Product Variant Inventory Item)

The Inventory Items related to the product variant. Available if the relation inventory_items is expanded.

original_price
number

The original price of the variant without any discounted prices applied.

calculated_price
number

The calculated price of the variant. Can be a discounted price.

original_price_incl_tax
number

The original price of the variant including taxes.

calculated_price_incl_tax
number

The calculated price of the variant including taxes.

original_tax
number

The taxes applied on the original price.

calculated_tax
number

The taxes applied on the calculated price.

Array of objects

An array of applied tax rates

Request samples

curl --location --request GET 'https://medusa-url.com/store/variants'

Response samples

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

Region

Region endpoints that allow handling regions in Medusa.

Get a Region

Retrieves a Region.

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 })
medusa.regions.retrieve(region_id)
.then(({ region }) => {
  console.log(region.id);
});

Response samples

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

List Regions

Retrieves a list of Regions.

query Parameters
offset
integer
Default: 0

How many regions to skip in the result.

limit
integer
Default: 100

Limit the number of regions returned.

object

Date comparison for when resulting regions were created.

object

Date comparison for when resulting regions were updated.

Responses

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

Response samples

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

Return

Return endpoints that allow handling returns in Medusa.

Create Return

Creates a Return for an Order.

Request Body schema: application/json
order_id
required
string

The ID of the Order to create the Return from.

required
Array of objects

The items to include in the Return.

object

If the Return is to be handled by the store operator the Customer can choose a Return Shipping Method. Alternatvely the Customer can handle the Return themselves.

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
{
  • "order_id": "string",
  • "items": [
    ],
  • "return_shipping": {
    }
}

Response samples

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

Return Reason

Return Reason endpoints that allow handling return reasons in Medusa.

Get a Return Reason

Retrieves a Return Reason.

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 })
medusa.returnReasons.retrieve(reason_id)
.then(({ return_reason }) => {
  console.log(return_reason.id);
});

Response samples

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

List Return Reasons

Retrieves a list of Return Reasons.

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

Response samples

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

Shipping Option

Shipping Option endpoints that allow handling shipping options in Medusa.

Get Shipping Options

Retrieves a list of Shipping Options.

query Parameters
is_return
boolean

Whether return Shipping Options should be included. By default all Shipping Options are returned.

product_ids
string

A comma separated list of Product ids to filter Shipping Options by.

region_id
string

the Region to retrieve Shipping Options from.

Responses

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

Response samples

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

List for Cart

Retrieves a list of Shipping Options available to a cart.

path Parameters
cart_id
required
string

The id of the Cart.

Responses

Response Schema: application/json
Array of objects (Shipping Option)
Array
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 })
medusa.shippingOptions.listCartOptions(cart_id)
.then(({ shipping_options }) => {
  console.log(shipping_options.length);
});

Response samples

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

Swap

Swap endpoints that allow handling swaps in Medusa.

Create a Swap

Creates a Swap on an Order by providing some items to return along with some items to send back

Request Body schema: application/json
order_id
required
string

The ID of the Order to create the Swap for.

required
Array of objects

The items to include in the Return.

required
Array of objects

The items to exchange the returned items to.

return_shipping_option
string

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

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

Content type
application/json
{
  • "order_id": "string",
  • "return_items": [
    ],
  • "return_shipping_option": "string",
  • "additional_items": [
    ]
}

Response samples

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

Get by Cart ID

Retrieves a Swap by the id of the Cart used to confirm the Swap.

path Parameters
cart_id
required
string

The id of the Cart

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 })
medusa.swaps.retrieveByCartId(cart_id)
.then(({ swap }) => {
  console.log(swap.id);
});

Response samples

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