Updated December 2023.

Introduction

This document is your guide to implementing Rakuten Advertising Product Catalog data feeds. It provides you with information on how to automate the process of obtaining product information from your advertiser partners who are part of Rakuten Advertising and have subscribed to the Product Catalog program.

There are two levels of implementation for Product Catalog data feeds. First, you will need to be approved and set up for the technical implementation of the product data feeds, and then you will need to be approved by each of your participating advertiser partners to use their Product Catalog data feed on your website or blog. See Getting Started for more information.

Technical Requirements for Using Product Catalog

To automate the process of obtaining product information, you must be able to:

• Download files from an SFTP account.
• Process XML or pipe-delimited text files that contain the product information.

File Sections

The product files have three sections: header, product data, and trailer; click the + for more information on each section:

File Formats

Product Catalog files are available in two formats: pipe-delimited text and XML:

File Names

Product Catalog file names have three parts, each separated by an underscore: Advertiser ID, Publisher Channel ID, and File Type.

1. The Advertiser ID or MID is a unique ID that Rakuten Advertising Affiliate Network uses to identify the advertiser. This is always numeric.
2. The Publisher Channel ID or SID is a unique ID that Rakuten Advertising Affiliate Network uses to identify the Publisher Channel. This is always numeric.
3. The file type “mp” defines that the file is a Product Catalog file.

The file name extensions specify what type of Product Catalog file it is. The pipe-delimited file has a .txt extension and the XML-formatted file has an .xml extension. The files are all compressed, so there is .gz after the file type extension.

Example: 2385_112_mp.txt.gz, where:

• 2385 is the Advertiser Program ID.
• 112 is the Publisher Channel ID.
• mp indicates that it is a Product Catalog file.
• .txt indicates that this is a pipe-delimited Product Catalog file.

File Types

The Rakuten Advertising Product Catalog feature allows advertisers to upload their product information to us. We process the uploaded information and create a corresponding publisher tracking URL for each product and make the product information available to publishers via SFTP. You have several choices of file types you can download for each advertiser; click the + to learn more about each file type:

Delta Files

Delta files allow you to download smaller files that contain only product updates, including new, changed, and deleted product records. This can be useful for updating feeds for advertisers with particularly large product catalogs. The type of change made is reflected in an additional field called Modification. In pipe-delimited files, this is the last field for each product record. In XML files, this is denoted by the <modification> tag. See the Modification field in Appendix A for supported values.

The file contains all changes that were made when the advertiser’s last feed was processed. Advertisers can process feeds multiple times a day, so it is recommended that you check the server often for updates, referring to the timestamp on the file to determine if changes have been made since you last pulled the file. Additionally, it is recommended that you pull a full file on a regular basis to ensure that you have the complete Product Catalog.

The delta file name is the same as the one used to download the full Product Catalog file, except that it has the word delta appended to it.

Examples:

• .txt file: 2385_112_mp_delta.txt.gz
• .xml file: 2385_112_mp_delta.xml.gz

The header for the Delta file is the same as the one for the full file and includes MID, Advertiser Name, and Time Stamp in the format shown in Product Catalog File Sections.

Category Files

Product Catalog by Category is a feature that allows you to download files for specific advertiser product categories instead of downloading the full product file. This means that if you only need products in the electronics product category, you can download the feed for just this category.

For each advertiser who has approved you for access to their Product Catalog feed, you will see a folder. The folder name will be the MID of the advertiser. The folder will contain two types of files: Product Category List File, and Category-Specific Product Catalog File; click the + for more information on each file:

Global and Additional Files

Rakuten Advertising permits advertisers to submit multiple files per account. If an advertiser chooses to make more than one Product Catalog file available, you will find these files nested under either a “GLOBAL” folder or an “ADDITIONAL” folder in the root directory of your SFTP account. “Global” files contain products in a different language and/or currency than the main feed file. “Additional” files have the same language and currency as the main feed file. Click the + for information on downloading Global or Additional files:

root

GLOBAL (folder)

FR-FR_EUR (folder – language-locale_currency)

12345 (folder – the number here is the Advertiser ID, or MID)

12345_678_mp_FR-FR_EUR.txt.gz

12345_678_mp_delta_FR-FR_EUR.txt.gz

FR-CA_CAD (folder – language-locale_currency)

12345 (folder)

12345_678_mp_FR-CA_CAD.txt.gz

12345_678_mp_delta_FR-CA_CAD.txt.gz

root

ADDITIONAL (folder)

12345 (folder – the number here is the Advertiser ID, or MID)

2017Summer (folder – name of the Additional file, as specified by the Advertiser)

12345_678_mp_2017Summer.txt.gz

12345_678_mp_delta_2017Summer.txt.gz

Back2School (folder – name of the Additional file, as specified by the Advertiser)

12345_678_mp_Back2School.txt.gz

12345_678_mp_delta_Back2school.txt.gz

Downloading Product Catalog Files

You can download the Product Catalog file from your account using any SFTP client software. See Getting Started to request enablement.

Example: get 2385_112_mp.txt.gz

Product files are generated dynamically at the time of retrieval. This ensures that all publishers receive the most up-to-date product information when they retrieve advertisers’ Product Catalog files. The timeliness of the product information depends on the frequency with which advertisers update the information in their Product Catalog database.

