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
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
<?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
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
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>