> ## 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.

# Seller Management

> Managing seller accounts through SCX: sign-up, update, and unlink flows.

This guide covers the key integration patterns for managing seller accounts through the SCX platform: sign-up, update, and unlink flows.

<Note>
  A channel must manage seller accounts autonomously. JTL will never be aware of any credentials required by an
  individual seller to connect to a marketplace or an external system (including API credentials).
</Note>

Each channel must maintain a **sign-up URL** and an **update URL**. The sign-up URL must point to a login page and the update
URL to a settings page, both hosted by the channel itself. A seller will create a sign-up or update session in JTL-Wawi,
and from there they will be redirected to the channel-hosted URLs with a unique one-time session ID.

<Tip>
  The sign-up flow described below applies to standalone channels. If the channel is a **platform channel**
  (multi-marketplace architecture), see [Platform Channels](/guides/marketplace-channels/platform-channels).
</Tip>

## Seller Sign-up

The aim of the sign-up process is to avoid managing sensitive access data to a marketplace within the client
environment or SCX. The channel itself has sovereignty over the access data to the connected marketplace.

```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/MYCHANNEL (initiate sign-up)
    SCX-->>Seller: Returns signUpUrl + sessionId

    Seller->>Channel: Opens signUpUrl in browser
    Channel->>Channel: Authenticate seller & create account
    Channel->>Channel: Generate unique SellerId

    Channel->>SCX: POST /v1/channel/seller (sessionId + sellerId)
    SCX-->>Seller: Sign-up complete, events now use this SellerId
```

<Steps>
  <Step title="Initiate sign-up via Seller API">
    The sign-up is initiated via the Seller API, which creates a session ID and a sign-up URL.
  </Step>

  <Step title="Redirect to channel sign-up page">
    JTL-Wawi redirects the seller to the sign-up URL (via web browser). The destination is a website hosted by the channel where the registration process takes place.
  </Step>

  <Step title="Authenticate and create seller">
    The channel authenticates the seller, stores the new seller record, and assigns a unique Seller ID.
  </Step>

  <Step title="Report Seller ID back to SCX">
    The channel reports the generated Seller ID together with the Session ID back to SCX. From now on, SCX sends all events with this Seller ID to the channel.
  </Step>
</Steps>

### Example: Create a Sign-up Session

Initiating a sign-up session returns a `signUpUrl` and a one-time session ID.

```json theme={null}
// POST /v1/seller/channel/MYCHANNEL
{
  "signUpUrl": "https://www.mychannel.com/?session=demoSessionId123&expiresAt=1646759360",
  "expiresAt": 1646759360
}
```

The seller is redirected to the `signUpUrl`, where the channel authenticates the seller and collects any information required to identify them. Once the seller has been successfully authenticated, the channel creates a unique Seller ID and sends it, together with the Session ID, to the Channel API.

<Warning>
  All events received from the Channel API will carry this Seller ID.
  The Seller ID is **immutable** and cannot be changed afterwards.
</Warning>

```json theme={null}
// POST /v1/channel/seller
{
  "session": "demoSessionId123",
  "sellerId": "1",
  "companyName": "JTL-Software-GmbH"
}
```

## Seller Update

Sometimes it may be necessary to update the connection between a JTL account and the seller. For example, the access
data pertaining to the marketplace may have been changed. In these cases, the JTL account must be able to update
this data on the channel.

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

    Seller->>SCX: PATCH /v1/seller/channel/MYCHANNEL (initiate update)
    SCX-->>Seller: Returns updateUrl + sessionId

    Seller->>Channel: Opens updateUrl in browser

    Channel->>SCX: GET /v1/channel/seller/update-session?sessionId=...
    SCX-->>Channel: Returns sellerId

    Channel->>Channel: Seller updates their settings

    Channel->>SCX: PATCH /v1/channel/seller (update seller data)
