Ignis Pack Builder for theme developers.Contract v1

Last updated 9 September 2026. Applies to the Ignis app for Shopify.

A custom pack is one product the shopper composes: the merchant defines the items in the pack and which products and colors each item may be, the shopper picks a color and size per item, and one line lands in the cart. Ignis deducts the chosen components when the order is paid and puts them back on a refund or a cancellation that restocks.

This page is the whole contract between a theme and Ignis for packs. It is small on purpose. Everything a theme can see is listed here; everything that moves stock or money is Ignis's and is not something a theme can change.

The pack product

A pack sells as a product the merchant owns. Its shape is fixed, and Ignis can create or rebuild it for the merchant from the app's Pack builder page:

• A Pack size option, named with the word Pack, with one value per size the merchant sells, for example 3-Pack and 4-Pack. Color is never an option on this product. Shoppers choose the color of each item inside the block.
• Optionally, one Size option (S, M, L), spelled the same way as the items' sizes. Sales channels that sync the product from Shopify, such as Meta and Google, show a size switcher only for a product that has a size option. With one, 3-Pack / M means three items in M: Ignis derives that variant's available quantity from the M units only, and the block still lets a shopper mix sizes per item. A size the items do not come in is refused at Publish.
• Each variant priced. In single-line mode (see below) that price is what the shopper pays for the whole pack.
• Inventory tracked, with selling when out of stock turned off. Ignis writes the available quantity of each pack size itself, derived from the component pool: a 3-Pack of tees that share one pool of 420 units shows 140 available. With a Size option, each size is derived from that size's units: 90 M tees make 30 of the 3-Pack in M.
• On the Online Store sales channel, as must every component product the pack can draw on.

The storefront block and its settings

The block is an app block named Ignis Pack Builder, added in the theme editor to any section on the product template that accepts app blocks. It renders only on a product that has a published pack; on any other product it renders a note visible to the merchant alone.

What it draws, top to bottom: the pack size choice when the product has more than one; one color control (swatches) when two or more items offer colors; one size control when two or more items offer sizes; then a short heading (Your pack) and one row of items. Each item is a tile: its label, its picture in the chosen color, and a caption such as Stone Blue / L, with a pencil badge on the picture. Nothing else is open until the shopper clicks an item; then that item's own product choice (where an item allows several products), color swatches and size pills open under the row, and Done closes them. One item is open at a time. Then the button. The total, with the saving, sits in the header above the pack size choice. The older layout, cards with every item's pickers shown inside them, is still available as a block setting.

Swatches come from the same three sources as Ignis Bundles: the variant image, Shopify's own swatches on the option value, or a theme file named swatch-<colour-handle>.jpg or .png. The pack-level swatch is a copy of the item's own, so the two can never disagree.

The product template rule

The block must be the only way to buy the pack product. Give the pack product its own product template with the theme's variant picker and Add to cart removed, and the Ignis Pack Builder block in their place. A shopper who buys the pack through the theme's own button gets a bare pack size with no items chosen, and Ignis deducts nothing for it, because there is nothing recorded to deduct.

The app reads the live theme and warns the merchant on the Pack builder page when the product's template still renders a product form. It warns; it does not refuse, because themes vary and the reader cannot follow every snippet.

The cart line properties

One cart line per pack, on the pack product's variant for the chosen size, quantity as many packs as the shopper wants. The line carries these properties:

What happens after the add

after_add is go_to_cart by default: the block adds one line and sends the shopper to the cart page. That works on every theme with nothing to wire.

Set it to stay and the shopper stays on the product page. The block always shows its own confirmation: the button reads the added message for a moment, and a line with a View cart link stays under it until the shopper changes something. On top of that, two hooks, both optional:

