Find products

A product call is made by passing at least one keyword. The XML response is designed to provide as much detail as possible in a single call. The products matching the supplied keywords will be returned as well as matching price ranges, merchants, categories, brands, and deals.

A simple product call limited to the products in your catalog would be a call to return all products in XML (products.xml) with the word "ipod 16gb" (keywords=ipod+16gb) within your catalog. Use the "+" sign to combine multiple words into a single keyword call. The first parameter would be separated with an question mark "?" and the additional parameters an ampersand "&". This call would look like the following:

2.
Call parameters

Required request parameters

The specifies which API version you wish to call. v2 provides the ability to make price
comparison calls through the use of product groups.

API key

string

Unique key identifying your account

catalog_key

string

Unique key identifying catalog of merchants

Optional request parameters

Field

Value

Description

keywords

string

A list of keywords to search across your catalog merchants.keywords=ipod Is a basic search for products containing the keyword "ipod"keywords=ipod -case is a search for products containing the keyword "ipod" and NOT containing the keyword "case"

merchant_id

integer

A unique Rakuten PopShops merchant_id, limiting products to a single merchant

merchant_type_id

integer

A unique merchant_type_id limiting products to a single merchant_type.

category_id

integer

A Rakuten PopShops category ID, limiting products to a single merchant's category. Category ids are currently only returned in product query responses.

brand_id

integer

A Rakuten PopShops brand_id, limiting products to a single brand

price_min

decimal

10.00,19.95, etc

Price minimum product prices should not go below

price_max

decimal

10.00,19.95, etc.

Price maximum product prices should not exceed

product_sort

price_ascprice_desc

Featured (default), Lowest Price, Highest Price

product_limit

1-100

Number of products to display at a time. 100 maximum.

product_offset

integer

Number to offset the product results by. For example, to display page 11 with 10 products per page the product_limit should be set to 10 and product_offset should be 110. Note: You can pagination for up to 15,000 top relevant results on a query.

include_product_ids

boolean

1 or 0

.v2 Product id information will be included on product nodes. Defaults to 0.

product_id

integer

.v2 A unique id for an individual product. This will return a single product
which can be used for product detail pages, wishlists, etc.
Note: You can pass in multiple product ids by separating with commas. For example: product_id=1234,7890

include_product_groups

boolean

1 or 0

.v2 Product group information will be included on product nodes. Defaults to 0.

product_group_id

integer

.v2 A unique id for a group of similar products. This will return a set of products belonging to the same product group, which can be used for price comparisons. The 'keywords' parameter is required when passing a product_group_id.

include_deals

boolean

1 or 0

Available deals can also be included in the result set that match returned products and merchants.

large_image_url: A url for the largest sized image available for the product.

medium_image_url: A url for a medium sized image of the product.

small_image_url: A url for a small sized image of the product.

merchant_price: The price offered through the merchant. Usually corresponds to the lowest price.

retail_price: The listed retail price of the product.

.v2id: A unique id identifying a single product.

.v2product_group_id: A unique id identifying a group of similar products the product belongs to.

.v2product_group_product_count: The number of products in the product group.

.v2product_group_merchant_count: The number of merchants belonging to the product group.

.v2product_group_min_price: The lowest price available in the product group.

.v2product_group_max_price: The highest price available in the product group.

price_ranges

Contains price_ranges for products matching the query parameters.

price_range

Contains an individual price_range. Attributes:

max: The max dollar value in the range

min: The min dollar value in the range

product_count: The number of products within this price range.

merchants

Contains top merchants for products matching the query parameters. In many cases the
number of merchants matching the query is too many to bring back, so this will only
bring back the top 50 merchant matches by product count. You may encounter results
where you get a product on a page and there is no matching merchant in the merchants
node.

merchant

Contains an individual merchant. Attributes:

id: A unique id for the merchant. You can pass this in as a merchant_id to filter products to this specific merchant.

name: The name of the merchant.

product_count: The number of products matching the query for this specific merchant.

logo_url: If available a logo_url will be provided which is a url to small thumbnail of a logo for the merchant.

url: If available the url will be returned, which is a landing page for this merchant.

merchant_type_id: If the merchant belongs to a merchant_type, this will be the id for the merchant_type. This can be used to further filter products as a merchant_type_id parameter.

merchant_types

Contains top merchant_types for products matching the query parameters.

merchant_type

Contains an individual merchant_type. Attributes:

id: A unique id for the merchant_type. You can pass this in as a merchant_type_id to filter products to this specific merchant_type.

name: The name of the merchant_type.

product_count: The number of products matching the query for this specific merchant_type.

brands

Contains top brands for products matching the query parameters.

brand

Contains an individual brand. Attributes:

id: A unique id for the brand. You can pass this in as a brand_id to filter products to this specific merchant_type.

name: The name of the brand.

product_count: The number of products matching the query for this specific brand.

suggested_merchants

If the keywords match any merchant names, or have been tagged by Rakuten PopShops as belonging to a
specific merchant, this node will return any merchants that may be possible matches. This node
will have child merchant nodes with attributes available on normal merchant nodes.

deals

Contains deals available for products,merchants, and suggested merchants matching the query. Attributes:

restrictions: Global restrictions that apply to any deal returned.

deal

Contains an individual deal. Attributes:

name: The name of the deal.

description: A description of the deal.

url: The redirect url for the deal.

