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
`cartId`	`string`	Yes	Current cart ID for integrations that track checkout attribution.
`clearError`	`() => void`	Yes	Function to dismiss the current error
`closeCart`	`() => void`	Yes	Function to close the cart UI
`error`	`CartError`	Yes	The last cart change that could not be saved, with a shopper-ready message. Set when an add, quantity change, removal, or discount fails; cleared when the next change starts or via `clearError`. Render it in the cart UI so the shopper knows to retry.
`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
`refreshCart`	`() => Promise<void>`	Yes	Re-read the persisted cart and adopt it if no mutations are in flight. Call after something outside the provider rewrote the cart — e.g. the checkout route clamped it and bounced back with `?checkout=adjusted`.
`replaceAttributes`	`(attributes: CartLineAttribute[]) => Promise<void>`	Yes	Replace the order-level cart attributes (Shopify `cart.attributes`), the key/value pairs gift-message and fulfillment apps read off the order. These are distinct from per-line `properties`. The full list is replaced on every call, so a key left out is removed; values are stored as strings. Shopify checkout only; on Replo Products (Stripe) sites the attributes are kept on the cart but are not forwarded to the order.
`updateDiscountCodes`	`(discountCodes: string[]) => Promise<void>`	Yes	Function to update discount codes on cart
`updateNote`	`(note: string) => Promise<void>`	Yes	Set the order-level cart note (Shopify `cart.note`, the “special instructions” field on the order). Pass an empty string to clear it. Each call is one Shopify mutation: save on blur or after the shopper stops typing, never on every keystroke. Shopify checkout only; on Replo Products (Stripe) sites the note is kept on the cart but is not forwarded to the order.

`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<{ adjustments: CartLineAdjustment[]; }>`	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
`clearError`	`() => void`	Yes	Function to dismiss the current error
`closeCart`	`() => void`	Yes	Function to close the cart UI
`currencyCode`	`string`	Yes	Currency code for the cart
`error`	`CartError`	Yes	The last cart change that failed to save; cleared when the next change starts
`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
`refreshCart`	`() => Promise<void>`	Yes	Re-read the persisted cart and adopt it if no mutations are in flight
`removeCartItem`	`(lineId: string) => Promise<void>`	Yes	Function to remove item from cart
`replaceAttributes`	`(attributes: CartLineAttribute[]) => Promise<void>`	Yes	Function to replace the order-level cart attributes
`subtotal`	`number`	Yes	Total price of all items
`updateCartItem`	`(line: CartLinePayload) => Promise<{ adjustments: CartLineAdjustment[]; }>`	Yes	Function to update cart item quantity
`updateDiscountCodes`	`(discountCodes: string[]) => Promise<void>`	Yes	Function to update discount codes on cart
`updateNote`	`(note: string) => Promise<void>`	Yes	Function to set the order-level cart note (empty string clears it)

`CartError`

The most recent cart change that could not be saved. message is written for the shopper, so a cart UI can render it as-is next to a retry.

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

Field	Type	Required	Description
`message`	`string`	Yes	Shopper-facing explanation with a retry prompt
`operation`	`CartOperation`	Yes	Which cart change failed

`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, country, }: React.PropsWithChildren<{ cart: Cart | null; country?: StorefrontCountryCode; }>) => 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

Also exported

Export	Kind	Type
`CartOperation`	type	`"add" \| "update" \| "remove" \| "discount" \| "note" \| "attributes"`

`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

`AddToCartResult`

What an addToCart call did. adjustments lists what the server changed about a saved request (a quantity clamped to stock, an unavailable line removed). error is set instead when the cart could not be created or saved; the same message is on useCart().error for the cart UI.

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

Field	Type	Required	Description
`adjustments`	`CartLineAdjustment[]`	Yes	What the server changed about a saved add; empty when nothing was
`error`	`CartError`	Yes	Why the add was not saved; null on success

