> ## 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.

# Sync the catalog

> Sync custom storefront products by CSV or authenticated management API.

virtual.fit can resolve and render only products that exist in its synced catalog. Use CSV for scheduled or manual imports. Use the management API for continuous server-to-server sync.

## Product record

Each product needs:

* A stable external product ID.
* A title.
* At least one publicly accessible product image URL.
* A handle when URL matching uses handles.
* `enabled: true` before it may appear on the storefront.

<Note>
  Product IDs and handles are identifiers, not display text. Keep them stable and send updates under the same product ID.
</Note>

## Import a CSV

In virtual.fit, open **Custom JS → Sync Products** and download the CSV template.

```csv theme={null}
product_id,title,handle,preview_image_url,product_image_urls,enabled
sku-10042,Linen Midi Dress,linen-midi-dress,https://cdn.example.com/linen-thumb.jpg,https://cdn.example.com/linen-front.jpg|https://cdn.example.com/linen-back.jpg,true
sku-10043,Blue Tailored Blazer,blue-tailored-blazer,https://cdn.example.com/blazer-thumb.jpg,https://cdn.example.com/blazer-front.jpg|https://cdn.example.com/blazer-back.jpg,false
```

### CSV columns

| Column                                      | Required                | Description                                                         |
| ------------------------------------------- | ----------------------- | ------------------------------------------------------------------- |
| `product_id`                                | Yes                     | Stable identifier used for upserts and optional URL matching.       |
| `title`                                     | Yes                     | Merchant-facing product title.                                      |
| `product_image_url` or `product_image_urls` | Yes                     | One URL, or multiple URLs separated by `\|`.                        |
| `handle`                                    | When matching by handle | URL-safe storefront handle or slug.                                 |
| `preview_image_url`                         | No                      | Thumbnail shown in virtual.fit.                                     |
| `enabled`                                   | No                      | `true` by default. Accepts `true/false`, `1/0`, `yes/no`, or `y/n`. |

CSV rows upsert by `product_id`. Importing the same ID updates the existing product.

## Push from your backend

Use the management API from a trusted server:

```bash theme={null}
curl --request PUT \
  "$VIRTUAL_FIT_API_BASE/vfr/manage/sites/$SITE_ID/products/sku-10042" \
  --header "Authorization: Bearer $VIRTUAL_FIT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Linen Midi Dress",
    "handle": "linen-midi-dress",
    "preview_image_url": "https://cdn.example.com/linen-thumb.jpg",
    "product_image_urls": [
      "https://cdn.example.com/linen-front.jpg",
      "https://cdn.example.com/linen-back.jpg"
    ],
    "enabled": true
  }'
```

Replace `$VIRTUAL_FIT_API_BASE`, `$SITE_ID`, and `$VIRTUAL_FIT_API_KEY` with values from your account and server environment.

<Warning>
  Never make this request from browser JavaScript. A management API key can modify catalog data and must remain server-side.
</Warning>

### Upsert behavior

* The `product_id` in the URL is the idempotency key.
* Sending an existing product ID updates its record.
* `title` and at least one product image URL are required.
* Sending `product_image_urls` replaces the linked image URL set for that product.
* `enabled` defaults to `true` when omitted on a new record.
* `handle` and `preview_image_url` are optional but recommended.

## Image requirements

Product image URLs must be reachable by virtual.fit without shopper cookies, expiring browser sessions, or IP-bound authorization.

Use:

* HTTPS URLs.
* Stable CDN paths.
* High-resolution JPEG, PNG, or WebP images.
* Images that show one garment clearly.

Avoid short-lived signed URLs unless they remain available during initial preparation and later refreshes.

## Recommended sync strategy

<Steps>
  <Step title="Upsert changed records">
    Send a product when its title, handle, images, or eligibility changes. Reusing the product ID keeps the operation idempotent.
  </Step>

  <Step title="Disable before deleting">
    Send `enabled: false` when a product should stop appearing. This removes storefront eligibility without losing diagnostic history.
  </Step>

  <Step title="Verify processing">
    Confirm the product appears in virtual.fit and finishes image preparation.
  </Step>

  <Step title="Test URL resolution">
    Paste the live URL into the product URL tester and confirm it matches the expected enabled record.
  </Step>
</Steps>

## Common sync failures

| Failure                           | Fix                                                                            |
| --------------------------------- | ------------------------------------------------------------------------------ |
| Missing required values           | Include `product_id`, `title`, and at least one image URL.                     |
| Image analysis never completes    | Confirm the image URL is publicly reachable and returns an image content type. |
| URL tester finds no product       | Align the URL-derived value with `handle` or `product_id`.                     |
| Unexpected image set after update | Send the complete intended `product_image_urls` array, not only the new image. |