Channel API Overview - JTL Developer Documentation

The Channel API is available for OnPremise integrations. Consuming SCX from within a Cloud App is in development and not yet available.

With the JTL-Channel API, you can:

Describe connected marketplace data structure by providing category and attribute data
Manage product and offer listings
Update price and quantity of a listing
Manage orders
Manage the post-order process (returns, refunds)

Terminology

The Channel API uses a small set of terms consistently throughout this guide.

Term	Definition
Channel	A connection to a marketplace or any external system which can be connected to the JTL-Channel API.
Seller	A person identified by a unique ID (SellerId) who wants to offer and sell their goods on the connected Channel.
Event	An action initiated by a seller. A channel needs to react to events in order to create or update a listing or to process post-order actions.
Seller API	The Channel API counterpart. The ERP system JTL-Wawi is connected with the Seller API.

Development Cycle

This section covers the hosts, prerequisites, and local setup you need to build and test a channel integration.

API Hosts

The Channel API is available in a sandbox environment for development and a production environment for live traffic.

https://scx-sbx.api.jtl-software.com

https://scx.api.jtl-software.com

Prerequisites

To access the JTL-Channel API you need an API refresh token. These tokens are created during the onboarding process together with JTL. Sellers connect to a channel with an eazyAuction subscription. If you are interested in connecting your marketplace with the JTL ecosystem, please contact us.

Development

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 Handling

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.

Setting Up a Local JTL-Wawi Instance

You can use the JTL-Wawi ERP system during development to create new listings or manage orders.

Install JTL-Wawi

Install JTL-Wawi version 1.8 or higher to connect with the sandbox environment.

Add the seller refresh token

Connect to the MSSQL Server directly and insert the seller’s refresh token (created during onboarding):

INSERT INTO SCX.tRefreshToken
(cRefreshToken, nType)
VALUES
(N'<SellerAPI-RefreshToken>', 1);

Switch the API host to Sandbox

UPDATE dbo.tOptions
SET cValue = 'https://scx-sbx.api.jtl-software.com'
WHERE ckey = 'SCX.URL'

Restart JTL-Wawi

Restart JTL-Wawi to apply the changes.

Using the Seller API Directly

To test workflows and send test data to the Channel API, you can use the Seller API directly. See the Seller API reference and the Postman Collection.

Events

Two important components of SCX are seller events and channel events. Seller events are emitted by a seller integration such as JTL-Wawi. 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.

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.

Seller Event Types

Seller events fall into three groups: offer events, order events, and seller meta events.

Offer Events

Event Type	Description
`Seller:Offer.New`	A new listing/offer was created by the seller
`Seller:Offer.Update`	An existing listing/offer was updated
`Seller:Offer.StockUpdate`	Stock quantity changed (deprecated, use stock update endpoints)
`Seller:Offer.PriceUpdate`	Price changed for an existing offer

Order Events

Event Type	Description
`Seller:Order.Shipping`	Seller has shipped (or partially shipped) an order
`Seller:Order.Payment`	Payment status changed
`Seller:Order.CancellationAccepted`	Seller accepted a cancellation request
`Seller:Order.CancellationDenied`	Seller denied a cancellation request
`Seller:Order.Refund`	Seller initiated a refund
`Seller:Order.ReturnProcessingResult`	Seller processed a return

Seller Meta Events

Event Type	Description
`Seller:Meta.SellerAttributesUpdateRequest`	Seller requested to update their seller attributes
`Seller:Channel.Unlinked`	Seller unlinked from the channel

Receiving Seller Events

A GET /v1/channel/event call returns an eventList containing the queued events for your channel.

// GET /v1/channel/event
{
  "eventList": [
    {
      "id": "63623b997d2c89a4e3e9f3c7",
      "event": {
        "channel": "WAWIDEV001",
        "sellerId": "EA4590MitName"
      },
      "createdAt": "2022-11-02T09:42:49+00:00",
      "type": "Seller:Meta.SellerAttributesUpdateRequest"
    },
    {
      "id": "636280fd498628e9f0b28984",
      "event": {
        "sellerId": "1",
        "offerId": 822,
        "channelCategoryId": "CAT7",
        "quantity": "0",
        "taxPercent": "19",
        "priceList": [
          {
            "id": "B2C",
            "quantityPriceList": [
              {
                "quantity": "1",
                "amount": "19.99",
                "currency": "EUR"
              }
            ]
          }
        ],
        "title": "Fahrrad Halterung",
        "channelAttributeList": [
          {
            "attributeId": "WAWI-61427_number_category",
            "value": "954",
            "group": "0"
          }
        ],
        "sku": "843609"
      },
      "createdAt": "2022-11-02T14:38:53+00:00",
      "type": "Seller:Offer.New"
    }
  ]
}

