search_catalog now has a new sources parameter that returns Shopify merchant products and external brand products in a single response. If you don't specify it, behavior is unchanged, so existing calls need no changes.
sources parameter, you can also returnproducts from brands that don't sell on Shopifyin the same response.
search_catalog results are limited to products sold on Shopify.sources is omitted, this behavior stays the same going forward.
["shopify","external"] returns both;["external"] returns external brands only. No new endpoint is needed.
search_catalog method just needs sources added.get_product also returns external products when you pass an external product ID.lookup_catalog support is listed as "coming later."
| sources value | Products returned | Impact on existing code |
|---|---|---|
Omitted or ["shopify"] |
Shopify Merchant products only | No changes needed (same behavior as before) |
["shopify", "external"] |
Shopify + External Both | You need to handle external products (e.g., their link destinations) |
["external"] |
External Only brands that don't sell on Shopify | Same as above |
sources parameter lets you include external products.
Returns external products when you pass an external product ID.
Only listed as "coming later." No timeline given.
eligible.native_checkout: false. They can't be purchased through Shopify checkout, andno Promoted Placements commission is charged.Apps that use the Catalog API for on-site search or recommendations and want to include products from brands outside Shopify.
External products are returned only when the shopper is in the US. In other countries, only Shopify merchant products are returned.
During the beta, external product data is sourced from each brand's website.
If you only need Shopify products, no action is required. Existing search_catalog calls keep working as-is.
For both, use ["shopify","external"]; for external brands only, use ["external"] in your request.
If you link to product detail pages, make sure external products correctly send shoppers to the brand's own site.
sources When omitted, it behaves the same as ["shopify"] . No regression risk for existing implementations.
External products always have eligible.native_checkout: false. The simplest approach is to use this flag to decide whether to show add-to-cart and Shopify checkout flows.
External products link to the brand's product page. Hardcoding links to your own PDP route will break them, so review how you handle URLs.
External products are returned only to US shoppers.["external"] only: what's returned outside the US (e.g., whether results are empty) isn't stated. Verify in testing.
search_catalog and get_product(by external product ID) is already supported, whilelookup_catalog will be supported later.For now, avoid designs that rely on lookup_catalog to handle external products.
search_catalog set to sources: ["shopify","external"] so products from brands outside Shopify appear in the same result list.native_checkout: false , so the card UI should show a different CTA, such as "Buy on brand site".eligible.native_checkout field:true keeps the existing flow, whilefalse switches to a link to the brand's product page.get_product lookups of external product IDs should go through the same branch.sources to include external , keep it omitted for everyone else, and compare the results.search_catalog , just add sources to show products from brands outside Shopify in search results too (beta, US only).