Small attributes. A strict cart contract.

Published data

Each successful publish mirrors display-safe data into the public Shopify metafield namespace shop.metafields.cinch. The shop-level sf_indexlists campaign IDs, placement hints, and the merchant-configured metafield sources used by compatible collection-backed cards. Each campaign config lives atsfc_<campaignId>.

The display config and checkout config are published together. Do not author a checksum or campaign payload in browser code; read the published value and pass it through unchanged.

type PublishedCampaignConfig = {
  v: 1;
  i: string;                    // campaign id
  cs: string;                   // 16-character publish checksum
  mode: "builder" | "ladder";
  pv: string;                   // parent variant numeric id
  ev: string[];                 // eligible variant ids
  ep: string[];                 // eligible product ids
  xv: string[];                 // excluded variant ids
  mq: number | null;            // paid quantity cap value
  mqv?: boolean;                // true: cap each variant independently
  t: Array<{
    i: string; label: string; mn: number; mx: number | null;
    dt: "pct"; dv: string;
    gm: "n" | "o" | "r"; g0: number; g1: number;
    gv: string[]; pre: string[]; chg: boolean; few: boolean;
    msg?: string; badge?: string;
  }>;
  disp: Array<{
    id: string; pid?: string; t: string;
    o?: Array<[string, string]>; img: string | null;
    pm: number; cur: string; av: boolean;
    bdg?: string[]; rt?: string; rc?: number; sw?: string; h?: string;
  }>;
  s: string | null; e: string | null;
  ea?: string; cd?: boolean; addParentLine: boolean;
  sec?: Array<{
    i: string; label: string; mn: number; mx: number | null;
    ev: string[]; ep: string[];
  }>;
};

Fields that affect a custom view

Control attributes

The engine delegates click and change handling from the container. IDs must be positive numeric Shopify IDs represented as decimal strings.

Outputs and state

Add data-bundle-out to any element and the engine updates its text. The supported values are count, remaining,tier-label, discount, progress-pct,gift-count, message, error, andqty:VARIANT_ID.

The container receives data-bundle-state withselecting, adding, added, orerror. Submit receives a data-bundle-block code ofempty, no_tier, section_min,gifts_min, or adding when blocked.

Events

Listen for bubbling bundle events to update presentation. The engine also emits Shopify standard cart events before each write and a cart error event when a write fails.

const root = document.querySelector("[data-cinch]");

root?.addEventListener("bundle:change", (event) => {
  const {
    count, qty, gifts, tierId, tierLabel, discountPct,
    remaining, canSubmit, blockCode, status,
  } = event.detail;

  // Update custom presentation only. The engine owns cart intent.
});

root?.addEventListener("bundle:added", (event) => {
  const { bundleId, items, replaced } = event.detail;
});

// Re-scan after your code injects new bundle markup.
window.Cinch?.mountAll();

Other verified events are bundle:error with { message },bundle:prefill with{ bundleId, count, gifts, dropped }, andbundle:resync from the view to request a freshbundle:change.

Atomic variant switching

A custom option picker should move the entire selected quantity in one transition. If every unit cannot fit the destination limits, the move is rejected rather than clipped.

root.dispatchEvent(
  new CustomEvent("bundle:variant-move", {
    bubbles: true,
    detail: { from: "4455667788", to: "4455667799" },
  }),
);

Editing carted bundles

Set data-bundle-edit-param="bundle" to read a valid Cinch bundle ID from?bundle=..., or provide it with data-bundle-edit. A verified prefill stamps data-bundle-editing="true" and emits the prefill event.

Merged bundle components are available to Liquid asline.item_components but are not exposed by AJAX /cart.js. An editing page must emit the documented data-bundle-cart JSON snapshot so the engine can replay merged contents. The custom-page guide includes the shape.

Replacement removes the old group before adding the new one. Restoration after a failed replacement add is best effort, not a transactional Shopify primitive.

Cart and checkout boundary

Never construct the add request or private line properties yourself. The engine stamps _cinch_campaign_id, _cinch_bundle_id,_cinch_tier_id, _cinch_role, and_cinch_config_checksum. The Function validates the whole composition and checksum before returning an operation.

Limits

• At most 100 storefront-display products are emitted; additional eligible targets can still price.
• A line quantity is capped at 99, and custom bundle sections are capped at five.
• Unavailable display items should not be rendered as selectable controls.
• Fixed bundles use a normal product form and checkout expansion, not this builder contract.
• The current headless asset measures about 6.9 KB Brotli.