Using your own IDs

By default, every product you create gets an id we generate — a UUID you’d need to store somewhere in your own system to look the product back up later, or to fill in PRODUCT_ID in the storefront snippet. external_id lets you skip that: set it to whatever you already use to identify the product — a SKU, a database primary key — and use that value as the storefront productId and to look products up, instead of storing our id.

Set it at create time

curl -X POST https://api.integration.tryonvirtual.com/v1/products \
  -H "Authorization: Bearer tryon_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Classic Fit Shirt — Red, XL",
    "category": "clothes",
    "external_id": "SHIRT-XL-RED"
  }'

{
  "product": {
    "id": "7a2b9c1d-3e4f-4a5b-8c6d-1234567890ab",
    "external_id": "SHIRT-XL-RED",
    "title": "Classic Fit Shirt — Red, XL",
    "category": "clothes",
    "tryon_status": "inactive",
    "swap_ready": false,
    "...": "..."
  },
  "images_failed": []
}

You still get an id back — that never goes away — but from here on you can ignore it and work entirely in terms of SHIRT-XL-RED.

Or set it later with PATCH

If a product already exists and you’re backfilling external_id for it (migrating from a system that only had our id, for example), PATCH works the same way:

curl -X PATCH https://api.integration.tryonvirtual.com/v1/products/7a2b9c1d-3e4f-4a5b-8c6d-1234567890ab \
  -H "Authorization: Bearer tryon_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "SHIRT-XL-RED"}'

It’s unique per shop

external_id only has to be unique within your own shop — two different shops can each use SHIRT-XL-RED for unrelated products. Trying to set an external_id that’s already in use on another product in your shop returns 400 validation_error.

Look products up by it

curl "https://api.integration.tryonvirtual.com/v1/products?external_id=SHIRT-XL-RED" \
  -H "Authorization: Bearer tryon_sk_your_key"

This is the read side of the same mapping — useful for a sync job that needs to check “does this SKU already exist as a TryOn product?” before deciding whether to POST or PATCH.

It’s also how you act on a product when all you have is its external_id: look it up, take the id from the result, then use that id in the path of any endpoint that isn’t POST /v1/products. For example, enabling try-on for SHIRT-XL-RED:

# 1. Look up the TryOn id for your external_id
PRODUCT_ID=$(curl -s "https://api.integration.tryonvirtual.com/v1/products?external_id=SHIRT-XL-RED" \
  -H "Authorization: Bearer tryon_sk_your_key" | jq -r '.products[0].id')

# 2. Use that id — not the external_id — in the PATCH path
curl -X PATCH "https://api.integration.tryonvirtual.com/v1/products/$PRODUCT_ID" \
  -H "Authorization: Bearer tryon_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"mode": "swap", "tryon_enabled": true}'

Use it as PRODUCT_ID directly

Once external_id is set, drop it straight into the storefront snippet in place of our id:

<button type="button" data-tryon-product-id="SHIRT-XL-RED">Try On</button>

<script async
  src="https://api.integration.tryonvirtual.com/api/v1/tryon/scripts/embed/bootstrap.js?shop_slug=YOUR_SHOP_SLUG&productId=SHIRT-XL-RED">
</script>

This is the one place external_id is a full drop-in for id — the embed script and the button’s data-tryon-product-id both accept either value interchangeably. Combined with the ?external_id= filter for lookups, most integrations that manage their own catalog find they never need to store our id in a template at all — only in the occasional server-side call that needs the lookup step above.

Not available on Shopify-platform shops

external_id is read-only for shops on the Shopify platform: PATCH requests that try to set it are rejected with 400 validation_error. On Shopify, that mapping is already owned by the Shopify sync — every TryOn product created from a Shopify sync carries the Shopify product id internally, and introducing a second, independently-set external id would create two competing sources of truth for the same mapping. This API’s external_id field exists for WooCommerce, custom platforms, and any other non-Shopify shop that needs to bring its own identifiers.

WooCommerce — a worked integration using the Woo product SKU as external_id.