search_catalog に新しく追加された sources パラメータで、Shopify マーチャントの商品と外部ブランドの商品をひとつのレスポンスで受け取れる。指定しなければ従来どおりなので、既存の呼び出しは変更不要。
sources パラメータを付ければ、Shopify で販売していないブランドの商品も同じレスポンスで返せる。
search_catalog の結果は Shopify で販売している商品に限定。sources を省略すれば今後もこの挙動のまま。
["shopify","external"] で両方、["external"] で外部ブランドのみ。新しいエンドポイントは不要。
search_catalog メソッドに sources を足すだけ。get_product も外部商品の ID を渡せば外部商品を返す。lookup_catalog の対応は「後日」とされている。
| sources の値 | 返る商品 | 既存コードへの影響 |
|---|---|---|
省略 または ["shopify"] |
Shopify マーチャント商品のみ | 変更不要（従来と同じ挙動） |
["shopify", "external"] |
Shopify ＋ 外部 両方 | 外部商品の扱い（リンク先など）を実装する必要あり |
["external"] |
外部 Shopify で販売していないブランドのみ | 同上 |
sources パラメータで外部商品を含められる。
外部商品の ID を渡すと外部商品を返す。
「coming later」とのみ記載。時期は記載なし。
eligible.native_checkout: false。Shopify checkout で購入できず、Promoted Placements の手数料（commission）も発生しない。Catalog API でサイト内検索やレコメンドを提供していて、Shopify 外のブランド商品も載せたいアプリ。
外部商品が返るのはショッパーが米国にいる場合だけ。他の国では Shopify マーチャント商品のみが返る。
ベータ期間中、外部商品のデータは各ブランドの Web サイトから取得されている。
Shopify 商品だけでよければ何もしなくてよい。既存の search_catalog 呼び出しはそのまま動く。
両方なら ["shopify","external"]、外部ブランドだけなら ["external"] をリクエストに追加。
商品詳細ページへのリンクを出している場合、外部商品はブランドの自社サイトへ遷移するよう URL を正しく扱う。
sources 省略時は ["shopify"] と同じ。既存実装の回帰リスクは無い。
外部商品は常に eligible.native_checkout: false。カート追加・Shopify checkout 導線を出すかどうかはこのフラグで判定するのが素直。
外部商品はブランドの商品ページへのリンクを持つ。自前の PDP ルートに決め打ちしているとリンクが壊れるので、URL の扱いを見直す。
外部商品は米国のショッパーにのみ返る。["external"] のみ指定時に米国外ではどう返るか（空になるか等）は記載なし。テストで要確認。
search_catalog と get_product（外部商品 ID 指定）は対応済み、lookup_catalog は後日対応。lookup_catalog に依存した処理で外部商品を扱う設計は、現時点では避けるべき。
search_catalog に sources: ["shopify","external"] を指定し、Shopify 外のブランド商品も同じ結果リストに含める。native_checkout: false のため、カード UI に「ブランドサイトで購入」等の導線を出し分ける。eligible.native_checkout で分岐し、true は従来導線、false はブランドの商品ページへのリンクに切り替える。get_product で外部商品 ID を引くケースも同じ分岐を通す。sources に external を含め、残りは省略のまま比較する。search_catalog に sources を足すだけで、Shopify 外のブランド商品も検索結果に出せる（beta・米国のみ）。