To access the JTL-Channel API you need an API refresh token. These tokens are created during the onboarding process
together with JTL. If you are interested in connecting your marketplace with the JTL ecosystem, please
contact us.
The Channel implementation runs on your own infrastructure. You as the Channel integrator have the full responsibility to
run, manage, and secure your application.
Error responses are indicated by an HTTP status code >= 400. The Channel API uses a consistent error response format:
{ "errorList": [ { "code": "VAL100", "message": "orderList[0].sellerId: SellerId must not be empty and may contain a maximum of 50 alphanumeric characters", "severity": "error", "hint": null }, { "code": "VAL100", "message": "orderList[0].orderStatus: Invalid or unknown Order Status. Must be one of UNACKED, CREATED, ACCEPTED, SHIPPED, PARTIALLY_SHIPPED, CANCELED_BY_SELLER, CANCELED_BY_BUYER", "severity": "error", "hint": null } ]}
The default language for error messages is German (de). You can switch to English by setting the Accept-Language: en header.
Two important components of SCX are seller events and channel events. Seller events are emitted by a seller integration such
as JTL-Wawi, while channel events are emitted by a channel integration. Such events are actions created by an actor
(either a seller or a channel) and may be handled by connected integrations.A channel integration needs to handle the various seller events provided by GET /v1/channel/event in order to create new
listings, and mark orders as paid or shipped.Event handling flow between Seller, SCX, and Channel
We recommend calling the seller event endpoint at regular intervals (such as once a minute) and consuming all available events.
When an event is consumed, it must be acknowledged by calling DELETE /v1/channel/event. Otherwise, the event will be
transmitted again after a timeout.
An event will be transmitted a maximum of 10 times. Afterwards it will be marked as a dead-letter and will
not be transmitted again.
Within the SCX context, there is no concept of a product catalogue. Only listing data is transmitted via the SCX interface.
This can, however, also contain detailed product data if required by the channel.A channel must provide descriptive data to describe what a listing may look like on a connected marketplace. This is called Metadata.Metadata components that a channel provides to SCX
Attributes provide a simple way of describing a listing for a channel. This lets the channel
define all marketplace requirements for a listing as attributes. SCX differentiates between the following attribute types:
Global Attributes
Category Attributes
Seller Attributes
Item-specific Attributes
Global attributes should be used when data is required for each listing.These are set via PUT /v1/channel/attribute/global and apply to all listings regardless of category.
Category attributes are related to a categoryId inside the category structure. JTL-Wawi will display these attributes
only when the listing is part of a given category.These are set via POST /v1/channel/attribute/category/{categoryId}.
Seller attributes are global attributes and can be used when a seller requires individual settings for their listings.These are set via POST /v1/channel/attribute/seller.
Item-specific attributes are not specified by the channel but are instead created and transferred by the seller.
Each attribute must provide a simple, non-schematic, key-value data structure. These attributes will be transmitted
along with the channelAttributeList in each Seller:Offer.New or Seller:Offer.Update event.These attributes are highly specific and depend on the input of the seller. The channel can use these attributes to
provide product and listing data.
When using repeatable sections, JTL-Wawi generates a group ID which is then transferred back to the channel with the
listing. This makes it possible to recognize related attributes in the listing data:
Events provided by SCX include pictureList and mainPicture in both Seller:Offer.New and Seller:Offer.Update payloads.
These fields are URLs to image files.
Any channel-specific attribute defined as type image or document also appears as a URL to the corresponding file.
Media URLs remain valid for 7 days after event generation. After this period, requests may return HTTP 404 or 403.
If your marketplace integration requires access beyond 7 days, you must proactively fetch and store or rehost the file.
