Checkout Step 5: Complete Cart

In this guide, you'll learn how to complete the cart and place the order. This is the last step of your checkout flow.

How to Complete Cart in Storefront Checkout#

Once you finish any required actions with the third-party payment provider, you can complete the cart and place the order.

To complete the cart, send a request to the Complete Cart API route. For example:

Code
1sdk.store.cart.complete(cart.id)2.then((data) => {3  if (data.type === "cart" && data.cart) {4    // an error occurred5    console.error(data.error)6  } else if (data.type === "order" && data.order) {7    // TODO redirect to order success page8    alert("Order placed.")9    console.log(data.order)10    // unset cart ID from local storage11    localStorage.removeItem("cart_id")12  }13})

In the response of the request, the type field determines whether the cart completion was successful:

• If the type is cart, it means the cart completion failed. The error response field holds the error details.
• If the type is order, it means the cart was completed and the order was placed successfully.

When the cart completion is successful, it's important to unset the cart ID from the localStorage, as the cart is no longer usable.

Payment Failure Handling#

When cart completion fails after the payment was authorized or captured, the completeCartWorkflow automatically reverts the payment so the customer isn't charged for an incomplete order:

• An authorized payment that wasn't yet captured is canceled.
• A captured payment is refunded, unless a later or concurrent completion attempt already placed an order for the same cart. In that case, the refund is skipped so that the successful order keeps its payment.

Because the payment is reverted before the response is returned, a storefront doesn't need to issue a refund itself when completion fails. The type: "cart" response signals that completion failed and the payment was rolled back.

Order's Locale after Cart Completion#

When you complete the cart, items in the order will be in the locale that was set for the cart. This ensures that the customer sees the order details in their preferred language.

If no locale was set for the cart, then the order's items will be in the original product content.

React Example with Default System Payment Provider#

For example, to complete the cart when the default system payment provider is used:

Code
1"use client" // include with Next.js 13+2
3import { useState } from "react"4import { useCart } from "@/providers/cart"5import { sdk } from "@/lib/sdk"6
7export default function SystemDefaultPayment() {8  const { cart, refreshCart } = useCart()9  const [loading, setLoading] = useState(false)10
11  const handlePayment = (12    e: React.MouseEvent<HTMLButtonElement, MouseEvent>13  ) => {14    e.preventDefault()15
16    if (!cart) {17      return18    }19
20    setLoading(true)21    22    // TODO perform any custom payment handling logic23    24    // complete the cart25    sdk.store.cart.complete(cart.id)26    .then((data) => {27      if (data.type === "cart" && data.cart) {28        // an error occurred29        console.error(data.error)30      } else if (data.type === "order" && data.order) {31        // TODO redirect to order success page32        alert("Order placed.")33        console.log(data.order)34        refreshCart()35      }36    })37    .finally(() => setLoading(false))38  }39
40  return (41    <button42      onClick={handlePayment}43      disabled={loading}44    >45      Place Order46    </button>47  )48}

In the example above, you create a handlePayment function in the payment component. In this function, you:

• Optionally perform any required actions with the third-party payment provider. For example, authorize the payment. For the default system payment provider, no actions are required.
• Send a request to the Complete Cart API route once all actions with the third-party payment provider are performed.
• In the received response of the request, if the type is cart, it means that the cart completion failed. The error is set in the error response field.
• If the type is order, it means the card was completed and the order was placed successfully. You can access the order in the order response field.
• When the order is placed, you must unset the cart_id from the localStorage. You can redirect the customer to an order success page at this point. The redirection logic depends on the storefront framework you're using.

React Example with Third-Party Payment Provider#

Refer to the Stripe guide for an example on integrating a third-party provider and implementing card completion.