Find products

Product calls are used to get all information related to products, and the specific merchant offers for those products. One thing to note is that only offers will have affiliate links associated with them, the product itself will not have an affiliate URL. Therefore products with multiple offers will require an additional API call using the "product' parameter listed below. Our product numbers use a 64bit integer.

Request URL

http://api.popshops.com/v3/products.xml
http://api.popshops.com/v3/products.json

Response Formats

XML, JSON

Required request parameters

Parameter name Type Kind Allowed values Default value Description
account account Your API account key. You can find this on your API keys account page.
catalog item A catalog key to limit the products to those for a specific catalog.

Optional request parameters

Parameter name Type Kind Allowed values Default value Description
brand query The brand ID the product offers should belong to. Limited to brand IDs as provided by the merchants.
category item The Rakuten PopShops category a product belongs to.
include_discounts control This will force the response to return the top discounted offer for each product as part of the results.
keyword query Positive Keyword: A keyword or phrase you want to find in the product name or description. A specific phrase will need double quotes "keyword phrase" or it will return result for both individual words.
Negative Keyword: A singular keyword you do not want to find in product name or description. These keywords are prefixed with a dash (-). Ex: keyword=ipod –case will bring up products containing the keyword ‘ipod’ but not the keyword ‘case’.
keyword_description query A keyword or phrase you want to find specifically in the product description
keyword_brand query A term you want to search against a product's brand, such as "lenovo" or "samsung".
keyword_ean query A term you want to search against a product's EAN.
keyword_identifier premium query A term you want to search against product EAN, ISBN, MPN, UPC
keyword_isbn query A term you want to search against product ISBNs
keyword_mpn query A term you want to search against product MPNs
keyword_name query A keyword or phrase you want to find specifically in the product name
keyword_person query A term you want to search against product author or artist
keyword_upc query A term you want to search against product UPCs
keyword_isbn query A term you want to search against product ISBNs
keyword_sku premium query A term you want to search against Merchant offer SKU
merchant selection filter The merchant ID of the merchant product offers should belong to. Could be a comma delimited list of multiple merchant IDs.
merchant_type selection filter The merchant type ID of the merchant product offers should belong to. Could be a comma delimited list of multiple merchant type IDs.
page item pagination 1-10 1 The page number of results to return. This parameter will return up to a total of 1000 products. Ten pages with 100 product is the max results.
percent_off range filter The exact percent off you want the offer merchant prices vs. retail prices. You can also use this as shorthand for percent_off_min and percent_off_max by passing in both values delimited with a '-'. This is an example of requesting products with offers with at least a 5% off price to a maximum of 10% off: percent_off=5-10. You will also want to include '&include_discounts=true' in this call.
percent_off_max specific percent max filter The maximum percent off you want the offer merchant prices vs. retail prices. You will also want to include '&include_discounts=true" in this call.
percent_off_min specific percent min filter The minimum percent off you want the offer merchant prices vs. retail prices. You will also want to include '&include_discounts=true" in this call.
price range filter The exact price you want the offer merchant prices. You can also use this as shorthand for price_min and price_max by passing in both values delimited with a '-'. This is an example of requesting products with offers with at least a $5 price to a maximum of $10 off: price=5-10
price_max range filter The maximum price you want the offer merchant prices. Please use whole dollar amounts only.
price_min range filter The minimum price you want the offer merchant prices. Please use whole dollar amounts only.
product selection The product ID of the exact product you want returned. Necessary to get all offer URLs from multiple product offers. Could be a comma delimited list of multiple product IDs.
product_spec premium view true,false false Indicates whether or not to include the product specification in the response. This will include an attributes node under the product node listing available attributes for the product. Offers will not be included in the results
include_identifiers premium view true,false false Indicates whether or not to include the product identifiers in the response. This will include an attributes node under the product node listing available identifiers for the product. Offers will be included in the results
results_per_page item pagination 1-100 20 The number of products to return in every response.
session session This is zipped up information we use to determine any state of previous requests. This allows us to build up more relevant filter values in the current response in order to get back to previous filtered states. You do NOT to generate the session value. We will provide the session value in the parameters block being returned. You just need to pass it forward for any additional calls you make.
sort_product sort name_desc, name_asc, price_desc, price_asc, percent_off_desc, percent_off_asc, cat_desc, cat_asc relevance
tracking_id view Optional custom tracking id to be passed along in affiliate links to the affiliate network. (Please note, there is a 20 character limit for tracking ids.)

Response results

By default the response only brings back products. There are two cases where you will get actual offer information back.

  1. The product only has a single offer. In this instance the offer will automatically be brought back.
  2. You pass in a 'product' parameter. This is the case where you are requesting information about a specific product or products, and so all offer information for each product is returned.
