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
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
Parameters
cart_id
stringRequiredThe shipping method to add.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredResolves to the cart's details.
ResponsePromise
ResponsePromise<StoreCartsRes>Requiredcomplete
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
Parameters
cart_id
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<StoreCompleteCartRes>RequiredResolves to the completion details.
ResponsePromise
ResponsePromise<StoreCompleteCartRes>Requiredcreate
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
Parameters
customHeaders
Record<string, any>RequiredDefault: {}
payload
StorePostCartReqThe cart to create.
payload
StorePostCartReqReturns
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredResolves to the created cart's details.
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredcreatePaymentSessions
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
Parameters
cart_id
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredResolves to the cart's details.
ResponsePromise
ResponsePromise<StoreCartsRes>RequireddeleteDiscount
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
Parameters
cart_id
stringRequiredcode
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredResolves to the cart's details.
ResponsePromise
ResponsePromise<StoreCartsRes>RequireddeletePaymentSession
Delete a Payment Session in a Cart. May be useful if a payment has failed. The totals will be recalculated.
Example
Parameters
cart_id
stringRequiredprovider_id
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredResolves to the cart's details.
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredrefreshPaymentSession
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
Parameters
cart_id
stringRequiredprovider_id
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredResolves to the cart's details.
ResponsePromise
ResponsePromise<StoreCartsRes>Requiredretrieve
Retrieve a Cart's details. This includes recalculating its totals.
Example
Parameters
cart_id
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredResolves to the cart's details.
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredsetPaymentSession
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
Parameters
cart_id
stringRequiredThe associated payment provider.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredResolves to the cart's details.
ResponsePromise
ResponsePromise<StoreCartsRes>Requiredupdate
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
Parameters
cart_id
stringRequiredThe attributes to update in the cart.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredResolves to the cart's details.
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredupdatePaymentSession
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
Parameters
cart_id
stringRequiredprovider_id
stringRequiredThe attributes to update in the payment session.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<StoreCartsRes>RequiredResolves to the cart's details.
ResponsePromise
ResponsePromise<StoreCartsRes>Required