Hooks

All hooks require a <KitenzoProvider> ancestor (except where noted). Provider hooks useKitenzo and useSettings are documented on the Provider & client page.

useBundles()

Fetch the list of published bundles on mount.

const { bundles, isLoading, error, refetch } = useBundles();

Field	Type	Description
bundles	Bundle[]	Published bundles (no product data).
isLoading	boolean	Initial load state.
error	Error | null	Fetch error, if any.
refetch	() => void	Re-run the request.

useBundle(id, options?)

Fetch a single bundle’s full detail (sections + products + variants). Supports SSR hydration. When countryCode is set on the provider, the bundle loads with Shopify Markets presentment prices and market availability.

const { bundle, isLoading, error, refetch } = useBundle(42, { initialData });

Param	Type	Description
id	number	Bundle ID.
options.initialData	BundleDetail	Pre-fetched data (e.g. from a server loader). Skips the initial client fetch.

Returns { bundle: BundleDetail \| null, isLoading, error, refetch }.

useBundleBuilder(bundle)

Wraps createBundleBuilder with React state. Tracks the customer’s selection, section navigation, validity and the conditions-engine result.

const b = useBundleBuilder(bundle);

b.addItem(sectionId, variantId, 1);
b.updateQuantity(sectionId, variantId, 3);
b.removeItem(sectionId, variantId);
b.nextSection();

State (read):

Field	Type	Description
selections	SectionSelections	Record<sectionId, BundleSelection[]>.
currentSectionIndex	number	Active section (0-based).
currentSection	BundleSection | null	Active section object.
isSectionValid	boolean	Current section meets its constraints.
isValid	boolean	All sections meet their constraints.
isComplete	boolean	Legacy completeness flag — see the aside below.
isSatisfied	boolean	The bundle’s actual limit rules are met — a selection /configure will accept. Gate add-to-cart on this.
allItems	BundleSelection[]	Flat list of all selections.
errors	ValidationError[]	Limit-rule / required-product violations (empty when valid).
conditions	ConditionsSnapshot	Conditions-engine result: hiddenSectionIds, hiddenProducts, hideCartButton, gotoSectionId, discountOverride. All-empty when the bundle has no rule graph.

Methods (write): addItem(sectionId, variantId, quantity?), removeItem(sectionId, variantId), updateQuantity(sectionId, variantId, quantity), reset(), nextSection(), prevSection(), goToSection(index), getSectionQuantity(sectionId).

Gate add-to-cart on `isSatisfied`, not `isComplete`

isComplete treats a section with no stated minimum as needing at least one pick, so it stays false forever on a bundle-wide “pick any 4 across groups” bundle and on a step whose only rule is a maximum. isSatisfied reads the bundle’s actual limit rules and mirrors the server-side validator. isComplete is unchanged because existing integrations depend on it.

Required products are appended on submit

A required product usually belongs to the bundle rather than to a step, so it never appears in selections — the SDK appends it automatically when you submit, and isSatisfied accounts for it (it counts toward the bundle-wide total, not any per-section window). Read bundle.requiredProducts (hydrated with full product detail) to display what’s included.

useBundlePrice(bundle, selections, options?)

Compute the price locally (no API call). Recomputes instantly as selections change, applies any firing conditions-engine discount, and formats with the shop’s money format.

const price = useBundlePrice(bundle, builder.selections);
// price.formattedDiscountedPrice → "$40.50"

Field	Type	Description
originalPrice	string | null	Raw, e.g. "45.00".
discountedPrice	string | null	Raw, e.g. "40.50".
formattedOriginalPrice	string | null	e.g. "$45.00".
formattedDiscountedPrice	string | null	e.g. "$40.50".
discountType	string | null	'percentage' | 'fixed' | 'price' | null.
discountValue	string | null	Discount amount.
currency	string | null	Currency label.
hasDiscount	boolean	Whether a discount applies.

options.currency overrides the shop currency. All fields are null when there are no selections. With countryCode on the provider, prices come back in the shopper’s market currency, formatted with Intl.NumberFormat instead of moneyFormat — no code change needed.

useBundleCart()

Submit a selection via client.submitBundle, tracking loading/error state. It does not touch a cart — for the whole flow, prefer useBundleAjaxCart (themed store) or useStorefrontBundleCart (Hydrogen) below.

const { addBundleToCart, isLoading, error, lastResult } = useBundleCart();

const result = await addBundleToCart(bundle, builder.selections, { countryCode: 'US' });
// result: SubmitBundleResult { configuredBundleId, variantId, productId, discount, subscriptionId, pricing }

This returns a result — it doesn't touch the cart

useBundleCart().addBundleToCart configures the bundle and returns cart data. To actually add it to the Shopify cart (lines + _bundles attribute), pass the result to the addBundleToCart cart helper — or use one of the flow hooks below, which own the whole choreography.

useBundleAjaxCart(options?)

Configures the bundle and puts it in the theme’s own cart (/cart/add.js → /cart/update.js), for a widget embedded in a normal Shopify storefront. Merges _bundles rather than replacing it, turns non-2xx responses into real errors, and never double-adds on retry.

const { addToCart, isAdding, isAdded, error, phase, failureReason, reset } = useBundleAjaxCart({
  onAdded: () => { window.location.href = '/cart'; },
});

<button disabled={isAdding} onClick={() => addToCart(bundle, selections)}>
  {isAdding ? 'Adding…' : 'Add to cart'}
</button>

Key facts about the shared cart-flow state (UseBundleCartFlowResult):

• phase is 'idle' | 'configuring' | 'adding' | 'attributes' | 'added' | 'failed'. The adding/attributes split matters: the discount lives in a second mutation, so only added means “safe to check out”.
• addToCart never rejects — it resolves { ok: true, result } or { ok: false, reason, error }, with failureReason one of already-in-progress, cart-busy, cart-not-ready, configure-failed, cart-error, timeout.
• Options: onAdded(result), onError(error, reason), routePrefix (locale-scoped stores, e.g. '/en-gb'), fetchImpl.

For a Storefront-API cart, useStorefrontBundleCart from @kitenzo/react/hydrogen returns the identical shape (plus hasMissingItems and a timeoutMs option), so one set of buttons serves both cart modes.

useSellingPlan(bundle, options?)

Purchase-option state for Kitenzo Subscriptions (subscriptions beta). Plans come off bundle.sellingPlans; one-time purchase is the null selection.

const { plans, hasPlans, selectedPlanId, selectPlan, cartLineOptions } = useSellingPlan(bundle);

// render one-time + each plan as radios; then pass cartLineOptions on:
const payload = buildCartPayload(result, cart.attributes, { bundle, selections }, cartLineOptions);

A stale selection (a plan unpublished mid-session) falls back to one-time rather than sending a dead plan id to the cart.