Skip to main content
Skip to main content

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

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

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

Default: {}

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