Cart - Replo

Cart state lives in CartProvider and is read with useCart. Amounts are handled in minor units, so see Money for formatting.

`cart/cart-provider`

@replohq/sdk/cart/cart-provider

`CartContextType`

Public cart context type for LLM use. For adding products to cart, use useAddToCart. For buy now functionality, use useBuyNow.

import type { CartContextType } from "@replohq/sdk/cart/cart-provider";

Field	Type	Required	Description
`closeCart`	`() => void`	Yes	Function to close the cart UI
`isCartOpen`	`boolean`	Yes	Whether the cart UI is open
`itemsCount`	`number`	Yes	Total number of items in cart
`openCart`	`() => void`	Yes	Function to open the cart UI
`updateDiscountCodes`	`(discountCodes: string[]) => Promise<void>`	Yes	Function to update discount codes on cart

`CartContextTypeInternal`

Internal cart context type with full functionality. This is for internal use only - external code should use the limited CartContextType.

import type { CartContextTypeInternal } from "@replohq/sdk/cart/cart-provider";

Field	Type	Required	Description
`addToCart`	`(lines: CartLinePayload[], openCartAfterAdd?: boolean) => Promise<void>`	Yes	Function to add items to cart
`buyNow`	`(lines: CartLinePayload[], discountCodes?: string[]) => Promise<Cart \| null>`	Yes	Function to create cart and checkout immediately
`cartData`	`Cart`	Yes	The current cart (can be null)
`checkoutUrl`	`string`	Yes	URL to redirect to checkout
`closeCart`	`() => void`	Yes	Function to close the cart UI
`currencyCode`	`string`	Yes	Currency code for the cart
`isCartOpen`	`boolean`	Yes	Whether the cart UI is open
`itemsCount`	`number`	Yes	Total number of items in cart
`lineItems`	`CartLine[]`	Yes	Array of cart line items
`openCart`	`() => void`	Yes	Function to open the cart UI
`removeCartItem`	`(lineId: string) => Promise<void>`	Yes	Function to remove item from cart
`subtotal`	`number`	Yes	Total price of all items
`updateCartItem`	`(line: CartLinePayload) => Promise<void>`	Yes	Function to update cart item quantity
`updateDiscountCodes`	`(discountCodes: string[]) => Promise<void>`	Yes	Function to update discount codes on cart

`CartProvider`

Provider component that manages global cart state and operations. Handles both server-side cart synchronization and client-side optimistic updates.

import { CartProvider } from "@replohq/sdk/cart/cart-provider";

CartProvider: ({ children, cart, }: React.PropsWithChildren<{ cart: Cart | null; }>) => JSX.Element

Returns: A context provider wrapping the children with cart functionality

`useCart`

Hook to access cart UI state and controls. For adding products to cart, use useAddToCart. For buy now functionality, use useBuyNow.

import { useCart } from "@replohq/sdk/cart/cart-provider";

useCart: () => CartContextType

import { useCart } from "@replohq/sdk/cart/cart-provider";

function MyComponent() {
  const { itemsCount, openCart } = useCart();
  ...
}

`useCartInternal`

Deprecated. For internal use only. Use useAddToCart or useBuyNow for cart operations. Use useCart for cart UI state (itemsCount, openCart, closeCart).

import { useCartInternal } from "@replohq/sdk/cart/cart-provider";

useCartInternal: () => CartContextTypeInternal

`cart/hooks/use-add-to-cart`

@replohq/sdk/cart/hooks/use-add-to-cart

`AddToCartItem`

Describes a single item to add to the cart. Uses the merchandiseId (e.g. a variant GID) directly from data loader output. Product display data for optimistic UI is resolved automatically from the React Query cache for both single-product loaders (e.g. ProductLoader) and product-list loaders (e.g. CollectionProductsLoader, RebuyRecommendationsLoader). Pass merchandise explicitly to bypass the cache lookup when the variant is known but its product was not loaded via a supported loader.

import type { AddToCartItem } from "@replohq/sdk/cart/hooks/use-add-to-cart";

Field	Type	Required	Description
`merchandise`	`CartLineMerchandise`	No
`merchandiseId`	`string`	Yes	The cart-addressable merchandise ID (e.g. `product.variants[N].id` from loader output).
`properties`	`CartLineAttribute[]`	No	Custom line item properties (appear on the order).
`quantity`	`number`	No
`sellingPlanId`	`string`	No

