Core API
...
Results
Core Requests

Product

9min

Product Results

When making a request with the type parameter set to type=product Countdown API will return product details for the product specified in either the epid and ebay_domain parameters or the url parameter. You can also request make a type=product by specifying a GTIN, EAN, ISBN or UPC code in the gtin parameter.

Master Pages vs. Individual Listing Pages There are two types of product pages that Countdown API can return data from. A Master Page shows a summary of all listings for a known product summerized in the top_picks array - i.e. "listings for the 'Nest Cam Indoor' product" and an Individual Listing Page will show detail for an individual listing.

Master Pages are denoted by is_master=true in the response and Individual Listing Pages are denoted by is_master=false in the response.

Countdown API will automatically detect the type of product page when the request is run, there is no difference in the request parameters required and no need to know what type of product page you're requesting ahead of running the request.

Master Pages and Individual Listing Pages have different results schemas, which are detailed below.



Master Page Results

Master Pages (see example here) show multiple offers in the top_picks array for a single, known product.

Typically the offers shown will be for different conditions - i.e. new, used, preowned, auction etc and contain links to the Individual Listing Pages for the given listings. Master Pages can be identified by is_master=true in the response.

Ebay Master Page
Ebay Master Page


An example of the JSON object returned from an Product request referencing a Master Page is shown below:

JSON


Countdown API returns the following properties for Master Page Product requests (i.e. when is_master=true ):

Property

Type

Description

is_master

boolean

A boolean set to true indicating that this is a Master Product page.

sold_out

boolean

A boolean set to true when all selling channels for the product in this Master Product page are currently sold out. Corresponds to the "Currently Sold Out" message on the Master Product page.

  • 

    Document image
    

top_picks

array

An array containing all of the Top Picks as shown on the Master Product page.

The top_picks array will be populated with objects containing the same properties as shown on an Individual Listing page (see the Individual Listing page response schema below).

Typically a Top Pick will be shown for each condition of listing shown on the Master Page - i.e. one for brand new, one for pre-owned, one for used, one for auction, etc.

Inspect the top_picks.condition.name property to see the description of the Top Pick condition.



Individual Listing Page Results

