> ## Documentation Index
> Fetch the complete documentation index at: https://docs.virtual.fit/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolve product URLs

> Map custom storefront URLs to enabled virtual.fit catalog products.

Before rendering, virtual.fit matches the current page to a synced product. Configure one deterministic rule and test it with real storefront URLs.

## Resolution modes

| Mode              | Example URL                       | Configuration                        | Extracted value     |
| ----------------- | --------------------------------- | ------------------------------------ | ------------------- |
| Path template     | `/products/linen-dress`           | `/products/:handle`                  | `linen-dress`       |
| Last path segment | `/collections/summer/linen-dress` | Match by handle                      | `linen-dress`       |
| Query parameter   | `/product?sku=sku-10042`          | Parameter `sku`, match by product ID | `sku-10042`         |
| Custom regex      | `/shop/item/linen-dress`          | `^/shop/item/([^/]+)$`               | First capture group |

### Path template

Use a path template when product routes have a consistent structure.

```text theme={null}
/products/:handle
/shop/:handle
/p/:product_id
```

The token must match **Match Products By**. Use `:handle` when matching handles and `:product_id` when matching external product IDs.

### Last path segment

Use this only when the final path segment is always the product handle or ID.

```text theme={null}
/women/dresses/linen-midi-dress
                      └─ linen-midi-dress
```

Avoid it if locale, variant, or campaign segments can appear after the product value.

### Query parameter

Use this for routes that expose a stable product identifier in the query string.

```text theme={null}
/product?sku=sku-10042
```

Set **Query Parameter Name** to `sku` and match by **Product ID**.

### Custom regex

Use a custom regular expression only when the standard modes cannot represent the route. The first capture group becomes the product hint.

```regex theme={null}
^/shop/item/([^/]+)$
```

<Warning>
  Keep the expression anchored and narrow. A broad regex can accidentally match category, search, or account pages.
</Warning>

## Test the rule

In virtual.fit's **Live URL Tester**:

1. Paste an absolute URL from the real storefront.
2. Confirm the extracted value.
3. Confirm the matched product title and ID.
4. Confirm the message says the product is enabled.

Test at least:

* A valid enabled product.
* A valid disabled product.
* An unknown product.
* A collection or search page.
* A localized route, if your storefront uses locales.

## Manual product context

For SPAs, query-driven PDPs, or routes that cannot be expressed by a rule, call `setProduct` after initialization:

```javascript theme={null}
window.bitstudio?.('setProduct', {
  id: product.id,
  handle: product.handle,
  title: product.title,
  imageUrl: product.featuredImage
});
```

The `id` or `handle` must still identify a synced, enabled product. Manual context does not bypass its availability settings in virtual.fit.

Call `setProduct` again after your router commits each new product page.

### Color and style variants

When variants use different garments or colors, sync each one with its own external product ID. Pass the selected variant's synced ID when the shopper changes variants.

`imageUrl` provides the media shown in the storefront context. It does not replace the garment associated with the synced product ID. Reusing one ID while changing only `imageUrl` continues to use that ID's prepared garment.

```javascript theme={null}
bitstudio('setProduct', {
  id: selectedVariant.virtualFitProductId,
  title: selectedVariant.title,
  imageUrl: selectedVariant.featuredImage
});
```

## Fail-closed behavior

The widget stays hidden when:

* The rule extracts no value.
* The value does not match a synced product.
* The matched product is disabled.
* The matched product has no usable garment images.

This is expected behavior. Do not add a fallback product unless every unmatched page should deliberately use that product.