`useAddToCart`

Hook for adding items to cart using merchandise IDs from data loader output. This is the primary hook for adding items to cart in the data-loader architecture. It works with the resolver-backed CartGateway so the scaffold never needs direct integration credentials. Merchandise display data (title, price, image) for optimistic cart UI is auto-resolved from the React Query cache for both single-product loaders (e.g. ProductLoader) and product-list loaders (e.g. CollectionProductsLoader, RebuyRecommendationsLoader). Just pass the merchandiseId. Pass merchandise explicitly only when the variant is known but its product was not loaded via a supported loader.

import { useAddToCart } from "@replohq/sdk/cart/hooks/use-add-to-cart";

useAddToCart: () => { addToCart: (items: AddToCartItem[], openCartAfterAdd?: boolean) => Promise<void>; isAdding: boolean; }

import { useAddToCart } from "@replohq/sdk/cart/hooks/use-add-to-cart";

function AddToCartButton({ variant }) {
  const { addToCart, isAdding } = useAddToCart();

  return (
    <button
      disabled={!variant.availableForSale || isAdding}
      onClick={() => {
        addToCart([{ merchandiseId: variant.id, quantity: 1 }]);
      }}
    >
      {isAdding ? "Adding..." : "Add to Cart"}
    </button>
  );
}

Also exported

Export	Kind	Type
`findMerchandiseInQueryCache`	function	`({ queryClient, merchandiseId, }: { queryClient: QueryClient; merchandiseId: string; }) => CartLineMerchandise \| undefined`

`cart/hooks/use-buy-now`

@replohq/sdk/cart/hooks/use-buy-now

`BuyNowOutcome`

What a buyNow call did. Out of stock is an expected storefront outcome (a buyer can race the last unit), so it rides the return value rather than a thrown error; variants carries each short variant with the purchasable remainder so the button can render a sold-out state.

import type { BuyNowOutcome } from "@replohq/sdk/cart/hooks/use-buy-now";

BuyNowOutcome: { result: "redirected"; } | { result: "outOfStock"; variants: { variantId: string; available: number; }[]; }

`useBuyNow`

React hook that returns a buyNow function for express checkout flows. Handles creating the cart/checkout session server-side and redirecting the browser to checkout.

import { useBuyNow } from "@replohq/sdk/cart/hooks/use-buy-now";

useBuyNow: () => { buyNow: (variants: VariantBuyNowInfo[], options?: { discountCodes?: string[]; }) => Promise<BuyNowOutcome>; }

Returns: Object containing the buyNow function

import { useBuyNow } from "@replohq/sdk/cart/hooks/use-buy-now";

function MyComponent({ selectedVariant, selectedSellingPlan, quantity }) {
  const { buyNow } = useBuyNow();
  const [isSoldOut, setIsSoldOut] = React.useState(false);

  return (
    <Button
      disabled={!selectedVariant?.availableForSale || isSoldOut}
      onClick={async () => {
        if (selectedVariant) {
          const outcome = await buyNow(
            [
              {
                variantId: selectedVariant.id,
                quantity,
                sellingPlanId: selectedSellingPlan?.id,
              },
            ],
            { discountCodes: ["SUMMER2024"] }
          );
          if (outcome.result === "outOfStock") {
            setIsSoldOut(true);
          }
        }
      }}
    >
      {isSoldOut ? "Sold out" : "Shop Now"}
    </Button>
  );
}

Also exported

Export	Kind	Type
`VariantBuyNowInfo`	type	`{ quantity?: number; sellingPlanId?: string; variantId: string }`

`cart/cart-types`

@replohq/sdk/cart/cart-types

`CartDiscountAllocation`

One discount Shopify applied to a cart line or to the whole cart. The amount is already subtracted from cost.totalAmount (and from cost.subtotalAmount for line-level discounts).

import type { CartDiscountAllocation } from "@replohq/sdk/cart/cart-types";

Field	Type	Required	Description
`discountedAmount`	`number`	Yes	Integer minor units (Stripe convention) in the cart’s currencyCode
`title`	`string`	Yes	Automatic discount title or discount code; null when Shopify has neither

