Listing status and errors

Sellers get their listings live faster when they can see what your channel did with each one. This step sends that feedback to Zentail: each listing’s status, the errors that block it, and a record of what you submitted.

What you’ll build

Three reports your ingestion process sends back to Zentail for each SKU: its status, its errors, and its submissions.

Before you start

You are ingesting listing data from Zentail.

1. Report status

Status is the most important report. It tells the seller whether a listing is live on your channel, and tells Zentail whether the listing still needs to be created or only updated.

Send each SKU’s status with POST /v2/storefront/listing/variant/{sku}/status:

{
  "status": "STANDARD_STATUS_PUBLISHED",
  "channelStatus": "Active",
  "channelId": "40123456789012",
  "channelListingId": "B0EXAMPLE1",
  "buyable": true,
  "listingUrl": "https://channel.example/item/B0EXAMPLE1"
}

Field	Type	Description
`status`	`string`	Zentail’s standard status, which Zentail acts on. One of `STANDARD_STATUS_PUBLISHED`, `STANDARD_STATUS_UNPUBLISHED`, `STANDARD_STATUS_SUPPRESSED` or `STANDARD_STATUS_RETIRED`
`channelStatus`	`string`	The listing’s status in your own terms
`channelId`	`string`	Your identifier for this variant — the one SKU this call is about
`channelListingId`	`string`	Your identifier for the listing the variant belongs to, such as an Amazon ASIN, an eBay ItemID or a Walmart id
`buyable`	`boolean`	True if the listing is available to buy. It tells the seller the product is live and sales should be expected
`listingUrl`	`string`	(optional) A URL where the seller can view the listing on your channel

That is every field in the request body.

channelId and channelListingId are not the same id, and a multi-variant listing needs both. channelId is per SKU; channelListingId is the listing all those SKUs sit under. Send the same channelListingId on each variant of one listing.

The call replaces the SKU’s current status. For a listing with several SKUs, make one call per SKU, since each variant can have its own status, id and link.

2. Report errors

When a listing fails to ingest — often because of bad data on specific attributes — send the errors to Zentail. The seller then sees which attributes to fix, and gets more listings live.

Errors are kept per SKU and per submissionType. A submissionType is a name you choose for one of your processes, such as inventory, pricing or listing data, so separate processes do not overwrite each other’s errors. Each call replaces all errors for that SKU and submissionType.

Send them with POST /v2/storefront/listing/variant/{sku}/errors:

{
  "submissionType": "listing data",
  "errors": [
    {
      "attributeIds": ["color"],
      "severity": "SEVERITY_ERROR",
      "type": "TYPE_INVALID_VALUE",
      "message": "Color must be one of the channel's listed colors."
    }
  ]
}

Each error has these fields:

Field	Type	Description
`attributeIds`	`array`	The `attributeSpecId`s from taxonomy ingestion linked to this error. Zentail points the seller at them
`severity`	`string`	How urgently the seller must fix it. One of `SEVERITY_NOTICE`, `SEVERITY_WARNING` or `SEVERITY_ERROR` — use `SEVERITY_ERROR` when it stops the listing being ingested
`type`	`string`	The error type, which gives the seller a standard message and fix screen in Zentail. One of `TYPE_MISSING_VALUE`, `TYPE_INVALID_VALUE`, `TYPE_RESTRICTED_VALUE`, `TYPE_TOO_MANY_VALUES` or `TYPE_OTHER`
`message`	`string`	A message for the seller, as plain as you can make it. Required when the type is `TYPE_OTHER` or `TYPE_TOO_MANY_VALUES`

3. Record submissions

A submission records that you received an update and started processing it. Sellers find the progress reassuring, and good data here helps everyone debug.

Send them with POST /v2/storefront/listing/submission, as a submissions array. Submissions are grouped by SKU and type, like errors, and despite the name the call replaces the earlier submissions for that pair.

Field	Type	Description
`submissionId`	`string ($int64)`	Read-only. Zentail assigns it and returns it. Setting it on this call has no effect
`sku`	`string`	The SKU that was submitted
`contentSent`	`string`	The content that was ingested
`contentReceived`	`string`	The result of the content ingestion
`metadata`	`object`	String keys and values, for anything else the seller would find helpful
`type`	`string`	The `submissionType` from step 2
`successful`	`boolean`	Whether the ingestion succeeded
`submittedAttributeVersionIds`	`array`	The `versionId` of every attribute in this submission. Zentail uses these to show the seller when each attribute on the listing was last sent
`preparedAt`	`string ($date-time)`	When the data was prepared for ingestion
`submittedAt`	`string ($date-time)`	When the ingestion started
`acknowledgedAt`	`string ($date-time)`	When the ingestion completed

That is every field on a submission. The response returns the submissions with their submissionId, which the inventory drift check needs.

Populating submittedAttributeVersionIds puts a “submitted” timestamp on each attribute in the seller’s view of the listing. Each versionId comes from its attribute in the listing payload you ingested; see the pricing example.

To move a submission on once it is created, call PUT /v2/storefront/listing/submission/{type}/{sku} with a status of STATUS_SUBMITTED, STATUS_ACCEPTED or STATUS_REJECTED.