Send order data via SFTP server

If you do not send order data automatically through BV Pixel, you can send it manually by uploading it to the Bazaarovoice's SFTP server. The supported file formats are XML and TXT. This manual method can be useful for importing historical order data or for sending review requests to email addresses and phone numbers collected during in-store purchases.

Bazaarvoice recommends using an XML feed because TXT files have the following limitations:

• Email templates by deployment zone are not supported for text feeds. Only email templates from the implementation deployed to Main Site can be used.
• If data is not available for a column in the feed, leave the column blank (keep the tab delimiter).
• Product information—external ID, product name, product image, and price—can be repeated if an order contains several products (refer to the example below).
• Transaction date must be formatted as follows: YYYY-MM-DD hh:mm:ss.
• Do not include the currency symbol, such as $, with the product price.
• When you name the file, make sure the extension is lowercase (for example, filename.txt)

Caution: Ensure order data files are being actively sent to Bazaarvoice—otherwise Bazaarvoice will stop sending RREs.

Setup overview

To send order data via SFTP, follow these steps:

1. Create an order data file: XML file (recommended) or TXT file
2. Validate the file before uploading it to the SFTP server
3. Upload the file to the SFTP server

Create XML file

You can create an XML file that contains order data (transactional and non-transactional) about consumers who have purchased products and services on your site or at a physical location. Bazaarvoice uses this file to send review requests to your consumers. You must generate this file and upload it to Bazaarvoice by 12 AM Central Time (CST: UTC-6 or CDT: UTC-5) every day.

The XML schema for your order data file resides at the following location: https://www.bazaarvoice.com/xs/PRR/PostPurchaseFeed/<version>

where <version> is the appropriate Bazaarvoice release number. For example, the XML schema for the order data file that is associated with version 14.8 resides at the following location: https://www.bazaarvoice.com/xs/PRR/PostPurchaseFeed/14.8

Mandatory technical requirements

• Ensure that the first line of your feed adheres to the following format:

  <?xml version="1.0" encoding="utf-8"?>  
  

• Ensure that the <Feed> element has the following attribute:

  xmlns="http://www.bazaarvoice.com/xs/PRR/PostPurchaseFeed/14.8"  
  

• Ensure the product name in the <ExternalId> field within <Product> element matches the name provided in the product catalog feed. The field is case-sensitive and must align with the exact casing used in the product catalog feed file. 
• The standard character-encoding scheme, such as UTF-8 or Windows-1252, must match the scheme that you use for any special characters in the feed.

• When you name the XML file, be aware that the filename must begin with "bv_ppe_tag_feed" and extension is lowercase (for example, filename.xml). You can also include your company name and the date, as in the following example:

  bv_ppe_tag_feed_YourSiteName_20150928.xml


  Each file you upload must have a unique name to avoid overwriting the previous file. If you intend to upload multiple feeds a day, add a timestamp to the filename. For example:

  • bv_ppe_tag_feed_YourSiteName_20150928-1030.xml
  • bv_ppe_tag_feed_YourSiteName_20150928-1645.xml
• If you publish implementations to multiple deployment zones, be sure to include the <DeploymentZone> element in the feed to indicate the implementation's email templates to use when sending review request email messages. The implementation where the templates are configured must be published to the deployment zone before you reference the deployment zone in the order data file. Check with your Bazaarvoice representative to obtain the correct ID, or sign in to the configuration to verify.
• If you do not have a value for a specific field, omit the field from your feed. Do not include fields with blank values.

Here is a simple example of an XML feed:

<?xml version="1.0" encoding="UTF-8"?>
<Feed xmlns="http://www.bazaarvoice.com/xs/PRR/PostPurchaseFeed/14.8">
  <Interaction>
    <TransactionDate>
      2016-08-23T15:09:41.000
    </TransactionDate>
    <EmailAddress>user@example.com</EmailAddress>
    <Locale>en_GB</Locale>
    <UserName>name</UserName>
    <UserID>715987491</UserID>
    <TransactionId>
      someorder1
    </TransactionId>
    <Products>
      <Product>
        <ExternalId>product902</ExternalId>
        <Name>Product Name</Name>
        <ImageUrl>http://example.cimages/products/image01.jpg</ImageUrl>
        <Price>
          33.99
        </Price>
        <IncentivizedReview>True</IncentivizedReview>
      </Product>
    </Products>
    <DeploymentZone>secondary_site</DeploymentZone>
  </Interaction>
  <Interaction>
    <TransactionDate>
      2016-08-23T15:11:41.000
    </TransactionDate>
    <EmailAddress>user2@example.com</EmailAddress>
    <Locale>en_US</Locale>
    <UserName>name2</UserName>
    <UserID>715983395</UserID>
    <TransactionId>
      someorder2
    </TransactionId>
    <Products>
      <Product>
        <ExternalId>product14</ExternalId>
        <Name>Product Name2</Name>
        <ImageUrl>http://example.cimages/products/image02.jpg</ImageUrl>
        <Price>
          14.49
        </Price>
        <IncentivizedReview>True</IncentivizedReview>
      </Product>
      <Product>
        <ExternalId>product42</ExternalId>
        <Name>Product Name3</Name>
        <ImageUrl>http://example.cimages/products/image03.jpg</ImageUrl>
        <Price>
          234.99
        </Price>
        <IncentivizedReview>False</IncentivizedReview>
      </Product>
    </Products>
  </Interaction>
