Product Customization & Options (Swatches, Uploads, Pricing Add-ons)

Free — GPL coresize Lplanned, not built

Generated from docs/plan/core/product-customization-options/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Core free module that allows unlimited product options (color, size, engraving text, file upload) without Shopify’s 3-variant limit. Each option can have a modifier (add €5 for gold plating, add €0 for free engraving). Storefront renders option swatches (color) or dropdowns (size), and checkout ensures required options are selected. Inventory can be tracked per option combination or globally per product.

The problem

A retailer sells customizable items (engraved jewelry, personalized t-shirts) but Shopify limits to 3 options (color, size, engraving) — any additional customization requires a plugin. With AstroBaaS, merchants need to offer unlimited options (color, size, engraving text, monogram, gift wrapping) to stay competitive.

What it does

• Unlimited options per product: {name, type (‘select’ or ‘text’ or ‘file’), values: [‘red’, ‘blue’, …]}
• Option modifiers: each option value can add cost (e.g., gold plating = +€5) or be free
• Swatch UI for color options: storefront renders color swatches (CSS background-color), not dropdowns
• Text input options: ‘monogram’ option allows free-form text, up to 20 characters (constraint in product schema)
• File upload options: customer can upload an image for custom printing; file is stored and linked to order
• Inventory tracking: merchants choose ‘global’ (product stock is shared across all options) or ‘per-combination’ (each color+size combo has own stock)
• Required options validation: if product has ‘size’ as required, checkout rejects orders without size selected
• Order storage: order.items[].selected_options = {color: ‘red’, size: ‘M’, monogram: ‘AB’} + all modifiers applied

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• 3D preview or AR visualization (storefront owns this)
• Dynamic pricing based on option combinations beyond flat modifiers (too complex; use tier-quantity-pricing for volume-based pricing)
• Multi-language option names (localization is a separate concern; option names stored in shop.language only)

Data model

Add product_options table: { id, product_id, option_name, option_type (‘select’, ‘text’, ‘file’), required (boolean), display_order }. Add product_option_values table: { id, option_id, value_name, value_modifier_minor_units, color_hex (if type=‘select’) }. Schema migration: new tables. Existing products have no options by default.

API

• POST /admin/products/:id/options — create new option for product
• GET /products/:id/options — read all options, values, and modifiers
• POST /checkout/apply-options — { product_id, selected_options: {color: ‘red’, size: ‘M’} } → calculates total_price with modifiers
• GET /admin/products/:id/inventory/by-option — if per-combination tracking, show stock for each option combo

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

In product editor, add ‘Options’ section. ‘Add option’ button opens form: name (color, size, monogram), type (select/text/file), required checkbox, display order. For select type: ‘Add value’ rows with value name and optional cost modifier (€5 for gold). For text/file: show constraints (max 20 chars for text, max 5MB for file). Show inventory mode: radio buttons ‘global’ or ‘per-combination’.

The seam — why this is core

Core owns unlimited options data structure, swatch rendering, and checkout validation. Merchants can create options freely. Paid module owns AI customization recommendations (e.g., suggest complementary options based on product category).

Core owns unlimited option primitive in product schema and variant rendering; paid module owns visual customizer UI, file upload hosting, and 3D preview tools

Dependencies

• Product system (options are per-product data)
• Checkout flow (to validate required options and apply modifiers)
• File storage system (to store uploaded images)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Product ‘engraved ring’ has 5 options: size (select, required), color (select, color swatches), metal type (select, +€50 for gold), engraving (text, 20 char max), gift wrap (select, +€2)
• Selecting size=8, color=silver, metal=gold, engraving=‘AB’, gift_wrap=yes calculates price = base + €50 + €2
• Storefront renders color options as clickable swatches, not dropdown
• If size option is required and customer doesn’t select size, checkout shows error ‘please select a size’
• Order stores selected_options = {size: ‘8’, color: ‘silver’, metal: ‘gold’, engraving: ‘AB’, gift_wrap: ‘yes’} for fulfillment

Risks

If file upload size limit is not enforced (always check before storing). If swatch color is user-input (hex code) not validated, malicious input is possible (whitelist hex format). If option modifiers are stored as floats instead of integers, checkout math breaks.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.