Acknowledging Events

After processing, acknowledge the received events so they are not retransmitted:

// DELETE /v1/channel/event
{
  "eventIdList": [
    "63623b997d2c89a4e3e9f3c7",
    "636280fd65a66c4430ec0d67"
  ]
}

Metadata

Within the SCX context, there is no concept of a product catalogue. Instead, only listing data is transmitted via the SCX interface. Depending on the channel’s requirements, this listing data may also include detailed product information. A channel provides descriptive information that defines what a listing can look like on a connected marketplace. This descriptive information is called Metadata.

Price Types

There must be at least one price type available to create a listing on a connected marketplace. Examples of price types are B2C or B2B prices.

// POST /v1/channel/price
{
  "priceTypeId": "MarketplaceTypeId",
  "displayName": "Marketplace Price",
  "description": "Selling price on Marketplace"
}

The priceTypeId will be transmitted with the Seller:Offer.New or Seller:Offer.Update seller events:

{
  "sellerId": "1",
  "offerId": 4711,
  "channelCategoryId": "Stuff",
  "quantity": "508.00",
  "taxPercent": "19",
  "priceList": [
    {
      "id": "MarketplaceTypeId",
      "quantityPriceList": [
        {
          "amount": "6.95",
          "currency": "EUR",
          "quantity": "1"
        }
      ]
    }
  ]
}

Category Tree

A connected channel may provide a category structure to set specific attributes related to a category.

The API endpoint replaces the entire category structure on each call.

// PUT /v1/channel/categories
{
  "categoryList": [
    {
      "categoryId": "1",
      "displayName": "First Category",
      "listingAllowed": false,
      "parentCategoryId": "0"
    },
    {
      "categoryId": "1.1",
      "displayName": "First Leaf Category",
      "listingAllowed": true,
      "parentCategoryId": "1"
    },
    {
      "categoryId": "1.2",
      "displayName": "Second Leaf Category",
      "listingAllowed": true,
      "parentCategoryId": "1"
    }
  ]
}

Attributes

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.

Attribute Types Reference

Each attribute is declared with one of the following types.

Type	Description
`smalltext`	Short text value
`text`	Longer text value
`integer`	Integer number
`decimal`	Decimal number
`boolean`	True/false value
`enum`	Enumerated value with predefined options
`htmltext`	HTML-formatted text
`date`	Date value
`image`	Link to an image file
`document`	Link to a document file

Attributes with Different Types

The following request registers one attribute of each supported type against a category.

// POST /v1/channel/attribute/category/DEMO-TYPES
// DEMO-TYPES is a categoryId created earlier via PUT /v1/channel/categories
{
  "attributeList": [
    {
      "attributeId": "DEMO-TYPES_smalltext",
      "displayName": "Smalltext",
      "type": "smalltext"
    },
    {
      "attributeId": "DEMO-TYPES_text",
      "displayName": "Text",
      "type": "text"
    },
    {
      "attributeId": "DEMO-TYPES_integer",
      "displayName": "Integer",
      "type": "integer"
    },
    {
      "attributeId": "DEMO-TYPES_decimal",
      "displayName": "Decimal",
      "type": "decimal"
    },
    {
      "attributeId": "DEMO-TYPES_boolean",
      "displayName": "Boolean",
      "type": "boolean"
    },
    {
      "attributeId": "DEMO-TYPES_enum",
      "displayName": "Enum",
      "type": "enum",
      "values": [
        { "display": "Value 1", "value": "Id1", "sort": 10 },
        { "display": "Value 2", "value": "Id2", "sort": 20 },
        { "value": "This has no Display" }
      ]
    },
    {
      "attributeId": "DEMO-TYPES_htmltext",
      "displayName": "Html-text",
      "type": "htmltext"
    },
    {
      "attributeId": "DEMO-TYPES_date",
      "displayName": "Date",
      "type": "date"
    },
    {
      "attributeId": "DEMO-TYPES_image",
      "displayName": "Image",
      "description": "Link to Image file",
      "type": "image"
    },
    {
      "attributeId": "DEMO-TYPES_document",
      "displayName": "Document",
      "description": "Link to a Document file",
      "type": "document"
    }
  ]
}

Using Sections and Sub-sections

You can organize attributes into logical groups using sections and sub-sections:

// POST /v1/channel/attribute/category/DEMO-SECTIONS
// DEMO-SECTIONS is a categoryId created earlier via PUT /v1/channel/categories
{
  "attributeList": [
    {
      "attributeId": "DEMO-SECTIONS_WAREHOUS",
      "displayName": "Warehouse",
      "type": "smalltext",
      "section": "Shipping",
      "sectionPosition": 100
    },
    {
      "attributeId": "DEMO-SECTIONS_SHIPPING",
      "displayName": "Shipping Group",
      "type": "smalltext",
      "section": "Shipping",
      "sectionPosition": 80
    },
    {
      "attributeId": "DEMO-SECTIONS_LEADTIME",
      "displayName": "Lead time until shipment",
      "type": "integer",
      "section": "Shipping",
      "sectionPosition": 50
    },
    {
      "attributeId": "DEMO-SECTIONS_OFFER_START",
      "displayName": "Start",
      "type": "date",
      "section": "Discount",
      "sectionPosition": 50
    },
    {
      "attributeId": "DEMO-SECTIONS_OFFER_DISCOUNT",
      "displayName": "Discount Value",
      "type": "decimal",
      "section": "Discount",
      "sectionPosition": 100,
      "subSection": "Deduction",
      "subSectionPosition": 100
    },
    {
      "attributeId": "DEMO-SECTIONS_OFFER_DISCOUNT_UNIT",
      "displayName": "Discount Unit",
      "type": "enum",
      "values": [
        { "value": "%" },
        { "value": "EUR" }
      ],
      "section": "Discount",
      "sectionPosition": 100,
      "subSection": "Deduction",
      "subSectionPosition": 90
    }
  ]
}

Multiple-value Attributes

It is possible to create repeatable attributes if the attribute supports multiple values:

// POST /v1/channel/attribute/category/DEMO-MULTIPLY_ALLOWED
// DEMO-MULTIPLY_ALLOWED is a categoryId created earlier via PUT /v1/channel/categories
{
  "attributeList": [
    {
      "attributeId": "DEMO-TYPES_isMultipleAllowed",
      "displayName": "Attribute is Multiple Allowed",
      "isMultipleAllowed": true,
      "type": "smalltext"
    }
  ]
}

Repeatable Sub-sections

You can also create repeatable sub-sections for grouped attribute sets:

// POST /v1/channel/attribute/category/DEMO-REPEATABLE_SUBSECTIONS
// DEMO-REPEATABLE_SUBSECTIONS is a categoryId created earlier via PUT /v1/channel/categories
{
  "attributeList": [
    {
      "attributeId": "shipping_carrier",
      "displayName": "Versanddienstleister",
      "type": "enum",
      "values": [
        { "value": "carrierID_2", "display": "Brief", "sort": 1 },
        { "value": "carrierID_3", "display": "DHL Paeckchen", "sort": 2 },
        { "value": "carrierID_4", "display": "DHL Paket", "sort": 3 },
        { "value": "carrierID_22", "display": "Kostenloser Download", "sort": 20 }
      ],
      "section": "Versandkosten",
      "sectionPosition": 2,
      "subSection": "Versandart",
      "subSectionPosition": 10,
      "isRepeatableSubSection": true
    },
    {
      "attributeId": "shipping_cost_nat",
      "displayName": "National",
      "type": "decimal",
      "section": "Versandkosten",
      "sectionPosition": 2,
      "subSection": "Versandart",
      "subSectionPosition": 9,
      "isRepeatableSubSection": true
    },
    {
      "attributeId": "shipping_cost_eu",
      "displayName": "EU",
      "type": "decimal",
      "section": "Versandkosten",
      "sectionPosition": 2,
      "subSection": "Versandart",
      "subSectionPosition": 8,
      "isRepeatableSubSection": true
    },
    {
      "attributeId": "shipping_cost_int",
      "displayName": "International",
      "type": "decimal",
      "section": "Versandkosten",
      "sectionPosition": 2,
      "subSection": "Versandart",
      "subSectionPosition": 7,
      "isRepeatableSubSection": true
    }
  ]
}

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:

// GET /v1/channel/event: Offer with repeatable sub-sections
{
  "type": "Seller:Offer.New",
  "sellerId": "1",
  "offerId": 1,
  "channelCategoryId": "DEMO-REPEATABLE_SUBSECTIONS",
  "channelAttributeList": [
    { "attributeId": "shipping_carrier", "value": "DHL Paket", "group": "1" },
    { "attributeId": "shipping_cost_nat", "value": "2.99", "group": "1" },
    { "attributeId": "shipping_cost_eu", "value": "2.99", "group": "1" },
    { "attributeId": "shipping_cost_int", "value": "9.99", "group": "1" },
    { "attributeId": "shipping_carrier", "value": "Brief", "group": "2" },
    { "attributeId": "shipping_cost_nat", "value": "1.20", "group": "2" },
    { "attributeId": "shipping_cost_eu", "value": "2.40", "group": "2" },
    { "attributeId": "shipping_cost_int", "value": "2.40", "group": "2" }
  ]
}

