Skip to main content
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.
Product IDs and handles are identifiers, not display text. Keep them stable and send updates under the same product ID.

​
Import a CSV

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

​
CSV columns

ColumnRequiredDescription
product_idYesStable identifier used for upserts and optional URL matching.
titleYesMerchant-facing product title.
product_image_url or product_image_urlsYesOne URL, or multiple URLs separated by |.
handleWhen matching by handleURL-safe storefront handle or slug.
preview_image_urlNoThumbnail shown in virtual.fit.
enabledNotrue 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:
Replace $VIRTUAL_FIT_API_BASE, $SITE_ID, and $VIRTUAL_FIT_API_KEY with values from your account and server environment.
Never make this request from browser JavaScript. A management API key can modify catalog data and must remain server-side.

​
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.
1

Upsert changed records

Send a product when its title, handle, images, or eligibility changes. Reusing the product ID keeps the operation idempotent.
2

Disable before deleting

Send enabled: false when a product should stop appearing. This removes storefront eligibility without losing diagnostic history.
3

Verify processing

Confirm the product appears in virtual.fit and finishes image preparation.
4

Test URL resolution

Paste the live URL into the product URL tester and confirm it matches the expected enabled record.

​
Common sync failures

FailureFix
Missing required valuesInclude product_id, title, and at least one image URL.
Image analysis never completesConfirm the image URL is publicly reachable and returns an image content type.
URL tester finds no productAlign the URL-derived value with handle or product_id.
Unexpected image set after updateSend the complete intended product_image_urls array, not only the new image.