Getting Started

All Product Catalog publishers must first register to become a member of Rakuten Affiliate. If your company has yet to do so, sign up by going to https://rakutenadvertising.com/ and clicking Become a Publisher. Once registered, you will receive an email with registration approval and your new publisher account information, along with your Site ID.

You will then need to follow Step 1 to obtain FTP access and Step 2 to obtain advertiser approval to use their Product Catalog feeds, as outlined below.

Step 1: Technical Set Up Process

SFTP Set Up

The Product Catalog feed is available to you via SFTP. The Rakuten Affiliate SFTP server hostname is aftp.linksynergy.com.

To get started, contact Customer Support with your Rakuten Affiliate username and site ID (SID). When you submit your application for Product Catalog, these steps are performed:

• We establish a unique SFTP account on our servers from which you can download files.
• A username and password are assigned to the SFTP account.

Within one business day, a Customer Support representative will respond to your request with your username, password, and the URL of your SFTP account.

SFTP Access

You can access your SFTP account using any SFTP client. You can also automate the process of downloading the file or do it manually. You should set the transfer mode to binary before you start downloading files, as the files are stored in a compressed format. Using ASCII mode will corrupt the data in the file and render it useless. If you are using a script to automate the process of downloading the files, ensure that you do not open more than five connections to the SFTP server at one time.

Please note:

• Always use passive connections when connected to aftp.linksynergy.com with plain FTP.
• Always set mode to binary before downloading files with plain FTP.
• No more than five concurrent connections are allowed per publisher SFTP account.
• File sizes shown are estimates. Actual file sizes will vary. Therefore, you are advised to NOT use file size as a check to ensure successful downloads. Downloads should be considered successful if the file extracts correctly and ends with a trailer record indicating the number of products in the file.
• If you are using a script to retrieve the files, Wget is preferred over cURL. If using cURL, you must use the --ignore-content-length option.
• While plain FTP is currently supported, it is strongly recommended that you use SFTP instead. Support for plain FTP will be deprecated in the future.

SFTP Account Contents

In the root directory of your SFTP account, you will see files and a folder for each advertiser who has approved you for access to their Product Catalog feed. You may also see folders titled “GLOBAL” and “ADDITIONAL” if any of your advertiser partners have more than one product feed.

The files in the root directory are your Product Catalog files and the numbered folders contain files that provide you with product data for individual product categories. The folder name corresponds to the MID of the advertiser and the files are available in two formats: pipe-delimited text and XML.

You can select the format you prefer in your Publisher Dashboard by following these steps:

1. Go to Links in the navigation header and click Product Feeds.
2. Scroll down to Preferred feed format to make your selection:

   Click on the image for a larger version.

If you do not select a format, your SFTP account will contain two files and a folder for each advertiser that has approved you for access to their Product Catalog feed.

Step 2: Advertiser Product Catalog Approval Process

Once you have completed the technical setup of Product Catalog, you will need to request access from the participating advertisers with whom you are already partnered.

To view a list your advertiser partners who offer Product Catalog in your Publisher Dashboard, go to Links in the navigation header and click Product Feeds. Scroll down to view the list and search for advertisers by name. From there, you can apply for access, remove yourself from access, and view the status of your application:

Click on the image for a larger version.

You can automatically request Product Catalog approval when you apply to a new participating advertiser’s program with our Auto enrollment option. You can turn Auto enrollment on or off in the Feed Settings section of the Product Feeds page:

Click on the image for a larger version.

Common Questions

My script only downloads the files when the file date changes. Will this work with Product Catalog?

Yes, you should be able to use the date stamp of the file in the directory, which indicates the creation time in UTC, to see what has been changed and pull only the newest items.

Why do I have multiple advertiser files in my account?

You have the choice of a pipe-delimited text file and an XML-formatted file. You can select your preferred format in your Publisher Dashboard, as outlined in SFTP Account Contents above. If you do not select a format, your SFTP account will contain .txt and .xml versions of each file type.

What are the folders that I see in my SFTP account?

The folders in your SFTP account are for each advertiser that you are eligible to get Product Catalog files from. The folders contain the category-specific Product Catalog files for the advertisers.

Do I need to be approved by each advertiser for use of their Product Catalog product data feed?

Yes, there are two levels of approval for Product Catalog. First you receive technical approval, then you need advertiser approval. You need to request Product Catalog approval when you apply to a new advertiser program, or request it separately from existing advertiser partners, as detailed in Step 2 above.

What should I do if an advertiser’s Product Catalog data is stale?

It is best to let the advertiser know directly. You can find an advertiser’s contact information in your Publisher Dashboard: go to Advertisers in the navigation header, click My Advertisers, then click on the relevant advertiser to access their details page.

If you are not sure if what you are concerned about is a stale data issue, contact Customer Support.

Appendix A: Product Catalog File Field Definitions

Consult Appendix A for field definitions.

Appendix B: Attribute File Class Definitions

Consult Appendix B for attribute file class definitions.

Appendix C: XML Formatting Standards

Consult Appendix C for XML formatting standards.

Appendix D: Sample Records

Consult Appendix D for sample records of a pipe-delimited and an XML file.