Shopify’s Global Catalog is getting a powerful boost. In the latest beta release, the Catalog API now supports a sources parameter that lets you pull in products from brands that don’t sell on Shopify alongside traditional merchant listings. This opens new horizons for on‑site search, recommendation widgets, and any app that surfaces product data. In this post we’ll unpack the change, identify who needs to act, and give you ready‑to‑paste code so you can start testing right away.
What Changed
The beta Catalog API now accepts a new sources array on the existing search_catalog method. The array tells Shopify which product pools to return:
- ["shopify"] or omit sources → only Shopify merchant products (default behavior).
- ["shopify","external"] → both merchant and external brand products.
- ["external"] → only brands that don’t sell on Shopify.
External products come with a full description, image, price, and a direct link to the brand’s own storefront. They are always marked eligible.native_checkout: false, so shoppers complete the purchase off‑site and the transaction doesn’t generate Promoted Placements commissions.
Who Is Affected
Any app or custom integration that uses the Catalog API for search, autocomplete, or product recommendation now has the option to surface external brand inventory. During the beta, external data is scraped from each brand’s website and is only available to shoppers located in the United States. If your audience is global, you’ll still see Shopify‑only results for non‑US IPs.
How to Implement the New sources Parameter
Updating your API calls is straightforward because the endpoint itself does not change—only the request payload does. Below is a minimal example using Node.js and the official Shopify Admin GraphQL client.
js
import { GraphQLClient } from '@shopify/graphql-client';
const client = new GraphQLClient({
storeDomain: process.env.SHOPIFY_STORE_DOMAIN,
accessToken: process.env.SHOPIFY_ACCESS_TOKEN,
});
// Search both Shopify and external products
const query = `
query SearchCatalog($term: String!, $sources: [CatalogSource!]) {
searchCatalog(term: $term, sources: $sources) {
products {
id
title
description
price {
amount
currencyCode
}
primaryImage {
url
altText
}
eligible {
nativeCheckout
}
externalUrl
}
}
}`;
await client.query({
data: query,
variables: {
term: 'running shoes',
sources: ['shopify', 'external'] // <-- change this array as needed
}
});
If you only need external brands, simply pass ['external'] instead. Existing integrations that omit sources continue to work exactly as before, so no breaking changes are introduced.
Best Practices & Edge Cases
• Handle externalUrl properly – when a shopper clicks an external product, redirect them to that URL in a new tab or a full‑page navigation. Do not attempt to process the checkout through Shopify.
• Check eligible.nativeCheckout before showing a “Buy Now” button. For external items it will be false, so you may want to replace the CTA with “View on Brand Site.”
• Respect the US‑only limitation during beta. If you detect a non‑US shopper, you can either fallback to Shopify‑only results or display a friendly message explaining that external catalog data isn’t available in their region yet.
• Cache external product responses separately. Because external data is scraped, it may change more frequently than merchant data. A short‑term cache (e.g., 5 minutes) can reduce API load while keeping the catalog fresh.
Next Steps & CTA
Start experimenting today: add the sources parameter to a test app, verify that external products appear for US shoppers, and update your UI to handle external URLs gracefully. Keep an eye on the official docs for the upcoming lookup_catalog support and any changes to regional availability.
Got questions or want a walkthrough? Drop a comment below or reach out on the Shopify Community forums. Happy coding!
