Admin GraphQL API / 2026-04

Sales channel app
Multi-channel support

A single sales channel app can now create and manage multiple channel connections on a single shop. Each connection can have its own specification file and external account. The model of splitting apps per account or per market can now be consolidated into a single app.

On this page
  1. What's actually changing (understand in 30 seconds)
  2. How it works: 1 app → multiple channels
  3. What's new
  4. How to create channels in a new app
  5. What to do when migrating an existing app
  6. New APIs / affected APIs
  7. 5 points engineers should know
  8. 3 use cases you can apply to your business
  9. One-line summary for pitching

1What's actually changing

Previously, sales channel apps assumed 1 app = 1 channel as the model.
With this change,a single app can establish multiple channel connections on the same shop, and each connection can be assigned its own specification file and external account.

Before: split apps per account or market

If you wanted to sell under different accounts or in different markets, you built that many apps and managed them separately. Code and infrastructure were duplicated.

Now: consolidate multiple channels into one app

Connections are kept inside a single app and each is managed as a "separate channel." No more splitting.

2How it works: 1 app → multiple channels

Sales channel app Channel Config extension (1 per app) channelCreate specification 1 accountId / accountName A specification 2 accountId / accountName B specification 3 accountId / accountName C Independent channels on the same shop Channel A External account A / Market A Channel B External account B / Market B Channel C Different surface / Account C
The core of the architecture is the Channel Config extension (1 per app) + a specification file per target channel (1 per channel). Each channel points to specificationHandle a different specification, and links toaccountId / accountName a different external account.

3What's new

NEW

Multiple channels in one app

A single sales channel app can establish multiple channels on the same shop.

NEW

Config extension + specification file

In addition to the Channel Config extension,one specification file per target channelcan be provided.

NEW

Separate spec and account per connection

Each channel can point to a separate specification and a separate external account.

You no longer need to split apps to sell across different accounts, different markets, and different surfaces. Connections can live inside a single app and be treated asdistinct channels.

4Steps to create channels in a new app

1

Add the Channel Config extension

Every new sales channel adds the Channel Config extension.

2

Define a specification file

Define one specification file per target channel.

3

Create a connection with channelCreate

specificationHandle accountId accountName Pass these to create each channel connection.

5What to do when migrating an existing app

1. Migrate to the channel connections model

Migrate legacy sales channel apps to use channel connections by following the migration guide.

ID

2. Audit code that assumes one channel per app

If you read or write channel-specific state, do not rely on app-level defaults and pass the channel ID explicitlyinstead.

Watch for downstream code that implicitly assumes one channel per app. The moment you go multi-channel, it becomes ambiguous which channel an operation targets.Switch to a design that threads channelId through.

6New / affected APIs

APIs added in this release

channel

Get a channel

channelCreate

Create a channel connection

channelByHandle

Get a channel by handle

channelUpdate

Update a channel

channelDelete

Delete a channel

channelFullSync

Full sync of a channel

APIs deprecated under the single-channel assumption

They still work today, but will be removed in a future API version.

Deprecated APIsUse instead
publishablePublishToCurrentChannelpublishablePublish
publishableUnpublishToCurrentChannelpublishableUnpublish
AppInstallation.channelRoot-level channels query
AppInstallation.publicationRoot-level publications query
Product.publishedOnCurrentPublicationpublishedOnPublication
Publishable.resourcePublicationOnCurrentPublicationresourcePublications

Updated: APIs that now accept an optional channelId

bulkProductResourceFeedbackCreate

Lets you specify which channel an operation targets via channelId .

bulkProductPublicationStatusUpdate

Same as above. Apps that create multiple channels must specify channelId .

Apps that create multiple channels must pass channelId . Single-channel apps can keep their existing calls unchanged.

75 key points for developers

1. The Channel Config extension is a prerequisite

Every new sales channel must add a Channel Config extension. This is the foundation for bundling multiple channels together.

2. One specification file per channel

Define a specification file for each target channel. Each channel can point to a different spec and a different external account.

create

3. The three arguments to channelCreate

specificationHandle accountId accountName Pass these together to create each channel connection.

channelId

4. Stop relying on app-level defaults

Refactor code that reads or writes channel-specific state to explicitly pass channelId instead of relying on implicit app-level defaults.

5. Plan to replace the CurrentChannel / CurrentPublication APIs

publishablePublishToCurrentChannel and Product.publishedOnCurrentPublication and other APIs that assume a 'current' context are now deprecated. They still work today, but will be removed in a future API version, so migrate early topublishablePublish or the root-level channels / publications query..

83 practical use cases

app
USE CASE 1

Consolidate per-account connections of a marketplace integration app into a single app

Problem
Integrations that required a separate connection per merchant or per sales account used to be managed by splitting them into as many apps as there were accounts.
Solution
Embed a Channel Config extension in a single app and prepare a specification file for each account. PasschannelCreate to accountId / accountName to spin up connections in bulk.
Result
No more app splitting—codebase, submissions, and operations are unified. Adding an account is just a spec file plus channelCreate and nothing else.
Technical notes
Each connection is treated as a separate channel, so state reads and writes must always include channelId .
USE CASE 2

Multi-market sales app that splits channels per market/region

Problem
We wanted to sell with separate external accounts or different specs per market (country/region), but the 1-app-1-channel constraint made this impossible.
Solution
Define a specification file per market and create market-level channels via channelCreate.bulkProductPublicationStatusUpdate , passing channelId to control publish state per market.
Result
Listings and publishing per market are managed separately within a single app. Adding a new market just means adding a new channel, so rollout is fast.
Technical notes
Once you create multiple channels, specifyingchannelId is mandatory. Keep the market mapping internally and attach it to every API call.
Old API New API
USE CASE 3

Auditing and proactively migrating soon-to-be-removed APIs in existing channel apps

Problem
Existing apps depend on ...ToCurrentChannel / ...OnCurrentPublication -family single-channel APIs. Once these are removed in a future API version, the apps will stop working.
Solution
Follow the migration guide and move to the channel-connection model. Replace deprecated APIs with publishablePublish or root-level channels / publications queries, and thread channelId through downstream code.
Result
Avoids future breakage when APIs are removed. At the same time, this lays the groundwork for going multi-channel, making future feature expansion easier.
Technical notes
Deprecated APIs still work today, so you can migrate in stages with minimal production impact. Start by grepping for places that assume the "current" channel.

9One-line summary you can use in proposals

"With a single sales channel app, you can now createmultiple channel connectionson a shop.
Channel Config extension + a per-channel spec file + channelCreate is the basic pattern.
Setups that used to split apps by account, market, or surface can be consolidated into one app, and
existing apps should migrate the deprecated "current"-based APIs to channelId It's safer to migrate to the base early."