image_url: If an image is available for the deal, this will be a url for that image.

specific: This is a boolean (true/false) indicating whether the deal is specific to a product, or applies to all products from the merchant.

start_on: The start date the deal is valid.

end_on: The end date the deal is no longer valid.

code: Any associated code for the deal. This is a code that would need to be used to redeem the deal.

deal_type_ids: The deal_type id indicating what kind of deal this is.

restrictions: Any applicable restrictions unique to this deal or merchant.

merchant_id: A unique id for the merchant.

merchant_type_id: The id of the merchant_type the merchant of this deal belongs to.

4.
Price comparison

Available in v2 of the API is the ability to get back additional data about products which can be
used to build price comparison applications.

Price comparison product attributes

Additional attributes will be returned with a product if it belongs to a group of similar products
and you have passed in the 'include_product_groups=1' parameter on your product request.

This group of related products is identified within Rakuten PopShops with a product_group_id. These
attributes will be returned in addition to the normal product attributes.

Attribute

Value

Description

product_group_id

integer

A unique id identifying a group of similar products the product belongs to.

product_group_product_count

integer

The number of products in the product group.

product_group_merchant_count

integer

The number of merchants belonging to the product group.

product_group_min_price

decimal

10.00,19.95, etc

The lowest price available in the product group.

product_group_max_price

decimal

10.00,19.95, etc

The highest price available in the product group.

Example price comparison request

To retrieve products for a specific product group you make a normal product query, but add the product_group_id for the relevant product group. Here is an example call.
(Note: It may not work because of the specific merchants in your catalog)

Optional request parameters

.v2 Product group information will be included on product nodes. Defaults to 0.

include_deals

boolean

1 or 0

Available deals can also be included in the result set that match returned products and merchants.

url_subid

string

Custom subid/sid to be appended in any final affiliate product urls.

Response fields

Field

Description

search_results

Contains all of the query responses. Attributes:

product_id: product id passed in

products

Contains products matching the query parameters. Attributes:

total_count: Total number of products matching the query parameters

product_group_products

Contains products within a product's product group. This is only returned if the parameter include_product_groups=1 was passed in. This is helpful if you want to retrieve comparable products within a single call. Attributes:

total_count: Total number of products in the product group

product_group_id: Unique id identifying the product group

product

Contains an individual product. Attributes:

name: The name of the product

description: The description of the product

merchant_id: The merchant_id for the merchant the product belongs to.

large_image_url: A url for the largest sized image available for the product.

medium_image_url: A url for a medium sized image of the product.

small_image_url: A url for a small sized image of the product.

merchant_price: The price offered through the merchant. Usually corresponds to the lowest price.

retail_price: The listed retail price of the product.

.v2id: A unique id identifying a single product.

.v2product_group_id: A unique id identifying a group of similar products the product belongs to.

.v2product_group_product_count: The number of products in the product group.

.v2product_group_merchant_count: The number of merchants belonging to the product group.

.v2product_group_min_price: The lowest price available in the product group.

.v2product_group_max_price: The highest price available in the product group.

ONLY IN PRODUCT_ID CALLSactive: Indicates whether the product is still actively available

merchants

Contains top merchants for products matching the query parameters. In many cases the
number of merchants matching the query is too many to bring back, so this will only
bring back the top 50 merchant matches by product count. You may encounter results
where you get a product on a page and there is no matching merchant in the merchants
node.

merchant

Contains an individual merchant. Attributes:

id: A unique id for the merchant. You can pass this in as a merchant_id to filter products to this specific merchant.

name: The name of the merchant.

product_count: The number of products matching the query for this specific merchant.

logo_url: If available a logo_url will be provided which is a url to small thumbnail of a logo for the merchant.

url: If available the url will be returned, which is a landing page for this merchant.

merchant_type_id: If the merchant belongs to a merchant_type, this will be the id for the merchant_type. This can be used to further filter products as a merchant_type_id parameter.

merchant_types

Contains top merchant_types for products matching the query parameters.

merchant_type

Contains an individual merchant_type. Attributes:

id: A unique id for the merchant_type. You can pass this in as a merchant_type_id to filter products to this specific merchant_type.

name: The name of the merchant_type.

product_count: The number of products matching the query for this specific merchant_type.

brands

Contains top brands for products matching the query parameters.

brand

Contains an individual brand. Attributes:

id: A unique id for the brand. You can pass this in as a brand_id to filter products to this specific merchant_type.

name: The name of the brand.

product_count: The number of products matching the query for this specific brand.

deals

Contains deals available for products,merchants, and suggested merchants matching the query. Attributes:

restrictions: Global restrictions that apply to any deal returned.

deal

Contains an individual deal. Attributes:

name: The name of the deal.

description: A description of the deal.

url: The redirect url for the deal.

image_url: If an image is available for the deal, this will be a url for that image.

specific: This is a boolean (true/false) indicating whether the deal is specific to a product, or applies to all products from the merchant.

start_on: The start date the deal is valid.

end_on: The end date the deal is no longer valid.

code: Any associated code for the deal. This is a code that would need to be used to redeem the deal.

deal_type_ids: The deal_type id indicating what kind of deal this is.

restrictions: Any applicable restrictions unique to this deal or merchant.

merchant_id: A unique id for the merchant.

merchant_type_id: The id of the merchant_type the merchant of this deal belongs to.