`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. addToCart never throws. It resolves an AddToCartResult: adjustments when the add was saved, or error when the cart could not be created or saved. On failure the provider also records the error on useCart().error and opens the cart UI, which renders it, so a click handler needs no handling of its own. checkoutAvailability is "unavailable" while the store can’t take payments yet, or when the catalog passed is one this site’s checkout can’t sell. Show the button disabled with “Coming soon” then: a shopper could fill a cart but never check out.

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

useAddToCart: ({ catalog, }?: { catalog?: CheckoutCatalog | null; }) => { addToCart: (items: AddToCartItem[], openCartAfterAdd?: boolean) => Promise<AddToCartResult>; isAdding: boolean; checkoutAvailability: CheckoutAvailability; }

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

function AddToCartButton({ variant }) {
  const { addToCart, isAdding, checkoutAvailability } = useAddToCart({
    catalog: "shopify",
  });
  const isComingSoon = checkoutAvailability === "unavailable";

  return (
    <button
      disabled={!variant.availableForSale || isAdding || isComingSoon}
      onClick={() => {
        void addToCart([{ merchandiseId: variant.id, quantity: 1 }]);
      }}
    >
      {isComingSoon ? "Coming soon" : 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. Stripe checkout ignores selling plans and discount codes, logging a server-side warning when either is supplied. checkoutAvailability is "unavailable" while the store can’t take payments yet (Replo checkout not set up, or checkout turned off), or when the catalog passed is one this site’s checkout can’t sell. Show the button disabled with “Coming soon” then, instead of letting the shopper hit a failed checkout.

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

useBuyNow: ({ catalog, }?: { catalog?: CheckoutCatalog | null; }) => { buyNow: (variants: VariantBuyNowInfo[], options?: { discountCodes?: string[]; attributes?: { key: string; value: string; }[]; }) => Promise<BuyNowOutcome>; checkoutAvailability: CheckoutAvailability; }

Returns: Object containing the buyNow function and whether checkout can take payments

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

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

  return (
    <Button
      disabled={!selectedVariant?.availableForSale || isSoldOut || isComingSoon}
      onClick={async () => {
        if (selectedVariant) {
          const outcome = await buyNow(
            [
              {
                variantId: selectedVariant.id,
                quantity,
                sellingPlanId: selectedSellingPlan?.id,
                properties: [
                  {
                    key: "Pre-order item",
                    value: "Shipping between Aug 20 - Aug 27",
                  },
                ],
              },
            ],
            { discountCodes: ["SUMMER2024"] }
          );
          if (outcome.result === "outOfStock") {
            setIsSoldOut(true);
          }
        }
      }}
    >
      {isComingSoon ? "Coming soon" : isSoldOut ? "Sold out" : "Shop Now"}
    </Button>
  );
}

`VariantBuyNowInfo`

Describes a single variant to send directly to checkout.

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

Field	Type	Required	Description
`properties`	`CartLineAttribute[]`	No	Custom line item properties forwarded to checkout. Shopify persists them on the order; Stripe order persistence is not yet supported. Underscore-prefixed keys are hidden at Shopify checkout.
`quantity`	`number`	No
`sellingPlanId`	`string`	No
`variantId`	`string`	Yes

`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

`CartLineAdjustment`

How a cart write differed from what the shopper asked for, derived by comparing the requested lines against the cart the server saved. Cart UIs render these as Shopify-style notices (“Only 9 in stock — we’ve updated your cart”); the underlying clamp has already been applied to the cart.

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

CartLineAdjustment: { type: "quantityClampedToStock"; variantId: string; requested: number; applied: number; } | { type: "unavailableLineRemoved"; variantId: string; }

`CartLineComponent`

A variant inside a bundle line. For a bundle Shopify merged from lines the shopper added, these are those lines.

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

Field	Type	Required	Description
`merchandiseId`	`string`	Yes	The component’s variant ID
`quantity`	`number`	Yes	How many of this variant the bundle line holds in total
`sellingPlanId`	`string`	Yes	The component’s selling plan, or null for a one-time purchase

`REPLO_ATTRIBUTION_PROPERTY`

Replo order attribution. Shopify carts the SDK adds to carry it as a cart attribute; buy-now and Stripe checkout lines carry it as a line property.

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	`{ attributes?: CartLineAttribute[]; buyerIdentity?: { country: string \| null; }; checkoutUrl?: string; cost: CartCost; discountAllocations?: CartDiscountAllocation[]; discountCodes?: CartDiscountCode[]; id: string; lines: CartLine[]; note?: string }`
`CartBuyerIdentity`	type	`{ country: StorefrontCountryCode }`
`CartCost`	type	`{ currencyCode: string; subtotalAmount: number; totalAmount: number }`
`CartLine`	type	`{ attributes: CartLineAttribute[]; components?: CartLineComponent[]; 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[] }`
`ReplaceCartAttributesPayload`	type	`{ attributes: CartLineAttribute[]; cartId: 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 }`
`UpdateCartNotePayload`	type	`{ cartId: string; note: string }`

