Medusa Storefront API (1.0.0)

Download OpenAPI specification:Download

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.

Sort Order

The order field available on endpoints supporting pagination allows you to sort the retrieved items by an attribute of that item. For example, you can sort products by their created_at attribute by setting order to created_at:

curl "http://localhost:9000/list/products?order=created_at"

By default, the sort direction will be ascending. To change it to descending, pass a dash (-) before the attribute name. For example:

curl "http://localhost:9000/list/products?order=-created_at"

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

Auth

Authentication endpoints allow customers to manage their session, such as login or log out. When a customer is logged in, the cookie header is set indicating the customer's login session.

How to implement customer profiles in your storefront

Get Current Customer

Retrieve the currently logged in Customer's details.

Authorizations:

Cookie Session ID

Responses

Response Schema: application/json

required

object (Customer)

A customer can make purchases in your store and manage their profile.

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 Learn about the metadata attribute, and how to delete and update it.
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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Address) The details of the shipping addresses associated with the customer.
orders	Array of objects The details of the orders this customer placed.
	Array of objects (Customer Group) The customer groups the customer belongs to.

Request samples

JS Client
cURL

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": {"id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"email": "user@example.com",
"first_name": "Arno",
"last_name": "Willms",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_addresses": [{"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"phone": 16128234334802,
"has_account": false,
"orders": [{ }
],
"groups": [{"id": null,
"name": null,
"customers": [ ],
"price_lists": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Customer Login

Log a customer in and includes the Cookie session in the response header. The cookie session can be used in subsequent requests to authenticate the customer. When using Medusa's JS or Medusa React clients, the cookie is automatically attached to subsequent requests.

Request Body schema: application/json

email required	string The Customer's email.
password required	string The Customer's password.

Responses

Response Schema: application/json

required

object (Customer)

A customer can make purchases in your store and manage their profile.

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 Learn about the metadata attribute, and how to delete and update it.
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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Address) The details of the shipping addresses associated with the customer.
orders	Array of objects The details of the orders this customer placed.
	Array of objects (Customer Group) The customer groups the customer belongs to.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"email": "string",
"password": "string"
}

Response samples

Content type

application/json