Media Content Handling

The SCX system emits seller events containing media file links; channels receive these events but do not generate them.

Media Fields in Events and Attributes

Media reaches a channel through event payload fields and through channel-defined attributes.

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.

Defining Media Attributes

Channels can register attributes of type image or document:

// PUT /v1/channel/attribute/global
{
  "attributeList": [
    {
      "attributeId": "DEMO-TYPES_image",
      "displayName": "Image",
      "description": "Link to Image file",
      "type": "image"
    },
    {
      "attributeId": "DEMO-TYPES_document",
      "displayName": "Document",
      "description": "Link to a Document file",
      "type": "document"
    }
  ]
}

File URL Structure

All media links are hosted on S3-compatible storage and follow this pattern:

https://s3.api.jtl-software.com/scx-api/public/{media-hash}.{ext}

Where:

{media-hash} is the SHA-1 hash of the file contents.
{ext} is the file extension (gif, jpg, png, svg, or pdf).

Media URL Lifetime

Media links expire, so plan for retrieval within a fixed window.

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.

Supported Formats and Size Limits

The Channel API accepts the following media MIME types and extensions.

MIME Type	Extension
`image/gif`	`gif`
`image/jpeg`	`jpg`
`image/pjpeg`	`jpg`
`image/png`	`png`
`image/x-png`	`png`
`image/svg+xml`	`svg`
`application/pdf`	`pdf`

Maximum file size is 16 MB per media file. Files that do not match these MIME types or exceed the size limit may be rejected.

Example: `Seller:Offer.New` Event with Media

The following payload shows how media URLs appear in an offer event.

{
  "type": "Seller:Offer.New",
  "sellerId": "MYSELLERID",
  "offerId": 1,
  "mainPicture": "https://s3.api.jtl-software.com/scx-api/public/ca953...872.jpg",
  "pictureList": [
    "https://s3.api.jtl-software.com/scx-api/public/ff5a3...4c3.jpg",
    "https://s3.api.jtl-software.com/scx-api/public/11aa2...p77.png"
  ],
  "channelAttributeList": [
    {
      "attributeId": "thumbnailImage",
      "value": "https://s3.api.jtl-software.com/scx-api/public/aabbc...899.pdf"
    }
  ]
}

What’s Next?

Product Sync

Learn how to synchronize product and offer listings with marketplace channels.

Order Management

Handle orders, cancellations, returns, and refunds across channels.

Seller Management

Seller sign-up, update, and unlink flows.

Authorization

Refresh tokens, access tokens, and Bearer headers for all SCX APIs.

Channel API Reference

Full endpoint reference for the Channel API.

Postman Collection

Ready-made requests for the Channel and Seller APIs.

​Terminology

​Development Cycle

​API Hosts

​Prerequisites

​Development

​Error Handling

​Setting Up a Local JTL-Wawi Instance

​Using the Seller API Directly

​Events

​Seller Event Types

​Receiving Seller Events

​Acknowledging Events

​Metadata

​Price Types

​Category Tree

​Attributes

​Attribute Types Reference

​Attributes with Different Types

​Using Sections and Sub-sections

​Multiple-value Attributes

​Repeatable Sub-sections

​Media Content Handling

​Media Fields in Events and Attributes

​Defining Media Attributes

​File URL Structure

​Media URL Lifetime

​Supported Formats and Size Limits

​Example: Seller:Offer.New Event with Media

​What’s Next?

Product Sync

Order Management

Seller Management

Authorization

Channel API Reference

Postman Collection

Terminology

Development Cycle

API Hosts

Prerequisites

Development

Error Handling

Setting Up a Local JTL-Wawi Instance

Using the Seller API Directly

Events

Seller Event Types

Receiving Seller Events

Acknowledging Events

Metadata

Price Types

Category Tree

Attributes

Attribute Types Reference

Attributes with Different Types

Using Sections and Sub-sections

Multiple-value Attributes

Repeatable Sub-sections

Media Content Handling

Media Fields in Events and Attributes

Defining Media Attributes

File URL Structure

Media URL Lifetime

Supported Formats and Size Limits

Example: `Seller:Offer.New` Event with Media

What’s Next?