Skip to main content
Skip to main content
You're viewing the documentation for v1, which isn't the latest Medusa version.Latest documentation

CartsResource

This class is used to send requests to Store Cart API Routes. All its method are available in the JS Client under the medusa.carts property.

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.

Related Guide: How to implement cart functionality in your storefront.

Properties​

lineItemsLineItemsResourceRequired
An instance of LineItemsResource used to send requests to line-item-related routes part of the Store Cart API Routes.

Methods​

addShippingMethod​

Add a shipping method to the cart. The validation of the data field is handled by the fulfillment provider of the chosen shipping option.

Example​

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

Parameters​

cart_idstringRequired
The ID of the cart to add the shipping method to.
payloadStorePostCartsCartShippingMethodReqRequired
The shipping method to add.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<StoreCartsRes>Required
Resolves to the cart's details.

complete​

Complete a cart and place an order or create a swap, based on the cart's type. 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.

Example​

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

Parameters​

cart_idstringRequired
The ID of the cart to complete.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<StoreCompleteCartRes>Required
Resolves to the completion details.

create​

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, make sure to pass its ID or email within the cart's details so that the cart is attached to the customer.

Example​

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

Parameters​

customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

payloadStorePostCartReq
The cart to create.

Returns​

ResponsePromiseResponsePromise<StoreCartsRes>Required
Resolves to the created cart's details.

createPaymentSessions​

Create Payment Sessions for each of the available Payment Providers in the Cart's Region. If there's only one payment session 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.

Example​

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

Parameters​

cart_idstringRequired
The ID of the cart to create the payment sessions for.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<StoreCartsRes>Required
Resolves to the cart's details.

deleteDiscount​

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

Example​

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

Parameters​

cart_idstringRequired
the ID of the cart to remove the discount from.
codestringRequired
The code of the discount to remove from the cart.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<StoreCartsRes>Required
Resolves to the cart's details.

deletePaymentSession​

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

Example​

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

Parameters​

cart_idstringRequired
The ID of the cart to delete the payment session from.
provider_idstringRequired
The ID of the payment provider that the session is associated with.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<StoreCartsRes>Required
Resolves to the cart's details.

refreshPaymentSession​

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.

Example​

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

Parameters​

cart_idstringRequired
The ID of the cart to refresh its payment session.
provider_idstringRequired
The ID of the payment provider that's associated with the payment session.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<StoreCartsRes>Required
Resolves to the cart's details.

retrieve​

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

Example​

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

Parameters​

cart_idstringRequired
The cart's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<StoreCartsRes>Required
Resolves to the cart's details.

setPaymentSession​

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.

Example​

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

Parameters​

cart_idstringRequired
The cart's ID.
payloadStorePostCartsCartPaymentSessionReqRequired
The associated payment provider.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<StoreCartsRes>Required
Resolves to the cart's details.

update​

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.

Example​

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

Parameters​

cart_idstringRequired
The cart's ID.
payloadStorePostCartsCartReqRequired
The attributes to update in the cart.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<StoreCartsRes>Required
Resolves to the cart's details.

updatePaymentSession​

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.

Example​

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.updatePaymentSession(cartId, "manual", {
  data: {

  }
})
.then(({ cart }) => {
  console.log(cart.id);
})

Parameters​

cart_idstringRequired
The cart's ID.
provider_idstringRequired
The ID of the payment provider that the payment session is associated with.
payloadStorePostCartsCartPaymentSessionUpdateReqRequired
The attributes to update in the payment session.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<StoreCartsRes>Required
Resolves to the cart's details.
Was this section helpful?
© 2025 Medusa, Inc. All rights reserved.