Sections, products & variants

Sections

A bundle is organized into sections — the groups a customer picks from. Sections come from GET /bundles/:id:

Field	Type	Description
id	number	Section ID.
name	string	Section title (e.g. “Choose a shirt”).
description	string	Optional description.
imageUrl	string	Optional section image.
order	number	Display order.
autoNextSection	boolean	The merchant’s “advance to the next step once this one is satisfied” setting from the step editor. Mirror it — don’t hardcode either behaviour.
products[]	array	Allowed items in this section.

Each entry in products[] references a product (and optionally specific variants) allowed in that section:

Field	Type	Description
bundleItemId	number	The bundle-item ID.
shopifyProductId	string	Shopify product ID.
variantIds	string[]	Allowed variant IDs. Empty = all variants allowed.

Section quantities live in limit rules

There is deliberately no min/max on a section. A step’s pick counts arrive as total-number-of-products entries in limitRules carrying that section’s id, and a bundle-wide “pick any N” is the same rule with sectionId: null. The SDK resolves both via getSectionLimits(bundle, sectionId) / getBundleLimits(bundle) — see Limit rules.

Products & variants

Full product and variant detail comes from GET /bundles/:id/products (the SDK merges it into getBundle()):

Product

Field	Type	Description
shopifyProductId	string	Numeric ID.
shopifyProductGid	string	gid://shopify/Product/<id>.
title	string	Product title.
handle	string	URL handle.
imageUrl	string	Product image (may be empty).
status	string	ACTIVE | ARCHIVED | DRAFT — see below.
tags	string[]	Product tags, minus Kitenzo’s internal bundle-builder-* control tags. Useful for grouping/filtering in your UI.
descriptionHtml	string	Raw Shopify product description HTML. Sanitise before rendering.
options[]	array	Option definitions (name, position, values[], swatches) in Shopify’s order.
variants[]	array	The product’s variants.

Variant

Field	Type	Description
shopifyVariantId	string	Numeric ID.
shopifyVariantGid	string	gid://shopify/ProductVariant/<id>.
title	string	Variant title (e.g. “Small / Black”).
price	string	Shop-currency price to 2 decimals, e.g. "29.99".
compareAtPrice	string | null	The variant’s own compare-at price. Meaningful for products sold alongside a bundle (an accessory upsell) — a bundle’s own saving comes from its discount.
sku	string	SKU (empty string if none).
available	boolean	Whether it can be purchased (see below).
inventoryQuantity	number	Current inventory quantity.
grams	number	Weight in grams, as Shopify stores it — what the amount-of-weight limit rule measures.
optionValues	string[]	Option values positionally aligned with the product’s options (e.g. ["Small", "Black"]).
image	string?	Variant image — present only when the variant has its own; absent means “use the product image”.

One dropdown per option

options + optionValues exist so a custom UI can render one selector per option (Size / Colour) instead of a flat list of variant titles. Don’t split title on " / " — it doesn’t survive a real catalogue. The SDK ships the resolution logic: defaultOptionValues, reachableOptionValues, resolveVariant, selectOptionValue in @kitenzo/core.

Product status

An ARCHIVED or DRAFT product stays in the bundle until the merchant removes it, but it’s unpublished from the Online Store and cannot be added to the cart. Filter on status rather than rendering it as pickable.

Availability logic

available is computed as:

1. true if inventory is not managed by Shopify for the variant; or
2. true if the inventory policy is continue (oversell allowed); otherwise
3. inventoryQuantity > 0.

Shopify Markets (localised pricing)

Pass ?countryCode=DE (ISO 3166-1 alpha-2) to the products endpoint — or set countryCode on the SDK client/provider — and each variant sold in that market additionally carries:

Field	Description
presentmentPrice	Price in the shopper’s market currency (full precision — don’t assume 2 decimals).
presentmentCurrency	ISO 4217 code, e.g. "EUR".
priceInShopCurrency	The presentment price expressed back in shop currency.
availableForSale	Whether the variant is sellable in that market. false = not sold there — distinct from available (base-store stock). Gate selection on this when a market is set.

Set the same country as buyerIdentity.countryCode on your Shopify cart, or the displayed price won’t match checkout.

Use GIDs for the cart

Add to the Shopify cart with the …Gid fields (gid://shopify/ProductVariant/…). The numeric IDs are handy for matching against your own data or the bundle’s variantIds.