Individual Listing Pages (see example here contain details of an individual listing. Individual Listing Pages can be identified by is_master=false in the response.

Ebay Individual Listing Page
Ebay Individual Listing Page


An example of the JSON object returned from an Product request referencing an Individual Listing Page is shown below:

JSON


Countdown API returns the following properties for Individual Listing Page Product requests (i.e. when is_master=false ):

Property

Type

Description

is_master

boolean

A boolean set to false indicating that this is a Individual Listing page.

is_auction

boolean

A boolean indicating whether the product listing is an auction or not.

make_offer

boolean

A boolean set to true if the "Make Offer" button is visible on the listing, null if not.

product

object

An object containing details of the primary product shown on the product page.

  • title
  • string
  • The product name.



  • epid
  • string
  • The Ebay product ID (EPID) for the product.



  • spid
  • string
  • The Ebay secondary product ID (SPID) for the product.



  • link
  • string
  • The product page link.



  • brand
  • string
  • The product brand name (if available).



  • model_number
  • string
  • The product model number (if available).



  • description
  • string
  • The product description (if available). Note that in certain circumstances descriptions nested in IFrames on the listing page will not be available.



  • primary_image
  • object
  • Primary Image Object The primary image object contains primary image shown when the product page was loaded.
    • 
      1. link
      2. string
      3. A link to the main image.



  • images
  • array
  • Images Array The images property contains an array of image objects containing the other available product images, excluding the main image. The image object has the following properties:
    • 
      1. link
      2. string
      3. A link to the image.



  • attributes
  • array
  • Attributes Array The attributes array contains details of the product attributes as shown underneath the product title.
    • 
      1. name
      2. string
      3. The name of the product attribute i.e. "Capacity".
    • 
      1. value
      2. string
      3. The value of the product attribute i.e. "128 GB".



  • variants
  • array
  • Variants Array An array containing details of the product variants shown with this product. Each object in the array may contain the following properties (the presence of these properties will vary depending on whether Ebay themselves show them, you should expect one or more to be null):
    • 
      1. name
      2. string
      3. The name of the variant (i.e. "8 Pack"), if shown.
    • 
      1. epid
      2. string
      3. The EPID of the variant, if shown.
    • 
      1. image
      2. string
      3. The link to the variant's image, if shown.
    • 
      1. price
      2. number
      3. The price of the variant, if shown.
    • 
      1. currency
      2. string
      3. The currency of the variant, if shown.
    • 
      1. attributes
      2. array
      3. An array of name value containing the variant attribute names and values, if shown.
    • 
      1. stock_status
      2. object
      3. An object containing the stock status of the variant, if shown. Contains status , quantity_sold and quantity_available properties.

auction

object

Auction Object An object containing auction-specific information that is present when this is an auction listing (i.e when is_auction=true :

  • bids
  • number
  • The number of bids currently placed on this auction.



  • winning_bid_price
  • number
  • The current winning bid price.



  • winning_bid_price_raw
  • string
  • The current winning bid price in raw form. Typically including the currency identifier.



  • winning_bid_price_converted
  • number
  • The current winning bid price, converted into the currency of the Ebay domain (if different from the listing currency).



  • winning_bid_price_converted_raw
  • string
  • The current winning bid price, converted into the currency of the Ebay domain (if different from the listing currency) in raw form. Typically including the currency identifier.



  • buy_it_now
  • boolean
  • A boolean indicating whether Buy It Now is available for this auction.



  • time_left
  • object
  • An object describing the time left on the auction. The raw property contains a locale-specific string showing the time remaining on the auction.



  • end_date
  • object
  • An object describing the end date of the auction. The raw property contains a locale-specific string showing the time remaining on the auction. If possible, Countdown API will parse the end date into a standard UTC timestamp and present it in the utc property.

returns_policy

object

Return Policy Object An object showing details of the returns policy for the product, if available:

  • raw
  • string
  • The raw returns policy description as shown on the product page.



  • returns_accepted
  • boolean
  • Whether or not returns are accepted, true or false .

stock_status

object

Stock Status Object An object showing details of the stock status for the product, if available:

  • raw
  • string
  • The raw stock status string as shown on the product page.



  • status
  • string
  • The normalized stock status string, for example in_stock .



  • quantity_available
  • number
  • The number of products that are available for sale.



  • quantity_sold
  • number
  • The quantity of this product that have been sold.

condition

object

Condition Object An object containing details of the condition for the product that's being offered for sale, if available:

  • raw
  • string
  • The raw condition string as shown on the product page.



  • name
  • string
  • The normalized condition name string, for example new .



  • description
  • number
  • The full test description of the condition.



  • is_new
  • boolean
  • A boolean indicating whether the product is new condition or not.



  • is_used
  • boolean
  • A boolean indicating whether the product is used condition or not.

offer

object

Offer Object An object showing details of the offer for the product, if available:

  • price
  • number
  • The price of the product.



  • currency
  • string
  • The 3-letter currency code of the price.



  • best_offer_accepted
  • boolean
  • Set to true when the "Best Offer accepted" text is shown next to the price on the product page.



  • end_date
  • object
  • An object, present when the listing is flagged as "ended", with a raw property containing the raw date, as shown on the listing page, when the listing ended.

payment_methods

array

An array of strings with each entry in the array being a payment method that is accepted as payment for this product, for example PayPal .

seller

object

Seller Object An object showing details of the seller for the product, if available:

  • name
  • string
  • The seller name.



  • link
  • string
  • A link to the seller's Ebay profile page.



  • feedback_score
  • number
  • The feedback score for the seller of the product.



  • positive_feedback_percent
  • string
  • The seller positive feedback expressed as a percentage.

shipping

object

Shipping Object An object showing details of the shipping for the product, if available:

  • price
  • number
  • The shipping price of the product.



  • link
  • string
  • A link to the seller's Ebay profile page.



  • service
  • string
  • The service name description of the shipping.



  • ships_to
  • string
  • The text from the "ships to" section of the shipping information.



  • location
  • string
  • The location the product is shipped from.



  • delivery_estimate
  • string
  • The delivery time estimate for shipping the product to the location specified in the customer_location and/or customer_zipcode .

reviews

array

Reviews Object An array of Review objects, containing each of the Customer Reviews shown on the Individual Listing product page.

Note to see all reviews you should make a type=reviews request .

The Review object has the following properties:

  • id
  • string
  • The unique, Ebay-assigned, ID of the customer review. This can be used by your app to flag whether you have previously processed this review on a prior request.



  • title
  • string
  • The title of the review.



  • body
  • string
  • The body text of the review.



  • rating
  • number
  • The product rating given by the reviewer, out of 5.



  • helpful_votes
  • number
  • The number of helpful votes this review has received from other Ebay customers.



  • unhelpful_votes
  • number
  • The number of unhelpful votes this review has received from other Ebay customers.



  • seller_name
  • string
  • The name of the Ebay seller who sold the product this reviewer reviewed.



  • attributes
  • array
  • Attributes Array The attributes array contains details of the product attributes as shown underneath the product title on the customer reviews page.
    • 
      1. name
      2. string
      3. The name of the product attribute i.e. "Capacity".
    • 
      1. value
      2. string
      3. The value of the product attribute i.e. "128 GB".



Date Object The date object contains details about the date of the review.

  • raw
  • string
  • The raw date as retrieved from the Ebay page.



  • utc
  • string
  • The date of the review, parsed from the raw date, in ISO 8601 format. If Countdown API cannot parse the raw date then this property will be null.

Profile Object The profile object contains details of the profile of the reviewer.

  • name
  • string
  • The reviewer's profile name.



  • link
  • string
  • A link to the reviewer's profile page on the Ebay domain.

parts_compatibility

array

Parts Compatibility Array Determines whether Countdown returns the parts_compatibility property as part of the product request. The parts compatibility properties are typically shown in the descriptive section of the Ebay product listing page - for example, a compatibility table showing the vehicle a particular part is compatible with (screenshot shown below).

  • 

    Document image
    

Note: The parts_compatibility property is only shown when the include_parts_compatibility=true request parameter is set.

  • product
  • string
  • The name of the product that the current product is compatible with.



  • properties
  • array
  • An array of objects containing id , name and value properties describing the properties of the compatible product.


Unavailable / Redirected Products

Often times, when the specified epid is unavaialble Ebay will redirect the user to another, similar, listing. In these scenarios Countdown will return a response with the redirected=true property set, as-per the example below. The redirected EPID, and the link, are shown in the redirected_link and redirected_epid properties allowing you (should your use-case require it) to make a subsequent request for the redirected EPID.

Ebay Redirected Product Page
Ebay Redirected Product Page


An example of the JSON object returned from a redirected Product request is shown below:

JSON


Countdown API returns the following properties for Product requests that have been redirected:

Property

Type

Description

redirected

boolean

A boolean set to true when the requested EPID has resulted in Ebay redirecting to another, similar EPID due to the request EPID no longer being avaialble.

redirected_link

string

A URL to the product listing page of the EPID that has been redirected to.

redirected_epid

string

The EPID that has been redirected to.



Next Steps      Product Parameters

Updated 08 Aug 2024
Did this page help you?