Sale channel API: brands and marketplace accounts

Nasam's sale channel API is the part of MM-API that discovers marketplace channels and manages a brand's connected accounts. A brand is the business scope for those connections. A sale channel names a marketplace and region. A sale-channel account connects one brand to that channel and carries its connection, fulfillment, and inventory settings. Keep all three IDs: they answer different questions. For an integration that uses these identities across catalog, stock, orders, and reporting, see the multi-channel API guide.

Connection lifecycle

Stage	What to read or do	Gate before moving on
Identify the business and marketplace	List brands, channel definitions, and the brand's connected accounts	Use the right brandId, channel ID, region, and account ID; do not substitute one for another.
Start connection	Submit the channel-specific connect request	Follow oauthUrl when returned and read the account again for its status.
Complete channel setup	Reconcile fulfillment setup where needed and review imported catalog items	Check the account's status and review queue; a connection alone does not mean listings or fulfillment are ready.
Configure stock handling	Read source and branches, then update account inventory settings	Verify the resulting inventoryScope, branch, and Sync Health.
Maintain access	Reauthorize or update portal login as appropriate for the connection	Read the account and sync state after renewal.
Pause or end a connection	Deactivate, reactivate, or disconnect based on the intended lifecycle	Read the account again; these operations have different effects on credentials, history, and future sync.

Discover the scope

1. List brands to obtain accessible brand.id values. Optional status is Active, Inactive, or All; search narrows names. Without limit, this read returns the accessible set for pickers. With page and limit, use its pagination object.
2. Read channel definitions to obtain the numeric sale-channel ID and region. A name alone is insufficient where the same marketplace operates in multiple regions.
3. Read connected accounts for a brand. The response separates connected from available channels. A connected entry has its own account id, channel identity, status, fulfillmentModel, inventoryScope, and an attentionCount for catalog review.

The channel definition answers which marketplace and region? The account answers which brand connection and settings? Use saleChannelId to filter cross-channel reads such as orders or reports. Use the account id for account-scoped actions such as review, branch lookup, and fulfillment setup. A shared marketplace account can be attached to another brand through the alias flow; use the brand and account returned for that association rather than assuming the owner brand's ID belongs in every path.

Read one brand when you need its detail. Search brands uses a required query; check brand existence returns an exists flag and a minimal brand identity.

Connect a marketplace account

POST /v1/brands/{brandId}/sale-channels/connect requires saleChannelName. Its other inputs depend on the channel: region, marketplace brand identifier, credentials, fulfillmentModel, or inventoryScope can apply. The default inventory scope is BrandPool if omitted. The response includes a connection status and may include an oauthUrl. Send the account owner through that URL when returned, then read connected accounts again for its resulting status.

Before connecting, check whether the channel already appears under connected or available. Choose the region and fulfillment model from the actual marketplace account, and choose inventory scope after reading the brand's stock source. If there is no source, do not assume a new account can safely share a brand pool. After connect, treat the returned status as a stage, not proof that the marketplace has finished authorization or the first import.

Connection and seller fulfillment are separate stages. A connection may exist while the marketplace warehouse setup remains incomplete. The fulfillment setup operation can reconcile an account whose setup stopped partway through. Where the response provides a marketplace panel URL, the merchant completes the marketplace side there.

Once the account is connected, check its catalog review. Imported channel items may need brand attribution or product matching before they become useful listings. Read Sync Health to distinguish a connection that is authorized from one whose capture or processing is stale. For seller fulfillment, check the account's fulfillment setup before offering pack or pickup actions.

Use reauthorization when a connected account needs marketplace consent again. Portal-login update changes seller-panel credentials independently of API credentials: omitted fields are unchanged, null clears them, and a string sets them. Alias connection links a shared marketplace account to another brand under its own request rules.

Stock and lifecycle settings

Inventory settings control whether an account uses the brand pool, tracks stock independently, or has externally managed inventory. A D2C storefront can select an inventoryBranchId; available branches reports whether the channel supports that concept. Transfer time and shelf-life overrides feed the forecast, so read the current account before changing them.

Changing inventory scope changes how future stock is interpreted and pushed. Read the account's current scope and the brand's source first, then update only with the intended branch and overrides. Afterward, read the account again and inspect the forecast and sync state. Do not infer that a successful settings response means every existing listing quantity has already changed at the marketplace.

Deactivate, reactivate, and disconnect are separate actions. Choose from the operation's semantics rather than treating them as interchangeable. After a connection or lifecycle change, read Sync Health for capture status and catalog review for unresolved items.

Deactivation is a pause: the account becomes inactive, its listings and history stay, and push and sync paths skip it. Reactivation may return an oauthUrl; for an OAuth channel the account remains inactive until the callback completes. Disconnect ends the connection under its own operation rules. If the goal is only to renew access, use reauthorization or portal-login update instead of changing the account lifecycle.