`CartDiscountCode`

Represents a discount code applied to a cart.

import type { CartDiscountCode } from "@replohq/sdk/cart/cart-types";

Field	Type	Required	Description
`applicable`	`boolean`	Yes	Whether the discount code is applicable to the current cart. A code may not be applicable due to: - Cart contents not meeting product/collection eligibility - Minimum purchase amount not met - Code expired or usage limits reached - Customer restrictions - Conflicting discount rules
`code`	`string`	Yes	The discount code string

`REPLO_ATTRIBUTION_PROPERTY`

Replo attribution property added to cart/buy-now line items for order attribution in Shopify.

import { REPLO_ATTRIBUTION_PROPERTY } from "@replohq/sdk/cart/cart-types";

REPLO_ATTRIBUTION_PROPERTY: CartLineAttribute

Also exported

Export	Kind	Type
`AddToCartPayload`	type	`{ cartId: string; lines: CartLinePayload[] }`
`Cart`	type	`{ checkoutUrl?: string; cost: CartCost; discountAllocations?: CartDiscountAllocation[]; discountCodes?: CartDiscountCode[]; id: string; lines: CartLine[] }`
`CartCost`	type	`{ currencyCode: string; subtotalAmount: number; totalAmount: number }`
`CartLine`	type	`{ attributes: CartLineAttribute[]; id: string; merchandise: CartLineMerchandise; quantity: number; sellingPlanAllocation?: SellingPlanAllocation }`
`CartLineAttribute`	type	`{ key: string; value: string \| number \| boolean }`
`CartLineMerchandise`	type	`{ compareAtPrice?: number; id: string; image: Image; price: number; product: { id: string; title: string; sellingPlanGroups?: SellingPlanGroup[]; }; selectedOptions: { name: string; value: string; }[]; title: string }`
`CartLinePayload`	type	`{ id: string; merchandise?: CartLineMerchandise; properties?: CartLineAttribute[]; quantity: number; sellingPlanId?: string }`
`Image`	type	`{ altText: string; url: string }`
`RemoveFromCartPayload`	type	`{ cartId: string; lineIds: string[] }`
`SellingPlanAllocation`	type	`{ checkoutChargeAmount: { amount: number; currencyCode: string; }; priceAdjustments: SellingPlanPriceAdjustment[]; remainingBalanceChargeAmount: { amount: number; currencyCode: string; }; sellingPlan: { id: string; name: string; description: string \| null; } }`
`SellingPlanPriceAdjustment`	type	`{ compareAtPrice: { amount: number; currencyCode: string; }; perDeliveryPrice: { amount: number; currencyCode: string; }; price: { amount: number; currencyCode: string; }; unitPrice: { amount: number; currencyCode: string; } }`
`UpdateCartDiscountCodesPayload`	type	`{ cartId: string; discountCodes: string[] }`
`UpdateCartLineItemPayload`	type	`{ cartId: string; line: CartLinePayload }`

`cart/buy-now-action`

@replohq/sdk/cart/buy-now-action

`buyNowAction`

Server action that handles the full buy-now flow: 1. For Shopify: creates a cart via the canopy-api-backed gateway, returns checkoutUrl. 2. For Stripe: creates a Stripe checkout session via canopy-api, returns session URL. Variant IDs are expected to already be Storefront GIDs (from data loader output). No internal→external ID mapping is needed.

import { buyNowAction } from "@replohq/sdk/cart/buy-now-action";

buyNowAction: (input: Parameters<typeof buyNowWithRecoveryAction>[0]) => Promise<{ result: "created"; redirectUrl: string; } | { result: "outOfStock"; variants: { variantId: string; available: number; }[]; }>

Also exported

Export	Kind	Type
`buyNowWithRecoveryAction`	function	`(input: { checkoutAttemptId?: string; lineItems: { variantId: string; quantity: number; sellingPlanId: string \| null; properties: CartLineAttribute[]; }[]; discountCodes: string[]; pageUrl: string; }) => Promise<{ result: "created"; redirectUrl: string; } \| { result: "restartCheckout"; message: string; } \| { result: "outOfStock"; variants: { variantId: string; available: number; }[]; }>`

`cart/utils/cart-utils`

@replohq/sdk/cart/utils/cart-utils