</Feed>

Required or recommended fields for transactional order data

Field	Best practice for review requests?	Required?	Description
TransactionDate	Yes	Yes, if using send delay	Specifies the purchase, shipping, or other interaction date in the .XML DateTime format.
Locale	Yes	Yes, if supporting review requests in multiple languages	Controls the language-specific email template that is used. This field includes language and country information. Examples: en_US for English es_US for Spanish
DeploymentZone	Yes	Yes, if multiple deployment zones are used	Indicates the ID of the deployment zone whose email templates to use when sending review request email messages. The implementation where the templates are configured must be published to the deployment zone before you reference the deployment zone in the order data file. If you omit this field, main_site is used. You must specify the ID, not the deployment zone name. To determine the deployment zone ID to use, select to the right of the deployment zone on the Site Manager page of the configuration. Note: This field is supported for schema versions 14.6+.
EmailAddress	Yes	Yes	Specifies the email address of the consumer. Must be in a valid format. Note: You can use encryption to ensure the security of consumer email addresses used for notifications and requests. To learn how, refer to Encrypt order data PII.
UserID	No (Hosted Authentication) Yes (Site Authentication)	No	Specifies the consumer's user ID, typically created during an online transaction. This value is encoded into the Bazaarvoice user authentication string (UAS). The user ID in the order data feed must match the user ID that is passed to Bazaarvoice during the review-submission process (as part of your Ratings & Reviews implementation). This field can be omitted from the feed if no user ID was generated during the checkout process (for example, if a consumer has placed a purchase order as a guest purchaser). If the same user ID occurs in the same feed more than once with different email addresses, the user ID will be set to null and a warning is printed to the log file. This field should be omitted if using Bazaarvoice hosted authentication.
UserName	Yes	Yes if you want to: auto-populate the nickname field on the submission form address the email recipient by their user name in the review request email message (example, “Hi Vicki”)	Specifies the user's first name or nickname created by the consumer on an online account. This field can be used to personalize the email greeting.
TransactionID	Yes	No	Specifies a unique identifier for an order generated by the site. This is essential for accurately tracking individual orders and is a key metric for measuring return on investment (ROI).

Fields that apply to each product or service in the order

The maximum number of products that will be listed on a review request is five.

