> ## Documentation Index
> Fetch the complete documentation index at: https://developer.jtl-software.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform channels

> Multi-marketplace architectures with shared seller sign-up, multi-currency, and multi-language support.

This guide explains how platform channels group multiple marketplace channels under a single seller
sign-up flow in SCX.

<Info>
  **What you'll learn:**

  * Why platform channels exist and what problem they solve
  * How platform channels and marketplace channels relate to each other
  * How the seller sign-up flow works from the seller's and channel integrator's perspective
  * How you assign sellers to marketplace channels without additional sign-up sessions
  * How stock sync groups prevent duplicate inventory updates
</Info>

## Why platform channels?

Some marketplaces operate across multiple geographic regions. Each region has its own language, currency,
and regulatory requirements. For example, a marketplace may operate in Germany (EUR, German), the UK (GBP, English),
and Spain (EUR, Spanish).

Without platform channels, each region would be a separate channel with its own sign-up flow. The seller
would need to sign up multiple times — once for each region.

Platform channels solve this:

* **One sign-up for the seller.** The seller sees only the platform channel in JTL-Wawi and signs up once.
  Marketplace channels are invisible to the seller.
* **Multi-currency support.** Each marketplace channel defines its own currency.
* **Multi-language support.** Each marketplace channel represents a specific geographic region with its own
  language context.
* **Centralized URL management.** The sign-up and update URLs live on the platform and are inherited by all
  marketplace channels automatically.
* **Automatic marketplace assignment.** The channel integration creates or deactivates sellers on marketplace
  channels without requiring additional sign-up sessions from the seller.
* **Shared inventory management.** Stock sync groups prevent duplicate stock updates across marketplace
  channels that share the same warehouse.

***

## Terminology

| Term                       | Definition                                                                                                                                                                                                                                    |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Platform channel**       | A virtual channel that acts as an umbrella for one or more marketplace channels. It owns the sign-up and update URLs and is the only channel visible to the seller in JTL-Wawi. It cannot be accessed via the Channel API. Example: "Amazon". |
| **Marketplace channel**    | A channel that belongs to a platform. It inherits URLs from its parent and represents a specific geographic marketplace. Invisible to the seller. Example: "Amazon DE".                                                                       |
| **marketplaceChannelList** | A property on the platform channel's public channel list response. It contains identifiers and metadata (including `stockSyncGroup`) for each marketplace channel that belongs to the platform.                                               |
| **stockSyncGroup**         | A label grouping marketplace channels that share inventory. Within a group, JTL-Wawi sends stock updates to only one channel.                                                                                                                 |

***

## Architecture

A platform channel is the entry point for seller sign-up. Each marketplace channel beneath it represents
a specific region or variant.

```mermaid theme={null}
graph TD
    P["Platform Channel (e.g. Amazon)"]
    P -->|"owns"| URL["signUpUrl / updateUrl"]
    P -->|"parent of"| MC1["Marketplace Channel DE<br/>(EUR, German)"]
    P -->|"parent of"| MC2["Marketplace Channel UK<br/>(GBP, English)"]
    P -->|"parent of"| MC3["Marketplace Channel ES<br/>(EUR, Spanish)"]

    MC1 -.->|"inherits URLs"| URL
    MC2 -.->|"inherits URLs"| URL
    MC3 -.->|"inherits URLs"| URL
```

*Platform and marketplace channel relationship*

Key characteristics:

* The platform channel holds the single source of truth for `signUpUrl` and `updateUrl`.
* When the platform's URLs change, all marketplace channels are updated automatically.
* Marketplace channels cannot override their own URLs.
* Only the platform channel appears in the public channel list (`GET /v1/public/channel`).
  Marketplace channels are filtered out and invisible to the seller.

<Note>
  A platform channel is **virtual**. It cannot be accessed via the Channel API: no access token can be
  created for it, and it does not receive or emit events. It exists purely as an organizational umbrella
  that groups marketplace channels and owns the sign-up and update URLs.
</Note>

***

## Seller sign-up flow

The seller sees only the platform channel in JTL-Wawi. They sign up once, and the channel integration
handles marketplace channel assignment.

```mermaid theme={null}
sequenceDiagram
    participant Seller as Seller (JTL-Wawi)
    participant SCX as SCX Platform
    participant Channel as Channel Integration

    Seller->>SCX: POST /v1/seller/channel/amazon (initiate sign-up)
    SCX-->>Seller: Returns platform signUpUrl + sessionId

    Seller->>Channel: Opens signUpUrl in browser
    Channel->>Channel: Authenticate seller and select marketplaces

    Channel->>SCX: POST /v1/channel/seller (sessionId + sellerId)
    SCX-->>Channel: Seller created on platform

    Channel->>SCX: POST /v1/channel/seller/platform/{jtlAccountId}
    Note over SCX: Seller assigned to marketplace channels
    SCX-->>Channel: Seller active on amazon-de, amazon-uk
```

*Platform seller sign-up flow*

<Steps>
  <Step title="Seller initiates sign-up">
    In JTL-Wawi, the seller selects the platform channel (e.g. "Amazon") from the available channel list
    and starts a sign-up session. SCX returns the platform's `signUpUrl` with a one-time session ID.
  </Step>

  <Step title="Seller authenticates on the channel">
    The seller is redirected to the platform's sign-up page (hosted by the channel integration). The
    channel integration authenticates the seller and determines which marketplace regions the seller
    should be connected to.
  </Step>

  <Step title="Channel completes platform sign-up">
    The channel integration reports the seller ID and session ID back to SCX via
    `POST /v1/channel/seller`. This completes the platform-level sign-up.
  </Step>

  <Step title="Channel assigns seller to marketplace channels">
    The channel integration calls `POST /v1/channel/seller/platform/{jtlAccountId}` to activate
    the seller on specific marketplace channels. No additional sign-up session is required.
  </Step>
