Contextual product feeds

Contextual product feeds allow sales channels to sync merchant catalogs to their platforms. You can configure distinct feeds for the different language and country pairs that a merchant supports.

Product feed output is resolved from the intersection of your channel's publishing controls and the relevant channel market catalog, pricing, and currency configuration.

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

• Describe your channel to Shopify
• Establish a new channel connection
• Subscribe to product feed webhooks
• Initiate a full sync

Anchor to RequirementsRequirements

• Your app has the read_product_listings access scope. Learn more about requesting access scopes when your app is installed using authorization code grant.

Anchor to Step 1: Describe your channelStep 1: Describe your channel

When you create a sales channel, you need to describe its properties to Shopify.

Channel descriptions include capabilities, categories, fields, validation rules, and more. This channel description enables Shopify to automatically manage a large part of the merchant's channel experience.

Describing a channel requires the following steps:

1. Add the channel config extension to your app
2. Create a channel specification example-us-channel.toml for that channel

Then deploy your channel targets with Shopify CLI:

Anchor to Step 2: Establish channel connectionsStep 2: Establish channel connections

Before subscribing to product feeds, you need to establish at least one channel connection. Channel connections link your channel specification to a merchant's external account and automatically create the product feeds for the channel's configured regions.

See Managing channel connections for the full guide on creating, updating, and querying channel connections using the channelCreate, channelUpdate, channelDelete mutations and channels query.

Anchor to Step 3: Subscribe to product feed webhooksStep 3: Subscribe to product feed webhooks

Subscribe to product feed webhooks to receive feed status changes, initial full sync payloads, incremental sync events, and full sync completion signals. Market or catalog changes can also cause feed update or reconciliation events.

Anchor to Subscribe to full sync eventsSubscribe to full sync events

Full sync events are triggered when a product feed full sync is initiated. Full sync events contain individual product payloads and allow you to sync a merchant's entire catalog during channel setup.

Use the webhookSubscriptionCreate mutation to subscribe to the PRODUCT_FEEDS_FULL_SYNC webhook topic.

Individual product listing payloads are sent when a full sync is initiated.

Anchor to (Optional): Subscribe to full sync completion events(Optional): Subscribe to full sync completion events

You can subscribe to the PRODUCT_FEEDS_FULL_SYNC_FINISH webhook topic to be notified whenever a full sync finishes. This is a useful signal for scenarios where the merchant hasn't published any products to the channel.

Anchor to Subscribe to incremental sync eventsSubscribe to incremental sync events

Incremental sync events are triggered whenever changes occur relative to app's feeds, such as when:

• Product fields are updated.
• Product variant fields are added, updated, or deleted.
• Product translations are updated.
• Product market price is updated.
• Channel market catalog, pricing, or currency configuration requires product-level reconciliation.
• Products are published to the app.
• Products are unpublished from the app.

Use the webhookSubscriptionCreate mutation to subscribe to the PRODUCT_FEEDS_INCREMENTAL_SYNC webhook topic.

Anchor to Subscribe to product feed updatesSubscribe to product feed updates

Product feeds might change as the merchant modifies a market configuration. For example, if a merchant unpublishes a language, then dependent feeds become inactive. Catalog, pricing, or currency changes on channel or region markets can also require feed reconciliation. Subscribe to the PRODUCT_FEEDS_UPDATE webhook topic to stay updated on feed statuses.

Anchor to Step 4 (Optional): Create feeds manuallyStep 4 (Optional): Create feeds manually

If you set productFeedManagement to "manual" in your channel specification, you need to create product feeds for each country and language pair before initiating a full sync.

Use the productFeedCreate mutation to create a feed:

Repeat this for each country and language pair defined in your channel specification.

Anchor to Step 5: Initiate a full syncStep 5: Initiate a full sync

After your app has subscribed to the necessary webhook topics, trigger a full sync to fetch the merchant's published catalog.

Use the full sync mutation that matches how your channel manages feeds:

• If your channel uses productFeedManagement = "automatic", use channelFullSync to trigger a full sync for a channel connection. Shopify syncs all relevant feeds for that channel, or the feeds matching the optional country and language filters. See Managing channel connections.
• If your channel uses productFeedManagement = "manual", use productFullSync to trigger a full sync for each individual product feed that you created in Step 4. The returned id can be used to attribute the webhooks and identify the sync completion event.

Your app should trigger a full sync once during initialization to fetch the store's entire catalog. You can trigger additional full syncs on a regular schedule for reconciliation.

When a full sync is initiated, Shopify fires individual PRODUCT_FEEDS_FULL_SYNC webhook payloads for each of the merchant's published products. The webhook payloads contain localized data and market-specific catalog, pricing, and currency data according to the feed's context. Shopify sends a confirmation event to the PRODUCT_FEEDS_FULL_SYNC_FINISH subscription after the full sync is complete. The payload's fullSyncId identifies the sync operation.

An initial full sync should be triggered during app onboarding, and regular reconciliation syncs should be scheduled after. The optional beforeUpdatedAt and updatedAtSince parameters allow you to specify a time range for the sync.

Anchor to Full sync by download (Optional)Full sync by download (Optional)

An alternative solution is to download a single JSONL file containing all products that would normally be sent through individual PRODUCT_FEEDS_FULL_SYNC payloads. This can be useful in scenarios where the amount of webhook traffic is difficult to manage. When full sync by download is enabled, the PRODUCT_FEEDS_FULL_SYNC_FINISH webhook payload contains a JSONL file URL. This functionality is similar to bulk operations.

Anchor to Next stepsNext steps

• For other channel product sync solutions, refer to the Options to sync product data guide.