Documentation | Scaly Visual Product Builder

What the app does

Shoppers put a product together out of parts and watch it come together while they choose. A chain, the clasp that hangs from it, the pendants on that clasp. Each one is a real product from your catalog, drawn in place on a live preview.

Nothing about your catalog changes. Every part the shopper picks enters the cart as its own line item, so stock, prices, discounts, taxes and reporting keep working exactly as before. You create no new SKUs and you write no theme code.

Despite the examples above, nothing here is specific to jewellery. The same structure fits a gift box with chosen contents, a watch of case, dial and strap, a bouquet, a bicycle, a furniture set: anything where the parts are products you already sell and the combinations are too many to model as variants.

Before you start

Your parts must be products in your store, published to the Online Store sales channel. A product that is not published cannot be loaded by the builder and will not appear.
Images matter. The preview stacks the product images on top of each other. Images with a transparent background (PNG or WebP) look best. You can also upload a separate image per part just for the builder, without touching the product itself.
Your theme must support app blocks. Every Online Store 2.0 theme does. If yours is older, the block cannot be placed.

Quick start

Open the app and click Configurator in the left navigation.
Click + Configurator and give it a name, for example Necklace.
Under General settings, create your layers, the steps the shopper goes through.
Under Products, add the products for each layer and set the anchor points on their images.
Check the Preview tab. Click through it as a shopper would.
Save configuration. Nothing is stored until you do.
Back on the overview, click Create page in shop on that builder, then Open theme editor and save there.

The builder is then live on that page. Everything below explains these steps in depth.

The four concepts

Builders

Each row on the Configurator screen is one independent builder, with its own layers, products, input fields and design. A store can have several (a necklace builder and a gift-box builder, say), and each is placed on its own page. How many you may have depends on your plan.

Every builder has an ID. That ID is what ties a builder to a page in your shop.

Layers

A layer is one step of the choice, and also one level of the picture. You name them in the plural, as the shopper sees them: Chains, Clasps, Pendants.

Each layer names its parent layer: what its parts hang on. The first layer has none; it is the base. This is what makes the preview work: a pendant knows it hangs on a clasp, and the clasp knows it hangs on the chain.

Per layer you set:

Required: the shopper cannot add to cart without choosing from this layer.
Multiple selection: several parts from this layer at once, each landing on its own mount point. Without it, a new choice replaces the old one.
Preview size (%): how large parts of this layer are drawn relative to the whole. A chain might be 82 %, a pendant 26 %. This is the quickest way to fix a preview where something looks far too big or too small.
Category selected on load: which filter is active when the builder opens. Useful when a layer holds many products and you want the first step to show a short list.

Anchor points

This is the part that makes the preview more than a pile of images, and the only concept worth reading twice. You set anchors by clicking directly on a product's image in the app.

There are two kinds, and which ones a product needs follows from where its layer sits:

Connection point (exactly one per product): the spot on this image that hooks into the parent layer. On a pendant it is the little loop at the top. A part in the base layer does not have one, because it hangs on nothing.
Mount points (any number): the spots on this image where parts of the child layer will hang. On a clasp with three positions you set three. The order in which you set them is the order they get filled.

A part in the middle of the stack therefore has both: one connection point upwards and several mount points downwards. When a shopper chooses two pendants and the clasp has three mount points, the pendants take the first two, and the shopper can drag them onto other positions.

Set the anchors once per product and they hold for every combination. If a product has variants that look different, you can override the anchors per variant.

Building a configurator

General settings

Name the builder, then create the layers from the base upwards, so each layer can point at a parent that already exists. Drag rows to reorder them; the order is the order of the steps.

Products

Per layer you add the products that belong to it. For each one you can set:

The image used in the preview: the product image, an upload, or an image URL. The upload stays inside the app and never changes the product.
Anchor points: as described above, clicked onto the image.
Preview size: an override for this one product, if it needs to differ from the layer.
Categories: which filters this product appears under.
A custom tile image: the picture on the selection tile can be zoomed and moved independently of the preview image, so a wide product still reads well in a small square.

Variants become their own tiles. A product with three colours appears as three choices. Per variant you can override category, image, anchors and size; whatever you leave empty is inherited from the product.

Input fields

Fields collect details that are not a product choice, such as a desired length, an engraving or a gift-wrap tick. Four types are available:

Selection: a dropdown of values you define. With custom value enabled, the shopper can also type something of their own.
Text: a free line, for engravings and the like.
Number
Checkbox: yes or nothing.

Each field belongs to a layer. Its value is attached to that layer's line item in the cart, which is what puts the engraving on the pendant rather than on the chain. Fields not tied to a layer land on the first line item.

A selection field can also take its values from the chosen product. If your chains carry their lengths as Shopify variant options, the field offers exactly the lengths that chain has, instead of a fixed list that might not apply. The app recognises the right option by how well its values overlap with your list, not by its name, so it works whatever the option is called and in any language.

Design

The Design tab sets the colours and the loading animation for this builder. Eleven colours, grouped by what they affect rather than by name:

Brand: the add-to-cart button, the active category chip, the border of the selected tile; a darker tone for headings and hover; and the text on the brand colour, which you set to a dark tone if your brand colour is light.
Surfaces and borders: tile, field and chip backgrounds; the quieter background of the preview; and every border and rule.
Text: body text and secondary text.
Accents: the two placeholder dots in the empty preview, and the warning colour used for the sold-out badge and the asterisk on required steps.

