Assemblage Documentation

Getting Started: Your First 5 Minutes 🚀

Follow these three simple steps to set up your product options correctly using the new Adapter Key workflow.

Step 1: Installing the Product Options Block

Enable the app in your Shopify theme so options appear on your storefront.

Shopify Theme Editor showing Product Options Block

From the Dashboard Onboarding Checklist, click "Install App Block".
You will be taken to the Shopify Theme Editor.
On the left panel, under "Product information," click Add block and select Product Options (Apps).
Drag the block to where you want options to appear (usually above the Buy buttons).
Click Save. Return to the app and click "Verify Installation".

Step 2: Creating an Assembly & Adapter Keys

Create a reusable template. Instead of linking specific products here, you define Adapter Keys (like placeholders) to make the template reusable across different products.

Go to Assemblies > Create Assembly to open the Setup Guide.
Step 1 & 2: Name your assembly and add options (Dropdown, Color Swatch, etc.).
Step 3 (Crucial): Define Adapter Keys for choices that need inventory tracking.
- Example: For a "Large" option, type size_large_sku.
- The app automatically appends _sku to your keys.
Step 4: Optionally add hidden components (like manuals or packaging) that are included with every order.

Step 3: Deploying & Linking SKUs

Assign the assembly to products and then link specific SKUs to the Adapter Keys you created.

Deploy: Click "Deploy to Product" or use the Product Manager to assign your assembly to one or more products.
Manage Links: In the Product Manager, you will see a "Needs Configuration" status for newly assigned products.
Click Manage Links for a product.
You will see the Adapter Keys (e.g., size_large_sku). Click Link Variant to select the actual Shopify variant (e.g., "T-Shirt - Large") that corresponds to that key for this specific product.

2

Core Concepts

What is an Assembly?

An Assembly is a reusable configuration template. It defines the structure of your options (e.g., "Size", "Color", "Material") but doesn't contain the specific inventory items yet.

User Interface: Dropdowns, Swatches, Buttons.
Logic: Required fields, price modifiers.

What is an Adapter Key?

An Adapter Key is a unique ID (e.g., frame_color_sku) that acts as a bridge between your Assembly and your Inventory. It allows one Assembly to be used on different products with different SKUs.

Assembly: Defines size_m_sku.
Red Shirt: Links size_m_sku → "Red Medium Shirt" Variant.
Blue Shirt: Links size_m_sku → "Blue Medium Shirt" Variant.

3

Feature Guides 🔧

Dashboard & Setup Guide

Your central hub for monitoring deployment status.

Setup Guide: A collapsible checklist that walks you through creating, assigning, and verifying your first assembly.
Metrics: Track total assemblies and products.
Needs Attention: A critical counter showing how many products have been assigned an assembly but haven't had their Adapter Keys linked to SKUs yet.

Product Manager

The control center for your catalog assignments. Replaces the simple "Products" list.

Smart Filters: Filter by "Menu Item" tag, "Needs Configuration", or "AI Suggested".
Menu Items: Tag customer-facing products as assemblage-menu-item to keep your list clean.
Bulk Actions: Deploy assemblies, tag products, or unassign in bulk (Advanced Plan).
Manage Links: The interface where you connect Adapter Keys to actual inventory variants.

Managing Assemblies

Create and edit your configuration templates.

Create/Edit: Use the Setup Guide for new assemblies or the full editor for existing ones.
Adapter Keys: Define keys for any option choice that needs to track inventory.
Auto-Included Components: Add components (like manuals or hardware) that don't require customer selection but consume inventory.

Production Forecast (Advanced) 📊

Prevent stockouts by analyzing component usage rates.

🔴 At Risk < 7 days left

🟡 Low Stock 7-30 days left

Get AI-driven Reorder Recommendations and create Purchase Orders directly in Shopify.

Analytics (Advanced) 📈

Deep insights into which configurations generate revenue.

Option Popularity: See exactly which components (e.g., "Gold Handle") are chosen most often.
Top Combinations: Discover popular pairings (e.g., "Large Frame + Matte Black") to create pre-built bundles.
Revenue Metrics: Track total sales generated specifically through custom assemblies.

Settings & Theme

Configure app behavior and appearance.

Theme Styling: Click Configure Theme Styles to auto-extract colors/fonts from your live theme and apply them to the app block.
Notifications: Set low-stock alert thresholds.
Billing: Manage your subscription plan (Starter vs. Advanced).

4

Frequently Asked Questions

This means you have assigned an assembly to a product, but you haven't linked the Adapter Keys to actual SKU variants yet.

Go to the Product Manager, find the product, click Actions > Manage Links, and select the specific variants for each key.

We switched to Adapter Keys to make assemblies reusable. If you linked a specific "Blue Shirt" variant in the builder, you couldn't use that same assembly layout for a "Red Shirt" product.

By using keys (like shirt_sku), you can use the same assembly for hundreds of products, linking each one to its own correct inventory item.

The tag assemblage-menu-item is used to identify "parent" or "package" products that customers actually buy. This helps filter out the thousands of individual component SKUs in your store so you can focus on the products that need assemblies.

Go to Settings > Theme Styling. Use the "Configure Theme Styles" tool to automatically detect your theme's fonts and colors, or manually tweak borders, spacing, and colors to match your brand.