Build a Plugin

This guide is for engineers who need to wrap OV25 in a first-class plugin / app for an e-commerce platform we don't already ship for. It's a checklist plus the cross-cutting patterns we already shipped in the open-source WooCommerce extension.

🧱 1. Plugin Anatomy

A complete OV25 plugin is five layers stacked on top of ov25-ui:

💡 You almost always want a sixth piece - a swatches path - but it's optional and reuses the cart bridge.

⚙️ 2. Settings UI - use ov25-setup, don't roll your own

Every option injectConfigurator accepts (selectors, display modes, branding, flags, multi-line layout shells like snap2 / bed / dining) is already exposed by the ov25-setup React package - the same UI that powers the visual builder at app.orbital.vision/configurator-setup.

It emits the exact JSON shape that injectConfigurator consumes, with a live preview, so plugin authors get the entire settings surface for free and stay in sync as we add new options.

🌍 Two scopes, same component

All oif our plugins reference it twice:

Both wire it up the same way:

import { ConfiguratorSetup, type ConfiguratorSetupPayload } from 'ov25-setup';
import 'ov25-setup/index.css';
 
<ConfiguratorSetup
  onSave={(payload: ConfiguratorSetupPayload) => savePluginSetting(payload)}
  className="h-full min-h-0 w-full flex"
/>

The payload is the same JSON injectConfigurator(...) already accepts - store it verbatim and pass it straight into the storefront bundle at runtime. The Woo extension's per-product editor (src/admin/components/ProductField.tsx) and global page (src/admin/pages/ConfiguratorSetup.tsx) are both ~50 lines of wrapper around <ConfiguratorSetup> plus the platform's save mechanism.

2.1 Merging global + per-product

When both exist, deep-merge the per-product payload over the global one before injecting:

Per-product wins. Arrays replace, objects merge.

The Woo plugin does this in resolveConfiguratorConfig + deepMerge (src/frontend/index.ts); the Shopify equivalent is in assets/ov25-configurator.js (window.ov25DefaultConfiguratorSettings overlaid by window.ov25ProductConfiguratorSettings).

Configurator layouts are bucketed by shape (single-line vs multi-line - currently standard vs snap2) so a product flipped to a multi-line layout picks up the right defaults.

2.2 What the plugin still has to persist itself

ov25-setup does not know about the things that aren't part of injectConfigurator's contract. Your settings UI still needs fields for:

• apiKey - productConfiguratorAccess key, generated at app.orbital.vision/auth/api-keys. Used by the storefront bundle.
• privateApiKey - a separate private productConfiguratorAccess key used only by the admin / settings UI to call the products-list endpoint and the swatches admin endpoints. Never expose it to the storefront.
• swatchProductId - platform product/variant id used to charge for sample packs.
• Anything platform-specific - Woo cart flags like useNativeCartSubmit / disableCartFormHiding, Shopify metafield names, etc.

Push the merged result into a window.ov25Settings-style global from the server template so the storefront bundle picks it up synchronously - see ov25_configurator.liquid (Shopify) and OV25_Admin_Page::enqueue_settings (Woo).

🔗 3. Product Linking

Each platform product needs one piece of data: the OV25 productLink string. The current valid shapes - every one of them is rendered straight from the products-list endpoint:

🧭 Branch on shape, not prefix. Anything that writes through mode: 'multi' is a multi-line layout. Future configurator types will surface as new prefixes on this same field - your plugin only needs to branch on payload.skus.mode === 'single' | 'multi', never on the prefix string. Treat the productLink as an opaque string the merchant pastes in from the picker.

3.1 The products-list endpoint

