Skip to main content

Managing channel connections

Channel connections represent authenticated links between a Shopify store and external platforms. Each connection ties a channel specification to a specific seller account on the external platform. A single app can manage multiple channel connections — for example, an Amazon app can connect Amazon US, Amazon CA, and Amazon DE as separate connections, each with its own specification, account, and product feeds.

Anchor to What you'll learnWhat you'll learn

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

Anchor to RequirementsRequirements

Anchor to How channel connections workHow channel connections work

When you call channelCreate with a specification handle and account details, Shopify:

  1. Reads the specification to determine regional coverage (countries, languages, currencies)
  2. Finds the store's markets that intersect with the specification's covered countries
  3. Creates product feeds for each covered country, which immediately begin emitting events to your app's webhook subscriptions

When a channel connection is deleted via channelDelete, all associated product feeds are removed.

Anchor to Create a channel connectionCreate a channel connection

After a merchant completes authentication with their external platform account, call channelCreate to establish the connection:

POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json

channelCreate mutation

mutation ChannelCreate($input: ChannelCreateInput!) {
channelCreate(input: $input) {
channel {
id
handle
}
userErrors {
field
message
code
}
}
}

Input variables

{
"input": {
"handle": "amazon-us-A1B2C3D4E5F6G7",
"specificationHandle": "amazon-us",
"accountId": "A1B2C3D4E5F6G7",
"accountName": "My Amazon Store"
}
}

JSON response

{
"data": {
"channelCreate": {
"channel": {
"id": "gid://shopify/Channel/1068177798",
"handle": "amazon-us-A1B2C3D4E5F6G7"
},
"userErrors": []
}
}
}

Anchor to Input fieldsInput fields

channelCreate input fields
FieldTypeRequiredDescription
handleStringNoA unique identifier for the channel connection, for example "amazon-us-A1B2C3D4E5F6G7". If not provided, a handle is auto-generated from the specification handle and account ID.
specificationHandleStringYesThe handle of a channel specification deployed via the channel config extension.
accountIdStringYesA unique identifier for the merchant's account on the external platform.
accountNameStringYesA human-readable name for the merchant's account, displayed in the Shopify admin when referencing the connection.

Anchor to Online store parity requirementsOnline store parity requirements

If the channel specification declares requirements.expectsOnlineStoreParity = true (traffic-driving channels like Google or Meta), channelCreate requires the store to have at least one region market with a valid web presence covering the specification's countries. If no matching markets exist, the mutation returns an error.

Anchor to Update a channel connectionUpdate a channel connection

Use channelUpdate to modify account information or reassign a channel specification:

POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json

channelUpdate mutation

mutation ChannelUpdate($id: ID!, $input: ChannelUpdateInput!) {
channelUpdate(id: $id, input: $input) {
channel {
id
handle
}
userErrors {
field
message
}
}
}

Input variables

{
"id": "gid://shopify/Channel/10079785100",
"input": {
"accountName": "Updated Store Name"
}
}

JSON response

{
"data": {
"channelUpdate": {
"channel": {
"id": "gid://shopify/Channel/10079785100",
"handle": "amazon-us-A1B2C3D4E5F6G7"
},
"userErrors": []
}
}
}
Tip

channelUpdate is also used to migrate legacy automatic channel records to explicit connections. See Migrating to a multi-channel app for details.

Anchor to Delete a channel connectionDelete a channel connection

When a merchant disconnects their external account or a channel connection is no longer valid, remove it with channelDelete. This removes all associated product feeds.

POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json

channelDelete mutation

mutation ChannelDelete($id: ID!) {
channelDelete(id: $id) {
deletedId
userErrors {
field
message
}
}
}

Input variables

{
"id": "gid://shopify/Channel/10079785100"
}

Anchor to Query channel connectionsQuery channel connections

Anchor to Query a single channel by IDQuery a single channel by ID

channel query

query Channel($id: ID!) {
channel(id: $id) {
id
handle
accountId
accountName
specificationHandle
}
}

For the full list of fields available on Channel, refer to the Channel object in the GraphQL Admin API reference.

Anchor to Query a channel by handleQuery a channel by handle

channelByHandle query

query ChannelByHandle($handle: String!) {
channelByHandle(handle: $handle) {
id
handle
accountId
accountName
}
}

Anchor to List all channels for the appList all channels for the app

channels query

query {
channels(first: 10) {
nodes {
id
handle
accountId
accountName
specificationHandle
}
}
}
Note

A sales channel app cannot query channels belonging to other apps.

Anchor to Trigger a full sync for a channelTrigger a full sync for a channel

After establishing a channel connection and subscribing to product feed webhooks, trigger a full sync to receive the merchant's published product catalog. A full sync is triggered by default when your feed is first created, but if you need a full reconciliation you can trigger a full sync manually using the following mutation:

POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json

channelFullSync mutation

mutation ChannelFullSync($channelId: ID!, $language: LanguageCode, $country: CountryCode) {
channelFullSync(channelId: $channelId, language: $language, country: $country) {
fullSyncTraceInfo {
country
language
operationId
}
userErrors {
message
}
}
}

Input variables

{
"channelId": "gid://shopify/Channel/1",
"language": "en",
"country": "CA"
}

JSON response

{
"data": {
"channelFullSync": {
"fullSyncTraceInfo": [
{
"country": "CA",
"language": "en",
"operationId": "gid://shopify/ProductFullSync/31987319841212"
}
],
"userErrors": []
}
}
}

The country and language parameters are optional. If omitted, all feeds for the channel are synced.

If your channel manages feeds manually, create the feeds first and trigger productFullSync for each feed instead. See Contextual product feeds.

Anchor to Typical integration flowTypical integration flow

A typical sales channel app integrates channel connections as part of its post-authentication flow:

  1. Merchant installs the app and completes OAuth
  2. App presents the external platform authentication (for example, Amazon Seller Central login)
  3. Merchant authenticates with their external account
  4. App calls channelCreate with the appropriate specification handle and account details
  5. Shopify creates product feeds
  6. App subscribes to product feed webhooks and triggers a full sync
  7. Product data begins flowing to the app

For apps supporting multiple channel connections, repeat steps 2–6 for each additional connection.

Anchor to Next stepsNext steps

Was this page helpful?