Creating and managing catalogs

The Catalog management API, currently in public BETA, provides a simple way to integrate the creation and management of Rakuten PopShops catalogs into your applications.

The basic features provided are the ability to list, create, update, and delete catalogs. This is implemented using a few different approaches. You can choose how you want to interact with the API: http query parameters, XML over http, or JSON over http.

Note: All requests require the subdomain to be 'www' and that they are an SSL request.

Note: You can change the default response type you wish to receive by changing the extension of the action being taken. For example the following url: https://www.popshops.com/v2/[api_key]/catalogs/list.xml will return a list of catalogs formatted as xml. If you wish to receive a JSON response instead you would change it to https://www.popshops.com/v2/[api_key]/catalogs/list.js

Back to top

1. List catalogs

You can get a list of all catalogs you currently have. This call can also list all merchant information for merchants in the individual catalogs.

Request URL

[GET]   https://www.popshops.com/v2/[api_key]/catalogs/list.xml

Required parameters

Field Description
private_api_key This is an api_key that must be submitted on all calls to get information about catalogs. Do not expose the private_api_key publicly. You can find your private api key in your settings.

Optional parameters

Field Value Description
catalog_key string, XML, JSON This is one or more catalog api keys.
string - If including more than one, they must be separated by commas.
XML
JSON 
              {"catalogs":
                [
                  {"catalog_key": "XXXXXXXXXXXXXXXX"},
                  {"catalog_key": "XXXXXXXXXXXXXXXX"}
                ]
              }
include_merchants 1 If passed in the catalog nodes will contain a child node listing all merchants in the catalog.

Sample requests

List all catalogs:
https://www.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/catalogs/list.xml?private_api_key=bw0fhqjuksg9t7y3xjmu3l5l2

Filter for specific catalog:
https://www.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/catalogs/list.xml?private_api_key=bw0fhqjuksg9t7y3xjmu3l5l2&catalog_key=48qsligejm5qng6cv5waprcoq

Filter for specific catalog and list merchants:
https://www.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/catalogs/list.xml?private_api_key=bw0fhqjuksg9t7y3xjmu3l5l2&catalog_key=48qsligejm5qng6cv5waprcoq&include_merchants=1

Back to top

2. Create catalogs

Creating catalogs is fairly straight forward, and the only requirement is a unique name for the catalog.

Request URL

[POST] https://www.popshops.com/v2/[api_key]/catalogs/create.xml

Required parameters

Field Value Description
private_api_key string This is an api_key that must be submitted on all calls to get information about catalogs. Do not expose the private_api_key publicly. You can find your private api key in your "Settings" tab.
name string, XML, JSON This is a unique name for the catalog
XML
JSON 
                  {
                      "catalogs":
                      [
                        {"name": "XXXXXXXXXXXXXXXX"},
                        {"name": "XXXXXXXXXXXXXXXX"},
                      ]
                  }

Sample requests:

NOTE: All requests need to be an HTTP [POST].

Create catalog:

https://www.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/catalogs/create.xml?private_api_key={YOUR PRIVATE API KEY}&name={MY NEW CATALOG}

Back to top

3. Update catalogs

Currently updating a catalog consists of activating or de-activating merchants within the catalog.

Request URL

[POST] https://www.popshops.com/v2/[api_key]/catalogs/update.xml

Required parameters

Field Value Description
private_api_key string This is an api_key that must be submitted on all calls to get information about catalogs. Do not expose the private_api_key publicly. Your private_api_key can be found in your "Settings" tab.
catalog_key string, XML, JSON The catalog_key of the catalog to be updated. If you are passing information in XML or JSON format then use this parameter.
XML 

<?xml version="1.0" encoding="UTF-8"?>
<catalogs>
  <catalog catalog_key="XXXXXXXXXXXXXXXX">
    <merchants>
      <merchant id="XXXXX" active="1" />
      <merchant network_merchant_id="XXXXXXXXX" network_id="XX" active="1" />
    </merchants>
  </catalog>
</catalogs>
JSON 

{
  "catalogs": [
                {
                  "catalog_key": "XXXXXXXXXXXXXXXX", 
                  merchants: [
                              { id: XXXXX, active: 1},
                              { network_merchant_id: XXXXXXXXXX, network_id: XX, active: 1 }
                             ]
                }
              ]
}
merchant_id integer Only pass this paraemter if you are not passing XML or JSON. This is one or more Rakuten PopShops merchant_id's. If including more than one, they must be separated by commas.
network_merchant_id string Only pass this parameter if you are not passing XML or JSON.
If you prefer working with a merchant id provided through the network, you can use the "network_merchant_id" parameter instead of the "merchant_id" parameter.

Because we can't guarantee a network merchant id will be unique across all networks, this actually has to be a combination value of the Rakuten PopShops' network id and the network merchant id. These are combined using a dash '-' character like: {network_id}-{network_merchant_id}.

For example, if you wanted to add 'Things From Another World' (network_merchant_id=8908) from the ShareASale network (network_id = 1). By adding the two values together you get the following network_merchant_id: 1-8908.

You would pass in the following: network_merchant_id=1-8908
active 1 or 0 Only pass this parameter if you are not passing XML or JSON. This is an integer indicating the active state of the merchant_id provided. Valid values are 1 or 0.
Back to top

4. Sample Catalog List Requests

Activate a single merchant:
https://www.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/catalogs/update.xml?catalog_key=48qsligejm5qng6cv5waprcoq&private_api_key=[private_api_key]&merchant_id=352&active=1

Activate multiple merchants:
https://www.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/catalogs/update.xml?catalog_key=48qsligejm5qng6cv5waprcoq&private_api_key=[private_api_key]&merchant_id=352,515,314&active=1

Activate a single merchant using network merchant id:
https://www.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/catalogs/update.xml?catalog_key=48qsligejm5qng6cv5waprcoq&private_api_key=[private_api_key]&network_merchant_id=1-8908&active=1

Activate multiple merchants using merchant id AND network merchant id:
https://www.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/catalogs/update.xml?catalog_key=48qsligejm5qng6cv5waprcoq&private_api_key=[private_api_key]&merchant_id=352&network_merchant_id=1-8908&active=1

Deactivate multiple merchants:
https://www.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/catalogs/update.xml?catalog_key=48qsligejm5qng6cv5waprcoq&private_api_key=[private_api_key]&merchant_id=352,515,314&active=0

You can always confirm the current list of active merchants in a catalog:
http://www.popshops.com/v2/brgymtenmw5ea9unauesmh9nz/merchants.xml?catalog_key=48qsligejm5qng6cv5waprcoq

Support home

API v2