```

<Steps>
  <Step title="Create an update session">
    The update process is initiated via the Seller API, which creates an update URL for the channel.
  </Step>

  <Step title="Redirect to channel update page">
    JTL-Wawi redirects the seller to the update URL. The destination is a website hosted by the channel where the update process takes place.
  </Step>

  <Step title="Resolve the Seller ID">
    The channel asks SCX which Seller ID belongs to the current update Session ID (for security reasons, the Seller ID is not part of the update URL).
  </Step>

  <Step title="Perform update">
    The channel enables an update of the seller account and, after the update process, can also update the seller on the SCX system.
  </Step>
</Steps>

### Example: Initiate an Update Session

Initiating an update session returns an `updateUrl` and a one-time session ID.

```json theme={null}
// PATCH /v1/seller/channel/MYCHANNEL?sellerId=1
{
  "updateUrl": "https://www.mychannel.com/update?session=demoUpdateSessionId123&expiresAt=1646759360",
  "expiresAt": 1646759360
}
```

The seller is redirected to the update URL and receives a one-time session ID. Resolve the Seller ID from the session:

```json theme={null}
// GET /v1/channel/seller/update-session?sessionId=demoUpdateSessionId123
{
  "sellerId": "1"
}
```

After the update workflow is complete, the channel may update the seller at the Channel API:

```json theme={null}
// PATCH /v1/channel/seller
{
  "sessionId": "demoUpdateSessionId123",
  "isActive": true,
  "companyName": "JTL-Software-GmbH"
}
```

## Seller Unlink

There are different scenarios when a seller reaches a state where they are no longer allowed to use a channel:

* The seller deactivates the connection on their own behalf.
* The seller does not have an active JTL-eazyAuction subscription.

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

    alt Seller-initiated unlink
        Seller->>SCX: Deactivates channel connection
        SCX->>Channel: Seller:Channel.Unlinked event
    else Channel-initiated unlink
        Channel->>SCX: DELETE /v1/channel/sellerId/{sellerId}
        SCX->>Seller: Seller:Channel.Unlinked event
    end

    alt permanentlyRemoved = false
        Note over Channel: Deactivate seller, keep data
    else permanentlyRemoved = true
        Note over Channel: Safe to delete seller data
    end
```

In this scenario, the channel receives a `Seller:Channel.Unlinked` event:

```json theme={null}
{
  "sellerId": "1",
  "reason": "deactivated by Seller",
  "unlinkedAt": "2024-02-13T06:00:00+0000",
  "permanentlyRemoved": false
}
```

<Warning>
  When `permanentlyRemoved` is `false`, you should deactivate the seller in your system but **not** delete them. SCX will not accept any more data for that Seller ID until the seller initiates an update process.

  When `permanentlyRemoved` is `true`, the Seller ID is completely removed from SCX and you can delete it on your end as well.
</Warning>

### Unlinking a Seller from the Channel Side

There are scenarios where the channel needs to unlink a seller:

* API credentials become invalid or are revoked, requiring re-authorization
* Seller does not have an active contract or subscription with your company
* Suspicious behavior detected and you want to stop the seller's activity

Send a `DELETE /v1/channel/sellerId/{sellerId}` request to unlink the seller.

<Warning>
  Do not delete the Seller ID in your system until you receive a `Seller:Channel.Unlinked` event with `"permanentlyRemoved": true`.
</Warning>

## Managing Minimum Client Version

The `minimumClientsVersionRequired` property enables controlled rollout and compatibility assurance
between channels and JTL clients (JTL-Wawi). It defines which client versions are supported for connecting
to a specific channel and only affects the seller sign-up process.

### How It Works

Each entry in the list includes:

| Property  | Description                                                                |
| --------- | -------------------------------------------------------------------------- |
| `type`    | Defines the client (currently only `Wawi`).                                |
| `version` | Minimum version required in semantic versioning format (e.g., `1.11.0.0`). |

When a seller connects, SCX compares the seller's Wawi version (from the User-Agent) with the defined minimum:

* If the version is **lower**, onboarding fails with error code `SLR202`.
* If **equal or higher**, onboarding proceeds as usual.

<Tip>
  Existing sellers are not affected. Their connection will not be interrupted when using a client version lower than the defined minimum.
</Tip>

### Configuration

A channel can manage this property using `PATCH /v1/channel`:

```json theme={null}
// PATCH /v1/channel
{
  "minimumClientsVersionRequired": [
    {
      "type": "Wawi",
      "version": "1.11.0.0"
    }
  ]
}
```

### Use Cases

The property supports several rollout and compatibility scenarios.

| Scenario                | Description                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| **Gradual rollouts**    | Require a minimum client version for new signups to ensure feature compatibility.         |
| **Controlled upgrades** | Encourage merchants to update to the latest Wawi version when using new channel features. |
| **Legacy protection**   | Avoid issues caused by outdated clients without disrupting existing integrations.         |

***

## What's Next?

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

  <Card title="Product Sync" icon="refresh-cw" href="/guides/marketplace-channels/product-sync">
    Listing and stock synchronization.
  </Card>

  <Card title="Order Management" icon="box" href="/guides/marketplace-channels/order-management">
    Orders, cancellations, returns, and refunds.
  </Card>

  <Card title="Authorization" icon="key" href="/guides/marketplace-channels/authorization">
    Token exchange and Bearer headers once a seller is onboarded.
  </Card>

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

  <Card title="Postman Collection" icon="rocket" href="https://www.postman.com/jtl-eazyauction/workspace/jtl-scx-public">
    Try the API with ready-made requests.
  </Card>
</CardGroup>