Order Feed

An order feed contain details about orders made by your customers. It describes the customer and the purchased products. TestFreaks uses your order feed to know when and how to send review invitations to your customers.

Concepts

Order A collection of products ordered or purchased at the same time
Customer The person making the order or purchase. The recipient of the review invitation.
Product A product (or service) that is part of an order and should be included in a review invitation. Products have individual delivery dates.

Each Product has a corresponding entry in the Product Feed.

A Customer typically receives our review invitation 1-2 weeks after Product delivery. Products with similar delivery dates are included in the same invitation, even across different orders.

Supported fields

The order feed can contain the following fields. Some of the fields are mandatory, and required to be present and valid.

Order fields

Field Description  
order_id Order identifier Required
customer_id Unique and stable customer identifier Required
customer_name Customer’s full name Required for use in the review invitation or for suggesting a nickname when writing reviews.
customer_email Customer’s email address Required for email invitations
customer_phone Customer’s phone number Required for SMS invitations
customer_lang Language code used by the customer Required if you have a multi-lingual website with orders combined into a single feed
store_name Name or identifier for the store the purchase was made from Optional

Customer ID

Note: The customer_id field must contain a unique and stable customer identifier to make it possible to connect orders to the same customer over time.

The customer_id would typically be generated by your system more or less randomly, and then associated with a specific customer indefinitely. Using this type of customer ID is always preferred when available.

Using the customer’s email address is an alternative when a generated customer ID is not available. This should be avoided if possible, since an email address could be considered personal information.

Product fields

The following fields describe a product included in the order. The fields are nested under a product entry when using XML and JSON.

Field Description  
sku Product ID as it appears in the Product Feed Required
family_id or parent_sku Family ID as it appears in the Product Feed Required if sku is different from the sku in the product feed
delivery_date The YYYY-MM-DD date when the product was (or is expected to be) delivered.

If this date is not available then the closest available date (such as dispatch date or order date) can be used instead.
Required
name
manufacturer
category
url
image_url
Same as the fields in the Product Feed and will be used instead if present Optional
reviewable Boolean describing whether this product should be included in the review collection email. This can be changed if you send information for the same order again later. A product which has been returned can have reviewable set to false, for example. Optional
price The price of the product in an arbitrary currency. This value can be used to determine which products to collect reviews for from a customer. The product with the highest price value will be the most prioritized for review collection. The currency is not important as long as the same is used for all products. Optional
priority The relative priority of how important review collection is for this specific product. This value can be used to determine which products to collect reviews for from a customer. The product with the highest priority value will be the most prioritized for review collection. This is similar to price but without any association to a price and a currency. Optional

Feed formats

We accept order feeds in CSV, XML, and JSON format.

CSV

order_id,customer_id,customer_name,customer_email,sku,delivery_date
O123,C001,John Doe,john.doe@example.com,P001-02-BLK,2020-04-20

The order fields will be repeated for each product in the same order.

CSV Example File: example-order-feed.csv

XML

<?xml version="1.0" encoding="UTF-8"?>
<orders>
  <order>
    <order_id>O123</order_id>
    <customer_id>C001</customer_id>
    <customer_name>John Doe</customer_name>
    <customer_email>john.doe@example.com</customer_email>
    <store_name>Store A</store_name>
    <products>
      <product>
        <sku>P001-02-BLK</sku>
        <delivery_date>2020-04-20</delivery_date>
      </product>
    </products>
  </order>
</orders>

XML Example File: example-order-feed.xml

JSON

{
  "orders": [
    {
      "order_id": "O123",
      "customer_id": "C001",
      "customer_name": "John Doe",
      "customer_email": "john.doe@example.com",
      "store_name": "Store A",
      "products": [
        {
          "sku": "P001-02-BLK",
          "delivery_date": "2020-04-20"
        }
      ]
    }
  ]
}

JSON Example File: example-order-feed.json

Feed delivery

The order feed can either be made available for download by TestFreaks, sent to TestFreaks via SFTP, or managed through the Orders API.

As a file

TestFreaks can fetch order feeds from URLs on https:// or sftp://.

Alternatively, you can schedule daily feed uploads to TestFreaks using SFTP after setting up an account with us.

The file can be in either CSV, XML, or JSON format.

Order feed filename

The name of each file should contain the feed type, client ID and date / time.

For example, an XML order feed for the clients example.com-en and example.com-sv should be named:

orders-example.com-en-2020-04-20.xml
orders-example.com-sv-2020-04-20.xml

Orders API

You can also use our Orders API to insert and update orders to our system.

Product returns or cancellations

If you send the same order (same order_id) again, and include the same product(s) but set reviewable to false for returned products, that product will not be included the review invitation email. If you set reviewable to false for all products in the order, no email will be sent.

Checklist and best practices

Is the feed is automatically updated?

Is there an existing API integration we can use?

Does it contain the same identifiers that you use in the product feed?

If you have offline stores, are these included? If so, is it clear which orders are online and which are offline? You can also set up two separate feeds for these channels.

Does it contain maximum granularity on the items? Try to collect reviews on the most specific identifer, and use the TestFreaks product grouping features to group them together.

Can we correctly detect returns? You can update an order by sending it again, using the same order_id.

What dates can we use to calculate when to ask for a review? Ideally when customer received the product, otherwise delivery date, otherwise shipping, and worst case order date. Add some time to the scheduling if the delivery date is not known.

Do you want to filter out some orders, for example large orders where the actual end user is not the one orderering the products? If so, either filter these out before generating the feed, or make sure enough information is available in the feed in order to do the filtering in the TestFreaks system.

Can we get some retrospective data for seeding? This one-time feed can use a different format.

Do you need to allow TestFreaks ip-addresses in your firewall or CDN?