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


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


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


```json
// 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


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