JavaScript API

At runtime the frontend exposes everything through the global window.FPD object. The same object also serves as the input configuration (see Configuration) — the bundle merges its runtime state into whatever your theme defined before load.

Runtime objects

Property	What it is
FPD.instance	The live FancyProductDesigner instance — the main scripting surface (see below). Exists after the designer was created on a product page.
FPD.productPage	The product page orchestrator (see below).
FPD.CartPage	Cart page handler (cart page only).
FPD.generalPage	AJAX-cart handler (all pages).
FPD.optionsManager	Access to all resolved options and feature flags.
FPD.ta	The resolved theme-abstraction selector tree (product, cart, cartJS, modal).
FPD.shopOptions	The merged shop options.
FPD.utils	{ deepMerge, formatPrice } helpers.
FPD.formatMoney	Shopify money formatter.
FPD.func	Callable helpers (see below).

FPD.func.*

Function	Purpose
FPD.func.fpdDebug()	Highlights and logs all theme-abstraction selectors on the page — the fastest way to see whether FPD found your form, button, and container.
FPD.func.updateCartImages()	Re-runs cart page thumbnail replacement.
FPD.func.updateCartJSImages()	Re-runs AJAX-cart/drawer thumbnail replacement.

FPD.instance — the designer

The designer instance follows the Fancy Product Designer API. The most useful members for integrators:

const fpd = FPD.instance;

fpd.calculatePrice();        // current total customization price
fpd.getElements();           // all elements of the current view
fpd.getCustomElements('all') // elements the customer added
fpd.currentViewInstance      // active view (fabricCanvas etc.)
fpd.viewInstances            // all views
fpd.loadProduct(productJson) // load an FPD product programmatically

fpd.addEventListener('ready', ...);
fpd.addEventListener('productCreate', ...);

caution

FPD.instance is replaced when the designer is re-initialized (e.g. after certain variant changes). Don't keep long-lived references; re-read FPD.instance or re-attach listeners on productCreate.

FPD.productPage

Member	Purpose
getPluginOption(path)	Read any per-product plugin option by path, e.g. getPluginOption('langJSON').
getShopifyProduct()	The Shopify product JSON (from #ProductJson-FPD).
getCurrentShopifyVariant()	The currently selected variant (from the URL).
getAtcBehavior()	'add' or 'update' (update = editing an existing cart line).
updateTa(path, value)	Change a theme-abstraction selector at runtime.
reinitializeDesigner()	Full designer rebuild — use after your theme morphs the surrounding DOM.
debugTa()	Same as FPD.func.fpdDebug().
existingLic	The loaded saved design when the page was opened via an edit link, otherwise unset.

Callbacks (FPD.callbacks)

Callbacks are functions your theme provides before the bundle loads; the frontend invokes them at defined points. This is the supported way to customize flow behavior.

window.FPD = window.FPD || {};
window.FPD.callbacks = {
  beforeAddToCart(form) {
    // validate; throw to abort the add-to-cart
  },
  addToCart(addedProduct) {
    // after a successful add
  },
};

Add-to-cart flow

Callback	Signature	Purpose
beforeAddToCart	(form)	Runs before the add. Throwing aborts the add-to-cart — use for custom validation.
addToCart	(addedProduct)	After a successful add.
addProductToForm	(form)	Replaces the default form.submit() under the submit_form strategy; also called after bulk-order adds with (form, data).
triggerCartDrawer	(response)	Open your own cart drawer under the trigger_cart_drawer strategy.
cartSections	() => string[]	Section IDs to request from /cart/add.js (Section Rendering API).

Line item properties

Callback	Signature	Purpose
cartTextPropertiesPost	(properties, lineItemCache, shopifyProduct) => properties	Rewrite the line item properties before they are written. Keep all _fpd* keys!
afterSaveCustomization	(properties) => properties	Same, for the save-button flow.

Custom products (LIC)

Callback	Signature	Purpose
onLicCreated	(lic, resolve)	Intercept after the design was stored; must call resolve() to continue.
newProductName	(shopifyProduct, variantId) => string	Name for a generated custom product.
extraTags	(shopifyProduct, variantId) => tags	Extra tags for a generated custom product.

Page lifecycle & UI

Callback	Signature	Purpose
productPageDone	()	Product page init finished (designer may still be loading).
afterProductLoaded	(fpdProductJSON)	The FPD product configuration was loaded.
elementModify	(isCustomized)	An element changed.
mainImageReplaceCallback	(imageEl, previewDataUrl)	Customize how the main product image is replaced with the design preview.
cartImageFallback	(item, rowEl, images, originalUrl)	Take over cart-page thumbnail replacement when the default doesn't fit your markup.
cartJSImageFallback	(item, itemEl, image, originalUrl, result) => result	Same for AJAX carts/drawers.
cartAfterUpdate	()	After a cart update on the cart page.
cartBeforeCheckout	()	After the checkout button was clicked (best-effort; not guaranteed on all themes).

Other useful globals

• FPD.additionalPrice — a flat surcharge added to every calculated price (number).
• FPD.earlyLoadProduct — start loading the product JSON as early as possible.
• FPD_EXT.productHash — alternative way to hand a saved-design hash to the page (instead of the ?_fpd-hash URL parameter).
• FPD.debug / FPD.errorReporting — see Troubleshooting.