You can upload custom recommendations directly into Blueshift as recommendation feeds. The recommendations must be in the form of a CSV file. The following types of feeds are supported.

  • User to Product: Recommendations for each user can be imported using one of the user identifiers and one or more product_ids from the catalog. For example, include personalized promotions.
  • Product to Product: Recommendations that go from one product to others. For example, people who view or buy a product can consider these other products.

Data Format

After you prepare a CSV file that contains the recommendations data, you can then import it to Blueshift by creating an import feed.

  • The data for User to Product recommendations must include one of the following customer identifiers: email or customer_id
  • If multiple products are included, they must be separated by a delimiter.

You can also click the Download Sample CSV link in an import task and review its format to understand the type of file required. 

Sample Data for User to Product recommendations

email product_ids ITEM_0000 | ITEM_1111 ITEM_222 | ITEM_333 | ITEM_5555

Sample Data for Product to Product recommendations:

source_product_id product_ids
ITEM_123 ITEM_234 , ITEM_345
ITEM_234 ITEM_123 , ITEM_345 , ITEM_456

Upload CSV file to an S3 bucket

You can either upload the CSV file from the UI or you can upload the CSV file to an S3 bucket. You can use the S3 bucket provided by Blueshift (using the default adapter Blueshift Import) or to your custom S3 bucket (using the Custom Import adapter).

If you are using the Blueshift Import option:

  • Add data files to the folder customers/<site-name>/import/recommendations/feeds/.
  • You can obtain the S3 credentials from the Account Settings > API Keys tab. The credentials are visible only to users with an Admin role.

If you are using the Custom Import option:

  • Ensure that your S3 bucket has a CORS configuration.
  • Provide your own S3 credentials and S3 file path. For example,
    bucket: bsft-customers

Create a recommendation feed

Complete the following steps to set up a recommendation feed:

  1. To import recommendation data, go to Recommendations and then go to the Feeds tab.


  2. Click +CONTENT FEED.


    • Add the Name for the feed.
    • Select the type of recommendation data as User to Product or Product to Product.
    • Add a Description.
    • Click OK.
  3. In the Import Form, select the Import Method as File Upload or S3 Upload.
  4. If you select File Upload, for Choose File, select the file to be uploaded.


    Sample data from the file is uploaded. Go to Step 11 to Map Attributes.

  5. If you select S3 Upload as the source, for the Adapter, select one of the following options:
    • Select Blueshift Import if you are using the S3 bucket provided by Blueshift. 
    • Select Custom Import to use your own S3 location.


  6. If you select Blueshift Import, specify the S3 Path where you upload the customers data files. For example, you can create a location on the S3 bucket called customers/<site-name>/import/recommendations/feeds/SummerCampaign and upload files to this path.
  7. If you select Custom import, provide the access credentials for the S3 bucket. For more information, see Working with Amazon S3 buckets in the AWS documentation.
    • Access Key: The Access Key ID that we use to get files that contain your customers' data from your S3 bucket. 
    • Secret Access Key: The Secret Access Key that we use to get the files from your S3 bucket.
      For more information on the Access Key ID and Secret Access Key, see Programmatic access on AWS documentation.
    • Bucket: Provide the URL to your S3 bucket where you store the files. 
    • AWS Region: Specify the AWS region where the S3 bucket resides. 
    • S3 Path: Specify the path on the S3 bucket where you upload the files with your customers' data.
  8. Add the Update Frequency. You can select from Only once, Weekly, Daily, or Hourly.
  9. Click advanced to specify the character encoding of the CSV file you upload. You can select Unicode (UTF-8), Unicode (UTF-16), or Western Europe (ISO-8859-1).
  10. Click Fetch Sample S3 File to fetch sample data from the file. 
  11. Map columns from the CSV file to standard Blueshift columns (email, customer_id and product_ids).


  12. Specify the Field Separator (delimiter) for your product item list.
  13. Click Import Recommendations.

    You can view the task status from the Feeds index page.

    You will receive an email notification when the recommendations are uploaded. The email includes information for both processed and failed records.

View Feed Tasks

To view Feed Tasks, go to Recommendations and then go to the Feeds tab. Click the feed to view details for the task.

The table provides details on the data that was processed when the task ran.

  • The status can be Processing, Processed, or Failed.
  • Information about Total records, Processed records, and Errored records is also shown.
  • You can Download the data that was processed in CSV format and View more details.

Note: If there are errors in processing the fetched data, the status is still set as ‘Processed’


Import errors and possible causes

It is possible that some records might not be imported due to errors. Here are a few errors that you may run into and the reasons why they might occur:

Firefly resource not found error=“{\“errors\“:[\“attribute_value_not_found\“]}”

An item in the product_ids list is not present in the catalog.

Firefly resource not found error=“{\“errors\“:[\“product_id_not_found\“]}”

The source_product_id itself is not the catalog.


Was this article helpful?
1 out of 1 found this helpful



Please sign in to leave a comment.