Leave a field empty and the default applies. Hex, rgb(), hsl() and plain colour names all work. Each colour has its own reset, and there is one to clear the whole design.

The loading animation is what shoppers see while the products load: your logo, a spinning ring, or text only; how the logo moves and how fast; and whether the loading text appears. The preview below updates as you change things.

Design is set per builder, so two builders in the same store can look different.

Preview

The Preview tab is not a mock-up. It is the same builder your customers get, running on your real product data, only without a cart. If it works here it works on the storefront.

The Load example button adds a ready-made configuration (necklace, bracelet, gift box, watch, bouquet) so you can see how layers and anchor points fit together. Examples are marked with an Example badge and work only in the preview. They reference demo products that do not exist in your store and are never published to your shop, no matter how often you save. Replace the demo products with your own to make one go live.

Putting the builder on your storefront

The block does not know by itself which builder to show. Assigning one is the step people miss. There are three ways, and the first is the easy one:

Create page in shop. On the builder's row, click it. The app creates a page and stores the assignment on that page. Then click Open theme editor: the block is inserted into the page template and you only have to save.
By template suffix. A page template named byo-<builder ID> assigns itself.
By hand. Place the block yourself in the theme editor, click Copy ID in the app, and paste it into the block's Builder ID field.

Without an assignment the block stays invisible on the storefront. That is deliberate: it means the block sitting in a shared page template does not appear on pages where it does not belong. The one exception: if your store has exactly one builder, the block shows it without being told.

The theme block also carries a few settings of its own: a heading, and a logo for the loading animation.

What the shopper gets, and what you get

The shopper works through the steps, sees the piece assemble, can drag parts onto other mount points, and can zoom and pan the preview. When they add to cart, every chosen part becomes its own line item.

Those line items carry hidden properties so you can tell one assembled piece from another:

_byo_id: the same value on every line of one piece. This is what groups them.
_byo_layer: which layer the part came from.
_byo_slot: which mount point it sits on, so you can reproduce the arrangement the shopper built.

Properties starting with an underscore are hidden from the customer in cart and checkout but are in the order, visible to you. Your input fields appear under their own labels and are shown to the customer. If two fields on the same line carry the same label, the second is stored as “Label (2)” rather than overwriting the first.

Sold out and unavailable products

Per builder you decide what happens when a part's stock runs out: show it as normal and let it be chosen, show it greyed out, or hide it. Products that can no longer be loaded at all (unpublished, deleted, renamed handle) are handled separately and are hidden by default.

A required layer in which nothing is selectable will block the add-to-cart button. The builder says so plainly in that step rather than leaving the shopper hunting for something that is not there. If you see this, the layer has no products, or all of them are out of stock and set to be hidden.

Languages

The storefront builder follows your shop language automatically. It ships with English, German, French, Spanish and Brazilian Portuguese; a shop in any other language gets English. Prices are formatted for the shop language too, not for the visitor's browser.

Your own text, such as layer names, category names, field labels and product titles, is shown exactly as you entered it and is never translated.

The language of the app's admin interface is separate and set under Settings → Language. It starts in English and remembers your choice.

Plans and limits

Plans are managed by Shopify, so the plan selection is a page Shopify hosts rather than one inside the app. The quickest way there is from the app itself: Settings → Plan → Change plan. The same button appears in the message you get if a limit stops you from saving.

If you would rather go straight there, the address is admin.shopify.com/store/<your-store>/charges/custom-designer-charms/pricing_plans.

What differs between plans is how many builders you may have, how many products you may put across all of them, and how many input fields each builder may carry. The limits are checked when you save a configuration. A builder that is already live keeps running, and shoppers are never affected by a limit.

If you exceed a limit, saving is refused with a message naming the plan, the limit and what you tried to save. Remove what is over, or move to a larger plan.

If something does not work

The builder does not appear on the page

Almost always a missing assignment. Open the theme editor, select the block, and check whether its Builder ID field is filled, or use Create page in shop, which does it for you. Also check that you saved in the theme editor after inserting the block.

A message says products could not be loaded

The named products are not published to the Online Store sales channel, or their handle changed after you added them. Publish them, or remove them from the builder. This message is only ever shown to you, in the theme editor and in the app's preview. Your customers never see it; for them, a part that cannot be loaded is simply skipped.

The preview looks wrong: parts too big, or in the wrong place

Size comes from Preview size (%), on the layer or overridden per product. Position comes from the anchor points: a part that floats in the wrong spot usually has its connection point set somewhere other than where it should hook in, or the parent's mount point is misplaced. Both are clicked directly on the image and can be dragged.

The example has no content

Examples work only in the app's preview, by design. They point at demo products that exist in no store. That is also why they are never published to your shop.

Changes do not show up in the shop

Check that you clicked Save configuration: the app does not save on its own, and it warns you when you have unsaved changes. After saving, a storefront page may still be served from cache for a short while; reload once.

Uninstalling

Apps are uninstalled in the Shopify admin under Settings → Apps and sales channels; the app's own settings page links straight there. Your products are untouched by this. The configuration is stored in your own shop and goes with the app.

Scaly Visual Product Builder: Documentation