`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; country?: StorefrontCountryCode; lineItems: { variantId: string; quantity: number; sellingPlanId: string \| null; properties: CartLineAttribute[]; }[]; discountCodes: string[]; attributes?: { key: string; value: string; }[]; pageUrl: string; }) => Promise<StripeCheckoutOutcome>`

`cart/checkout`

@replohq/sdk/cart/checkout

`CheckoutCrossSell`

A product offered in the summary, with its price formatted.

import type { CheckoutCrossSell } from "@replohq/sdk/cart/checkout";

Field	Type	Required	Description
`imageUrl`	`string`	Yes
`price`	`string`	Yes	e.g. “$38.00”.
`title`	`string`	Yes
`variantId`	`string`	Yes

`CheckoutLineItem`

One line of the order, with Stripe’s preformatted amounts.

import type { CheckoutLineItem } from "@replohq/sdk/cart/checkout";

Field	Type	Required	Description
`id`	`string`	Yes
`imageUrl`	`string`	Yes
`name`	`string`	Yes
`quantity`	`number`	Yes
`total`	`string`	Yes	Line total, e.g. “$58.00”.

`CheckoutSessionProvider`

Loads the checkout session createCheckoutSessionAction opened and shares it with <StripePaymentForm /> and useCheckoutSession() below it. The form takes its colors, corner radius and font from the site’s design tokens (--primary, --background, --foreground, --border, --radius, …).

import { CheckoutSessionProvider } from "@replohq/sdk/cart/checkout";

CheckoutSessionProvider: ({ startCheckoutPath, children, }: React.PropsWithChildren<{ startCheckoutPath: string; }>) => JSX.Element

<CheckoutSessionProvider startCheckoutPath="/checkout">
  <OrderSummary />
  <StripePaymentForm />
</CheckoutSessionProvider>

`CheckoutState`

What useCheckoutSession() returns. retry opens a fresh checkout from the cart, which also recovers an expired or already-paid session.

import type { CheckoutState } from "@replohq/sdk/cart/checkout";

CheckoutState: { status: "loading"; } | { status: "empty"; } | { status: "error"; message: string; retry: () => void; } | { status: "ready"; summary: CheckoutSummary; isQuotingShipping: boolean; message: string | null; crossSells: CheckoutCrossSell[]; addCrossSell: (variantId: string) => Promise<void>; addingCrossSellVariantId: string | null; }

`CheckoutSummary`

The live order behind the form. Amounts are formatted by Stripe in the session’s currency and follow every shipping re-quote and promo code.

import type { CheckoutSummary } from "@replohq/sdk/cart/checkout";

Field	Type	Required	Description
`currencyCode`	`string`	Yes	ISO code, e.g. “USD”.
`discount`	`{ amount: string; name: string; code: string \| null; }`	Yes
`lineItems`	`CheckoutLineItem[]`	Yes
`shipping`	`{ name: string \| null; amount: string; deliveryEstimate: string \| null; isQuoted: boolean; }`	Yes	Null when nothing in the order ships.
`subtotal`	`string`	Yes
`tax`	`{ status: "ready"; amount: string; } \| { status: "pending"; }`	Yes
`total`	`string`	Yes

`StripePaymentForm`

Stripe’s contact, shipping-address and payment form, inside <CheckoutSessionProvider>. Each completed address is re-quoted on the server, so print-on-demand items show their real shipping cost before the buyer pays. Renders nothing until the session has loaded.

import { StripePaymentForm } from "@replohq/sdk/cart/checkout";

StripePaymentForm: () => JSX.Element

`useCheckoutSession`

The live checkout session, inside <CheckoutSessionProvider>.

import { useCheckoutSession } from "@replohq/sdk/cart/checkout";

useCheckoutSession: () => CheckoutState

`cart/checkout-actions`

