Find coupons and deals

Request URL

Response Formats


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 deals to those for a specific catalog.

Optional request parameters

Parameter name Type Kind Allowed values Default value Description
end_on range filter The end on date a deal is still valid for. Pass in a single date for an exact match, or pass in a range of dates delimited with a dash '-'. The date format is YYYY/MO/DA .
end_on_max range filter The maximum end on date for a deal.
end_on_min range filter The minimum end on date for a deal.
deal_type selection filter The deal type ID a deal belongs to.
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 term or phrase you want to find in the deal description.
keyword_name query A term or phrase you want to find in the deal name.
merchant selection filter The merchant ID of the merchant a deal belongs to.
merchant_type selection filter The merchant type ID that a deal's merchant belongs to.
page item pagination 1-10 1 The page number of the results you want returned.
results_per_page item pagination 1-100 20 The number of deals 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.
site_wide item filter all,yes,no all Indicates whether or not a deal applies site wide on a merchant's site, as opposed to being for a specific product or specific category within the merchant's site.
sort_deal sort relevance, name_asc, name_desc, start_on_asc, start_on_desc, end_on_asc, end_on_desc, merchant_name_asc, merchant_name_desc relevance
start_on range filter The start on date a deal is valid for. Pass in a single date for an exact match, or pass in a range of dates delimited with a dash '-'. The date format is YYYY/MO/DA .
start_on_max range filter The maximum start on date for a deal.
start_on_min range filter The minimum start on date for a deal.
tracking_id view Optional custom tracking id to be passed along in affiliate links to the affiliate network.

Response results

Node Attribute Kind Data Type Description
deals Container for all individual deals.
count count integer The number of deals matching the query
deal An individual deal.
code display String If the deal happens to be a coupon, this is the coupon code for it.
deal_typerequired resource integer This is the deal_type ID of the deal type the deal belongs to. It is possible for this to be a comma delimited list of deal type ids, if the deal belongs to more than one.
description display string A merchant provided description of the deal
end_on display date The date the deal expires on.
idrequired primary_key integer The Rakuten PopShops assigned unique identifier for the deal.
image_url image_url string The URL to an image for the deal.
merchant resource integer The merchant ID of the merchant the deal belongs to.
namerequired display string The name of the deal.
restrictions display string A description of any related restrictions on the deal that may limit its ability to be redeemed.
site_wide display boolean Indicates whether or not the deal is applicable across a merchant's entire website, or limited to a specific product or category.
start_on display date The starting date a deal is valid on.
url redirect_url string A redirect url that links to the deal landing page by passing through the affiliate network and passing along any tracking information for you.

Sample response

<?xml version="1.0" encoding="UTF-8"?>
<response status="200" message="ok">
    <deals count="14287">
      <deal start_on="04/03/2009" site_wide="yes" end_on="01/01/2017" 
        code="popshop" merchant="1473" name="Save 5% off your order." 
        url="" deal_type="2,5"></deal>
      <deal start_on="01/03/2012" site_wide="yes" 
        description="$10 Off $125 Or More" end_on="01/01/2013" code="pocky10" 
        merchant="4282" name="$10 Off $125 Or More" id="289403"
        url="" deal_type="2,6"></deal>
    <filter type="selection" parameter="merchant" resource="merchant" name="merchant"></flter>
    <filter type="range" parameter="start_on" name="start_on">
        <value count="13331" min="10/31/2004" max="11/18/2012"></value>
    <filter type="range" parameter="end_on" name="end_on">
        <value count="1090" min="11/16/2012" max="11/19/2012"></value>
    <networks count="5">
      <network count="5714" name="Commission Junction" id="2"></network>
    <merchant_types count="49">
      <merchant_type count="1218" name="Home and Garden" id="33"></network>
    <merchants count="25">
      <merchant count="10" name="" id="6296" url=""></merchant>
    <countries count="4">
      <country count="14053" name="United States" id="1"></country>
    <deal_types count="16">
      <deal_type count="2620" name="Free Shipping" id="1"></deal_type>