Node Attribute Kind Data Type Description
products The container for all individual products.
count count integer A count of all products matching the query.
product An individual product.
brand resource integer The id of the brand a product belongs to.
category resource integer The id of the category a product belongs to.
description display string A description of the product.
idrequired primary_key integer A unique identifier assigned by Rakuten PopShops for a product.
image_url_large image_url string A URL for a large sized image of the product.
image_url_medium image_url string A URL for a medium sized image of the product.
image_url_small image_url string A URL for a small sized image of the product
namerequired display string The name of the product.
offer_count count integer A count of the number of merchant offers available for the product.
price_max price float The maximum price of all merchant offers for the product.
price_min price float The minimum price of all merchant offers for the product.
offers Contains all offers for a given product
offer An individual offer for a product.
condition premium display string The condition of the offer, such as refurbished or new.
currency_iso display string The currency ISO code for the offer.
currency_symbol display string The HTML entity for the currency symbol of the offer.
description display string The merchant provided description of the product offer.
estimated_shipping premium price float The merchant provided estimated shipping of the product offer.
estimated_price_total premium price float The total calculated price of an offer that takes into consideration any estimated sales tax or estimated shipping.
idrequired primary_key integer This is the unique identifier assigned by Rakuten PopShops for the merchant offer.
image_url_large image_url string The merchant provided large sized image URL.
image_url_medium image_url string The merchant provided medium sized image URL.
image_url_small image_url string The merchant provided small sized image URL.
merchant resource integer The merchant ID of the merchant the offer belongs to.
namerequired display string The merchant provided name of the product offer.
percent_off percentage float The calculated percent off from the merchant provided price, and the merchant provided retail price.
price_merchant price float The merchant provided price they are selling the product offer for.
price_retail price float The merchant provided retail price to compare against the price they are offering the product at.
sku premium display string The SKU (stock keep unit) identifier assigned by the merchant for the product offer.
url redirect_url string A redirect url that will go through the affiliate network and pass along your tracking information to get to the final merchant product offer landing page.
attributes premium Contains all attributes for a product. This is only returned if you pass in 'product_spec=true' in your api call.
attribute premium An individual attribute for a product.
namerequired display string The name describing what type of attribute this is for the product. Examples of this are: mpn, upc
value display string The actual value of the attribute for the product.

Sample response


<?xml version="1.0" encoding="UTF-8"?>
<response status="200" message="ok"...>
  <parameters>...</parameters>
  <results>
    <products count="1535">
      <product brand="37254" offer_count="10" category="32277" image_url_large="http://www.popshops.com/img/public/o/0/2/352/18-3.jpg" price_min="149.99" 
        description="Logitech Squeezebox Radio (BLACK) brings a world of musicfree Internet radio subscription services or your personal digital music collection to any space in your home over your WiFi network." 
        image_url_medium="http://www.popshops.com/img/public/o/0/2/352/18-2.jpg" 
        price_max="214.54" name="Logitech Inc 930000101 Squeezebox Radio Black" 
        image_url_small="http://www.popshops.com/img/public/o/0/2/352/18-1.jpg" id="405966"></product>
    </products>
    <deals count="25">
      <deal start_on="05/06/2010" site_wide="no" end_on="01/01/2017" merchant="5653" 
        description="PROMO: Dented Box and Refurbished Items From Logitech" 
        image_url="http://www.ftjcfx.com/image-2133188-10762343" deal_type="4" 
        name="Save big with Dented Box products have cosmetic damage to the packaging, but product is new and fully warranted." id="209974" 
        url="http://r.popshops.com/r/V1dKVzJJRmlvM241ZnhFTitubEk5by9NblF6aDErd3NDNUNLR25HSmFsRjlPTEJKS25lVm16bXNnTnlBCm0yQ2wK"></deal>
      ...
    </deals>
  </results>
  <resources>
    <merchants count="25">
      <merchant logo_url="http://www.popshops.com/img/public/l/0/0/0/230-1.jpg" 
        count="268" name="Newegg.com" id="230"
        url="http://r.popshops.com/r/V1dKVzJJRmlvM241ZnhFTitubEk5bnhlTEMwbnprN1k1dEQxRDN6cjlUSkp2eVpzY2lha2d3OG1nUWxTClBzS2QK"></merchant>
      ....
    </merchants>
    <brands count="25">...</brands>
    <deal_types count="6">...</deal_types>
    <categories>
      <context>
        <category order="0" name="All" id="1"></category>
      </context>
      <matches>
        <category count="2" leaf="true" name="AM / FM &amp; Clock Radios" id="32280"></category>
        ...
      </matches>
    </categories>
  </resources>
  <filters>
    <filter type="selection" resource="merchant" name="merchant" parameter="merchant"></filter>
    <filter type="range" name="price" parameter="price">
      <values>
        <value count="1475" min="0" max="360"></value>
        ...
      </values>
    </filter>
    ...
  </filters>
