Product identifiers and variants#
The storefront target must identify the same product as the merchant catalog. Most integration failures start with a mismatch between those two values.
Choose a stable identifier#
Use the productCode shown for the prepared product. In the Shopify tutorial this is the variant SKU. Product Import API request fields are defined in the import reference; do not replace those field names with storefront attribute names.
Keep identifiers identical, including case. Do not generate them from mutable display names or assume that a platform's internal product ID equals an SKU.
Map the selected variant#
| Storefront state | Target behavior |
|---|---|
| A prepared variant is selected | Set its exact productCode |
| The selection changes | Update the target and clear stale SDK state using your integration guide |
| No SKU or matching product exists | Keep the authored button hidden or disabled |
| A product card points to a default variant | Use that variant's identifier consistently |
For Shopify, wire the tutorial's synchronization helper to your theme's actual variant-change callback. For other storefronts, follow dynamic pages.
Validate the mapping#
Choose two variants with visibly different products. Record their catalog codes, inspect each rendered data-product-code in browser developer tools, then open the Viewer for each. Repeat after navigating without a full page reload.
When an identifier changes in your source system, coordinate the catalog import and storefront release. A successful HTTP import response is only acceptance; inspect job status and item failures before relying on the new code.