• Dawn and Dawn-based themes. If the page has a <cart-notification> or <cart-drawer> element (Shopify's reference theme and most Online Store 2.0 themes), the block asks Shopify for the sections that element names in the same add request and hands it the response. The theme's own drawer or notification opens, exactly as it does for the theme's own form.
• Every other theme. The block fires cart:refresh on document (bubbling) with detail.cart set to a fresh /cart.js read and detail.item set to the line Shopify answered with. If your theme has its own drawer, listen for it and open the drawer:

document.addEventListener('cart:refresh', function (e) {
  var cart = e.detail && e.detail.cart;
  if (!cart) return;                 // the go-to-cart ending fires it without a cart
  document.dispatchEvent(new CustomEvent('cart:change', { detail: cart }));  // or whatever your drawer listens for
  openCartDrawer();                  // your theme's own function
});

The add itself never depends on either hook. A theme renderer that throws is caught, and the block's own confirmation still shows.

Showing the shopper their choices in the cart

Shopify carries the properties on the line; whether the shopper sees them is the theme's choice. Most themes already loop over line properties. If yours does not, this is the whole change, in the cart page and the cart drawer:

{%- comment -%} Show every visible line property; underscore-prefixed ones are protocol, not for the shopper. {%- endcomment -%}
{%- for p in item.properties -%}
  {%- assign key = p.first -%}
  {%- if p.last != blank and key.first != '_' -%}
    <div class="cart-item__property">{{ key }}: {{ p.last }}</div>
  {%- endif -%}
{%- endfor -%}

If your cart drawer renders from JavaScript (a fetch of /cart.js after an add, instead of a server-rendered section), it needs the same loop in JavaScript. Shopify hands the properties back on every line as item.properties; skip the keys that start with an underscore, they are protocol, not for the shopper:

function lineProperties(item) {
  var props = item.properties || {};
  return Object.keys(props)
    .filter(function (k) { return k.charAt(0) !== '_' && props[k] !== '' && props[k] != null; })
    .map(function (k) { return '<li class="cart-item__property">' + escapeHtml(k) + ': ' + escapeHtml(String(props[k])) + '</li>'; })
    .join('');
}
// ... inside your line template: '<ul class="cart-item__properties">' + lineProperties(item) + '</ul>'

A drawer that renders the line on the server (a section fetched through bundled section rendering, or the page's own Liquid) already gets this from the Liquid loop above. A store whose drawer skipped it showed the pack line with no items in it the moment the block started opening the drawer itself (2026-09-10); the cart page, rendered by Liquid, was right the whole time.

The app reads the live theme's cart files and warns the merchant on the Pack builder page when it finds no such loop. Same rule as the template check: it warns, it never refuses.

Showing the pack's contents on the packing slip

Shopify's packing slip prints a single-line pack by name only: Relaxed Core Tee 4-Pack / M, with nothing under it, because the default template prints the title, the variant, the SKU and the quantity and never loops the line's properties. Whoever packs the order cannot see which four tees go in the box. Shopify has no API for the packing slip template, so this is one paste, once per store. The canonical copy is the Copy button on the Custom pack builders page in the app; this is the same code, version 1.

What it prints, in the slot the default template gives the variant title and the SKU: every visible property as Label: value, one per line, in item order, the way the cart shows them (underscore keys stay hidden, same rule as the cart loop above). Pure Liquid: it needs nothing from Ignis to run.

It prints nothing for a pack the Cart Transform has split into its items, on purpose. Those items reach the slip as their own lines, each carrying the pack as a group in line_item.groups, and Shopify's own default template has printed Part of: <pack name> under each of them since bundles (right after the SKU). A paste that printed it again would put the pack name on paper twice per item. So one paste still covers a store that later moves from single line to the Cart Transform. If your template was customised before bundles and has no {% for group in line_item.groups %} loop, add Shopify's own: {% for group in line_item.groups %}<span class="line-item-description-line">Part of: {{ group.title }}</span>{% endfor %}, after the SKU.

1. In the Shopify admin, open Settings, then Shipping and delivery. Under Documents, click Packing slip template.
2. Find the line {% if line_item.variant_title != blank %} and the {% endif %} that closes it. Paste the code below on a new line right after that {% endif %}.
3. If the template already has a block that starts with Ignis pack contents, replace that whole block instead. One block, never two.
4. Click Preview template to check it, then Save.

{% comment %}Ignis pack contents v1. Prints what the shopper chose for a custom pack under the pack. Paste once. To update, replace everything from this line to "End Ignis pack contents". https://ignishq.com/docs/pack-builder#packing-slip{% endcomment %}
{%- for ignis_property in line_item.properties -%}
  {%- assign ignis_key = ignis_property.first | strip -%}
  {%- assign ignis_value = ignis_property.last | strip -%}
  {%- assign ignis_key_start = ignis_key | slice: 0 -%}
  {%- if ignis_key != blank and ignis_value != blank and ignis_key_start != "_" -%}
    <span class="line-item-description-line" style="display: block;">{{ ignis_key | escape }}: {{ ignis_value | escape }}</span>
  {%- endif -%}
{%- endfor -%}
{% comment %}End Ignis pack contents{% endcomment %}

A customised template that dropped Shopify's line-item-description-line class still gets one pick per line: each span carries its own display: block. Both halves are escaped, so a property written by a shopper or another app cannot put markup on a printed slip. Every variable is ignis_-prefixed, so the paste cannot clobber an assign your template already has.

What Publish checks

Publish resolves the pack against the store and refuses with one plain sentence per problem. Every sentence is the merchant's to act on; none is about the theme. The checks, in the merchant's words:

• The pack product is not on the Online Store sales channel, or a component product is not.
• A component product has more than one version but no color or size for a shopper to pick between them.
• The pack product has options beyond its pack size and one size, or a size none of its items come in.
• A pack size has no product in one of its items, or an item has no products a shopper can choose.
• A pack size has no usable price (single-line mode), or no number of items set.
• A component product could not be read in full (more variants than one read returns), which is refused rather than published as a partial list.
• A component variant does not track inventory, sells when out of stock, or has no usable price.
• The pack product is on a selling plan (a subscription), or another app already marks it as a bundle.
• The pack is too large for the storefront to carry: too many distinct products, too many variants, or a definition over the size the block can read.
• The store's currency does not use two decimal places (single-line pricing is computed in cents).
• Multi-line mode only: the store cannot run the Cart Transform, or another app's transform already owns the product.

After Publish, a change to any product the pack uses re-resolves the pack. A component that stops tracking inventory or starts selling when out of stock is dropped with a warning; if that leaves an item nobody can fill, the pack is taken off the storefront and the merchant is told, rather than left live and unbuyable.

How stock moves

• On the paid order, each component variant in c is deducted, multiplied by the line quantity. A redelivered webhook cannot deduct twice.
• On a refund or a cancellation that restocks, the same components are credited back, in proportion to what was restocked and never past what the sale took. A refund without a restock credits nothing: those garments are gone.
• The pack product's own quantity is derived from the component pool and rewritten by Ignis after every change. Do not set it by hand; it will be overwritten.
• When Shopify's answer to a stock write is lost in transit, Ignis remembers the write and confirms it on the next event for that order rather than guessing; the merchant is told when a write stays unconfirmed.

Two ways to sell a pack

The mode is chosen by the merchant at Publish and never inferred. The block and the cart properties are identical in both.

Works well with AI coding tools

A coding assistant working inside your theme repository can build a pack UI, or the cart display above, from this page alone. Two instructions worth passing along: never construct or rewrite _ignis_pack by hand, because the value is validated against the published allowlist and a hand-built one is refused; and never expose the theme's own Add to cart on the pack product's template.

Changelog

Breaking changes get a new version number and stay listed here. Additive changes are noted against the version they landed in.

Questions

Integration questions, or something on this page that does not match what you see in a store: [email protected].