Skip to content
JTL-Marketplaces (SCX)
/
/
Listings
Last updated

Listings

Listings are transmitted by the Seller:Offer.New and Seller:Offer.Update event. Each time the listing data changes, JTL-Wawi will transmit the entire listing again.

Essentials Properties

It is generally not necessary to provide attributes for essential data, as each listing already implements a set of essential properties by default, including a title, description, GTIN, quantity and price.

Pictures / Images

Product or listing images are transmitted as a link along with the listing event. These links have a lifetime of 7 days after the listing event was triggered. The filename is generated based on the file content; i.e., each separate image will have a filename similar to its file content.

Listing State

offer_listing.png

We highly recommend informing the seller about the processing status of their listings. Most marketplaces use an asynchronous listing process during which the listing data is curated in a semi-automated process — a process which may take some time.

State: In-Progress

Send this state to inform the seller that the listing process is now in progress for their listing.

// POST /v1/channel/offer/in-progress
{
	"offerList": [
		{
      "offerId": 1,
			"sellerId": "1",
      "startedAt": "2022-11-28T01:00:13+00"
		}
	]
}

State: Successful

We recommend informing the seller once a listing is successfully listed on the connected marketplace. The optional listingUrl is useful in this case and allows the seller to visit and thereby directly check the listing on the connected marketplace.

// POST /v1/channel/offer/listed

{
	"offerList": [
		{
			"sellerId": "1",
			"offerId": 1,
			"listedAt": "2022-11-28T01:00:13+00",
			"listingUrl": "https://marketplace.de/offer1",
			"channelOfferId": "AFGHDHDFH"
		}
	]
}

State: Failed

You need to inform the seller if the listing process for a listing failed.

// POST v1/channel/offer/listing-failed

{
	"offerList": [
		{
			"sellerId": "1",
			"offerId": 1,
			"errorList": [
				{
					"code": "123",
					"message": "A listing error occur",
					"longMessage": "A serious listing error occure."
				}
			],
			"failedAt": "2019-02-09T05:33:12+00:00"
		}
	]
}

Stock Updates

The Stock Updates API enables channels to keep their inventory synchronized with seller stock levels. There are ways to syncronize stock

  • Fetch stock updates using GET /v1/channel/offer/stock-updates for individual Seller.
    • Use this endpoint when your channel processes are running in paralell for each Seller
    • Has a higher rate limit
  • Fetch stock updates using GET /v1/channel/offer/stock-updates/all for all Sellers.
    • Use this endpoint to get stock changes for all your active Sellers at once
  • Consuming Seller:Offer.StockUpdate Seller Event.
    • Not recommended to use.
    • Will be dreprecated.

Example Requests & Responses

// GET /v1/channel/offer/stock-updates/all?updatedAfter=2025-12-29T00:00:00+00:00
{
  "stockUpdateList": [
    {
      "channel": "MYCHANNEL",
      "sellerId": "SELLER001",
      "offerId": 4711,
      "channelOfferId": "SKU-WIDGET-001",
      "quantity": 25,
      "updatedAt": "2025-12-29T10:15:30+00:00"
    },
    {
      "channel": "MYCHANNEL",
      "sellerId": "SELLER002",
      "offerId": 8822,
      "channelOfferId": "SKU-GADGET-042",
      "quantity": 0,
      "updatedAt": "2025-12-29T11:22:45+00:00"
    }
  ],
  "lastUpdatedAt": "2025-12-29T11:22:45+00:00"
}

Incremental Sync Pattern

For efficient synchronization, use the lastUpdatedAt value from the response as the updatedAfter parameter in your next request:

1. First call:    GET /v1/channel/offer/stock-updates/all?updatedAfter=2025-12-01T00:00:00Z
   Response:      lastUpdatedAt = "2025-12-29T11:22:45+00:00"

2. Next call:     GET /v1/channel/offer/stock-updates/all?updatedAfter=2025-12-29T11:22:45+00:00
   Response:      lastUpdatedAt = "2025-12-29T14:30:00+00:00"

3. Continue...
Previous page
Next page