Seller Management

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

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

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.

The sign-up flow described below applies to standalone channels. If the channel is a platform channel (multi-marketplace architecture), see Platform Channels.

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.

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.

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.

Authenticate and create seller

The channel authenticates the seller, stores the new seller record, and assigns a unique Seller ID.

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.

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

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

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

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

Create an update session

The update process is initiated via the Seller API, which creates an update URL for the channel.

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.

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

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.

Example: Initiate an Update Session

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

// 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:

// 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:

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

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

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

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.

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.

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

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.

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

Configuration

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

// 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?

Channel API Overview

Events, metadata, and media content handling.

Product Sync

Listing and stock synchronization.

Order Management

Orders, cancellations, returns, and refunds.

Authorization

Token exchange and Bearer headers once a seller is onboarded.

Channel API Reference

Endpoint-level reference for the Channel API.

Postman Collection

Try the API with ready-made requests.

Essentials

Cloud Apps

Marketplace Channels

ERP Integration

Vouchers API

Seller Update

Example: Initiate an Update Session

Seller Unlink

Unlinking a Seller from the Channel Side

Managing Minimum Client Version

How It Works

Configuration

Use Cases

What’s Next?

Channel API Overview

Product Sync

Order Management

Authorization

Channel API Reference

Postman Collection

​Seller Sign-up

​Example: Create a Sign-up Session

​Seller Update

​Example: Initiate an Update Session

​Seller Unlink

​Unlinking a Seller from the Channel Side

​Managing Minimum Client Version

​How It Works

​Configuration

​Use Cases

​What’s Next?

Channel API Overview

Product Sync

Order Management

Authorization

Channel API Reference

Postman Collection

Seller Sign-up

Example: Create a Sign-up Session

Seller Update

Example: Initiate an Update Session

Seller Unlink

Unlinking a Seller from the Channel Side

Managing Minimum Client Version

How It Works

Configuration

Use Cases

What’s Next?