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.

Note: The Orders API is an alternative way to create and update orders.

Concepts

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

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.

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?