--- title: "Retrieve a list of listings" method: GET path: "/listing" tags: ["Listing"] --- # Retrieve a list of listings `GET /listing` ## Request - Base URL: `https://api.zentail.com/v1` - URL: `https://api.zentail.com/v1/listing` - Auth: API key in header `AUTHORIZATION` This endpoint is restricted to developers who have registered an application with Zentail. Please refer to our [guide](https://developer.zentail.com/sales-channel-integration/getting-started) on building a sales channel integration to learn more about the registration process and how to use the listing endpoint. ## Query parameters - `lastUpdateTs` string, date-time - `skus` string[] - `pageLength` integer - `nextToken` string ## Response `200` Success - object - `results` Listing[] - `id` string: A unique identifier for this listing. - `sku` string: SKU which references the entire listing - `title` string: A "group-level" title, applies to the entire listing - `description` string: A description which applies to the entire listing - `tags` string: Tags which can help identify this listing - `created_at` string, date-time: Timestamp this listing was created at - `updated_at` string, date-time: Timestamp this listing was last updated at - `pivot_attributes` string[]: The list of attributes that the variants in this group should be selectable by - `primary_image` ListingImage - `url` string: This is the URL that you can download the image from - `hash` string: This is a hash of the image contents, it can be used to differentiate one image from another. - `category` string: The category for this listing on the channel - `cpsia_warnings` CPSIAWarnings - `choking hazard balloon` boolean - `choking hazard contains a marble` boolean - `choking hazard contains a small ball` boolean - `choking hazard is a marble` boolean - `choking hazard is a small ball` boolean - `choking hazard small parts` boolean - `prop65` Prop65 - `required` boolean - `type` 'alcoholic_beverage' | 'chemical' | 'diesel_engines' | 'food' | 'furniture' | 'on_product_cancer' | 'on_product_combined_cancer_reproductive' | 'on_product_reproductive' | 'passenger_or_off_road_vehicle' | 'raw_wood' | 'recreational_vessel' - `chemicals` string[] - `listing_data` ListingData[]: listing data should provide all of the listing-level data attributes. Only a subset of the total realm of possible attributes will be provided. This will be based on the Zentail SMART Type system and some other factors. If an attribute is not provided, it can be assumed the value is null. If attributes were created during the mapping process that require explicit units that would be provided in separate `unit` and `value` keys. - `attribute` string: Name of attribute - `value` string: Value for attribute - `variants` VariantData[]: The list of variants. Each item provides variant specific inventory, pricing, and catalog attribute data. - `sku` string: A unique identifier for this variant - `available_inventory` number: The available inventory to be sold. This number is Zentails understanding of the sellable quantity which should account for units reserved by unfulfilled orders. - `last_external_inventory_change_timestamp` string, date-time: The last time an inventory change was made to this product by anything other than a sale on this channel. This can be used to know when Zentails available inventory level should be ingested in place of any internal inventory accounting your system may be doing. - `pricing` VariantPricing - `current_selling_price` number: This is the price the item should be sold for - `msrp` number: MSRP - `map` number: MAP - minimum advertised price - `pricing` number: If this value is provided, this product is on sale and markedDownFrom can be shown as a "strike-through" price - `primary_image` ListingImage - `url` string: This is the URL that you can download the image from - `hash` string: This is a hash of the image contents, it can be used to differentiate one image from another. - `images` ListingImage[]: An array of secondary images for this variant. - `url` string: This is the URL that you can download the image from - `hash` string: This is a hash of the image contents, it can be used to differentiate one image from another. - `standard_identifier` string: A UPC/EAN/ISBN/GTIN for this variant - `standard_identifier_type` 'UPC' | 'EAN' | 'GTIN' | 'ISBN': Indicates the type of ID provided in `standard_identifier` - `brand` string: The brand associated with this variant - `manufacturer` string: The manufacturer of this variant - `model_number` string: The model number for this variant - `condition` 'New' | 'New Other (see details)' | 'New with defects' | 'Manufacturer refurbished' | 'Seller refurbished' | 'Like New' | 'Used' | 'Very Good' | 'Good' | 'Acceptable' | 'For parts or not working' | 'refurbished' | 'recertified' | 'Pre-owned' | 'New with box' | 'New without box' | 'New with tags' | 'New without tags' | 'Open box': The condition of this variant - `condition_description` string: Additional details about the condition of this variant. - `bullet_points` string[]: A list of bullet points that describe this variant. - `listing_data` ListingData[]: listing data should provide all of the product data attributes. At a minimum, the pivot attributes will be provided here. All other listing attributes will be provided here as well. Only a subset of the total realm of possible attributes will be provided. This will be based on the Zentail SMART Type system and some other factors. If an attribute is not provided, it can be assumed the value is null. If attributes were created during the mapping process that require explicit units that would be provided in separate `unit` and `value` keys. - `attribute` string: Name of attribute - `value` string: Value for attribute - `validation_errors` ValidationError[]: Any errors that were found during the validation process - `attribute` string: Name of attribute - `error` string: The error message - `pagination` Pagination - `hasNext` boolean: Indicates if there is an additional page. This is `true` if there is another page, otherwise it is `false`. - `nextToken` string, uri: If `hasNext` is `true` this provides the full URL for the next page of results. ## Other responses - `400`: Bad Request - `403`: Permission Denied - `404`: Not Found - `500`: Zentail Error - `503`: Zentail Error --- [API](https://skmtc.dev/zentail/apis/zentail-api.md) - [All operations](https://skmtc.dev/zentail/apis/zentail-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zentail/apis/zentail-api/revisions/55e43cb43caf?raw)