`calculateCartTotals`

Calculate cart totals including subtotal, discounts, and final total. When cart cost data is provided (from Shopify), uses the actual totalAmount and sums the provider’s discount allocations (automatic, code, and custom discounts, at both line and cart level) for the discount amount.

import { calculateCartTotals } from "@replohq/sdk/cart/utils/cart-utils";

calculateCartTotals: ({ lineItems, cart, }: { lineItems: CartLine[]; cart: Cart | null; }) => CartTotals

Parameter	Description
`options`	- Object containing lineItems and cart
`options.lineItems`	- Array of cart line items
`options.cart`	- Optional cart data from Shopify (includes discount allocations)

`calculateLineItemsSubtotal`

Sum the final (post selling-plan) price of every line item in the cart. This is the authoritative subtotal for cookie-based carts, which have no server-computed cost to rely on.

import { calculateLineItemsSubtotal } from "@replohq/sdk/cart/utils/cart-utils";

calculateLineItemsSubtotal: (lineItems: CartLine[]) => number

`formatPrice`

Deprecated. Back-compat shim kept for surface parity with canopy-sdk, so sites migrating off import { formatPrice } from "canopy-sdk/cart/utils/cart-utils" keep rendering with only the package specifier renamed. It formats INTEGER MINOR UNITS — the units every cart value uses (calculateCartTotals, getCartLinePricing, CartCost): passing 1999 yields “

19.99", not "

1,999.00”. New code should call formatAmount({ amount, currencyCode }) from @replohq/sdk/money directly.

import { formatPrice } from "@replohq/sdk/cart/utils/cart-utils";

formatPrice: (price: number, currency?: string) => string

`formatSellingPlanId`

Validates and formats a Shopify selling plan ID to ensure it has the correct GID format.

import { formatSellingPlanId } from "@replohq/sdk/cart/utils/cart-utils";

formatSellingPlanId: (sellingPlanId: string | null | undefined) => string | null

Parameter	Description
`sellingPlanId`	- The selling plan ID to validate and format

Returns: The formatted selling plan ID with GID prefix, or null if no ID provided

`recalculateCartCost`

Recompute a cart’s cost from its line items. Cookie carts are their own source of truth (no server roundtrip) and apply no discounts, so subtotal equals total and there are no discount allocations. Without this the cost stays at the 0 it was created with, and every consumer that trusts it (cart total, checkout analytics) reports $0 for a priced cart.

import { recalculateCartCost } from "@replohq/sdk/cart/utils/cart-utils";

recalculateCartCost: (cart: Cart) => Cart

Also exported

Export	Kind	Type
`CartTotals`	type	`{ discountAmount: number; subtotal: number; total: number; totalSavings: number }`

@replohq/sdk/cart/utils/cookie-cart-persistence

`addToCartWithPersistence`

Add lines to cart with configurable line merging strategy

import { addToCartWithPersistence } from "@replohq/sdk/cart/utils/cookie-cart-persistence";

addToCartWithPersistence: (payload: AddToCartPayload, options: AddToCartOptions) => Promise<Cart | null>

`clearCartCookie`

Clear cart cookie

import { clearCartCookie } from "@replohq/sdk/cart/utils/cookie-cart-persistence";

clearCartCookie: (cookieName: string) => Promise<void>

`createCartWithPersistence`

Create a new cart with persistence

import { createCartWithPersistence } from "@replohq/sdk/cart/utils/cookie-cart-persistence";

createCartWithPersistence: (options: CreateCartOptions) => Promise<Cart | null>

`LineMergeFn`

Line merge function type - returns index of existing line to merge with, or -1 to add as new line

import type { LineMergeFn } from "@replohq/sdk/cart/utils/cookie-cart-persistence";

LineMergeFn: (existingLines: CartLine[], newLine: CartLinePayload) => number

`loadCartFromCookie`

Load cart from cookie

import { loadCartFromCookie } from "@replohq/sdk/cart/utils/cookie-cart-persistence";

loadCartFromCookie: (cookieName: string) => Promise<Cart | null>

`removeCartLineItemsWithPersistence`

Remove cart line items

import { removeCartLineItemsWithPersistence } from "@replohq/sdk/cart/utils/cookie-cart-persistence";

