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?