@replohq/sdk/cart/checkout-actions

`createCheckoutSessionAction`

Starts Stripe checkout on the site’s own page: the outcome’s redirectUrl opens paymentPagePath (a page built on <CheckoutSessionProvider> and <StripePaymentForm />) with the session in the URL fragment. Where canopy can’t serve embedded checkout it returns Stripe’s hosted page instead, and a store that doesn’t check out through Stripe gets buyNowWithRecoveryAction’s redirect. Same outcomes as buyNowWithRecoveryAction, which keeps redirecting to the hosted page.

import { createCheckoutSessionAction } from "@replohq/sdk/cart/checkout-actions";

createCheckoutSessionAction: (input: { checkoutAttemptId: string | null; lineItems: { variantId: string; quantity: number; sellingPlanId: string | null; properties: CartLineAttribute[]; }[]; discountCodes: string[]; pageUrl: string; paymentPagePath: string; }) => Promise<StripeCheckoutOutcome>

`getCrossSellsAction`

Up to three live products from the store that aren’t in the cart, newest first. Pass the cart’s variant ids from a cart drawer, or the session id from embedded checkout (which also leaves out items that session can’t take). Empty when the store isn’t checking out through Stripe.

import { getCrossSellsAction } from "@replohq/sdk/cart/checkout-actions";

getCrossSellsAction: (input: { excludeVariantIds: string[]; sessionId: string | null; }) => Promise<CrossSell[]>

`cart/utils/cart-utils`

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

`applyCartLineReconciliation`

Rewrite a cookie cart with the catalog’s current facts: live prices and currency always, unavailable lines dropped, and — on write paths only — quantities clamped to the purchasable remainder. Reads never clamp (clampQuantities: false): a quantity change without messaging is worse than one the mutation or checkout path reports, mirroring Shopify’s cart behavior. reconciledLines must be the catalog’s answer for this cart’s merchandise-bearing lines in order — the shape reconcileCartLines returns.

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

applyCartLineReconciliation: (cart: Cart, reconciledLines: ReconciledCartLine[], { clampQuantities }: { clampQuantities: boolean; }) => Cart

`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, reconcile?: (cart: Cart) => Promise<Cart>) => Promise<Cart | null>

`updateCartLineItemWithPersistence`

Update cart line item

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

updateCartLineItemWithPersistence: (payload: UpdateCartLineItemPayload, cookieName: string, reconcile?: (cart: Cart) => Promise<Cart>) => 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

​CartError

​CartProvider

​useCart

​useCartInternal

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

​AddToCartItem

​AddToCartResult

​useAddToCart

​cart/hooks/use-buy-now

​BuyNowOutcome

​useBuyNow

​VariantBuyNowInfo

​cart/cart-types

​CartDiscountAllocation

​CartDiscountCode

​CartLineAdjustment

​CartLineComponent

​REPLO_ATTRIBUTION_PROPERTY

​cart/buy-now-action

​buyNowAction

​cart/checkout

​CheckoutCrossSell

​CheckoutLineItem

​CheckoutSessionProvider

​CheckoutState

​CheckoutSummary

​StripePaymentForm

​useCheckoutSession

​cart/checkout-actions

​createCheckoutSessionAction

​getCrossSellsAction

​cart/utils/cart-utils

​applyCartLineReconciliation

​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`

`CartError`

`CartProvider`

`useCart`

`useCartInternal`

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

`AddToCartItem`

`AddToCartResult`

`useAddToCart`

`cart/hooks/use-buy-now`

`BuyNowOutcome`

`useBuyNow`

`VariantBuyNowInfo`

`cart/cart-types`

`CartDiscountAllocation`

`CartDiscountCode`

`CartLineAdjustment`

`CartLineComponent`

`REPLO_ATTRIBUTION_PROPERTY`

`cart/buy-now-action`

`buyNowAction`

`cart/checkout`

`CheckoutCrossSell`

`CheckoutLineItem`

`CheckoutSessionProvider`

`CheckoutState`

`CheckoutSummary`

`StripePaymentForm`

`useCheckoutSession`

`cart/checkout-actions`

`createCheckoutSessionAction`

`getCrossSellsAction`

`cart/utils/cart-utils`

`applyCartLineReconciliation`

`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`