Listing data retrieval

Listing data works like inventory and pricing, with one difference. There are two polls, not one:

Listings Zentail believes should be created on your channel.
Listings already on your channel whose product data has changed.

What you’ll build

Two pollers — one that creates new listings on your channel, and one that updates listings already there. Run both on the inventory page’s strategy.

Before you start

You have created your taxonomy.

1. Poll for new listings

Request GET /v2/storefront/listing/new with the time of your last successful poll:

GET /v2/storefront/listing/new?since=2026-09-22T14:00:00.000Z

Parameter	Type	Description
`since`	`string ($date-time)`	Only listings created or updated at or after this time.
`cursor`	`string`	The `nextPageCursor` from the previous page. Leave it out for the first page.

A listing is “new” while none of its variants has a channel ID. It must also have product data enabled for at least one variant, or it does not appear here. Once you report a channel ID for any variant, through listing status, the listing leaves this poll and moves to the one in step 2.

Still check each new listing against the SKUs already on your channel, so you do not create a duplicate.

2. Poll for updated listings

Request GET /v2/storefront/listing/product_data/updated with the same two parameters, since and cursor. It returns each listing that has at least one variant with a channel ID and a product data change since since, including a change on one of its variants.

3. Read each listing

Both polls return the same shape. A listing carries everything you need to build it on your channel:

{
  "listings": [
    {
      "id": "7788",
      "sku": "TSHIRT-RED",
      "productData": {
        "enabled": true,
        "categoryId": "string",
        "productTypeId": "mens-tshirts",
        "pivotAttributes": ["size", "color"],
        "attributes": [/* … */],
      },
      "variants": [
        {
          "sku": "TSHIRT-RED-M",
          "channelId": "string",
          "inventory": {/* … */},
          "identifiers": {
            "enabled": true,
            "attributes": [/* … */],
            "updatedAt": "2026-09-22T14:03:11.000Z",
          },
          "productData": {
            "enabled": true,
            "attributes": [/* … */],
            "updatedAt": "2026-09-22T14:03:11.000Z",
          },
          "pricing": {/* … */},
          "logistics": {
            "enabled": true,
            "attributes": [/* … */],
            "updatedAt": "2026-09-22T14:03:11.000Z",
          },
        },
      ],
      "createdAt": "2026-09-20T10:00:00.000Z",
      "updatedAt": "2026-09-22T14:03:11.000Z",
    },
  ],
  "nextPageCursor": "",
}

id is Zentail’s listing id, and sku is the SKU for the listing as a whole.
The top-level productData carries the attributes you marked LEVEL_LISTING during taxonomy ingestion.
pivotAttributes names the attributes the listing varies on. For ["size", "color"], let buyers pick a size and a colour from the listing’s variants.
On each variant, inventory and pricing are covered in the previous steps. identifiers, logistics and productData carry the attributes with those classifications.
Every attributes array holds attributes whose id is the attributeSpecId you set during taxonomy ingestion. Each has one value key for its type; the pricing page lists all six.

When you ingest a listing, take all of its data, so your copy is as current as possible.

4. Fetch one listing

To read one listing outside a poll, request GET /v2/storefront/listing/{listingId} with Zentail’s listing id. Or request GET /v2/storefront/listing/sku/{sku} with any of its variants’ SKUs. Both return one listing in the shape above.

Next steps

Report each listing’s status and any ingestion errors back to Zentail, so sellers can find and fix data problems quickly. See listing status and errors.