Creating and managing catalogs

The Catalog Management APIs provide a simple way to integrate the creation and management of Rakuten PopShops catalogs into your applications.

The APIs permit users to list, to create, and to update v3 catalogs.

Note: All requests must be be sent over HTTPS.

List API

Request URL

GET http://api.popshops.com/v3/catalogs.xml
GET http://api.popshops.com/v3/catalogs.json

Response Formats

XML, JSON

Required request parameters

Parameter name Type Kind Allowed values Default value Description
account account Your v3 API account key. You can find this on your account page.

Response results

The response simply presents a list of catalogs associated with your account.

Node Attribute Kind Data Type Description
catalogs The container for all individual catalogs.
count count integer A count of all catalogs associated with the account
catalog An individual catalog.
key resource string The catalog's v3 API key.
name resource string The catalog's name.

Sample response

http://popshops.com/v3/catalogs.xml?account=d1lg0my9c6y3j5iv5vkc6ayrd

<?xml version="1.0" encoding="UTF-8"?>
<response status="200" message="ok">
   <parameters>
      <parameter name="account" kind="account" value="d1lg0my9c6y3j5iv5vkc6ayrd" />
   </parameters>
   <results>
      <catalogs count="4">
         <catalog key="dp4rtmme6tbhugpv6i59yiqmr" name="Megabuzz" />
         <catalog key="7oagwptizb7lq07mb87tzny8w" name="Revenge of the Son of HewliPicklu and Friends" />
         <catalog key="81g5bfjyisk0c2yf1861yr507" name="UK" />
         <catalog key="3wpx2811381j2o5kva6lf4f0s" name="US" />
      </catalogs>
   </results>
</response>

Create API

Request URL

POST http://api.popshops.com/v3/catalogs/create.xml
POST http://api.popshops.com/v3/catalogs/create.json

Response Formats

XML, JSON

Required request parameters

Parameter name Type Kind Allowed values Default value Description
account account Your v3 API account key. You can find this on your account page.
private_api_key account Your private v3 API account key. You can find this on your account page.
name item value The name of the catalog you would like to create.

Optional request parameters

Parameter name Type Kind Allowed values Default value Description
merchant selection value The set of merchant ids you would like to include in or exclude (see the exclude_merchants parameter) from your catalog.
Note: either the merchant and/or network_merchant parameter must be provided.
Note: merchant ids prefixed with a dash (-) will be deactivated upon catalog creation.
network_merchant selection value The set of affiliate network merchant ids you would like to include in or exclude (see the exclude_merchants parameter) from your catalog.
Note: either the merchant and/or network_merchant parameter must be provided.
Note: network merchant ids must be prefixed with the network org id associated with the desired affiliate network followed by a colon (i.e. <NETWORK_ORG_ID>:<NETWORK_MERCHANT_ID>). Please refer to the network lookup API if you need to consult a lookup reference.
Note: network merchant ids prefixed with a dash (-) will be deactivated upon catalog creation.
exclude_merchants control If true then start with all affiliated merchants (i.e. the default catalog) and exclude the set of passed-in merchant ids.

Response results

The response presents the newly-created catalog if successfully created.

Node Attribute Kind Data Type Description
catalogs The container for all individual catalogs.
count count integer A count of all catalogs associated with the account
catalog An individual catalog.
key resource string The catalog's v3 API key.
name resource string The catalog's name.

Sample response


<?xml version="1.0" encoding="UTF-8"?>
<response status="200" message="ok">
<parameters>
    <parameter name="account" kind="account" value="d1lg0my9c6y3j5iv5vkc6ayrd"/>
    <parameter name="name" type="item" kind="value" value="My new, shiny catalog!"/>
    <parameter name="exclude_merchants" kind="control" value="false"/>
    <parameter name="merchant" type="selection" kind="filter" value="M1,M2,M3,...,MN"/>
</parameters>
<results>
    <catalogs count="1">
        <catalog name="My new, shiny catalog!" key="EZ3a7PSevOxV5nBVLz3vERdr8F" /> <!-- api_key of successfully-created catalog -->
    </catalogs>
</results>

Update API

Request URL

POST http://api.popshops.com/v3/catalogs/update.xml
POST http://api.popshops.com/v3/catalogs/update.json

Response Formats

XML, JSON

Required request parameters

Parameter name Type Kind Allowed values Default value Description
account account Your v3 API account key. You can find this on your account page.
private_api_key account Your private v3 API account key. You can find this on your account page.
catalog item The v3 API key of the catalog you would like to update.

Optional request parameters

Parameter name Type Kind Allowed values Default value Description
merchant selection value The set of merchant ids you would like to include in or exclude (see the exclude_merchants parameter) from your catalog.
Note: either the merchant and/or network_merchant parameter must be provided.
Note: merchant ids prefixed with a dash (-) will be deactivated upon catalog update.
network_merchant selection value The set of affiliate network merchant ids you would like to include in or exclude (see the exclude_merchants parameter) from your catalog.
Note: either the merchant and/or network_merchant parameter must be provided.
Note: network merchant ids must be prefixed with the network org id associated with the desired affiliate network followed by a colon (i.e. <NETWORK_ORG_ID>:<NETWORK_MERCHANT_ID>). Please refer to the network lookup API if you need to consult a lookup reference.
Note: network merchant ids prefixed with a dash (-) will be deactivated upon catalog update.
exclude_merchants control If true then start with all affiliated merchants (i.e. the default catalog) and exclude the set of passed-in merchant ids.

Response results

The response presents the catalog if successfully updated.

Node Attribute Kind Data Type Description
catalogs The container for all individual catalogs.
count count integer A count of all catalogs associated with the account
catalog An individual catalog.
key resource string The catalog's v3 API key.
name resource string The catalog's name.

Sample response


<?xml version="1.0" encoding="UTF-8"?>
<response status="200" message="ok">
   <parameters>
      <parameter name="merchant" value="M1,M2,...,MN" />
      <parameter name="catalog" kind="catalog" value="vmnpjliigbt37cxo6y3yekmd8" />
      <parameter name="account" kind="account" value="d1lg0my9c6y3j5iv5vkc6ayrd" />
   </parameters>
   <results>
      <catalogs count="1">
         <catalog key="vmfhpjliigbt37cxo6y3yekmd8" name="test_catalog55" />
      </catalogs>
   </results>
</response>
Support home

API v3