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.

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 initial full sync payloads and incremental sync events whenever products are updated.

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.
• 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 their market settings. For example, if a merchant un-publishes a language, then any dependant feeds will become inactive. 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, individual PRODUCT_FEEDS_FULL_SYNC webhook payloads are fired for each of the merchant's published products. The webhook payloads contain localized data according to the feed's context. A confirmation event is sent to the PRODUCT_FEEDS_FULL_SYNC_FINISH subscription once the full sync has completed. 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 (Optional): Full Sync by download(Optional): Full Sync by download

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.