</response>

{
   "resources":
   {
       "deal_types":
       {
           "count": 6,
           "deal_type":
           [
               {
                   "count": "1",
                   "name": "Sale/Clearance",
                   "id": "4"
               }
               ...
           ]
       },
       "brands":
       {
           "brand":
           [
               {
                   "count": "16",
                   "name": "Franklin Sports",
                   "id": "29727"
               },
               ...
           ],
           "count": 25
       },
       "categories":
       {
           "context":
           {
               "category":
               [
                   {
                       "order": "0",
                       "name": "All",
                       "id": "1"
                   }
               ]
           },
           "matches":
           {
               "category":
               [
                   {
                       "count": "2",
                       "leaf": "true",
                       "name": "AM / FM & Clock Radios",
                       "id": "32280"
                   },
                   ...
               ]
           }
       },
       "merchants":
       {
           "count": 25,
           "merchant":
           [
               {
                   "logo_url": "http://www.popshops.com/img/public/l/0/0/0/230-1.jpg",
                   "count": "268",
                   "name": "Newegg.com",
                   "id": "230",
                   "url": "http://r.popshops.com/r/TE1lK0VaWXRlNUt6RURHajhJMWFySnk0NWlYMFhjNUFhbS9TU2VtVHRXS0pKeXJaV0hpZU11T3ZENWxYCkNwS20K"
               },
               ...
           ]
       }
   },
   "filters":
   {
       "filter":
       [
           {
               "type": "selection",
               "resource": "merchant",
               "name": "merchant",
               "parameter": "merchant"
           },
           {
               "type": "selection",
               "resource": "brand",
               "name": "brand",
               "parameter": "brand"
           },
           ...
           {
               "type": "item",
               "resource": "category",
               "name": "category",
               "parameter": "category"
           }
       ]
   },
   "results":
   {
       "products":
       {
           "count": 1535,
           "product":
           [
               {
                   "brand": "37254",
                   "offer_count": "10",
                   "category": "32277",
                   "image_url_large": "http://www.popshops.com/img/public/o/0/2/352/18-3.jpg",
                   "price_min": "149.99",
                   "description": "Logitech Squeezebox Radio (BLACK) brings a world of musicfree Internet radio subscription services or your personal digital music collection to any space in your home over your WiFi network.",
                   "image_url_medium": "http://www.popshops.com/img/public/o/0/2/352/18-2.jpg",
                   "price_max": "214.54",
                   "name": "Logitech Inc 930000101 Squeezebox Radio Black",
                   "image_url_small": "http://www.popshops.com/img/public/o/0/2/352/18-1.jpg",
                   "id": "405966"
               },
               {
                   "brand": "37254",
                   "offer_count": "16",
                   "category": "32279",
                   "image_url_large": "http://www.capitolsupply.com/ImageServer.ashx?t=product&h=200&w=200&imageid=CS12935298",
                   "price_min": "79.99",
                   "description": "Enjoy crystal-clear calls and video chats and listen to up to 10 hours of music per charge with this Logitech 984-000204 Bluetooth-enabled boombox that features a specially designed acoustic chamber that delivers great sound with enhanced bass.",
                   "price_max": "119.37",
                   "name": "Logitech - Bluetooth-Enabled Boombox for Apple? iPod? and Most MP3 Players",
                   "id": "18725796"
               },
               {
                   "brand": "37254",
                   "offer_count": "3",
                   "category": "32275",
                   "image_url_large": "http://www.restockit.com/images/Product/medium/930000090.jpg",
                   "price_min": "309.42",
                   "description": "Logitech Squeezebox Touch. The color touch-screen Wi-Fi music player that lets you discover a world of music - all through your stereo!",
                   "price_max": "365.34",
                   "name": "Logitech Squeezebox Touch",
                   "id": "1334248"
               },
               ...
           ]
       },
       "deals":
       {
           "count": 25,
           "deal":
           [
               {
                   "start_on": "05/06/2010",
                   "site_wide": "no",
                   "end_on": "01/01/2017",
                   "merchant": "5653",
                   "description": "PROMO: Dented Box and Refurbished Items From Logitech",
                   "image_url": "http://www.ftjcfx.com/image-2133188-10762343",
                   "deal_type": "4",
                   "name": "Save big with Dented Box products have cosmetic damage to the packaging, but product is new and fully warranted.",
                   "id": "209974",
                   "url": "http://r.popshops.com/r/TE1lK0VaWXRlNUt6RURHajhJMWFySklleUFEc1JhQzNWNEoxeWJzSFNjcjNhL0FTd3pnZFIyeXlLUy83CkF3QkwK"
               },
               ...
           ]
       }
   },
   "status": 200,
   "parameters":
   [
       ...
   ],
   "message": "ok",
}