removeCartLineItemsWithPersistence: (payload: RemoveFromCartPayload, cookieName: string) => Promise<Cart | null>

`saveCartToCookie`

Save cart to cookie

import { saveCartToCookie } from "@replohq/sdk/cart/utils/cookie-cart-persistence";

saveCartToCookie: (cart: Cart, cookieName: string) => Promise<void>

`updateCartInCookie`

Update cart in cookie atomically (load-transform-save pattern)

import { updateCartInCookie } from "@replohq/sdk/cart/utils/cookie-cart-persistence";

updateCartInCookie: (cartId: string, cookieName: string, updater: (cart: Cart) => Cart) => Promise<Cart | null>

`updateCartLineItemWithPersistence`

Update cart line item

import { updateCartLineItemWithPersistence } from "@replohq/sdk/cart/utils/cookie-cart-persistence";

updateCartLineItemWithPersistence: (payload: UpdateCartLineItemPayload, cookieName: string) => Promise<Cart | null>

`cart/utils/variant-to-cart-line`

@replohq/sdk/cart/utils/variant-to-cart-line

`createOptimisticSellingPlanAllocation`

Creates an optimistic selling plan allocation using product data. This matches the exact structure that Shopify returns so the UI doesn’t need conditional logic.

import { createOptimisticSellingPlanAllocation } from "@replohq/sdk/cart/utils/variant-to-cart-line";

createOptimisticSellingPlanAllocation: ({ merchandise, sellingPlanId, currencyCode, }: { merchandise: CartLineMerchandise; sellingPlanId: string | null; currencyCode?: string; }) => SellingPlanAllocation | null

`getCartLineAttribute`

Gets a specific attribute value from a cart line.

import { getCartLineAttribute } from "@replohq/sdk/cart/utils/variant-to-cart-line";

getCartLineAttribute: (cartLine: CartLine, key: string) => string | number | boolean | undefined

Parameter	Description
`cartLine`	- The cart line to get the attribute from
`key`	- The attribute key to retrieve

Returns: The attribute value, or undefined if not found

`getCartLineBundleInfo`

Extracts bundle information from cart line attributes.

import { getCartLineBundleInfo } from "@replohq/sdk/cart/utils/variant-to-cart-line";

getCartLineBundleInfo: (cartLine: CartLine) => { bundleId: string; bundleDiscount: number; isBundleItem: boolean; }

Parameter	Description
`cartLine`	- The cart line to get bundle info from

Returns: Object containing bundle ID, discount, and whether it’s a bundle item

`getCartLinePricing`

Calculates pricing information for a cart line, including discounts and selling plan adjustments.

import { getCartLinePricing } from "@replohq/sdk/cart/utils/variant-to-cart-line";

getCartLinePricing: (cartLine: CartLine) => { compareAtPrice: number; discountPercentage: number; hasDiscount: boolean; sellingPlanAdjustedPrice: number; finalPrice: number; }

Parameter	Description
`cartLine`	- The cart line to calculate pricing for

Returns: Object containing compareAtPrice, discountPercentage, hasDiscount, sellingPlanAdjustedPrice, and finalPrice

`getCartLineSpecialInfo`

Extracts special item information from cart line attributes.

import { getCartLineSpecialInfo } from "@replohq/sdk/cart/utils/variant-to-cart-line";

getCartLineSpecialInfo: (cartLine: CartLine) => { isSpecialItem: boolean; specialInstructions: string[]; }

Parameter	Description
`cartLine`	- The cart line to get special info from

Returns: Object containing whether it’s a special item and any special instructions

`getCartLineSubscriptionInfo`

Extracts subscription (selling plan) information from a cart line.

import { getCartLineSubscriptionInfo } from "@replohq/sdk/cart/utils/variant-to-cart-line";

getCartLineSubscriptionInfo: (cartLine: CartLine) => { isSubscription: boolean; frequency: string; discount: number; sellingPlan: { id: string; name: string; description: string | null; }; }

Parameter	Description
`cartLine`	- The cart line to get subscription info from

Returns: Object containing isSubscription, frequency, discount, and sellingPlan

`cart/gateways/cart-constants`

@replohq/sdk/cart/gateways/cart-constants Exports

