Skip to main content

Cart

The @hv/cart package exposes a vendor-agnostic interface to vendor specific cart integrations.

Integration Function​

The integration function instantiates a CartIntegration, the vendor-agnostic interface to the Cart provider. It is intended to be used in server components or route handlers.

This Function is Server Only

Do not try to instantiate the Cart() function in client ("use client") components. Use the wrapping hooks provided in this package instead which expose these methods to the client.

Usage​

Example usage:

import { Cart } from '@hv/cart';

...

const { createCart } = Cart({
  locale: 'en-US',
});

const createCartResult = await createCart(cartDraft);

Capabilities​

Capabilities are read-only values which define the features and functionality of the cart provider from a commerce vendor package.

cartPromotionEntry​

type: boolean


Defines if cart provider supports the application of a promotion code to the cart.

checkout​

type: boolean


Defines if provider supports an external, "hosted" checkout process. Usually instead of expressCheckout.

customerProductLists​

type: boolean


Defines if provider supports customer product lists to save favorite products for later.

displayCartTotal​

type: boolean


Defines if provider supports the display of a cart total vs a subtotal only.

expressCheckout​

type: boolean


Defines if provider supports checking out directly in the High Velocity front-end app. This means shipping, taxes, etc. can be managed and calculated for the cart.

lineItemLimit​

type: number


Defines the maximum number of line items allowed in the cart, when restricted by the provider.

API​

The @hv/cart package contains an /api folder that exports code to stand-up Next.js Route Handlers.

These endpoints each correspond to a React hook from the @hv/cart/client export, and use the CartIntegration function as the underlying implementation.

Together these are useful for fetching and mutating data in client components.

Endpoints​

Typically you would only call these endpoints via their corresponding use...() hook in a client component.

/addPromoCode​

Adds a promo code to the current cart.

/addToCart​

Adds items to the current cart.

/getCapabilities​

Fetches the capabilities of the cart provider.

/getCart​

Fetches the current cart details.

/getOrder​

Fetches details of a specific order by order ID.

/getPaymentMethods​

Fetches available payment methods.

/getShippingMethods​

Fetches available shipping methods for the current cart.

/placeOrder​

Places an order using the current cart.

/removeFromCart​

Removes a line item from the cart.

/removePromoCode​

Removes a promo code from the current cart.

/updateCart​

Updates the cart details such as:

  • customerID
  • customerEmail
  • shippingMethodID
  • shippingAddress
  • billingAddress

/updateLineItem​

Updates a line item in the cart.

Hooks​

@hv/cart/client exports React hooks for fetching and mutating cart and order objects.

useAddPromoCode()​

Provides functionality to add a promo code to the cart via API and update status in the UX.

useAddToCart()​

Provides functionality to add items to the cart via API and update status in the UX.

useCart()​

Provides functionality to fetch the current cart details via API and update status in the UX.

useCartCapabilities()​

Provides functionality to fetch the capabilities of the cart provider via API and update status in the UX.

useCartListener()​

Provides functionality to listen for cart events and execute a callback when they occur.

useOrder()​

Provides functionality to fetch details of a specific order by order ID via API and update status in the UX.

usePaymentMethods()​

Provides functionality to fetch available payment methods via API and update status in the UX.

usePlaceOrder()​

Provides functionality to place an order using the current cart via API and update status in the UX.

useRemoveFromCart()​

Provides functionality to remove a line item from the cart via API and update status in the UX.

useRemovePromoCode()​

Provides functionality to remove a promo code from the cart via API and update status in the UX.

useShippingMethods()​

Provides functionality to fetch available shipping methods for the current cart via API and update status in the UX.

useUpdateCart()​

Provides functionality to update the cart details, such as customer address, via API and update status in the UX.

useUpdateLineItem()​

Provides functionality to update a line item in the cart via API and update status in the UX.

Reference​

For more documentation on the types exposed by this package, check out the reference section:

Reference