Prepare your Shopify catalogue for Keyban DPP
Before connecting a shop (see the Publish on Shopify tutorial), it's worth understanding how Keyban decides which DPP passport belongs to which Shopify product — and who is accountable if that match is wrong.
Why the match matters
A Digital Product Passport is only useful if it points to the right physical product. Keyban builds the passport from the data it receives through the catalogue sync; it has no way to know, on its own, whether a given Shopify product and a given passport are supposed to describe the same physical good.
How Keyban identifies your Shopify products today
The catalogue sync uses the Shopify product's own id — the identifier Shopify assigns automatically when a product is created — as the passport's modelNumber. This value is not something you type in; it's inherited unchanged from Shopify.
| Shopify object | DPP idGranularity | Identifier used |
|---|---|---|
Product | model | Shopify product id → modelNumber |
ProductVariant (at order time) | item | Same modelNumber as the parent product; the order's line item ties the item passport to a specific variant |
Every Shopify product always has at least one ProductVariant, even when the merchant never created one explicitly — Shopify's own data model requires it. That variant becomes an item passport only when a buyer orders it; it is never turned into a batch passport. The Shopify sync never produces batch-granularity passports — see Pick a granularity first and the granularity table for what each granularity means and when you'd want it instead.
Nothing to configure — and why
There's no setup step for the match on your side — Keyban uses the Shopify product id automatically, and that has three concrete advantages over a manually entered reference:
- No field to fill in. There is no screen in Shopify or in the Keyban Admin where you enter a reference for the match — the product
idis used as-is. - No format to validate. The identifier is a Shopify-issued value; Keyban does not impose or check a format on it.
- No duplicates to handle. Shopify guarantees product IDs are unique within a shop, so the failure mode "two products map to the same passport" cannot occur through this path.
The sync can still fail for other reasons — an unpublished variant, a revoked OAuth token, a webhook signature mismatch. Those are already covered in the Common errors table of the Shopify integration guide; this page doesn't repeat them.
Expose the DPP URL per product (e.g. in notification emails)
Because the match described above is keyed on the Shopify product id, Keyban can also write back to that same product once its model passport exists — a keyban.passport_path metafield (a path relative to your DPP application). This is how you link to a specific product's passport from Shopify surfaces that can read product metafields, including notification templates — see Product-scope metafields in the Shopify integration guide for the Liquid snippet and its caveats (it points to the model passport, not the buyer's claimable item passport).
Future flexibility
Using a different reference — a SKU, or a custom Shopify metafield — instead of the Shopify product ID is not configurable today. If this becomes possible in the future, expect the choice to be locked in before your first import: changing the reference field afterwards would require deleting and re-importing every synced product.