{"customer": {"id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"email": "user@example.com",
"first_name": "Arno",
"last_name": "Willms",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_addresses": [{"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"phone": 16128234334802,
"has_account": false,
"orders": [{ }
],
"groups": [{"id": null,
"name": null,
"customers": [ ],
"price_lists": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Customer Log out

Delete the current session for the logged in customer.

Authorizations:

Cookie Session ID

Responses

Request samples

cURL

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

Response samples

Content type

application/json

Example

Not Allowed Error

{"message": "Discount must be set to dynamic",
"type": "not_allowed"
}

Check if Email Exists

Check if there's a customer already registered with the provided email.

path Parameters

required

string <email>

The email to check.

Responses

Response Schema: application/json

exists

required

boolean

Whether email exists or not.

Request samples

JS Client
cURL

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
}

Carts

A cart is a virtual shopping bag that customers can use to add items they want to purchase. A cart is then used to checkout and place an order.

How to implement cart functionality in your storefront

Create a Cart

Create a Cart. Although optional, specifying the cart's region and sales channel can affect the cart's pricing and the products that can be added to the cart respectively. So, make sure to set those early on and change them if necessary, such as when the customer changes their region.

If a customer is logged in, the cart's customer ID and email will automatically be set.

Request Body schema: application/json

region_id	string The ID of the Region to create the Cart in. Setting the cart's region can affect the pricing of the items in the cart as well as the used currency. If this parameter is not provided, the first region in the store is used by default.
sales_channel_id	string The ID of the Sales channel to create the Cart in. The cart's sales channel affects which products can be added to the cart. If a product does not exist in the cart's sales channel, it cannot be added to the cart. If you add a publishable API key in the header of this request and specify a sales channel ID, the specified sales channel must be within the scope of the publishable API key's resources. If you add a publishable API key in the header of this request, you don't specify a sales channel ID, and the publishable API key is associated with one sales channel, that sales channel will be attached to the cart. If no sales channel is passed and no publishable API key header is passed or the publishable API key isn't associated with any sales channel, the cart will not be associated with any sales channel.
country_code	string The 2 character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address. See a list of codes.
	Array of objects An array of product variants to generate line items from.
context	object Example: {"ip":"::1","user_agent":"Chrome"} An object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`

Responses

Response Schema: application/json

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

Payload
JS Client
cURL

Content type

application/json

{"region_id": "string",
"sales_channel_id": "string",
"country_code": "string",
"items": [{"variant_id": "string",
"quantity": 0
}
],
"context": {"ip": "::1",
"user_agent": "Chrome"
}
}

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Get a Cart

Retrieve a Cart's details. This includes recalculating its totals.

path Parameters

required

string

The ID of the Cart.

Responses

Response Schema: application/json

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

JS Client
cURL

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

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Update a Cart

Update a Cart's details. If the cart has payment sessions and the region was not changed, the payment sessions are updated. The cart's totals are also recalculated.

path Parameters

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. Setting the cart's region can affect the pricing of the items in the cart as well as the used currency.
country_code	string The 2 character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address. See a list of codes.
email	string <email> An email to be used on the Cart.
sales_channel_id	string The ID of the Sales channel to create the Cart in. The cart's sales channel affects which products can be added to the cart. If a product does not exist in the cart's sales channel, it cannot be added to the cart. If you add a publishable API key in the header of this request and specify a sales channel ID, the specified sales channel must be within the scope of the publishable API key's resources.
	AddressPayload (object) or string The Address to be used for billing purposes.
	AddressPayload (object) or string The Address to be used for shipping purposes.
	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 object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`

Responses

Response Schema: application/json

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

Payload
JS Client
cURL

Content type

application/json

{"region_id": "string",
"country_code": "string",
"email": "user@example.com",
"sales_channel_id": "string",
"billing_address": {"first_name": "Arno",
"last_name": "Willms",
"phone": 16128234334802,
"company": "string",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"province": "Kentucky",
"postal_code": 72093,
"metadata": {"car": "white"
}
},
"shipping_address": {"first_name": "Arno",
"last_name": "Willms",
"phone": 16128234334802,
"company": "string",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"province": "Kentucky",
"postal_code": 72093,
"metadata": {"car": "white"
}
},
"gift_cards": [{"code": "string"
}
],
"discounts": [{"code": "string"
}
],
"customer_id": "string",
"context": {"ip": "::1",
"user_agent": "Chrome"
}
}

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Complete a Cart

Complete a cart and place an order or create a swap, based on what the cart is created for. This includes attempting to authorize the cart's payment. If authorizing the payment requires more action, the cart will not be completed and the order will not be placed or the swap will not be created.

An idempotency key will be generated if none is provided in the header Idempotency-Key and added to the response. If an error occurs during cart completion or the request is interrupted for any reason, the cart completion can be retried by passing the idempotency key in the Idempotency-Key header.

Cart completion overview

path Parameters

required

string

The Cart ID.

Responses

Response Schema: application/json

type

required

string

Enum: "order" "cart" "swap"

The type of the data property. If the cart completion fails, type will be cart and the data object will be the cart's details. If the cart completion is successful and the cart is used for checkout, type will be order and the data object will be the order's details. If the cart completion is successful and the cart is used for swap creation, type will be swap and the data object will be the swap's details.

required

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

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

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"type": "order",
"data": {"id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"status": "pending",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"display_id": 2,
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": { },
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"currency_code": "usd",
"currency": {"code": "usd",
"symbol": "$",
"symbol_native": "$",
"name": "US Dollar",
"includes_tax": false
},
"tax_rate": 0,
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"payments": [{ }
],
"fulfillments": [{ }
],
"returns": [{ }
],
"claims": [{ }
],
"refunds": [{ }
],
"swaps": [{ }
],
"draft_order_id": null,
"draft_order": { },
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"edits": [{ }
],
"gift_card_transactions": [{"id": null,
"gift_card_id": null,
"gift_card": { },
"order_id": null,
"order": { },
"amount": null,
"created_at": null,
"is_taxable": null,
"tax_rate": null
}
],
"canceled_at": "2019-08-24T14:15:22Z",
"no_notification": false,
"idempotency_key": "string",
"external_id": null,
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_total": 1000,
"raw_discount_total": 800,
"discount_total": 800,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"paid_total": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0,
"returnable_items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Remove Discount

Remove a Discount from a Cart. This only removes the application of the discount, and not completely delete it. The totals will be re-calculated and the payment sessions will be refreshed after the removal.

path Parameters

id required	string The ID of the Cart.
code required	string The unique discount code.

Responses

Response Schema: application/json

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

JS Client
cURL

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

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Add a Line Item

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

path Parameters

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. Learn about the metadata attribute, and how to delete and update it.

Responses

Response Schema: application/json

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

Payload
JS Client
cURL

Content type

application/json

{"variant_id": "string",
"quantity": 0,
"metadata": { }
}

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Update a Line Item

Update a line item's quantity.

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 of the line item in the cart.
metadata	object An optional key-value map with additional details about the Line Item. If omitted, the metadata will remain unchanged." Learn about the metadata attribute, and how to delete and update it.

Responses

Response Schema: application/json

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

Payload
JS Client
cURL

Content type

application/json

{"quantity": 0,
"metadata": { }
}

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Delete a Line Item

Delete a Line Item from a Cart. The payment sessions will be updated and the totals will be recalculated.

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

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

JS Client
cURL

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

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Select a Payment Session

Select the Payment Session that will be used to complete the cart. This is typically used when the customer chooses their preferred payment method during checkout. The totals of the cart will be recalculated.

path Parameters

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

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

Payload
JS Client
cURL

Content type

application/json

{"provider_id": "string"
}

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Create Payment Sessions

Create Payment Sessions for each of the available Payment Providers in the Cart's Region. If there only one payment session is created, it will be selected by default. The creation of the payment session uses the payment provider and may require sending requests to third-party services.

path Parameters

required

string

The ID of the Cart.

Responses

Response Schema: application/json

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

JS Client
cURL

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

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Update a Payment Session

Update a Payment Session with additional data. This can be useful depending on the payment provider used. All payment sessions are updated and cart totals are recalculated afterwards.

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

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

Payload
JS Client
cURL

Content type

application/json

{"data": { }
}

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Delete a Payment Session

Delete a Payment Session in a Cart. May be useful if a payment has failed. The totals will be recalculated.

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

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

JS Client
cURL

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

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Refresh a Payment Session

Refresh a Payment Session to ensure that it is in sync with the Cart. This is usually not necessary, but is provided for edge cases.

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

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

JS Client
cURL

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

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Add Shipping Method

Add a Shipping Method to the Cart. The validation of the data field is handled by the fulfillment provider of the chosen shipping option.

path Parameters

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. This depends on the fulfillment provider you're using.

Responses

Response Schema: application/json

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

Payload
JS Client
cURL

Content type

application/json

{"option_id": "string",
"data": { }
}

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Calculate Cart Taxes

Calculate the taxes for a cart. This is useful if the automatic_taxes field of the cart's region is set to false. If the cart's region uses a tax provider other than Medusa's system provider, this may lead to sending requests to third-party services.

How to calculate taxes manually during checkout

path Parameters

required

string

The Cart ID.

Responses

Response Schema: application/json

required

object (Cart)

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 details of 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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Line Item) The line items added to the cart.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) An array of details of all discounts applied to the cart.
	Array of objects (Gift Card) An array of details of all gift cards applied to the cart.
customer	object or null The details of the customer the cart belongs to.
payment_sessions	Array of objects The details of all payment sessions created on the cart.
payment	object or null The details of the payment associated with the cart.
	Array of objects (Shipping Method) The details of 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 is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount rounded
raw_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

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

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Customers

A customer can register and manage their information such as addresses, orders, payment methods, and more.

How to implement customer profiles in your storefront

Create a Customer

Register a new customer. This will also automatically authenticate the customer and set their login session in the response Cookie header. The cookie session can be used in subsequent requests to authenticate the customer. When using Medusa's JS or Medusa React clients, the cookie is automatically attached to subsequent requests.

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 customer's email.
password required	string <password> The customer's password.
phone	string The customer's phone number.

Responses

Response Schema: application/json

required

object (Customer)

A customer can make purchases in your store and manage their profile.

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 Learn about the metadata attribute, and how to delete and update it.
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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Address) The details of the shipping addresses associated with the customer.
orders	Array of objects The details of the orders this customer placed.
	Array of objects (Customer Group) The customer groups the customer belongs to.

Request samples

Payload
JS Client
cURL

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": {"id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"email": "user@example.com",
"first_name": "Arno",
"last_name": "Willms",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_addresses": [{"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"phone": 16128234334802,
"has_account": false,
"orders": [{ }
],
"groups": [{"id": null,
"name": null,
"customers": [ ],
"price_lists": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Get a Customer

Retrieve the logged-in Customer's details.

Authorizations:

Cookie Session ID

Responses

Response Schema: application/json

required

object (Customer)

A customer can make purchases in your store and manage their profile.

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 Learn about the metadata attribute, and how to delete and update it.
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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Address) The details of the shipping addresses associated with the customer.
orders	Array of objects The details of the orders this customer placed.
	Array of objects (Customer Group) The customer groups the customer belongs to.

Request samples

JS Client
cURL

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": {"id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"email": "user@example.com",
"first_name": "Arno",
"last_name": "Willms",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_addresses": [{"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"phone": 16128234334802,
"has_account": false,
"orders": [{ }
],
"groups": [{"id": null,
"name": null,
"customers": [ ],
"price_lists": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Update Customer

Update the logged-in customer's 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.
	AddressPayload (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 customer's email.
metadata	object Additional custom data about the customer. Learn about the metadata attribute, and how to delete and update it.

Responses

Response Schema: application/json

required

object (Customer)

A customer can make purchases in your store and manage their profile.

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 Learn about the metadata attribute, and how to delete and update it.
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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Address) The details of the shipping addresses associated with the customer.
orders	Array of objects The details of the orders this customer placed.
	Array of objects (Customer Group) The customer groups the customer belongs to.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"first_name": "string",
"last_name": "string",
"billing_address": {"first_name": "Arno",
"last_name": "Willms",
"phone": 16128234334802,
"company": "string",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"province": "Kentucky",
"postal_code": 72093,
"metadata": {"car": "white"
}
},
"password": "string",
"phone": "string",
"email": "string",
"metadata": { }
}

Response samples

Content type

application/json

{"customer": {"id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"email": "user@example.com",
"first_name": "Arno",
"last_name": "Willms",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_addresses": [{"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"phone": 16128234334802,
"has_account": false,
"orders": [{ }
],
"groups": [{"id": null,
"name": null,
"customers": [ ],
"price_lists": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Add a Shipping Address

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

Authorizations:

Cookie Session ID

Request Body schema: application/json

required

object (AddressCreatePayload)

Address fields used when creating an address.

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 See a list of codes.
postal_code required	string Example: 72093 Postal Code
phone	string Example: 16128234334802 Phone Number
company	string
address_2	string Example: "Suite 369" Address line 2
province	string Example: "Kentucky" Province
metadata	object Example: {"car":"white"} An optional key-value map with additional details

Responses

Response Schema: application/json

required

object (Customer)

A customer can make purchases in your store and manage their profile.

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 Learn about the metadata attribute, and how to delete and update it.
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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Address) The details of the shipping addresses associated with the customer.
orders	Array of objects The details of the orders this customer placed.
	Array of objects (Customer Group) The customer groups the customer belongs to.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"address": {"first_name": "Arno",
"last_name": "Willms",
"phone": 16128234334802,
"company": "string",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"province": "Kentucky",
"postal_code": 72093,
"metadata": {"car": "white"
}
}
}

Response samples

Content type

application/json

{"customer": {"id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"email": "user@example.com",
"first_name": "Arno",
"last_name": "Willms",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_addresses": [{"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"phone": 16128234334802,
"has_account": false,
"orders": [{ }
],
"groups": [{"id": null,
"name": null,
"customers": [ ],
"price_lists": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Update a Shipping Address

Update the logged-in customer's saved Shipping Address's details.

Authorizations:

Cookie Session ID

path Parameters

address_id

required

string

The ID of the Address.

Request Body schema: application/json

Any of

first_name	string Example: "Arno" First name
last_name	string Example: "Willms" Last name
phone	string Example: 16128234334802 Phone Number
company	string
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 See a list of codes.
province	string Example: "Kentucky" Province
postal_code	string Example: 72093 Postal Code
metadata	object Example: {"car":"white"} An optional key-value map with additional details

Responses

Response Schema: application/json

required

object (Customer)

A customer can make purchases in your store and manage their profile.

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 Learn about the metadata attribute, and how to delete and update it.
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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Address) The details of the shipping addresses associated with the customer.
orders	Array of objects The details of the orders this customer placed.
	Array of objects (Customer Group) The customer groups the customer belongs to.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"first_name": "Arno",
"last_name": "Willms",
"phone": 16128234334802,
"company": "string",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"province": "Kentucky",
"postal_code": 72093,
"metadata": {"car": "white"
}
}

Response samples

Content type

application/json

{"customer": {"id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"email": "user@example.com",
"first_name": "Arno",
"last_name": "Willms",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_addresses": [{"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"phone": 16128234334802,
"has_account": false,
"orders": [{ }
],
"groups": [{"id": null,
"name": null,
"customers": [ ],
"price_lists": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Delete an Address

Delete 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

required

object (Customer)

A customer can make purchases in your store and manage their profile.

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 Learn about the metadata attribute, and how to delete and update it.
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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Address) The details of the shipping addresses associated with the customer.
orders	Array of objects The details of the orders this customer placed.
	Array of objects (Customer Group) The customer groups the customer belongs to.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged
medusa.customers.addresses.deleteAddress(addressId)
.then(({ customer }) => {
  console.log(customer.id);
});

Response samples

Content type

application/json

{"customer": {"id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"email": "user@example.com",
"first_name": "Arno",
"last_name": "Willms",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_addresses": [{"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"phone": 16128234334802,
"has_account": false,
"orders": [{ }
],
"groups": [{"id": null,
"name": null,
"customers": [ ],
"price_lists": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

List Orders

Retrieve a list of the logged-in Customer's Orders. The orders can be filtered by fields such as status or fulfillment_status. The orders can also be paginated.

Authorizations:

Cookie Session ID

query Parameters

q	string term to search orders' display ID, email, shipping address's first name, customer's first name, customer's last name, and customer's phone number.
id	string Filter by ID.
status	Array of strings Items Enum: "pending" "completed" "archived" "canceled" "requires_action" Filter by status.
fulfillment_status	Array of strings Items Enum: "not_fulfilled" "partially_fulfilled" "fulfilled" "partially_shipped" "shipped" "partially_returned" "returned" "canceled" "requires_action" Fulfillment status to search for.
payment_status	Array of strings Items Enum: "not_paid" "awaiting" "captured" "partially_refunded" "refunded" "canceled" "requires_action" Payment status to search for.
display_id	string Filter by display ID.
cart_id	string Filter by cart ID.
email	string Filter by email.
region_id	string Filter by region ID.
currency_code	string Filter by the 3 character ISO currency code of the order. See a list of codes.
tax_rate	string Filter by tax rate.
	object Filter by a creation date range.
	object Filter by an update date range.
	object Filter by a cancelation date range.
limit	integer Default: 10 Limit the number of orders returned.
offset	integer Default: 0 The number of orders to skip when retrieving the orders.
expand	string Comma-separated relations that should be expanded in the returned orders.
fields	string Comma-separated fields that should be included in the returned orders.

Responses

Response Schema: application/json

required	Array of objects (Order) An array of orders details.
count required	integer The total number of items available
offset required	integer The number of orders skipped when retrieving the orders.
limit required	integer The number of items per page

Request samples

JS Client
cURL

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": [{"id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"status": "pending",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"display_id": 2,
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": { },
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": null,
"name": null,
"currency_code": null,
"currency": null,
"tax_rate": null,
"tax_rates": [ ],
"tax_code": null,
"gift_cards_taxable": null,
"automatic_taxes": null,
"countries": [ ],
"tax_provider_id": null,
"tax_provider": null,
"payment_providers": [ ],
"fulfillment_providers": [ ],
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"discounts": [null
],
"gift_cards": [null
],
"shipping_methods": [null
],
"payments": [{ }
],
"fulfillments": [{ }
],
"returns": [{ }
],
"claims": [{ }
],
"refunds": [{ }
],
"swaps": [{ }
],
"draft_order_id": null,
"draft_order": { },
"items": [null
],
"edits": [{ }
],
"gift_card_transactions": [null
],
"canceled_at": "2019-08-24T14:15:22Z",
"no_notification": false,
"idempotency_key": "string",
"external_id": null,
"sales_channel_id": null,
"sales_channel": {"id": null,
"name": null,
"description": null,
"is_disabled": null,
"locations": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"shipping_total": 1000,
"raw_discount_total": 800,
"discount_total": 800,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"paid_total": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0,
"returnable_items": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Get Saved Payment Methods Deprecated

Retrieve the logged-in customer's saved payment methods. This endpoint only works with payment providers created with the deprecated Payment Service interface. The payment methods are saved using the Payment Service's third-party service, and not on the Medusa backend. So, they're retrieved from the third-party service.

Authorizations:

Cookie Session ID

Responses

Response Schema: application/json

required

Array of objects

An array of saved payment method details.

Array

provider_id required	string The ID of the Payment Provider where the payment method is saved.
data required	object The data needed for the Payment Provider to use the saved payment method.

Request samples

JS Client
cURL

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": [{"provider_id": "string",
"data": { }
}
]
}

Reset Password

Reset a Customer's password using a password token created by a previous request to the Request Password Reset endpoint. If the password token expired, you must create a new one.

How to reset password

Request Body schema: application/json

email required	string <email> The customer's email.
password required	string <password> The customer's password.
token required	string The reset password token

Responses

Response Schema: application/json

required

object (Customer)

A customer can make purchases in your store and manage their profile.

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 Learn about the metadata attribute, and how to delete and update it.
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 is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Address) The details of the shipping addresses associated with the customer.
orders	Array of objects The details of the orders this customer placed.
	Array of objects (Customer Group) The customer groups the customer belongs to.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"email": "user@example.com",
"password": "pa$$word",
"token": "string"
}

Response samples

Content type

application/json

{"customer": {"id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"email": "user@example.com",
"first_name": "Arno",
"last_name": "Willms",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_addresses": [{"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"phone": 16128234334802,
"has_account": false,
"orders": [{ }
],
"groups": [{"id": null,
"name": null,
"customers": [ ],
"price_lists": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Request Password Reset

Create a reset password token to be used in a subsequent Reset Password endpoint. This emits the event customer.password_reset. If a notification provider is installed in the Medusa backend and is configured to handle this event, a notification to the customer, such as an email, may be sent with reset instructions.

How to reset password

Request Body schema: application/json

required

string <email>

The customer's email.

Responses

Request samples

Payload
JS Client
cURL

Content type

application/json

{"email": "user@example.com"
}

Response samples

Content type

application/json

Example

Not Allowed Error

{"message": "Discount must be set to dynamic",
"type": "not_allowed"
}

Gift Cards

Customers can use gift cards during checkout to deduct the gift card's balance from the checkout total. The Gift Card endpoints allow retrieving a gift card's details by its code. A gift card can be applied to a cart using the Carts endpoints.

How to use gift cards in a storefront

Get Gift Card by Code

Retrieve a Gift Card's details by its associated unique code.

path Parameters

code

required

string

The unique Gift Card code.

Responses

Response Schema: application/json

required

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 Learn about the metadata attribute, and how to delete and update it.
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 this gift card is available in.
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) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
order	object or null The details of the order that the gift card was purchased in.

Request samples

JS Client
cURL

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": {"id": "gift_01G8XKBPBQY2R7RBET4J7E0XQZ",
"code": "3RFT-MH2C-Y4YZ-XMN4",
"value": 10,
"balance": 10,
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order": { },
"is_disabled": false,
"ends_at": "2019-08-24T14:15:22Z",
"tax_rate": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Order Edits

Order edits are changes made to items in an order such as adding, updating their quantity, or deleting them. Order edits are created by the admin. A customer can review order edit requests created by an admin and confirm or decline them.

How to handle order edits in a storefront

Retrieve an Order Edit

Retrieve an Order Edit's details.

path Parameters

required

string

The ID of the OrderEdit.

Responses

Response Schema: application/json

required

object (Order Edit)

Order edit allows modifying items in an order, such as adding, updating, or deleting items from the original order. Once the order edit is confirmed, the changes are reflected on the original order.

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 The details of the order that this order edit was created for.
	Array of objects (Order Item Change) The details of all the changes on the original order's line items.
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) The details of the cloned items from the original order with the new changes. Once the order edit is confirmed, these line items are associated with the original order.
	object (Payment Collection) A payment collection allows grouping and managing a list of payments at one. This can be helpful when making additional payment for order edits or integrating installment payments.

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"order_edit": {"id": "oe_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order_id": "order_01G2SG30J8C85S4A5CHM2S1NS2",
"order": { },
"changes": [{"id": null,
"type": null,
"order_edit_id": null,
"order_edit": { },
"original_line_item_id": null,
"original_line_item": null,
"line_item_id": null,
"line_item": null,
"created_at": null,
"updated_at": null,
"deleted_at": null
}
],
"internal_note": "Included two more items B to the order.",
"created_by": "string",
"requested_by": "string",
"requested_at": "2019-08-24T14:15:22Z",
"confirmed_by": "string",
"confirmed_at": "2019-08-24T14:15:22Z",
"declined_by": "string",
"declined_at": "2019-08-24T14:15:22Z",
"declined_reason": "string",
"canceled_by": "string",
"canceled_at": "2019-08-24T14:15:22Z",
"subtotal": 8000,
"discount_total": 800,
"shipping_total": 800,
"gift_card_total": 800,
"gift_card_tax_total": 800,
"tax_total": 0,
"total": 8200,
"difference_due": 8200,
"status": "confirmed",
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"payment_collection_id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": null,
"name": null,
"currency_code": null,
"currency": null,
"tax_rate": null,
"tax_rates": [ ],
"tax_code": null,
"gift_cards_taxable": null,
"automatic_taxes": null,
"countries": [ ],
"tax_provider_id": null,
"tax_provider": null,
"payment_providers": [ ],
"fulfillment_providers": [ ],
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"payment_sessions": [null
],
"payments": [null
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Complete an Order Edit

Complete an Order Edit and reflect its changes on the original order. Any additional payment required must be authorized first using the Payment Collection endpoints.

How to handle order edits in a storefront

path Parameters

required

string

The ID of the Order Edit.

Responses

Response Schema: application/json

required

object (Order Edit)

Order edit allows modifying items in an order, such as adding, updating, or deleting items from the original order. Once the order edit is confirmed, the changes are reflected on the original order.

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 The details of the order that this order edit was created for.
	Array of objects (Order Item Change) The details of all the changes on the original order's line items.
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) The details of the cloned items from the original order with the new changes. Once the order edit is confirmed, these line items are associated with the original order.
	object (Payment Collection) A payment collection allows grouping and managing a list of payments at one. This can be helpful when making additional payment for order edits or integrating installment payments.

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"order_edit": {"id": "oe_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order_id": "order_01G2SG30J8C85S4A5CHM2S1NS2",
"order": { },
"changes": [{"id": null,
"type": null,
"order_edit_id": null,
"order_edit": { },
"original_line_item_id": null,
"original_line_item": null,
"line_item_id": null,
"line_item": null,
"created_at": null,
"updated_at": null,
"deleted_at": null
}
],
"internal_note": "Included two more items B to the order.",
"created_by": "string",
"requested_by": "string",
"requested_at": "2019-08-24T14:15:22Z",
"confirmed_by": "string",
"confirmed_at": "2019-08-24T14:15:22Z",
"declined_by": "string",
"declined_at": "2019-08-24T14:15:22Z",
"declined_reason": "string",
"canceled_by": "string",
"canceled_at": "2019-08-24T14:15:22Z",
"subtotal": 8000,
"discount_total": 800,
"shipping_total": 800,
"gift_card_total": 800,
"gift_card_tax_total": 800,
"tax_total": 0,
"total": 8200,
"difference_due": 8200,
"status": "confirmed",
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"payment_collection_id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": null,
"name": null,
"currency_code": null,
"currency": null,
"tax_rate": null,
"tax_rates": [ ],
"tax_code": null,
"gift_cards_taxable": null,
"automatic_taxes": null,
"countries": [ ],
"tax_provider_id": null,
"tax_provider": null,
"payment_providers": [ ],
"fulfillment_providers": [ ],
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"payment_sessions": [null
],
"payments": [null
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Decline an Order Edit

Decline an Order Edit. The changes are not reflected on the original order.

path Parameters

required

string

The ID of the OrderEdit.

Request Body schema: application/json

declined_reason

string

The reason for declining the Order Edit.

Responses

Response Schema: application/json

required

object (Order Edit)

Order edit allows modifying items in an order, such as adding, updating, or deleting items from the original order. Once the order edit is confirmed, the changes are reflected on the original order.

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 The details of the order that this order edit was created for.
	Array of objects (Order Item Change) The details of all the changes on the original order's line items.
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) The details of the cloned items from the original order with the new changes. Once the order edit is confirmed, these line items are associated with the original order.
	object (Payment Collection) A payment collection allows grouping and managing a list of payments at one. This can be helpful when making additional payment for order edits or integrating installment payments.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"declined_reason": "string"
}

Response samples

Content type

application/json

{"order_edit": {"id": "oe_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order_id": "order_01G2SG30J8C85S4A5CHM2S1NS2",
"order": { },
"changes": [{"id": null,
"type": null,
"order_edit_id": null,
"order_edit": { },
"original_line_item_id": null,
"original_line_item": null,
"line_item_id": null,
"line_item": null,
"created_at": null,
"updated_at": null,
"deleted_at": null
}
],
"internal_note": "Included two more items B to the order.",
"created_by": "string",
"requested_by": "string",
"requested_at": "2019-08-24T14:15:22Z",
"confirmed_by": "string",
"confirmed_at": "2019-08-24T14:15:22Z",
"declined_by": "string",
"declined_at": "2019-08-24T14:15:22Z",
"declined_reason": "string",
"canceled_by": "string",
"canceled_at": "2019-08-24T14:15:22Z",
"subtotal": 8000,
"discount_total": 800,
"shipping_total": 800,
"gift_card_total": 800,
"gift_card_tax_total": 800,
"tax_total": 0,
"total": 8200,
"difference_due": 8200,
"status": "confirmed",
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"payment_collection_id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": null,
"name": null,
"currency_code": null,
"currency": null,
"tax_rate": null,
"tax_rates": [ ],
"tax_code": null,
"gift_cards_taxable": null,
"automatic_taxes": null,
"countries": [ ],
"tax_provider_id": null,
"tax_provider": null,
"payment_providers": [ ],
"fulfillment_providers": [ ],
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"payment_sessions": [null
],
"payments": [null
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Orders

Orders are purchases made by customers, typically through a storefront. Orders are placed and created using the Carts endpoints. The Orders endpoints allow retrieving and claiming orders.

How to retrieve order details in a storefront

Look Up an Order

Look up an order using filters. If the filters don't narrow down the results to a single order, a 404 response is returned with no orders.

query Parameters

display_id required	number Filter by ID.
email required	string <email> Filter by email.
fields	string Comma-separated fields that should be expanded in the returned order.
expand	string Comma-separated relations that should be expanded in the returned order.
	object Filter by the shipping address's postal code.

Responses

Response Schema: application/json

required

object (Order)

An order is a purchase made by a customer. It holds details about payment and fulfillment of the order. An order may also be created from a draft order, which is created by an admin user.

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 See a list of codes.
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 was created from.
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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 ID of the region this order was created in.
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 The details of the cart associated with the order.
customer	object or null The details of the customer associated with the order.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	object (Currency) Currency
	Array of objects (Discount) The details of the discounts applied on the order.
	Array of objects (Gift Card) The details of the gift card used in the order.
	Array of objects (Shipping Method) The details of the shipping methods used in the order.
payments	Array of objects The details of the payments used in the order.
fulfillments	Array of objects The details of the fulfillments created for the order.
returns	Array of objects The details of the returns created for the order.
claims	Array of objects The details of the claims created for the order.
refunds	Array of objects The details of the refunds created for the order.
swaps	Array of objects The details of the swaps created for the order.
draft_order	object or null The details of the draft order this order was created from.
	Array of objects (Line Item) The details of the line items that belong to the order.
edits	Array of objects The details of the order edits done on the order.
	Array of objects (Gift Card Transaction) The gift card transactions made in the order.
sales_channel_id	string or null Example: null The ID of the sales channel this order belongs to.
	object (Sales Channel) A Sales Channel is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
raw_discount_total	integer Example: 800 The total of discount
discount_total	integer Example: 800 The total of discount rounded
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 details of the line items that are returnable as part of the order, swaps, or claims

Request samples

JS Client
cURL

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": {"id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"status": "pending",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"display_id": 2,
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": { },
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"currency_code": "usd",
"currency": {"code": "usd",
"symbol": "$",
"symbol_native": "$",
"name": "US Dollar",
"includes_tax": false
},
"tax_rate": 0,
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"payments": [{ }
],
"fulfillments": [{ }
],
"returns": [{ }
],
"claims": [{ }
],
"refunds": [{ }
],
"swaps": [{ }
],
"draft_order_id": null,
"draft_order": { },
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"edits": [{ }
],
"gift_card_transactions": [{"id": null,
"gift_card_id": null,
"gift_card": { },
"order_id": null,
"order": { },
"amount": null,
"created_at": null,
"is_taxable": null,
"tax_rate": null
}
],
"canceled_at": "2019-08-24T14:15:22Z",
"no_notification": false,
"idempotency_key": "string",
"external_id": null,
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_total": 1000,
"raw_discount_total": 800,
"discount_total": 800,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"paid_total": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0,
"returnable_items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Claim Order

Allow the logged-in customer to claim ownership of one or more orders. This generates a token that can be used later on to verify the claim using the endpoint Verify Order Claim. This also emits the event order-update-token.created. So, if you have a notification provider installed that handles this event and sends the customer a notification, such as an email, the customer should receive instructions on how to finalize their claim ownership.

How to implement claim-order flow in a storefront

Authorizations:

NoneCookie Session ID

Request Body schema: application/json

order_ids

required

Array of strings

The ID of the orders to claim

Responses

Request samples

Payload
JS Client
cURL

Content type

application/json

{"order_ids": ["string"
]
}

Response samples

Content type

application/json

Example

Not Allowed Error

{"message": "Discount must be set to dynamic",
"type": "not_allowed"
}

Get by Cart ID

Retrieve an Order's details 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

required

object (Order)

An order is a purchase made by a customer. It holds details about payment and fulfillment of the order. An order may also be created from a draft order, which is created by an admin user.

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 See a list of codes.
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 was created from.
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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 ID of the region this order was created in.
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 The details of the cart associated with the order.
customer	object or null The details of the customer associated with the order.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	object (Currency) Currency
	Array of objects (Discount) The details of the discounts applied on the order.
	Array of objects (Gift Card) The details of the gift card used in the order.
	Array of objects (Shipping Method) The details of the shipping methods used in the order.
payments	Array of objects The details of the payments used in the order.
fulfillments	Array of objects The details of the fulfillments created for the order.
returns	Array of objects The details of the returns created for the order.
claims	Array of objects The details of the claims created for the order.
refunds	Array of objects The details of the refunds created for the order.
swaps	Array of objects The details of the swaps created for the order.
draft_order	object or null The details of the draft order this order was created from.
	Array of objects (Line Item) The details of the line items that belong to the order.
edits	Array of objects The details of the order edits done on the order.
	Array of objects (Gift Card Transaction) The gift card transactions made in the order.
sales_channel_id	string or null Example: null The ID of the sales channel this order belongs to.
	object (Sales Channel) A Sales Channel is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
raw_discount_total	integer Example: 800 The total of discount
discount_total	integer Example: 800 The total of discount rounded
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 details of the line items that are returnable as part of the order, swaps, or claims

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.orders.retrieveByCartId(cartId)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

Content type

application/json

{"order": {"id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"status": "pending",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"display_id": 2,
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": { },
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"currency_code": "usd",
"currency": {"code": "usd",
"symbol": "$",
"symbol_native": "$",
"name": "US Dollar",
"includes_tax": false
},
"tax_rate": 0,
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"payments": [{ }
],
"fulfillments": [{ }
],
"returns": [{ }
],
"claims": [{ }
],
"refunds": [{ }
],
"swaps": [{ }
],
"draft_order_id": null,
"draft_order": { },
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"edits": [{ }
],
"gift_card_transactions": [{"id": null,
"gift_card_id": null,
"gift_card": { },
"order_id": null,
"order": { },
"amount": null,
"created_at": null,
"is_taxable": null,
"tax_rate": null
}
],
"canceled_at": "2019-08-24T14:15:22Z",
"no_notification": false,
"idempotency_key": "string",
"external_id": null,
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_total": 1000,
"raw_discount_total": 800,
"discount_total": 800,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"paid_total": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0,
"returnable_items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Verify Order Claim

Verify the claim order token provided to the customer when they request ownership of an order.

How to implement claim-order flow in a storefront

Authorizations:

NoneCookie Session ID

Request Body schema: application/json

token

required

string

The claim token generated by previous request to the Claim Order endpoint.

Responses

Request samples

Payload
JS Client
cURL

Content type

application/json

{"token": "string"
}

Response samples

Content type

application/json

Example

Not Allowed Error

{"message": "Discount must be set to dynamic",
"type": "not_allowed"
}

Get an Order

Retrieve an Order's details.

path Parameters

required

string

The ID of the Order.

query Parameters

fields	string Comma-separated fields that should be expanded in the returned order.
expand	string Comma-separated relations that should be included in the returned order.

Responses

Response Schema: application/json

required

object (Order)

An order is a purchase made by a customer. It holds details about payment and fulfillment of the order. An order may also be created from a draft order, which is created by an admin user.

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 See a list of codes.
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 was created from.
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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 ID of the region this order was created in.
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 The details of the cart associated with the order.
customer	object or null The details of the customer associated with the order.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	object (Region) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	object (Currency) Currency
	Array of objects (Discount) The details of the discounts applied on the order.
	Array of objects (Gift Card) The details of the gift card used in the order.
	Array of objects (Shipping Method) The details of the shipping methods used in the order.
payments	Array of objects The details of the payments used in the order.
fulfillments	Array of objects The details of the fulfillments created for the order.
returns	Array of objects The details of the returns created for the order.
claims	Array of objects The details of the claims created for the order.
refunds	Array of objects The details of the refunds created for the order.
swaps	Array of objects The details of the swaps created for the order.
draft_order	object or null The details of the draft order this order was created from.
	Array of objects (Line Item) The details of the line items that belong to the order.
edits	Array of objects The details of the order edits done on the order.
	Array of objects (Gift Card Transaction) The gift card transactions made in the order.
sales_channel_id	string or null Example: null The ID of the sales channel this order belongs to.
	object (Sales Channel) A Sales Channel is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
shipping_total	integer Example: 1000 The total of shipping
raw_discount_total	integer Example: 800 The total of discount
discount_total	integer Example: 800 The total of discount rounded
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 details of the line items that are returnable as part of the order, swaps, or claims

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"order": {"id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"status": "pending",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"display_id": 2,
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": { },
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"currency_code": "usd",
"currency": {"code": "usd",
"symbol": "$",
"symbol_native": "$",
"name": "US Dollar",
"includes_tax": false
},
"tax_rate": 0,
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"payments": [{ }
],
"fulfillments": [{ }
],
"returns": [{ }
],
"claims": [{ }
],
"refunds": [{ }
],
"swaps": [{ }
],
"draft_order_id": null,
"draft_order": { },
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"edits": [{ }
],
"gift_card_transactions": [{"id": null,
"gift_card_id": null,
"gift_card": { },
"order_id": null,
"order": { },
"amount": null,
"created_at": null,
"is_taxable": null,
"tax_rate": null
}
],
"canceled_at": "2019-08-24T14:15:22Z",
"no_notification": false,
"idempotency_key": "string",
"external_id": null,
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_total": 1000,
"raw_discount_total": 800,
"discount_total": 800,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"paid_total": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0,
"returnable_items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Payment Collections

A payment collection is useful for managing additional payments, such as for Order Edits, or installment payments.

Get a PaymentCollection

Retrieve a Payment Collection's details.

Authorizations:

NoneCookie Session ID

path Parameters

required

string

The ID of the PaymentCollection.

query Parameters

fields	string Comma-separated fields that should be expanded in the returned payment collection.
expand	string Comma-separated relations that should be expanded in the returned payment collection.

Responses

Response Schema: application/json

required

object (Payment Collection)

A payment collection allows grouping and managing a list of payments at one. This can be helpful when making additional payment for order edits or integrating installment payments.

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 this payment collection is associated with. See a list of codes.
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 Learn about the metadata attribute, and how to delete and update it.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The ID of the region this payment collection is associated with.
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) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	object (Currency) Currency
	Array of objects (Payment Session) The details of the payment sessions created as part of the payment collection.
	Array of objects (Payment) The details of the payments created as part of the payment collection.

Request samples

JS Client
cURL

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": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"currency_code": "usd",
"currency": {"code": "usd",
"symbol": "$",
"symbol_native": "$",
"name": "US Dollar",
"includes_tax": false
},
"payment_sessions": [{"id": null,
"cart_id": null,
"cart": null,
"provider_id": null,
"is_selected": null,
"is_initiated": null,
"status": null,
"data": { },
"idempotency_key": null,
"amount": null,
"payment_authorized_at": null,
"created_at": null,
"updated_at": null
}
],
"payments": [{"id": null,
"swap_id": null,
"swap": { },
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"amount": null,
"currency_code": null,
"currency": null,
"amount_refunded": null,
"provider_id": null,
"data": { },
"captured_at": null,
"canceled_at": null,
"idempotency_key": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Create a Payment Session

Create a Payment Session for a payment provider in a Payment Collection.

Authorizations:

NoneCookie Session ID

path Parameters

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

required

object (Payment Collection)

A payment collection allows grouping and managing a list of payments at one. This can be helpful when making additional payment for order edits or integrating installment payments.

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 this payment collection is associated with. See a list of codes.
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 Learn about the metadata attribute, and how to delete and update it.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The ID of the region this payment collection is associated with.
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) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	object (Currency) Currency
	Array of objects (Payment Session) The details of the payment sessions created as part of the payment collection.
	Array of objects (Payment) The details of the payments created as part of the payment collection.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"provider_id": "string"
}

Response samples

Content type

application/json

{"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"currency_code": "usd",
"currency": {"code": "usd",
"symbol": "$",
"symbol_native": "$",
"name": "US Dollar",
"includes_tax": false
},
"payment_sessions": [{"id": null,
"cart_id": null,
"cart": null,
"provider_id": null,
"is_selected": null,
"is_initiated": null,
"status": null,
"data": { },
"idempotency_key": null,
"amount": null,
"payment_authorized_at": null,
"created_at": null,
"updated_at": null
}
],
"payments": [{"id": null,
"swap_id": null,
"swap": { },
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"amount": null,
"currency_code": null,
"currency": null,
"amount_refunded": null,
"provider_id": null,
"data": { },
"captured_at": null,
"canceled_at": null,
"idempotency_key": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Manage Payment Sessions

Create, update, or delete a list of payment sessions of a Payment Collections. If a payment session is not provided in the sessions array, it's deleted.

Authorizations:

NoneCookie Session ID

path Parameters

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. Existing sessions that are not added in this array will be deleted.

Array

provider_id required	string The ID of the Payment Provider.
amount required	integer The payment amount
session_id	string The ID of the Payment Session to be updated. If no ID is provided, a new payment session is created.

Responses

Response Schema: application/json

required

object (Payment Collection)

A payment collection allows grouping and managing a list of payments at one. This can be helpful when making additional payment for order edits or integrating installment payments.

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 this payment collection is associated with. See a list of codes.
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 Learn about the metadata attribute, and how to delete and update it.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The ID of the region this payment collection is associated with.
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) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	object (Currency) Currency
	Array of objects (Payment Session) The details of the payment sessions created as part of the payment collection.
	Array of objects (Payment) The details of the payments created as part of the payment collection.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"sessions": [{"provider_id": "string",
"amount": 0,
"session_id": "string"
}
]
}

Response samples

Content type

application/json

{"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"currency_code": "usd",
"currency": {"code": "usd",
"symbol": "$",
"symbol_native": "$",
"name": "US Dollar",
"includes_tax": false
},
"payment_sessions": [{"id": null,
"cart_id": null,
"cart": null,
"provider_id": null,
"is_selected": null,
"is_initiated": null,
"status": null,
"data": { },
"idempotency_key": null,
"amount": null,
"payment_authorized_at": null,
"created_at": null,
"updated_at": null
}
],
"payments": [{"id": null,
"swap_id": null,
"swap": { },
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"amount": null,
"currency_code": null,
"currency": null,
"amount_refunded": null,
"provider_id": null,
"data": { },
"captured_at": null,
"canceled_at": null,
"idempotency_key": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Authorize PaymentSessions

Authorize the Payment Sessions of a Payment Collection.

Authorizations:

NoneCookie Session ID

path Parameters

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

required

object (Payment Collection)

A payment collection allows grouping and managing a list of payments at one. This can be helpful when making additional payment for order edits or integrating installment payments.

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 this payment collection is associated with. See a list of codes.
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 Learn about the metadata attribute, and how to delete and update it.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The ID of the region this payment collection is associated with.
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) A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	object (Currency) Currency
	Array of objects (Payment Session) The details of the payment sessions created as part of the payment collection.
	Array of objects (Payment) The details of the payments created as part of the payment collection.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"session_ids": ["string"
]
}

Response samples

Content type

application/json

{"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"currency_code": "usd",
"currency": {"code": "usd",
"symbol": "$",
"symbol_native": "$",
"name": "US Dollar",
"includes_tax": false
},
"payment_sessions": [{"id": null,
"cart_id": null,
"cart": null,
"provider_id": null,
"is_selected": null,
"is_initiated": null,
"status": null,
"data": { },
"idempotency_key": null,
"amount": null,
"payment_authorized_at": null,
"created_at": null,
"updated_at": null
}
],
"payments": [{"id": null,
"swap_id": null,
"swap": { },
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"amount": null,
"currency_code": null,
"currency": null,
"amount_refunded": null,
"provider_id": null,
"data": { },
"captured_at": null,
"canceled_at": null,
"idempotency_key": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Refresh a Payment Session

Refresh a Payment Session's data 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

required

object (Payment Session)

A Payment Session is 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, which 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 payment processing such as capture or refund. Payment sessions can also be used as part of payment collections.

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 was 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. Learn more how to use the idempotency key.
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) A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"payment_session": {"id": "ps_01G901XNSRM2YS3ASN9H5KG3FZ",
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"items": [null
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": null,
"name": null,
"currency_code": null,
"currency": null,
"tax_rate": null,
"tax_rates": [ ],
"tax_code": null,
"gift_cards_taxable": null,
"automatic_taxes": null,
"countries": [ ],
"tax_provider_id": null,
"tax_provider": null,
"payment_providers": [ ],
"fulfillment_providers": [ ],
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"discounts": [null
],
"gift_cards": [null
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [null
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": null,
"name": null,
"description": null,
"is_disabled": null,
"locations": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
},
"provider_id": "manual",
"is_selected": true,
"is_initiated": true,
"status": "pending",
"data": { },
"idempotency_key": "string",
"amount": 100,
"payment_authorized_at": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Authorize Payment Session

Authorize 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

required

object (Payment Session)

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 was 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. Learn more how to use the idempotency key.
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) A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

Request samples

JS Client
cURL

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(paymentId, sessionId)
.then(({ payment_collection }) => {
  console.log(payment_collection.id);
});

Response samples

Content type

application/json

{"payment_session": {"id": "ps_01G901XNSRM2YS3ASN9H5KG3FZ",
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"items": [null
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": null,
"name": null,
"currency_code": null,
"currency": null,
"tax_rate": null,
"tax_rates": [ ],
"tax_code": null,
"gift_cards_taxable": null,
"automatic_taxes": null,
"countries": [ ],
"tax_provider_id": null,
"tax_provider": null,
"payment_providers": [ ],
"fulfillment_providers": [ ],
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"discounts": [null
],
"gift_cards": [null
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [null
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": null,
"name": null,
"description": null,
"is_disabled": null,
"locations": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"raw_discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
},
"provider_id": "manual",
"is_selected": true,
"is_initiated": true,
"status": "pending",
"data": { },
"idempotency_key": "string",
"amount": 100,
"payment_authorized_at": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Product Categories

Products can be categoriezed into categories. A product can be associated more than one category. Using these endpoints, you can list or retrieve a category's details and products.

How to use product categories in a storefront

List Product Categories

Retrieve a list of product categories. The product categories can be filtered by fields such as handle or q. The product categories can also be paginated. This endpoint can also be used to retrieve a product category by its handle.

How to retrieve a product category by its handle

Authorizations:

NoneCookie Session ID

query Parameters

q	string term used to search product category's names and handles.
handle	string Filter by handle.
parent_category_id	string Filter by the ID of a parent category. Only children of the provided parent category are retrieved.
include_descendants_tree	boolean Whether all nested categories inside a category should be retrieved.
offset	integer Default: 0 The number of product categories to skip when retrieving the product categories.
limit	integer Default: 100 Limit the number of product categories returned.
expand	string Comma-separated relations that should be expanded in the returned product categories.
fields	string Comma-separated fields that should be included in the returned product categories.

Responses

Response Schema: application/json

required	Array of objects (Product Category) An array of product categories details.
count required	integer The total number of items available
offset required	integer The number of product categories skipped when retrieving the product categories.
limit required	integer The number of items per page

Request samples

JS Client
cURL

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": [{"id": "pcat_01G2SG30J8C85S4A5CHM2S1NS2",
"name": "Regular Fit",
"handle": "regular-fit",
"mpath": "pcat_id1.pcat_id2.pcat_id3",
"is_internal": false,
"is_active": false,
"rank": 0,
"category_children": [{ }
],
"parent_category_id": null,
"parent_category": { },
"products": [{ }
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Get a Product Category

Retrieve a Product Category's details.

Authorizations:

NoneCookie Session ID

path Parameters

required

string

The ID of the Product Category

query Parameters

fields	string Comma-separated fields that should be expanded in the returned product category.
expand	string Comma-separated relations that should be expanded in the returned product category.

Responses

Response Schema: application/json

required

object (Product Category)

A product category can be used to categorize products into a hierarchy of categories.

category_children required	Array of objects The details of the category's children.
created_at required	string <date-time> The date with timezone at which the resource was created.
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.
rank	integer Default: 0 An integer that depicts the rank of category in a tree node
parent_category	object or null The details of the parent of this category.
products	Array of objects The details of the products that belong to this category.

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"product_category": {"id": "pcat_01G2SG30J8C85S4A5CHM2S1NS2",
"name": "Regular Fit",
"handle": "regular-fit",
"mpath": "pcat_id1.pcat_id2.pcat_id3",
"is_internal": false,
"is_active": false,
"rank": 0,
"category_children": [{ }
],
"parent_category_id": null,
"parent_category": { },
"products": [{ }
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Product Collections

A product collection is used to organize products for different purposes such as marketing or discount purposes. For example, you can create a Summer Collection. Using these endpoints, you can list or retrieve a collection's details and products.

List Collections

Retrieve a list of product collections. The product collections can be filtered by fields such as handle or created_at. The product collections can also be paginated.

query Parameters

offset	integer Default: 0 The number of product collections to skip when retrieving the product collections.
limit	integer Default: 10 Limit the number of product collections returned.
handle	Array of strings Filter by handles
	object Filter by a creation date range.
	object Filter by an update date range.

Responses

Response Schema: application/json

required	Array of objects (Product Collection) An array of product collections details
count required	integer The total number of items available
offset required	integer The number of product collections skipped when retrieving the product collections.
limit required	integer The number of items per page

Request samples

JS Client
cURL

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": [{"id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
"title": "Summer Collection",
"handle": "summer-collection",
"products": [{ }
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Get a Collection

Retrieve a Product Collection's details.

path Parameters

required

string

The id of the Product Collection

Responses

Response Schema: application/json

required

object (Product Collection)

A Product Collection allows grouping together products for promotional purposes. For example, an admin can create a Summer collection, add products to it, and showcase it on the storefront.

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 Learn about the metadata attribute, and how to delete and update it.
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 details of the products that belong to this product collection.

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"collection": {"id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
"title": "Summer Collection",
"handle": "summer-collection",
"products": [{ }
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Product Tags

Product tags are string values that can be used to filter products by. Products can have more than one tag, and products can share tags.

List Product Tags

Retrieve a list of product tags. The product tags can be filtered by fields such as id or q. The product tags can also be sorted or paginated.

query Parameters

limit	integer Default: 20 Limit the number of product tags returned.
offset	integer Default: 0 The number of product tags to skip when retrieving the product tags.
order	string A product-tag field to sort-order the retrieved product tags by.
discount_condition_id	string Filter by the ID of a discount condition. When provided, only tags that the discount condition applies for will be retrieved.
value	Array of strings Filter by tag values.
id	Array of strings Filter by IDs.
q	string term to search product tag's value.
	object Filter by a creation date range.
	object Filter by an update date range.

Responses

Response Schema: application/json

required	Array of objects (Product Tag) An array of product tags details.
count required	integer The total number of items available
offset required	integer The number of product tags skipped when retrieving the product tags.
limit required	integer The number of items per page

Request samples

JS Client
cURL

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": [{"id": "ptag_01G8K2MTMG9168F2B70S1TAVK3",
"value": "Pants",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Product Types

Product types are string values that can be used to filter products by. Products can have more than one tag, and products can share types.

List Product Types

Retrieve a list of product types. The product types can be filtered by fields such as value or q. The product types can also be sorted or paginated.

Authorizations:

NoneCookie Session ID

query Parameters

limit	integer Default: 20 Limit the number of product types returned.
offset	integer Default: 0 The number of product types to skip when retrieving the product types.
order	string A product-type field to sort-order the retrieved product types by.
discount_condition_id	string Filter by the ID of a discount condition. When provided, only types that the discount condition applies for will be retrieved.
value	Array of strings Filter by type values.
id	Array of strings Filter by IDs.
q	string term to search product type's value.
	object Filter by a creation date range.
	object Filter by an update date range.

Responses

Response Schema: application/json

required	Array of objects (Product Type) An array of product types details.
count required	integer The total number of items available
offset required	integer The number of product types skipped when retrieving the product types.
limit required	integer The number of items per page

Request samples

JS Client
cURL

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": [{"id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
"value": "Clothing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Product Variants

Product variants are the actual salable item in your store. Each variant is a combination of the different option values available on the product.

Get Product Variants

Retrieves a list of product variants. The product variants can be filtered by fields such as id or title. The product variants can also be paginated.

For accurate and correct pricing of the product variants based on the customer's context, it's highly recommended to pass fields such as region_id, currency_code, and cart_id when available.

Passing sales_channel_id ensures retrieving only variants of products available in the specified sales channel. You can alternatively use a publishable API key in the request header instead of passing a sales_channel_id.

How to pass product pricing parameters

query Parameters

ids	string Filter by a comma-separated list of IDs. If supplied, it overrides the `id` parameter.
	string or Array of strings Filter by one or more IDs. If `ids` is supplied, it's overrides the value of this parameter.
sales_channel_id	string "Filter by sales channel IDs. When provided, only products available in the selected sales channels are retrieved. Alternatively, you can pass a publishable API key in the request header and this will have the same effect."
expand	string Comma-separated relations that should be expanded in the returned product variants.
fields	string Comma-separated fields that should be included in the returned product variants.
offset	number Default: "0" The number of products to skip when retrieving the product variants.
limit	number Default: "100" Limit the number of product variants returned.
cart_id	string The ID of the cart. This is useful for accurate pricing based on the cart's context.
region_id	string The ID of the region. This is useful for accurate pricing based on the selected region.
currency_code	string A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency. See a list of codes.
	string or Array of strings Filter by title
	number or object Filter by available inventory quantity

Responses

Response Schema: application/json

required

Array of objects (Priced Product Variant)

An array of product variant descriptions.

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 Learn about the metadata attribute, and how to delete and update it.
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 The details of the product that the product variant belongs to.
	Array of objects (Money Amount) The details of the prices of the Product Variant, each represented as a Money Amount. Each Money Amount represents a price in a given currency or a specific Region.
variant_rank	number or null Default: 0 The ranking of this variant
	Array of objects (Product Option Value) The details of the product options that this product variant defines values for.
	Array of objects (Product Variant Inventory Item) The details inventory items of the product variant.
purchasable	boolean Only used with the inventory modules. A boolean value indicating whether the Product Variant is purchasable. A variant is purchasable if: inventory is not managed it has no inventory items it is in stock it is backorderable.
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

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

Response samples

Content type

application/json

{"variants": [{"id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
"title": "Small",
"product_id": "prod_01G1G5V2MBA328390B5AXJ610F",
"product": { },
"prices": [null
],
"sku": "shirt-123",
"barcode": null,
"ean": null,
"upc": null,
"variant_rank": 0,
"inventory_quantity": 100,
"allow_backorder": false,
"manage_inventory": true,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"weight": null,
"length": null,
"height": null,
"width": null,
"options": [null
],
"inventory_items": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"purchasable": true,
"original_price": 0,
"calculated_price": 0,
"original_price_incl_tax": 0,
"calculated_price_incl_tax": 0,
"original_tax": 0,
"calculated_tax": 0,
"tax_rates": [{ }
]
}
]
}

Get a Product Variant

Retrieve a Product Variant's details. For accurate and correct pricing of the product variant based on the customer's context, it's highly recommended to pass fields such as region_id, currency_code, and cart_id when available.

Passing sales_channel_id ensures retrieving only variants of products available in the current sales channel. You can alternatively use a publishable API key in the request header instead of passing a sales_channel_id.

How to pass product pricing parameters

path Parameters

required

string

The ID of the Product Variant.

query Parameters

sales_channel_id	string The ID of the sales channel the customer is viewing the product variant from.
cart_id	string The ID of the cart. This is useful for accurate pricing based on the cart's context.
region_id	string The ID of the region. This is useful for accurate pricing based on the selected region.
currency_code	string A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency. See a list of codes.

Responses

Response Schema: application/json

required

object (Priced Product Variant)

A Product Variant represents 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. A product must at least have one product variant.

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 Learn about the metadata attribute, and how to delete and update it.
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 The details of the product that the product variant belongs to.
	Array of objects (Money Amount) The details of the prices of the Product Variant, each represented as a Money Amount. Each Money Amount represents a price in a given currency or a specific Region.
variant_rank	number or null Default: 0 The ranking of this variant
	Array of objects (Product Option Value) The details of the product options that this product variant defines values for.
	Array of objects (Product Variant Inventory Item) The details inventory items of the product variant.
purchasable	boolean Only used with the inventory modules. A boolean value indicating whether the Product Variant is purchasable. A variant is purchasable if: inventory is not managed it has no inventory items it is in stock it is backorderable.
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

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

Response samples

Content type

application/json

{"variant": {"id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
"title": "Small",
"product_id": "prod_01G1G5V2MBA328390B5AXJ610F",
"product": { },
"prices": [{"id": null,
"currency_code": null,
"currency": null,
"amount": null,
"min_quantity": null,
"max_quantity": null,
"price_list_id": null,
"price_list": { },
"variant_id": null,
"variant": { },
"region_id": null,
"region": { },
"created_at": null,
"updated_at": null,
"deleted_at": null
}
],
"sku": "shirt-123",
"barcode": null,
"ean": null,
"upc": null,
"variant_rank": 0,
"inventory_quantity": 100,
"allow_backorder": false,
"manage_inventory": true,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"weight": null,
"length": null,
"height": null,
"width": null,
"options": [{"id": null,
"value": null,
"option_id": null,
"option": { },
"variant_id": null,
"variant": { },
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"inventory_items": [{"id": null,
"inventory_item_id": null,
"variant_id": null,
"variant": { },
"required_quantity": null,
"created_at": null,
"updated_at": null,
"deleted_at": null
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"purchasable": true,
"original_price": 0,
"calculated_price": 0,
"original_price_incl_tax": 0,
"calculated_price_incl_tax": 0,
"original_tax": 0,
"calculated_tax": 0,
"tax_rates": [{"rate": null,
"name": null,
"code": null
}
]
}
}

Products

Products are saleable items in a store. This also includes saleable gift cards in a store. Using these endpoints, you can filter products by categories, collections, sales channels, and more.

How to show products in a storefront

List Products

Retrieves a list of products. The products can be filtered by fields such as id or q. The products can also be sorted or paginated. This endpoint can also be used to retrieve a product by its handle.

For accurate and correct pricing of the products based on the customer's context, it's highly recommended to pass fields such as region_id, currency_code, and cart_id when available.

Passing sales_channel_id ensures retrieving only products available in the specified sales channel. You can alternatively use a publishable API key in the request header instead of passing a sales_channel_id.

How to retrieve a product by its handle

query Parameters

q	string term used to search products' title, description, variant's title, variant's sku, and collection's title.
	string or Array of strings Filter by IDs.
sales_channel_id	Array of strings Filter by sales channel IDs. When provided, only products available in the selected sales channels are retrieved. Alternatively, you can pass a publishable API key in the request header and this will have the same effect.
collection_id	Array of strings Filter by product collection IDs. When provided, only products that belong to the specified product collections are retrieved.
type_id	Array of strings Filter by product type IDs. When provided, only products that belong to the specified product types are retrieved.
tags	Array of strings Filter by product tag IDs. When provided, only products that belong to the specified product tags are retrieved.
title	string Filter by title.
description	string Filter by description
handle	string Filter by handle.
is_giftcard	boolean Whether to retrieve regular products or gift-card products.
	object Filter by a creation date range.
	object Filter by an update date range.
category_id	Array of strings Filter by product category IDs. When provided, only products that belong to the specified product categories are retrieved.
include_category_children	boolean Whether to include child product categories when filtering using the `category_id` field.
offset	integer Default: 0 The number of products to skip when retrieving the products.
limit	integer Default: 100 Limit the number of products returned.
expand	string Comma-separated relations that should be expanded in the returned products.
fields	string Comma-separated fields that should be included in the returned products.
order	string A product field to sort-order the retrieved products by.
cart_id	string The ID of the cart. This is useful for accurate pricing based on the cart's context.
region_id	string The ID of the region. This is useful for accurate pricing based on the selected region.
currency_code	string A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency. See a list of codes.

Responses

Response Schema: application/json

required	Array of objects (Priced Product) An array of products details.
count required	integer The total number of items available
offset required	integer The number of products skipped when retrieving the products.
limit required	integer The number of items per page

Request samples

JS Client
cURL

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": [{"id": "prod_01G1G5V2MBA328390B5AXJ610F",
"title": "Medusa Coffee Mug",
"subtitle": "string",
"description": "Every programmer's best friend.",
"handle": "coffee-mug",
"is_giftcard": false,
"status": "draft",
"images": [null
],
"thumbnail": "http://example.com",
"options": [null
],
"variants": [null
],
"categories": [null
],
"profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
"profile": {"id": null,
"name": null,
"type": null,
"products": [ ],
"shipping_options": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"profiles": [null
],
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
"collection": {"id": null,
"title": null,
"handle": null,
"products": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"type_id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
"type": {"id": null,
"value": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"tags": [null
],
"discountable": true,
"external_id": null,
"sales_channels": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Search Products

Run a search query on products using the search service installed on the Medusa backend. The searching is handled through the search service, so the returned data's format depends on the search service you're using.

Request Body schema: application/json

q	string The search query.
offset	number The number of products to skip when retrieving the products.
limit	number Limit the number of products returned.
filter	any Pass filters based on the search service.

Responses

Response Schema: application/json

hits

required

Array of arrays

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

Request samples

Payload
JS Client
cURL

Content type

application/json

{"q": "string",
"offset": 0,
"limit": 0,
"filter": null
}

Response samples

Content type

application/json

{"hits": [ ]
}

Get a Product

Retrieve a Product's details. For accurate and correct pricing of the product based on the customer's context, it's highly recommended to pass fields such as region_id, currency_code, and cart_id when available.

Passing sales_channel_id ensures retrieving only products available in the current sales channel. You can alternatively use a publishable API key in the request header instead of passing a sales_channel_id.

How to pass product pricing parameters

path Parameters

required

string

The ID of the Product.

query Parameters

sales_channel_id	string The ID of the sales channel the customer is viewing the product from.
cart_id	string The ID of the cart. This is useful for accurate pricing based on the cart's context.
region_id	string The ID of the region. This is useful for accurate pricing based on the selected region.
expand	string Comma-separated relations that should be expanded in the returned product.
fields	string Comma-separated fields that should be included in the returned product.
currency_code	string A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency. See a list of codes.

Responses

Response Schema: application/json

required

object (Priced Product)

A product is a saleable item that holds general information such as name or description. It must include at least one Product Variant, where each product variant defines different options to purchase the product with (for example, different sizes or colors). The prices and inventory of the product are defined on the variant level.

collection_id required	string or null Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG" The ID of 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 Learn about the metadata attribute, and how to delete and update it.
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. The shipping profile has a set of defined shipping options that can be used to fulfill the product.
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 ID of 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) The details of the product's images.
	Array of objects (Product Option) The details of the Product Options that are defined for the Product. The product's variants will have a unique combination of values of the product's options.
	Array of objects (Product Variant) The details of the Product Variants that belong to the Product. Each will have a unique combination of values of the product's options.
	Array of objects (Product Category) The details of the product categories that this product belongs to.
	object (Shipping Profile) A Shipping Profile has a set of defined Shipping Options that can be used to fulfill a given set of Products. For example, gift cards are shipped differently than physical products, so a shipping profile with the type `gift_card` groups together the shipping options that can only be used for gift cards.
	Array of objects or null (Shipping Profile) Available if the relation `profiles` is expanded.
	object (Product Collection) A Product Collection allows grouping together products for promotional purposes. For example, an admin can create a Summer collection, add products to it, and showcase it on the storefront.
	object (Product Type) A Product Type can be added to Products for filtering and reporting purposes.
	Array of objects (Product Tag) The details of the product tags used in this product.
	Array of objects (Sales Channel) The details of the sales channels this product is available in.

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"product": {"id": "prod_01G1G5V2MBA328390B5AXJ610F",
"title": "Medusa Coffee Mug",
"subtitle": "string",
"description": "Every programmer's best friend.",
"handle": "coffee-mug",
"is_giftcard": false,
"status": "draft",
"images": [{"id": null,
"url": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"thumbnail": "http://example.com",
"options": [{"id": null,
"title": null,
"values": [ ],
"product_id": null,
"product": { },
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"variants": [{"id": null,
"title": null,
"product_id": null,
"product": { },
"prices": [ ],
"sku": null,
"barcode": null,
"ean": null,
"upc": null,
"variant_rank": null,
"inventory_quantity": null,
"allow_backorder": null,
"manage_inventory": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"weight": null,
"length": null,
"height": null,
"width": null,
"options": [ ],
"inventory_items": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { },
"purchasable": null,
"original_price": null,
"calculated_price": null,
"original_price_incl_tax": null,
"calculated_price_incl_tax": null,
"original_tax": null,
"calculated_tax": null,
"tax_rates": [ ]
}
],
"categories": [{"id": null,
"name": null,
"handle": null,
"mpath": null,
"is_internal": null,
"is_active": null,
"rank": null,
"category_children": [ ],
"parent_category_id": null,
"parent_category": { },
"products": [ ],
"created_at": null,
"updated_at": null
}
],
"profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
"profile": {"id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
"name": "Default Shipping Profile",
"type": "default",
"products": [{ }
],
"shipping_options": [{ }
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"profiles": [{"id": null,
"name": null,
"type": null,
"products": [ ],
"shipping_options": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
"collection": {"id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
"title": "Summer Collection",
"handle": "summer-collection",
"products": [{ }
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"type_id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
"type": {"id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
"value": "Clothing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"tags": [{"id": null,
"value": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"discountable": true,
"external_id": null,
"sales_channels": [{"id": null,
"name": null,
"description": null,
"is_disabled": null,
"locations": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Regions

Regions are different countries or geographical regions that the commerce store serves customers in. Customers can choose what region they're in, which can be used to change the prices shown based on the region and its currency.

How to use regions in a storefront

List Regions

Retrieve a list of regions. The regions can be filtered by fields such as created_at. The regions can also be paginated. This endpoint is useful to show the customer all available regions to choose from.

How to use regions in a storefront

query Parameters

offset	integer Default: 0 The number of regions to skip when retrieving the regions.
limit	integer Default: 100 Limit the number of regions returned.
	object Filter by a creation date range.
	object Filter by an update date range.

Responses

Response Schema: application/json

required	Array of objects (Region) An array of regions details.
count	integer The total number of items available
offset	integer The number of regions skipped when retrieving the regions.
limit	integer The number of items per page

Request samples

JS Client
cURL

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": [{"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Get a Region

Retrieve a Region's details.

path Parameters

required

string

The ID of the Region.

Responses

Response Schema: application/json

required

object (Region)

A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. 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 used in the region. See a list of codes.
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 Learn about the metadata attribute, and how to delete and update it.
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 details of the tax rates used in the region, aside from the default rate.
	Array of objects (Country) The details of the countries included in this region.
	object (Tax Provider) A tax provider represents a tax service installed in the Medusa backend, either through a plugin or backend customizations. It holds the tax service's installation status.
	Array of objects (Payment Provider) The details of the payment providers that can be used to process payments in the region.
	Array of objects (Fulfillment Provider) The details of the fulfillment providers that can be used to fulfill items of orders and similar resources in the region.
includes_tax	boolean Default: false Whether the prices for the region include tax

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": "usd",
"symbol": "$",
"symbol_native": "$",
"name": "US Dollar",
"includes_tax": false
},
"tax_rate": 0,
"tax_rates": [{"id": null,
"rate": null,
"code": null,
"name": null,
"region_id": null,
"region": { },
"products": [ ],
"product_types": [ ],
"shipping_options": [ ],
"product_count": null,
"product_type_count": null,
"shipping_option_count": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [{"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
}
],
"tax_provider_id": null,
"tax_provider": {"id": "manual",
"is_installed": true
},
"payment_providers": [{"id": null,
"is_installed": null
}
],
"fulfillment_providers": [{"id": null,
"is_installed": null
}
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Return Reasons

Return reasons are key-value pairs that are used to specify why an order return is being created.

List Return Reasons

Retrieve a list of Return Reasons. This is useful when implementing a Create Return flow in the storefront.

Responses

Response Schema: application/json

required

Array of objects (Return Reason)

An array of return reasons details.

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 Learn about the metadata attribute, and how to delete and update it.
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 The details of the parent reason.
return_reason_children	object The details of the child reasons.

Request samples

JS Client
cURL

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": [{"id": "rr_01G8X82GCCV2KSQHDBHSSAH5TQ",
"value": "damaged",
"label": "Damaged goods",
"description": "Items that are damaged",
"parent_return_reason_id": null,
"parent_return_reason": { },
"return_reason_children": { },
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
]
}

Get a Return Reason

Retrieve a Return Reason's details.

path Parameters

required

string

The id of the Return Reason.

Responses

Response Schema: application/json

required

object (Return Reason)

A Return Reason is a value defined by an admin. It 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 Learn about the metadata attribute, and how to delete and update it.
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 The details of the parent reason.
return_reason_children	object The details of the child reasons.

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"return_reason": {"id": "rr_01G8X82GCCV2KSQHDBHSSAH5TQ",
"value": "damaged",
"label": "Damaged goods",
"description": "Items that are damaged",
"parent_return_reason_id": null,
"parent_return_reason": { },
"return_reason_children": { },
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Returns

A return can be created by a customer to return items in an order.

How to create a return in a storefront

Create Return

Create a Return for an Order. If a return shipping method is specified, the return is automatically fulfilled.

How to create a return in a storefront

Request Body schema: application/json

order_id required	string The ID of the Order to create the return for.
required	Array of objects The items to include in the return.
	object The return shipping method used to return the items. If provided, a fulfillment is automatically created for the return.

Responses

Response Schema: application/json

required

object (Return)

A Return holds information about Line Items that a Customer wishes to send back, along with how the items will be returned. Returns can also be used as part of a Swap or a Claim.

claim_order_id required	string or null Example: null The ID of the claim that the return may belong to.
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. Learn more how to use the idempotency key.
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 Learn about the metadata attribute, and how to delete and update it.
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 was created for.
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 may belong to.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	Array of objects (Return Item) The details of the items that the customer is returning.
swap	object or null The details of the swap that the return may belong to.
claim_order	object or null The details of the claim that the return may belong to.
order	object or null The details of the order that the return was created for.
	object (Shipping Method) A Shipping Method represents a way in which an Order or Return can be shipped. Shipping Methods are created from a Shipping Option, but may contain additional details that can be necessary for the Fulfillment Provider to handle the shipment. If the shipping method is created for a return, it may be associated with a claim or a swap that the return is part of.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"order_id": "string",
"items": [{"item_id": "string",
"quantity": 0,
"reason_id": "string",
"note": "string"
}
],
"return_shipping": {"option_id": "string"
}
}

Response samples

Content type

application/json

{"return": {"id": "ret_01F0YET7XPCMF8RZ0Y151NZV2V",
"status": "requested",
"items": [{"return_id": null,
"item_id": null,
"return_order": { },
"item": null,
"quantity": null,
"is_requested": null,
"requested_quantity": null,
"received_quantity": null,
"reason_id": null,
"reason": null,
"note": null,
"metadata": { }
}
],
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order": { },
"shipping_method": {"id": "sm_01F0YET7DR2E7CYVSDHM593QG2",
"shipping_option_id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
"order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": {"id": null,
"name": null,
"region_id": null,
"region": { },
"profile_id": null,
"profile": null,
"provider_id": null,
"provider": null,
"price_type": null,
"amount": null,
"is_return": null,
"admin_only": null,
"requirements": [ ],
"data": { },
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"tax_lines": [null
],
"price": 200,
"data": { },
"includes_tax": false,
"subtotal": 8000,
"total": 8200,
"tax_total": 0
},
"shipping_data": { },
"location_id": "sloc_01G8TJSYT9M6AVS5N4EMNFS1EK",
"refund_amount": 1000,
"no_notification": false,
"idempotency_key": "string",
"received_at": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Shipping Options

A shipping option is used to define the available shipping methods during checkout or when creating a return.

Shipping Option architecture

Get Shipping Options

Retrieve 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 "Comma-separated list of Product IDs to filter Shipping Options by. If provided, only shipping options that can be used with the provided products are retrieved."
region_id	string "The ID of the region that the shipping options belong to. If not provided, all shipping options are retrieved."

Responses

Response Schema: application/json

required

Array of objects (Priced Shipping Option)

An array of shipping options details.

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 Learn about the metadata attribute, and how to delete and update it.
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.
provider_id required	string Example: "manual" The ID of the fulfillment provider that will be used to later to process the shipping method created from this shipping option and its fulfillments.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The ID of the region this shipping option can be used in.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
region	object or null The details of the region this shipping option can be used in.
	object (Shipping Profile) A Shipping Profile has a set of defined Shipping Options that can be used to fulfill a given set of Products. For example, gift cards are shipped differently than physical products, so a shipping profile with the type `gift_card` groups together the shipping options that can only be used for gift cards.
	object (Fulfillment Provider) A fulfillment provider represents a fulfillment service installed in the Medusa backend, either through a plugin or backend customizations. It holds the fulfillment service's installation status.
	Array of objects (Shipping Option Requirement) The details of the requirements that must be satisfied for the Shipping Option to be available for usage in a Cart.
includes_tax	boolean Default: false Whether the shipping option price include tax
price_incl_tax	number Price including taxes
	Array of objects An array of applied tax rates
tax_amount	number The taxes applied.

Request samples

JS Client
cURL

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": [{"id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
"name": "PostFake Standard",
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": { },
"profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
"profile": {"id": null,
"name": null,
"type": null,
"products": [ ],
"shipping_options": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"provider_id": "manual",
"provider": {"id": null,
"is_installed": null
},
"price_type": "flat_rate",
"amount": 200,
"is_return": false,
"admin_only": false,
"requirements": [null
],
"data": { },
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"price_incl_tax": 0,
"tax_rates": [{ }
],
"tax_amount": 0
}
]
}

List for Cart

Retrieve a list of Shipping Options available for a cart.

How to implement shipping step in checkout

path Parameters

cart_id

required

string

The ID of the Cart.

Responses

Response Schema: application/json

required

Array of objects (Priced Shipping Option)

An array of shipping options details.

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 Learn about the metadata attribute, and how to delete and update it.
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.
provider_id required	string Example: "manual" The ID of the fulfillment provider that will be used to later to process the shipping method created from this shipping option and its fulfillments.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The ID of the region this shipping option can be used in.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
region	object or null The details of the region this shipping option can be used in.
	object (Shipping Profile) A Shipping Profile has a set of defined Shipping Options that can be used to fulfill a given set of Products. For example, gift cards are shipped differently than physical products, so a shipping profile with the type `gift_card` groups together the shipping options that can only be used for gift cards.
	object (Fulfillment Provider) A fulfillment provider represents a fulfillment service installed in the Medusa backend, either through a plugin or backend customizations. It holds the fulfillment service's installation status.
	Array of objects (Shipping Option Requirement) The details of the requirements that must be satisfied for the Shipping Option to be available for usage in a Cart.
includes_tax	boolean Default: false Whether the shipping option price include tax
price_incl_tax	number Price including taxes
	Array of objects An array of applied tax rates
tax_amount	number The taxes applied.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.shippingOptions.listCartOptions(cartId)
.then(({ shipping_options }) => {
  console.log(shipping_options.length);
});

Response samples

Content type

application/json

{"shipping_options": [{"id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
"name": "PostFake Standard",
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": { },
"profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
"profile": {"id": null,
"name": null,
"type": null,
"products": [ ],
"shipping_options": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"provider_id": "manual",
"provider": {"id": null,
"is_installed": null
},
"price_type": "flat_rate",
"amount": 200,
"is_return": false,
"admin_only": false,
"requirements": [null
],
"data": { },
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"price_incl_tax": 0,
"tax_rates": [{ }
],
"tax_amount": 0
}
]
}

Swaps

A swap is created by a customer or an admin to exchange an item with a new one. Creating a swap implicitely includes creating a return for the item being exchanged.

How to create a swap in a storefront

Create a Swap

Create a Swap for an Order. This will also create a return and associate it with the swap. If a return shipping option is specified, the return will automatically be fulfilled. To complete the swap, you must use the Complete Cart endpoint passing it the ID of the swap's cart.

An idempotency key will be generated if none is provided in the header Idempotency-Key and added to the response. If an error occurs during swap creation or the request is interrupted for any reason, the swap creation can be retried by passing the idempotency key in the Idempotency-Key header.

How to create a swap

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 with.
return_shipping_option	string The ID of the Shipping Option to create the Shipping Method from.

Responses

Response Schema: application/json

required

object (Swap)

A swap can be created when a Customer wishes to exchange Products that they have purchased with different Products. It consists of a Return of previously purchased Products and a Fulfillment of new Products. It also includes information on any additional payment or refund required based on the difference between the exchanged products.

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 uses to complete 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 amount between the order’s original total and the new total imposed by the swap. If its value is negative, a refund must be issues to the customer. If it's positive, additional payment must be authorized by the customer. Otherwise, no payment processing is required.
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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 that the swap belongs to.
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 The details of the order that the swap belongs to.
	Array of objects (Line Item) The details of the new products to send to the customer, represented as line items.
return_order	object or null The details of the return that belongs to the swap, which holds the details on the items being returned.
fulfillments	Array of objects The details of the fulfillments that are used to send the new items to the customer.
payment	object or null The details of the additional payment authorized by the customer when `difference_due` is positive.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Shipping Method) The details of the shipping methods used to fulfill the additional items purchased.
cart	object or null The details of the cart that the customer uses to complete the swap.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"order_id": "string",
"return_items": [{"item_id": "string",
"quantity": 0,
"reason_id": "string",
"note": "string"
}
],
"return_shipping_option": "string",
"additional_items": [{"variant_id": "string",
"quantity": 0
}
]
}

Response samples

Content type

application/json

{"swap": {"id": "swap_01F0YET86Y9G92D3YDR9Y6V676",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order": { },
"additional_items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"return_order": { },
"fulfillments": [{ }
],
"payment": { },
"difference_due": 0,
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": { },
"confirmed_at": "2019-08-24T14:15:22Z",
"canceled_at": "2019-08-24T14:15:22Z",
"no_notification": false,
"allow_backorder": false,
"idempotency_key": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Get by Cart ID

Retrieve a Swap's details by the ID of its cart.

path Parameters

cart_id

required

string

The id of the Cart

Responses

Response Schema: application/json

required

object (Swap)

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 uses to complete 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 amount between the order’s original total and the new total imposed by the swap. If its value is negative, a refund must be issues to the customer. If it's positive, additional payment must be authorized by the customer. Otherwise, no payment processing is required.
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. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details Learn about the metadata attribute, and how to delete and update it.
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 that the swap belongs to.
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 The details of the order that the swap belongs to.
	Array of objects (Line Item) The details of the new products to send to the customer, represented as line items.
return_order	object or null The details of the return that belongs to the swap, which holds the details on the items being returned.
fulfillments	Array of objects The details of the fulfillments that are used to send the new items to the customer.
payment	object or null The details of the additional payment authorized by the customer when `difference_due` is positive.
	object (Address) An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
	Array of objects (Shipping Method) The details of the shipping methods used to fulfill the additional items purchased.
cart	object or null The details of the cart that the customer uses to complete the swap.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.swaps.retrieveByCartId(cartId)
.then(({ swap }) => {
  console.log(swap.id);
});

Response samples

Content type

application/json

{"swap": {"id": "swap_01F0YET86Y9G92D3YDR9Y6V676",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order": { },
"additional_items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"return_order": { },
"fulfillments": [{ }
],
"payment": { },
"difference_due": 0,
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": { },
"confirmed_at": "2019-08-24T14:15:22Z",
"canceled_at": "2019-08-24T14:15:22Z",
"no_notification": false,
"allow_backorder": false,
"idempotency_key": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Medusa Storefront API (1.0.0)

Authentication

Cookie Session ID

How to Obtain the Cookie Session

Expanding Fields

Expanding One Relation

Expanding Multiple Relations

Prevent Expanding Relations

Selecting Fields

Selecting One Field

Selecting Multiple Fields

Retrieve Only the ID

Query Parameter Types

Strings

Integers

Boolean

Date and DateTime

Array

Object

Pagination

Query Parameters

Response Fields

Sort Order

Auth

Get Current Customer

Authorizations:

Responses

Response Schema: application/json

Request samples

Response samples

Customer Login

Request Body schema: application/json

Responses

Response Schema: application/json

Request samples

Response samples

Customer Log out

Authorizations:

Responses

Request samples

Response samples

Check if Email Exists

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Carts

Create a Cart

Request Body schema: application/json

Responses

Response Schema: application/json

Request samples

Response samples

Get a Cart

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Update a Cart

path Parameters

Request Body schema: application/json

Responses

Response Schema: application/json

Request samples

Response samples

Complete a Cart

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Remove Discount

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Add a Line Item