Export	Kind	Type
`getCartCookieOptions`	function	`() => { readonly secure: true; readonly sameSite: "none"; readonly partitioned: true; readonly maxAge: number; readonly httpOnly: true; readonly path: "/"; } \| { readonly secure: boolean; readonly sameSite: "lax"; readonly maxAge: number; readonly httpOnly: true; readonly path: "/"; }`
`REPLO_CART_COOKIE_NAME`	const	`"replo_cart_v2"`

`cart/return-urls`

@replohq/sdk/cart/return-urls Exports

Export	Kind	Type
`getReturnUrls`	function	`({ host, forwardedHost, forwardedProto, requestOrigin, pageUrl, }: { host: string; forwardedHost: string \| null; forwardedProto: string \| null; requestOrigin: string \| null; pageUrl: string; }) => { origin: string; cancelUrl: string; }`

`hooks/use-formatted-price`

@replohq/sdk/hooks/use-formatted-price

`useFormattedPrice`

Use useFormattedPrice to format prices with proper currency and locale.

import { useFormattedPrice } from "@replohq/sdk/hooks/use-formatted-price";

useFormattedPrice: (price: number | null, currency: string | null) => string

Returns: A formatted price string based on the price and currency code. It already takes into account the user’s locale/browser.

import { useFormattedPrice } from "@replohq/sdk/hooks/use-formatted-price";

const originalPrice = 1999; // integer minor units
const originalPriceFormatted = useFormattedPrice(originalPrice, "USD");
// Display the formatted price
<p>{originalPriceFormatted}</p>;

​cart/cart-provider

​CartContextType

​CartContextTypeInternal

​CartProvider

​useCart

​useCartInternal

​cart/hooks/use-add-to-cart

​AddToCartItem

​useAddToCart

​cart/hooks/use-buy-now

​BuyNowOutcome

​useBuyNow

​cart/cart-types

​CartDiscountAllocation

​CartDiscountCode

​REPLO_ATTRIBUTION_PROPERTY

​cart/buy-now-action

​buyNowAction

​cart/utils/cart-utils

​calculateCartTotals

​calculateLineItemsSubtotal

​formatPrice

​formatSellingPlanId

​recalculateCartCost

​cart/utils/cookie-cart-persistence

​addToCartWithPersistence

​clearCartCookie

​createCartWithPersistence

​LineMergeFn

​loadCartFromCookie

​removeCartLineItemsWithPersistence

​saveCartToCookie

​updateCartInCookie

​updateCartLineItemWithPersistence

​cart/utils/variant-to-cart-line

​createOptimisticSellingPlanAllocation

​getCartLineAttribute

​getCartLineBundleInfo

​getCartLinePricing

​getCartLineSpecialInfo

​getCartLineSubscriptionInfo

​cart/gateways/cart-constants

​cart/return-urls

​hooks/use-formatted-price

​useFormattedPrice

`cart/cart-provider`

`CartContextType`

`CartContextTypeInternal`

`CartProvider`

`useCart`

`useCartInternal`

`cart/hooks/use-add-to-cart`

`AddToCartItem`

`useAddToCart`

`cart/hooks/use-buy-now`

`BuyNowOutcome`

`useBuyNow`

`cart/cart-types`

`CartDiscountAllocation`

`CartDiscountCode`

`REPLO_ATTRIBUTION_PROPERTY`

`cart/buy-now-action`

`buyNowAction`

`cart/utils/cart-utils`

`calculateCartTotals`

`calculateLineItemsSubtotal`

`formatPrice`

`formatSellingPlanId`

`recalculateCartCost`

`cart/utils/cookie-cart-persistence`

`addToCartWithPersistence`

`clearCartCookie`

`createCartWithPersistence`

`LineMergeFn`

`loadCartFromCookie`

`removeCartLineItemsWithPersistence`

`saveCartToCookie`

`updateCartInCookie`

`updateCartLineItemWithPersistence`

`cart/utils/variant-to-cart-line`

`createOptimisticSellingPlanAllocation`

`getCartLineAttribute`

`getCartLineBundleInfo`

`getCartLinePricing`

`getCartLineSpecialInfo`

`getCartLineSubscriptionInfo`

`cart/gateways/cart-constants`

`cart/return-urls`

`hooks/use-formatted-price`

`useFormattedPrice`