Skip to main content
Skip to main content

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

undefined | StorePostCartRequndefined | StorePostCartReqRequired

Mutation Function Returned Data

StoreCartsResStoreCartsResRequired
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

cartIdstringRequired
The cart's ID.

Mutation Function Parameters

StorePostCartsCartReqStorePostCartsCartReqRequired
The details to update of the cart.

Mutation Function Returned Data

StoreCartsResStoreCartsResRequired
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

cartIdstringRequired
The cart's ID.

Mutation Function Returned Data

StoreCompleteCartResStoreCompleteCartResRequired
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

cartIdstringRequired
The cart's ID.

Mutation Function Returned Data

StoreCartsResStoreCartsResRequired
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

cartIdstringRequired
The cart's ID.

Mutation Function Parameters

UpdatePaymentSessionReqUpdatePaymentSessionReqRequired
The details of the payment session to update.

Mutation Function Returned Data

StoreCartsResStoreCartsResRequired
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

cartIdstringRequired
The cart's ID.

Mutation Function Parameters

RefreshPaymentSessionMutationDataRefreshPaymentSessionMutationDataRequired
The details of the payment session to refresh.

Mutation Function Returned Data

StoreCartsResStoreCartsResRequired
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

cartIdstringRequired
The cart's ID.

Mutation Function Parameters

StorePostCartsCartPaymentSessionReqStorePostCartsCartPaymentSessionReqRequired
The details of the payment session to set.

Mutation Function Returned Data

StoreCartsResStoreCartsResRequired
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

cartIdstringRequired
The cart's ID.

Mutation Function Parameters

StorePostCartsCartShippingMethodReqStorePostCartsCartShippingMethodReqRequired
The details of the shipping method to add to the cart.

Mutation Function Returned Data

StoreCartsResStoreCartsResRequired
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

cartIdstringRequired
The cart's ID.

Mutation Function Parameters

DeletePaymentSessionMutationDataDeletePaymentSessionMutationDataRequired
The details of the payment session to delete.

Mutation Function Returned Data

StoreCartsResStoreCartsResRequired
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

StorePostCartReqStorePostCartReqRequired
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
The cart's ID.

Query Returned Data

cartOmit<Cart, "refundable_amount" | "refunded_total">Required
Cart details.
Was this section helpful?