Field	Best Practice for review requests?	Required?	Description
ExternalId (product)	Yes	Yes	Must match the external product ID for the item that is sent to Bazaarvoice in your product catalog. This matching is crucial to associate the review with the appropriate product in your product catalog. For example, do not provide a stock-keeping unit (SKU) in the order data file rather than the less granular ExternalId in the product catalog.
ImageUrl (product)	Yes	Yes If you cannot provide a URL to the image, a customizable "no image available" graphic is displayed.	Product thumbnail will be displayed in the email template. Always provide the full URL including "http://www". If not provided, it will be retrieved from your current product database. Note: If the URL contains a reserved (special) character, you must URL-encode the character. For example, use &amp for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]).
Name (product)	Yes	Yes	Will be used in the email template. If not provided, it will be retrieved from your current product database. In XML feeds, it puts names in CDATA sections: <![CDATA[Your_Product_Name]]> Replace special characters with the HTML entity number equivalent (® = &#174;).
Price	Yes	No, but recommended for determining the order of products in review requests containing multiple products	Used to control the order in which products appear within a given email (for example, list highest value product first). Should be a decimal number with no currency symbols, for example, "20.99", "40.00"
IncentivizedReview	Yes	No, but recommended to determine if the review is incentivized.	Item parameter that captures whether the review is incentivized. Just specify "True" or "False" to indicate if any incentive was given.

Required or recommended fields for non-transactional order data

Field	Best practice for review requests?	Required?	Description
TransactionDate	Yes	Yes, if using send delay	The purchase, shipping, or other interaction date in the XML DateTime format.
Locale (includes language and country information)	Yes	Yes, if supporting review requests in multiple languages	Specifies the locale code and controls the language-specific email template that is used, as shown by the following examples: en_US for English es_US for Spanish
EmailAddress	Yes	Yes	Email address of consumer. Must be in a valid format. Note: You can use encryption to ensure the security of consumer email addresses used for notifications and requests. To learn how, refer to Encrypt order data PII.
UserID	Yes	No	Consumer's user ID, typically created during an online transaction. This value is encoded into the Bazaarvoice user authentication string (UAS). The user ID in the order data file must match the user ID that is passed to Bazaarvoice during the review-submission process (as part of your Ratings & Reviews implementation). This field can be blank on purchase records for which a user ID was not generated during the checkout process, such as a guest purchaser. If the same user ID occurs in the same feed more than once with different email addresses, the user ID will be set to null and a warning is printed to the log file. This field should be omitted if using Bazaarvoice hosted authentication.
UserName	Yes	Not required unless you want to: auto-populate the nick name field on the submission form address the email-recipient by their user name in the review request email message (example, “Hi Vicki”)	User's first name or nickname created by the consumer on an online account. This field can be used to personalize the email greeting.
TransactionID	Yes	No	Specifies a unique identifier for an order generated by the site. This is essential for accurately tracking individual orders and is a key metric for measuring return on investment (ROI).

Fields that apply to each non-transaction event you want to list on a review request

The maximum number of events that will be listed on a review request is five.

Field	Best practice for review requests?	Required?	Description
ExternalId (product)	Yes	No, but recommended	Must match the external product ID for the item that is sent to Bazaarvoice in your product-catalog data feed.
ImageUrl (product)	Yes	No, but recommended	Product thumbnail will be displayed in the email template. Always provide the full URL including "http://www". If not provided, it will be retrieved from your current product database. Note: If the URL contains a reserved (special) character, you must URL-encodethe character. For example, use &amp for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]).
Name (product)	Yes	No, but recommended	Will be used in the email template. If not provided, it will be retrieved from your current product database. In XML feeds, it puts names in CDATA sections: <![CDATA[Your_Product_Name]]> Replace special characters with the HTML entity number equivalent (® = &#174;).
Price	Yes	No, but recommended	Used to control the order in which products appear within a given email (for example, list highest value product first). Should be a decimal number with no currency symbols, for example, "20.99", "40.00".
IncentivizedReview	Yes	No, but recommended to determine if the review is incentivized.	Item parameter that captures whether the review is incentivized. Just specify "True" or "False" to indicate if any incentive was given.

Create TXT file

Important: Text feeds do not support multiple deployment zones and will default to your main site. If you use multiple deployment zones, send your order data using the XML,  format instead. 

The following data schema or header row for a tab-delimited data file is the only acceptable format in which Bazaarvoice can accept text feeds. 

TRANSACTION_TIME<Tab>EMAIL_ADDRESS<Tab>LOCALE<Tab>USER_ID<Tab>USER_NICKNAME<Tab>PRODUCT_EXTERNAL_ID<Tab>PRODUCT_NAME<Tab>PRODUCT_IMAGE_URL<Tab>PRODUCT_PRICE

Example: filename.txt

Validate the order data file

Before uploadin the order data file to the SFTP server, Bazaarvoice recommends you to use the Interaction Feed featue in the Portal to validate your xml or txt file to ensure the code is correct and error-free.

Tip: Do not use the Interaction Feed feature to validate catalog feed files—it is designed exclusively for order data files. Use this tool to validate your catalog feed files. 

Complete the following steps:

1. From the Bazaarvoice Portal, select Settings > Monitoring Tools > Interaction Feed.
2. In the Upload your feed section, you can either drag and drop your feed file or select Browse to upload it. The maximum file size allowed is 10 MB. 
3. Select Validate.
Your feed is automatically reviewed. The page will either display a list of errors or let you know that your feed is validated and ready to upload.

Note: If the feed file successfully validates against the schema, you must check that each transaction within the feed is unique. The user ID, transaction date, and email address values must not match with those of another transaction.

Additionally, you must verify the format of transaction dates and email addresses, as follows:

Upload the order data file

When you upload an order data file to one of the Bazaarvoice SFTP servers, the review request process is triggered and Bazaarvoice starts sending review requests to email addresses that appear in the order data file.

When you upload a feed file to test in the staging environment, keep the following in mind:

Email messages are sent to addresses with domains that have been whitelisted for your company only. In general, these domains have domain names that are associated with your company's sites.

Before you begin sending review requests to your consumers:

• We strongly recommend that you test the order data file in staging and production using internal email addresses and phone numbers. Refer to Test review requests for detailed information that you need when testing review requests in the staging and production environments.
• Verify that your Ratings & Reviews implementation is live and uses an active container page.
• Control when review requests are sent by specifying the review request delay and review request send time (optional). These options are on the Configure Messages page of your Ratings & Reviews configuration settings.

When you are ready to send review requests to your consumers, upload your order data file to ppe/inbox directory on the Bazaarvoice SFTP location:

• If your data is hosted in the United States (US), use the following URLs:
  • Staging server—sftp-stg.bazaarvoice.com
  • Production server—sftp.bazaarvoice.com
• If your data is hosted in Europe (EU), use the following URLs:
  • Staging server—sftp7-stg.bazaarvoice.com
  • Production server—sftp7.bazaarvoice.com

Be sure to connect to SFTP using port 22. Contact Bazaarvoice Support if you do not know your SFTP credentials or where your data is hosted.

We recommend that you upload order data files at least weekly. Bazaarvoice automatically imports order data files daily at 5:15 AM Central Time (CST: UTC-6 or CDT: UTC-5). Depending on the configured review request delay and review request send time, Bazaarvoice will deliver review requests as early as the morning that you upload the feed.

FAQs