Product IDs, Variant IDs, and SKUs

Faslet matches product-page interactions, orders, returns, and feed data by keeping three identifiers consistent: the product ID, the variant ID, and the SKU. Most integration issues happen when those values are mixed up across the feed, the PDP integration, checkout tracking, and return tracking.

This page is the canonical reference for which value Faslet expects in each place.

The Three Identifiers

Identifier	What it identifies	Recommended source	Important rule
Product ID	The parent product or style	Usually the same value as your feed `item_group_id`	Keep this stable across the PDP, order tracking, and returns. Do not use a per-variant SKU here.
Variant ID	One purchasable variant, such as size/color	Usually your commerce platform's variant identifier	This is mainly used for variant selection and add-to-cart. It does not have to equal the SKU.
SKU	The merchant SKU for a specific purchasable variant	The SKU shown in your commerce platform, OMS, and return systems	Keep this exact value consistent between the widget variants, order tracking, and return tracking.

A Good Product ID

It doesn't matter what format your Product ID has, as long as it refers to the parent product and stays the same everywhere. On product pages, Faslet uses this to resolve the right sizing context, so we do not recommend using variant identifiers such as a GTIN, SKU, or platform variant ID here.

In most setups, the best choice is the same value you use as the Google Shopping item_group_id. This is often called a Product ID, Product Group ID, Parent Product ID, or Parent ID.

One Concrete Product Example

For one product with three variants, the values could look like this:

Concept	Example value
Product title	`Classic Oxford Shirt`
Product ID	`OXFORD-SHIRT`
Variant ID for Small / Blue	`shopify-variant-451001`
Variant ID for Medium / Blue	`shopify-variant-451002`
Variant ID for Large / Blue	`shopify-variant-451003`
SKU for Small / Blue	`OXFORD-BLUE-S`
SKU for Medium / Blue	`OXFORD-BLUE-M`
SKU for Large / Blue	`OXFORD-BLUE-L`

The important part is the relationship:

OXFORD-SHIRT is the parent product and stays the same for every variant.
Each purchasable size has its own variantId.
Each purchasable size also has its own sku.

Same Values in Different Places

The identifiers above are the values that must stay consistent across systems. A few other fields are also important because they are required for order tracking, returns, analytics, or size matching.

Product ID Mapping

Surface	Expected field name
Product feed	`item_group_id`
Web component integration	`product-identifier`
`window._faslet`	`id`
NPM widget	`.withProductId(PRODUCT_IDENTIFIER)`
React widget	`productId`
PHP widget	`->withProductId(PRODUCT_IDENTIFIER)`
Headless size advice API	`productId`
Browser order tracking	`correlationId`
Orders API	`lineItems[].productId`
Returns API	`productId`

Variant ID Mapping

Surface	Expected field name
Product feed	`id`
`window._faslet`	`variants[].id`
NPM widget	`.addVariant(VARIANT_ID, ...)`
React widget	`variants[].variantId`
PHP widget	`->addVariant(VARIANT_ID, ...)`
Headless size advice API	`variants[].variantId`
Browser order tracking	`variant_id`
Orders API	`lineItems[].variantId`

SKU Mapping

Surface	Expected field name
`window._faslet`	`variants[].sku`
NPM widget	`.addVariant(..., VARIANT_SKU, ...)`
React widget	`variants[].sku`
PHP widget	`->addVariant(..., VARIANT_SKU, ...)`
Browser order tracking	`sku`
Orders API	`lineItems[].sku`
Returns API	`sku`

Size Label Mapping

Surface	Expected field name
Product feed	`size`
`window._faslet`	`variants[].size`
NPM widget	`.addVariant(..., SIZE_LABEL, ...)`
React widget	`variants[].sizeLabel`
PHP widget	`->addVariant(..., SIZE_LABEL, ...)`
Headless size advice API	`variants[].sizeLabel`
Browser order tracking	`variant`
Orders API	`lineItems[].variant`

For order tracking, variant should be the shopper-facing variant description, usually the size label or a size/color label such as M or M / Blue. Do not send the variant ID in this field.

Other Required Fields Worth Mapping

These are not identifier fields, but they are still important to get right:

Concept	Browser order tracking	Orders API	Returns API	Why it matters
Order number	`order`	`orderId`	`orderId`	Connects purchases and returns to the same order.
Payment status	`payment_status`	`paymentStatus`	Not used	Prevents unpaid or invalid orders from being counted.
Product title	`title`	`lineItems[].title`	Not used	Makes reporting and troubleshooting easier.
Variant label	`variant`	`lineItems[].variant`	Not used	Records which size or size/color the shopper bought.
Quantity	`quantity`	`lineItems[].quantity`	Not used	Needed for order value and conversion analysis.
Price	`price`	`lineItems[].price`	Not used	Needed for AOV and revenue analysis.
Return reason	Not used	Not used	`returnReason`	Required for return analysis.
Return date	Not used	Not used	`returnDate`	Required for return processing and reporting.
External return ID	Not used	Not used	`externalId`	Useful for debugging and reconciling returns.

If you send orders through the Orders API instead of the browser script, customerDataPackage is also required at the order level.

Example Payloads

Product Feed

For the example product above, your feed rows would normally use the same parent product ID and distinct variant IDs:

Feed field	Small / Blue	Medium / Blue
`item_group_id`	`OXFORD-SHIRT`	`OXFORD-SHIRT`
`id`	`shopify-variant-451001`	`shopify-variant-451002`
`size`	`S`	`M`

PDP Integration

<faslet-app
    shop-id="SHOP_ID"
    product-name="Classic Oxford Shirt"
    product-identifier="OXFORD-SHIRT"
    brand="Oxford Co"
    product-img="https://example.com/oxford-shirt.jpg"
></faslet-app>

window._faslet = {
    id: "OXFORD-SHIRT",
    variants: [
        {
            id: "shopify-variant-451001",
            sku: "OXFORD-BLUE-S",
            size: "S",
            color: "blue",
            available: true,
            price: 79.95,
        },
        {
            id: "shopify-variant-451002",
            sku: "OXFORD-BLUE-M",
            size: "M",
            color: "blue",
            available: true,
            price: 79.95,
        },
    ],
};

Order Tracking

In the browser integration, the same identifiers appear like this:

window._faslet_orders.event("widget_order_track", "SHOP_ID", {
    order: "100023",
    payment_status: "paid",
    sku: "OXFORD-BLUE-M",
    correlationId: "OXFORD-SHIRT",
    title: "Classic Oxford Shirt",
    variant_id: "shopify-variant-451002",
    variant: "M / Blue",
    price: 79.95,
    quantity: 1,
});

If you use the Orders API instead of the browser script, that same line item becomes productId, variantId, and sku.

Return Tracking

For return tracking, Faslet needs the order ID plus the same product-level and SKU-level identifiers:

[
    {
        "orderId": "100023",
        "productId": "OXFORD-SHIRT",
        "sku": "OXFORD-BLUE-M",
        "returnReason": "1",
        "returnDate": "2026-05-12T10:15:00.000Z",
        "externalId": "return-100023"
    }
]

In the Returns API, orderId, productId, and sku are the key matching values. orderId links the return back to the purchase, while productId and sku identify the specific item. There is no separate variantId field there.

Rules of Thumb

Use the same parent product ID everywhere the docs refer to productId, PRODUCT_IDENTIFIER, product-identifier, or correlationId.
Use a real variant identifier everywhere the docs refer to variantId, VARIANT_ID, variants[].id, or variant_id.
Use the exact purchasable SKU everywhere the docs refer to sku.
Use a human-readable size or size/color label everywhere the docs refer to variant or sizeLabel.
It is fine if variantId and sku are different values. That is normal on many platforms.
If your feed is already live in Faslet, start from its item_group_id and variant rows and map your storefront data to those values.

Variant IDs and Add-to-Cart

Variant IDs are especially important for add-to-cart. On many platforms, this must be the platform's real variant identifier so that add-to-cart can select the correct item. For custom platforms, Faslet simply passes the selected Variant ID back into your add-to-cart function.

That means the Variant ID should be whatever your storefront needs to add the correct variant to cart, while the SKU should stay whatever your operational systems use for order and return matching.

SKUs

It is important to send SKUs with the variants, as well as with orders and returns. This allows Faslet to track the specific item that was recommended, purchased, and returned. For analytics, this makes it possible to report at SKU level for outcomes such as return percentages and missed sales.

The Three Identifiers​

A Good Product ID​

One Concrete Product Example​

Same Values in Different Places​

Product ID Mapping​

Variant ID Mapping​

SKU Mapping​

Size Label Mapping​

Other Required Fields Worth Mapping​

Example Payloads​

Product Feed​

PDP Integration​

Order Tracking​

Return Tracking​

Rules of Thumb​

Variant IDs and Add-to-Cart​

SKUs​