Evolve Storefront

Evolve Storefront is already pre-integrated with Image Engine. This page will walk you through the necessary configuration to enable the functionality.

Prerequisites

Image Engine API credentials (origin, client ID, and client secret) are required. See Prerequisites for authentication details.

Configuration

Set the following configuration values in the Evolve Storefront instance.

Environment Variable	Feature Flag	Description
EVOLVE_IE_API_ORIGIN	feature.evolveImageEngineOrigin	The Evolve Image Engine API origin. For example, https://api-<tenant id>.evolvestorefront.com.
EVOLVE_IE_API_CLIENT_ID	feature.evolveImageEngineClientId	Evolve Image Engine Client ID for authentication.
EVOLVE_IE_API_CLIENT_SECRET	feature.evolveImageEngineClientSecret	Evolve Image Engine Client Secret for authentication.
EVOLVE_IE_ALLOWED_IMAGE_HOSTS	feature.evolveImageEngineAllowedImageHosts	Comma-separated additional hostnames allowed for product image fetching (e.g., cdn123.bigcommerce.com,images.example.com). The store's own domain, the request host, and the IMAGE_REQUEST_TEMPLATE CDN host are always allowed automatically.

Credentials

Image Engine API credentials must be set via environment variables or secrets management — never via client-accessible configuration such as BigCommerce channel metafields. These values grant access to the Image Engine API and must not be exposed to the browser.

Store Default Configuration

The following feature flags control store-wide VTO defaults. These serve as fallbacks when individual products do not specify their own VTO attributes.

Feature Flag	Default	Description
feature.evolveImageEngineVtoDefaultType	none	The store default VTO type. One of garment, scene, surface, or none. When set to none, VTO is disabled store-wide unless individual products opt in via product attributes.
feature.evolveImageEngineVtoDefaultGarmentClass	none	The default garment class. One of UPPER_BODY, LOWER_BODY, FOOTWEAR, FULL_BODY, or none. Required when default type is garment — VTO will not activate for garment mode unless a valid garment class is provided (either here or on the product).
feature.evolveImageEngineVtoDefaultMaterialClass	none	The default material class for surface mode. One of FABRIC, TILE, WOOD, PAINT, WALLPAPER, STONE, or none. Optional — surface VTO works without a material class, but providing one improves result quality.

tip

Set evolveImageEngineVtoDefaultType to a VTO mode (e.g., garment) to enable VTO across all products by default. Individual products can then override or opt out using product attributes.

Product Data Configuration

VTO can be configured on a per-product basis using product attributes. When set, product attributes take priority over store defaults.

Attribute	Values	Required	Description
vto.type	garment, scene, surface, none	Yes (to enable VTO)	The VTO mode for this product. Set to none to explicitly disable VTO for a product, even if store defaults would enable it.
vto.garmentClass	UPPER_BODY, LOWER_BODY, FOOTWEAR, FULL_BODY	Yes, for garment mode	Identifies the garment category. Either this attribute or the store default garment class must be set for garment VTO to activate.
vto.materialClass	FABRIC, TILE, WOOD, PAINT, WALLPAPER, STONE	No	The material type for surface mode. Optional — improves result quality when provided.

Resolution rules:

• Attribute identifiers are case-insensitive (e.g., VTO.Type and vto.type are equivalent).
• Product attributes take priority over store default feature flags. If a product has vto.type=scene, the store default type is ignored.
• Setting vto.type=none on a product disables VTO for that product, even if store defaults are configured.
• VTO attributes are automatically hidden from the product detail page — they are not displayed to shoppers.

HCL Commerce Setup

For HCL Commerce stores, configure VTO product attributes in Management Center:

1. Create product attributes named vto.type, vto.garmentClass, and/or vto.materialClass as descriptive attributes.
2. Assign the appropriate values to each product (e.g., vto.type = garment, vto.garmentClass = UPPER_BODY).
3. Store-level feature flag overrides can also be set via HCL store configuration (Vault or Secrets Manager).

BigCommerce Setup

For BigCommerce stores, VTO is configured using custom fields for per-product settings and channel metafields for store-wide defaults.

Per-Product VTO via Custom Fields

BigCommerce uses custom fields (not product options) to carry VTO attributes. The storefront queries custom fields via the GraphQL Storefront API and maps them to product attributes automatically.

To configure VTO on a product:

1. In the BigCommerce Admin, navigate to Products → Edit Product → Custom Fields.
2. Add custom fields with the same attribute names and values documented in the Product Data Configuration table above:
   • Name: vto.type — Value: garment, scene, surface, or none
   • Name: vto.garmentClass — Value: UPPER_BODY, LOWER_BODY, FOOTWEAR, or FULL_BODY
   • Name: vto.materialClass — Value: FABRIC, TILE, WOOD, PAINT, WALLPAPER, or STONE
3. Save the product.

Custom fields can also be managed in bulk via the BigCommerce Management API.

Store Defaults via Channel Metafields

Store-wide VTO defaults can be configured at runtime using channel metafields in the evolve_features namespace. This allows you to change defaults without redeployment.

Metafield Key	Values	Description
evolveImageEngineVtoDefaultType	garment, scene, surface, none	Store default VTO type
evolveImageEngineVtoDefaultGarmentClass	UPPER_BODY, LOWER_BODY, FOOTWEAR, FULL_BODY, none	Store default garment class
evolveImageEngineVtoDefaultMaterialClass	FABRIC, TILE, WOOD, PAINT, WALLPAPER, STONE, none	Store default material class

Example: Set the store default VTO type to garment

curl -X POST "https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}/metafields" \
  -H "X-Auth-Token: {management_api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "evolve_features",
    "key": "evolveImageEngineVtoDefaultType",
    "value": "garment",
    "permission_set": "read_and_sf_access",
    "description": "Store default VTO type for Image Engine"
  }'

Metafield values are always strings. Set permission_set to "read_and_sf_access" so the storefront can read the value via the GraphQL Storefront API.

Storefront Behavior

Once configured, a VTO action button appears on the product detail page (PDP). The button label varies by mode:

Mode	Button Label
Garment	Try On
Scene	See in Your Space
Surface	Visualize Material

The button is shown when all of the following are true:

• Image Engine API credentials are configured (origin URL is non-empty).
• VTO configuration resolves to a valid mode for the product.
• The product has at least one image.
• The product is not a kit or bundle.

User flow when the button is clicked:

1. Consent — A privacy disclosure is shown on first use, explaining that the user's photo is sent to an AI service and is not stored.
2. Upload — The user uploads a photo via drag-and-drop, file browser, or device camera.
3. Configure (scene and surface modes only) — The user enters a text prompt describing where the product should appear or which surface to apply the material to.
4. Processing — The image is generated (typically 3-8 seconds).
5. Result — The result image is displayed with an option to download.

Image Requirements

• Product images must be accessible via HTTPS from the storefront server. The server fetches the product image and sends it to the Image Engine API.
• User-uploaded photos must be JPEG or PNG format, with a maximum of 3,072 pixels on the longest side.
• If an image CDN is configured via IMAGE_REQUEST_TEMPLATE, product images are fetched through the CDN at 1200px width and 85% quality by default.