</Steps>

<Warning>
  Direct seller sign-up on a marketplace channel is not allowed. SCX rejects the request when a seller
  attempts to create a sign-up session for a marketplace channel (HTTP 403, error code `SLR204`).
  Sellers must always sign up via the parent platform.
</Warning>

***

## Managing sellers on marketplace channels

After the initial sign-up, the channel integration manages which marketplace channels a seller is
active on. This happens without any seller interaction.

### Creating a seller on a marketplace channel

Use `POST /v1/channel/seller/platform/{jtlAccountId}` to assign an existing platform seller to a
marketplace channel. This endpoint requires Channel API authentication (Bearer token).

```json theme={null}
// POST /v1/channel/seller/platform/{jtlAccountId}
// Content-Type: application/json
// Authorization: Bearer <channel-access-token>
{
  "sellerId": "SELLER-123",
  "channel": "amazon-de",
  "isActive": true
}
```

The seller must already exist on the platform or on another marketplace channel of the same platform.

### Deactivating a seller on a marketplace channel

The channel integration can deactivate a seller on a specific marketplace channel without affecting
other marketplace channels or the platform-level connection:

```json theme={null}
// POST /v1/channel/seller/platform/{jtlAccountId}
{
  "sellerId": "SELLER-123",
  "channel": "amazon-de",
  "isActive": false
}
```

<Note>
  The channel integration decides which marketplace channels a seller is active on. SCX does not
  dictate marketplace channel assignment.
</Note>

***

## URL inheritance

The platform channel owns the `signUpUrl` and `updateUrl`. All marketplace channels inherit these URLs
automatically.

* When the platform's URLs are updated, all marketplace channels receive the new URLs.
* Marketplace channels cannot set their own URLs independently.
* If no `updateUrl` is provided on the platform, the `signUpUrl` is used as fallback for both.

***

## Stock sync groups

### Why stock sync groups?

Marketplaces that belong to the same platform often share inventory. For example, Amazon DE, Amazon FR,
and Amazon ES all draw from the same European warehouse. The stock level is the same across all three
marketplaces — the marketplace synchronizes inventory internally.

Without stock sync groups, JTL-Wawi would send a separate stock update to each marketplace channel.
This creates unnecessary load and duplicate updates for stock that is already shared on the marketplace side.

### How it works

A `stockSyncGroup` is a label assigned to marketplace channels that share inventory. Within a group,
JTL-Wawi sends the stock update for a given SKU to **only one** marketplace channel. The marketplace
handles internal synchronization across the other channels in the group.

### Rules

* Only marketplace channels can have a `stockSyncGroup` (channels with a `platform` reference).
* Platform channels and standalone channels must have `stockSyncGroup: null`.
* All marketplace channels with the same `stockSyncGroup` value are treated as one inventory pool.
* The platform channel's response in the public channel list (`GET /v1/public/channel`) includes the
  `marketplaceChannelList` property, which contains each marketplace channel's `stockSyncGroup`. This
  is how JTL-Wawi discovers the grouping and sends stock accordingly.
* Setting `stockSyncGroup` to `null` removes the channel from its group — stock updates resume
  individually for that channel.

### Example

| Channel   | Type        | stockSyncGroup | Receives stock updates?                            |
| --------- | ----------- | -------------- | -------------------------------------------------- |
| amazon    | Platform    | `null`         | No (virtual channel)                               |
| amazon-de | Marketplace | `"AMAZON-EU"`  | Yes (Wawi sends to one active seller in the group) |
| amazon-fr | Marketplace | `"AMAZON-EU"`  | No (synced by marketplace)                         |
| amazon-es | Marketplace | `"AMAZON-EU"`  | No (synced by marketplace)                         |
| amazon-us | Marketplace | `"AMAZON-US"`  | Yes (separate group)                               |

In this setup, Wawi sends one stock update per SKU to any single channel in the `"AMAZON-EU"` group
(e.g. amazon-de). Amazon synchronizes stock across DE, FR, and ES internally. The US marketplace belongs
to a separate group and receives its own stock updates.

<Tip>
  Use the same `stockSyncGroup` value for all marketplace channels that share the same warehouse or
  inventory pool on the marketplace side. Use different values for regions with independent stock
  (e.g. EU vs US).
</Tip>

***

## Business rules and constraints

| Rule                                                                                                         |
| ------------------------------------------------------------------------------------------------------------ |
| Platform channels are virtual — no API access token, no events, no authentication.                           |
| Seller sign-up on a marketplace channel is forbidden (`SLR204`). Sellers must sign up via the platform.      |
| A platform cannot be converted to a regular channel while `marketplaceChannelList` is non-empty.             |
| Marketplace channels cannot set their own sign-up or update URLs — always inherited from the platform.       |
| A channel cannot be both a platform and belong to a platform simultaneously.                                 |
| The referenced platform must exist when creating a marketplace channel.                                      |
| `stockSyncGroup` can only be set on marketplace channels. Platform and standalone channels must have `null`. |

***

## Next steps

<CardGroup cols={2}>
  <Card title="Seller Management" icon="workflow" href="/guides/marketplace-channels/seller-management">
    Regular seller sign-up, update, and unlink flows.
  </Card>

  <Card title="Channel API Overview" icon="store" href="/guides/marketplace-channels/channel-api-overview">
    Events, metadata, and media content handling.
  </Card>

  <Card title="Authorization" icon="key" href="/guides/marketplace-channels/authorization">
    Refresh tokens, access tokens, and Bearer headers.
  </Card>

  <Card title="Channel API Reference" icon="code" href="/api-reference/scx/channel">
    Full endpoint reference for the Channel API.
  </Card>
</CardGroup>