Carts
Queries and Mutations listed here are used to send requests to the Store Cart API Routes.
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.
The hooks listed have general examples on how to use them, but it's highly recommended to use the CartProvider provider and the useCart hook to manage your cart and access the current cart across your application.
Related Guide: How to implement cart functionality in your storefront.
Mutations
useCreateCart
This hook creates 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 React from "react"
import { useCreateCart } from "medusa-react"
type Props = {
regionId: string
}
const Cart = ({ regionId }: Props) => {
const createCart = useCreateCart()
const handleCreate = () => {
createCart.mutate({
region_id: regionId
// creates an empty cart
}, {
onSuccess: ({ cart }) => {
console.log(cart.items)
}
})
}
// ...
}
export default Cart
Mutation Function Parameters
Mutation Function Returned Data
The cart's details.
useUpdateCart
This hook updates 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 React from "react"
import { useUpdateCart } from "medusa-react"
type Props = {
cartId: string
}
const Cart = ({ cartId }: Props) => {
const updateCart = useUpdateCart(cartId)
const handleUpdate = (
email: string
) => {
updateCart.mutate({
email
}, {
onSuccess: ({ cart }) => {
console.log(cart.email)
}
})
}
// ...
}
export default Cart
Hook Parameters
cartIdstringRequiredMutation Function Parameters
The details to update of the cart.
Mutation Function Returned Data
The cart's details.
useCompleteCart
This hook completes 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 React from "react"
import { useCompleteCart } from "medusa-react"
type Props = {
cartId: string
}
const Cart = ({ cartId }: Props) => {
const completeCart = useCompleteCart(cartId)
const handleComplete = () => {
completeCart.mutate(void 0, {
onSuccess: ({ data, type }) => {
console.log(data.id, type)
}
})
}
// ...
}
export default Cart
Hook Parameters
cartIdstringRequiredMutation Function Returned Data
If the cart is completed successfully, this will have the created order or the swap's details, based on the cart's type. Otherwise, it'll be the cart's details.
useCreatePaymentSession
This hook creates 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 React from "react"
import { useCreatePaymentSession } from "medusa-react"
type Props = {
cartId: string
}
const Cart = ({ cartId }: Props) => {
const createPaymentSession = useCreatePaymentSession(cartId)
const handleComplete = () => {
createPaymentSession.mutate(void 0, {
onSuccess: ({ cart }) => {
console.log(cart.payment_sessions)
}
})
}
// ...
}
export default Cart
Hook Parameters
cartIdstringRequiredMutation Function Returned Data
The cart's details.
useUpdatePaymentSession
This hook updates 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 React from "react"
import { useUpdatePaymentSession } from "medusa-react"
type Props = {
cartId: string
}
const Cart = ({ cartId }: Props) => {
const updatePaymentSession = useUpdatePaymentSession(cartId)
const handleUpdate = (
providerId: string,
data: Record<string, unknown>
) => {
updatePaymentSession.mutate({
provider_id: providerId,
data
}, {
onSuccess: ({ cart }) => {
console.log(cart.payment_session)
}
})
}
// ...
}
export default Cart
Hook Parameters
cartIdstringRequiredMutation Function Parameters
The details of the payment session to update.
Mutation Function Returned Data
The cart's details.
useRefreshPaymentSession
This hook refreshes 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 React from "react"
import { useRefreshPaymentSession } from "medusa-react"
type Props = {
cartId: string
}
const Cart = ({ cartId }: Props) => {
const refreshPaymentSession = useRefreshPaymentSession(cartId)
const handleRefresh = (
providerId: string
) => {
refreshPaymentSession.mutate({
provider_id: providerId,
}, {
onSuccess: ({ cart }) => {
console.log(cart.payment_sessions)
}
})
}
// ...
}
export default Cart
Hook Parameters
cartIdstringRequiredMutation Function Parameters
The details of the payment session to refresh.
Mutation Function Returned Data
The cart's details.
useSetPaymentSession
This hook selects 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 React from "react"
import { useSetPaymentSession } from "medusa-react"
type Props = {
cartId: string
}
const Cart = ({ cartId }: Props) => {
const setPaymentSession = useSetPaymentSession(cartId)
const handleSetPaymentSession = (
providerId: string
) => {
setPaymentSession.mutate({
provider_id: providerId,
}, {
onSuccess: ({ cart }) => {
console.log(cart.payment_session)
}
})
}
// ...
}
export default Cart
Hook Parameters
cartIdstringRequiredMutation Function Parameters
The details of the payment session to set.
Mutation Function Returned Data
The cart's details.
useAddShippingMethodToCart
This hook adds 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 React from "react"
import { useAddShippingMethodToCart } from "medusa-react"
type Props = {
cartId: string
}
const Cart = ({ cartId }: Props) => {
const addShippingMethod = useAddShippingMethodToCart(cartId)
const handleAddShippingMethod = (
optionId: string
) => {
addShippingMethod.mutate({
option_id: optionId,
}, {
onSuccess: ({ cart }) => {
console.log(cart.shipping_methods)
}
})
}
// ...
}
export default Cart
Hook Parameters
cartIdstringRequiredMutation Function Parameters
The details of the shipping method to add to the cart.
Mutation Function Returned Data
The cart's details.
useDeletePaymentSession
This hook deletes a Payment Session in a Cart. May be useful if a payment has failed. The totals will be recalculated.
Example
import React from "react"
import { useDeletePaymentSession } from "medusa-react"
type Props = {
cartId: string
}
const Cart = ({ cartId }: Props) => {
const deletePaymentSession = useDeletePaymentSession(cartId)
const handleDeletePaymentSession = (
providerId: string
) => {
deletePaymentSession.mutate({
provider_id: providerId,
}, {
onSuccess: ({ cart }) => {
console.log(cart.payment_sessions)
}
})
}
// ...
}
export default Cart
Hook Parameters
cartIdstringRequiredMutation Function Parameters
The details of the payment session to delete.
Mutation Function Returned Data
The cart's details.
useStartCheckout
This hook allows you to create a cart and set its payment session as a preparation for checkout. It performs the same actions as the useCreateCart and useCreatePaymentSession hooks.
Example
import React from "react"
import { useStartCheckout } from "medusa-react"
type Props = {
regionId: string
}
const Checkout = ({ regionId }: Props) => {
const startCheckout = useStartCheckout()
const handleCheckout = () => {
startCheckout.mutate({
region_id: regionId,
}, {
onSuccess: (cart) => {
console.log(cart.payment_sessions)
}
})
}
// ...
}
export default Checkout
Mutation Function Parameters
The details of the cart to be created.
Queries
useGetCart
This hook retrieves a Cart's details. This includes recalculating its totals.
Example
import React from "react"
import { useGetCart } from "medusa-react"
type Props = {
cartId: string
}
const Cart = ({ cartId }: Props) => {
const { cart, isLoading } = useGetCart(cartId)
return (
<div>
{isLoading && <span>Loading...</span>}
{cart && cart.items.length === 0 && (
<span>Cart is empty</span>
)}
{cart && cart.items.length > 0 && (
<ul>
{cart.items.map((item) => (
<li key={item.id}>{item.title}</li>
))}
</ul>
)}
</div>
)
}
export default Cart
Hook Parameters
idstringRequired