To build a product picker (so the merchant doesn't have to type the link by hand), call:

GET https://app.ov25.ai/api/public/products-list?apiKey={privateApiKey}

The response has three top-level lists. ranges carries products and snap2; bedConfigurators and diningConfigurators are separate top-level entries because they aren't tied to a product range:

{
  ranges: [
    {
      id: number;
      name: string;
      manufacturerName: string;
      description: string | null;
      hasSnap2: boolean;
      snap2Active: boolean;
      products: [
        {
          id: number;
          name: string;
          thumbnail: string | null;
          category: string | null;
          hasConfigurator: boolean;
          status: boolean;
        },
      ];
    },
  ],
  bedConfigurators: [
    {
      id: number;
      name: string;
      manufacturerId: number;
      sizes: string[] | null;          // bed sizes the configurator supports
    },
  ],
  diningConfigurators: [
    {
      id: number;
      name: string;
      manufacturerId: number;
    },
  ],
}

Render one row per link target

The Shopify picker (extensions/ov25-product-admin/src/utils.js → fetchOV25Products) is the canonical implementation - it iterates all five buckets in this order and pushes one item per row, with kind, linkValue, name, and subtitle so the search UI can group/filter.

🧱 Mirror that structure rather than rolling your own - if Orbital Vision adds a new top-level configurator family (e.g. kitchenConfigurators), your picker only needs to add one more loop.

Picker UX gotchas

Always provide a manual-entry fallback (text input) for when the API is unreachable or the merchant uses a retailer key that returns an empty list.

3.2 Where to store the link

The key thing is that it has to be readable from the storefront context (Liquid, PHP template, theme JSON, etc.) so the bundle can pick it up at first paint.

If your plugin supports per-product overrides for the inject config (see section 2.1), store that as a second JSON field next to the product link.

🖼️ 4. The Storefront Bundle

This is where ov25-ui does almost all of the work. The bundle's only job is to:

1. Build the inject config from the global settings + per-product overrides.
2. Call OV25.injectConfigurator(...) once.
3. Wire addToBasket, buyNow, buySwatches callbacks to your platform's cart APIs.
4. Hide the native add-to-cart UI on linked PDPs.

A minimal cross-platform skeleton:

import * as OV25 from 'ov25-ui';
import type { OnChangePayload } from 'ov25-ui';
 
const s = window.ov25Settings;
const link = window.ov25Settings.productLink;
if (!link) return;
 
OV25.injectConfigurator({
  apiKey: s.apiKey,
  productLink: link,
  images: s.images || [],
  selectors: {
    gallery:        { selector: s.gallerySelector,        replace: true },
    variants:       { selector: s.variantsSelector },
    price:          { selector: s.priceSelector,          replace: true },
    name:           { selector: s.nameSelector,           replace: true },
    swatches:       { selector: s.swatchesSelector },
    configureButton:{ selector: s.configureButtonSelector,replace: true },
  },
  branding: { logoURL: s.logoURL, cssString: s.customCSS },
  callbacks: {
    addToBasket:  (payload) => addToCart(payload, false),
    buyNow:       (payload) => addToCart(payload, true),
    buySwatches:  (swatches, rules) => createSwatchOnlyCart(swatches, rules),
  },
});

addToCart is your platform-specific function - it takes the normalized OnChangePayload produced by ov25-ui and POSTs it to whatever cart endpoint the platform exposes. See section 6 for what to do with the payload.

📚 For the full surface area of injectConfigurator (every selector, flag, branding option, and multi-line layout setting) read UI Package Integration. For the raw iframe message types under the hood—including SELECT_SELECTION by UUID triple or by a single fuzzy-matched display-name pair—read Code Integration.

4.1 Hiding the native add-to-cart UI

Once OV25 is in charge of pricing, you cannot let the platform's native form post - it would add the item at the platform's static price.

Both reference plugins remove the native form on linked PDPs:

• WooCommerce (src/frontend/index.ts → ensureOv25NativeAtcHideStyles + scheduleOv25NativeProductFormRemoval) ships a CSS rule keyed by body.postid-{id} that hides every flavour of form.cart submit, plus a MutationObserver that yanks any form WooCommerce re-renders later (variations form, blocks, etc.).
• Shopify does the same with a Liquid guard ({% if product.metafields.ov25.configuratorID %}) plus a JS hijack on [name="checkout"] and .shopify-payment-button.

🧯 Provide a way to opt out (the Woo plugin uses disableCartFormHiding / useNativeCartSubmit) for themes that need to keep the native form for non-OV25 reasons.

You should also remove the Add to Cart button from category / collection / related-product loops on linked products (those bypass the PDP and would post at the catalogue price). The Woo plugin does this in OV25_Loop_Button_Hook via the woocommerce_loop_add_to_cart_link filter; on Shopify the equivalent is wrapping the loop button in a {% if product.metafields.ov25.configuratorID %} guard.

The replacement should send the merchant to the PDP (or open the configurator from the loop), never let them buy without configuring.

4.2 Server-rendered DOM placeholders beat CSS selectors

Wherever you can, drop server-rendered placeholder elements on the PDP and let injectConfigurator mount into them, instead of relying on CSS selectors that vary per theme:

The CSS selectors in window.ov25Settings (gallerySelector, variantsSelector, …) stay as the escape hatch for themes that won't tolerate template overrides. Document both paths in your plugin's setup wizard.

4.3 Thumbnails

OV25 exposes window.ov25GenerateThumbnail() after injectConfigurator finishes - call it inside addToBasket / buyNow and ship the resulting URL on the cart line so every layer of the platform shows the configured product, not the catalogue photo.

You will need to override the thumbnail in every of these contexts:

• 🛒 Mini-cart / side-cart drawer
• 📄 Cart page
• 💳 Checkout summary
• ✅ Order confirmation page
• ✉️ Transactional emails
• 🛠 Order detail in the admin / merchant dashboard
• 🌐 Any REST / GraphQL / Store API response the theme uses for cart rendering (woocommerce_store_api_cart_item_images on Woo, line-item image field on Shopify)

📦 5. The OnChangePayload Contract

The single piece of API surface you need to understand to wire any platform's cart is what ov25-ui hands you. Every commerce callback (addToBasket, buyNow, onChange) receives a normalized payload with this shape:

type OnChangePayload = {
  price: UnifiedPricePayload | null;
  skus:  UnifiedSkuPayload   | null;
};
 
interface UnifiedPricePayload {
  mode: 'single' | 'multi';
  totalPrice: number;          // integer minor units (pence/cents)
  subtotal: number;
  formattedPrice: string;
  formattedSubtotal: string;
  discount: { amount: number; formattedAmount: string; percentage: number };
  lines: CommerceLineItemPrice[];
  // Raw passthrough (single-line priceBreakdown, multi-line productBreakdowns) when present
  priceBreakdown?: unknown[];
  productBreakdowns?: ProductPriceBreakdown[];
}
 
type UnifiedSkuPayload =
  | { mode: 'single'; skuString: string; skuMap?: Record<string,string>; lines: SkuLine[] }
  | { mode: 'multi';  lines: SkuLine[] };
 
interface SkuLine { id: string; skuString: string; skuMap?: Record<string,string>; quantity: number; }

🎯 Two decisions follow from mode

If you need the raw iframe payloads (e.g. you want to render a per-selection breakdown in the cart), pull them from price.priceBreakdown or price.productBreakdowns.

🛒 6. The Cart Bridge

The cart bridge is a server endpoint that takes the normalized payload and creates one or more cart lines with the correct dynamic price. Three problems to solve.

6.1 Force the configured price onto the line

Every e-commerce platform calculates line prices from the catalogue - you have to override that. Three patterns cover essentially every platform:

Pattern A - Cart-line price filter

Best for: WooCommerce, Magento, anything with a per-line price hook.

Store cfg_price as cart-item meta and re-apply it on every cart total recalculation, not just at add-to-cart. WooCommerce does this by cloning WC_Product per cart row inside woocommerce_before_calculate_totals (priority 1000) and calling set_price(), set_regular_price(), set_sale_price(''). Same goes for the price HTML filter (woocommerce_cart_item_price) so cart/checkout templates show the OV25 number.

Pattern B - Custom-price cart attribute

Best for: Magento custom_price, BigCommerce list_price, Adobe Commerce original_custom_price.

Set it directly when adding the line. Easiest path when available.

Pattern C - Draft order / invoice redirect

Best for: Shopify, any platform with a locked storefront cart.

You can't override the line price, so the native cart stays at the catalogue price as a placeholder; the checkout button is hijacked (requestOV25Checkout) and POSTs the cart to a server webhook that creates an Admin-API draft order with custom line prices and returns an invoiceUrl to redirect to.

Cross-cutting requirements

Whichever strategy you pick:

6.2 Persist the configuration on the line

Stash everything you'll need later (cart UI, email receipts, order admin, factory export) on the cart line as private metadata. The keys both reference plugins use:

🔒 Underscore-prefixed properties are hidden from the customer in both Shopify and WooCommerce - use whatever the equivalent "private/hidden line property" convention is on your platform.

The visible "cart properties" the customer sees on the cart line should be a small, human-readable subset:

Fabric:   Olive Velvet
Legs:     Walnut
Frame:    Solid Oak

Both reference plugins build this list by decoding cfg_skumap (the JSON SKU map) and emitting one row per non-structural key - see Woo's woocommerce_get_item_data filter in cart-item-config.php.

6.3 Handle multi-line add-to-cart

When payload.skus.mode === 'multi', you must split the request into one cart line per skus.lines[i]. Every line has its own skuString, quantity, and matching entry in price.productBreakdowns[i] (per-line subtotal, price, selections, image).

This is the path snap2 uses today; dining, bed and any future multi-line configurator type produce the same payload shape, so a mode === 'multi' branch covers all of them - don't gate the cart-bridge logic on the snap2/ prefix.

The Woo extension does this in OV25_Ajax_Cart::finish_multi_line_add_to_cart:

1. Allocate per-line totals from cfg_payload.price.lines (preferred) or split cfg_price evenly as a fallback (allocate_line_prices_minor).
2. Reconcile rounding drift so the per-line sum matches cfg_price (reconcile_line_pence_to_cfg_total).
3. Tag every resulting cart row with the same ov25_multi_line_group UUID so the storefront / order admin can show them as one bundle.
4. Roll back all already-added rows if any single line fails validation.

The Shopify equivalent (buildSnap2CreateInvoiceItems) builds one item per productBreakdowns row and ships them to the create-invoice webhook for resolution to Shopify product/variant ids on the server.

6.4 Promote line meta to the order

The cart bridge is only half the story - the same metadata has to land on the order so production / fulfilment / customer service can read it after checkout.

Hook the platform's "create order line item from cart item" event:

…and copy:

• SKU - the final cfg_sku for the line
• PART - multi-line carts only - the per-line product label decoded from skuMap.Product/Products; lets factory/admin tell which item in the multi-line set the row belongs to
• One order-meta entry per non-structural skuMap key (Fabric: …, Legs: …, Frame: …)
• The thumbnail URL (so admin order screens and emails render the configured product, not the catalogue photo)
• The _ov25_* private bag from section 6.2 verbatim, in case support needs to re-issue or audit a configuration

💳 7. The Checkout Bridge

Whatever you do at the cart, the checkout has to honour the OV25 price too.

Two patterns:

Pattern A - Cart-line price filter

WooCommerce, Magento, anything with a checkout-line filter.

Hook the platform's per-line price calculator and reapply cfg_price. This means default checkout, Shop Pay equivalents, finance widgets, and analytics all see the OV25 price natively. Make sure the filter runs on every OV25 line on every request - not just at add-to-cart.

Pattern B - Custom checkout

Shopify.

Shopify's checkout cannot accept arbitrary line-item prices, so the plugin POSTs the cart to a webhook that creates an Admin-API draft order with custom line prices and returns an invoiceUrl. The plugin replaces the storefront checkout button (requestOV25Checkout) with one that calls the webhook then window.location = data.invoiceUrl.

Subtleties shared by both patterns

1. Hide accelerated checkouts when an OV25 product is in the cart.

Apple Pay / Google Pay / Shop Pay / PayPal Express all skip your custom price logic - they post directly from the cart to the wallet at the catalogue total.

Detect "any cart line has an OV25 product link" and CSS-hide every express button you can find. The reference Shopify integration keys this on cart.items[].properties._ov25_product_id; the Woo equivalent sits in class-ov25-ajax-cart.php. See the theme docs in Shopify.

2. Provide a programmatic checkout entry point (window.requestOV25Checkout()) so themes that ship custom checkout buttons can opt in instead of being hijacked.

3. Set a cart-level marker when redirecting through your custom checkout. If your platform supports cart-level attributes (Shopify's cart.attributes, Woo's session data), set something like ov25_draft_order=true whenever you build the OV25 invoice/draft order. This is what your server-side guard checks (next bullet).

4. Ship a server-side guard.

Add a server-side guard at the checkout step that fails if a cart line has an OV25 product link and the cart-level "this went through OV25" marker is missing.

🎨 8. Swatches

Sample-pack ordering uses the same payload contract but goes through a separate "swatches-only cart" path.

The user clicks Order Samples in the configurator UI → ov25-ui calls your buySwatches(swatches, rules) callback → you redirect them to a checkout for the chosen swatch SKUs.

Both reference plugins implement it as a single REST endpoint:

You also need a swatch book page - a page template that renders the swatches block from ov25-ui against your whole product range. See the WooCommerce OV25_Swatch_Page and the Shopify ov25_swatches.liquid block for examples.

🎛️ 9. Programmatic Controls

Once injected, OV25 exposes a small global API the host theme can call from custom buttons:

window.ov25OpenConfigurator(optionId?: string);  // optional optionId opens directly to that option
window.ov25CloseConfigurator();
window.ov25OpenSwatchBook();
window.ov25CloseSwatchBook();
window.ov25GenerateThumbnail(): Promise<string>;
window.requestOV25Checkout();

Expose at least ov25OpenConfigurator and requestOV25Checkout in your plugin's documented API - every storefront integrator will need them at some point.

🚀 10. Update & Distribution

A real plugin needs to ship updates without breaking stores in production:

• 🏷️ Versioning - tag every release in semver. The Woo plugin uses Plugin Update Checker pointed at GitHub releases (includes/plugin-update-checker/).
• 🛑 Kill switch - keep the ability to remotely disable the plugin if a release goes wrong. The Woo extension polls a webhook (/api/woo-commerce/kill-switch) at boot, returns early if it gets disabled, and caches the result in a 5-minute transient.
• 🪵 Logging prefix - every console message should be prefixed ([ov25-woo], [ov25-shopify]) so support can grep merchant consoles quickly.
• 🧬 Migration safety - when you rename a settings field or cart-item key, write a one-shot migration that copies the old value to the new one.

📚 11. Reference Implementations

Both repositories are MIT-licensed; copy and adapt liberally.

WooCommerce extension

orbitalvision/ov25-woo-extension

Shopify app

orbitalvision/ov25-shopify-app (private; ask Orbital Vision for access)