TestFreaks Order Feed

An order feed is used to send purchase information to TestFreaks in order to trigger pro-active review collection.

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

Order fields

`order_id`	Order identifier	Required
`customer_id`	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

Product fields

`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

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

We 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.

When uploading order feeds, the name of each file should contain the feed type, client ID and date / time. For example, XML order feeds for the client IDs example.com-en and example.com-sv:

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

Order API

You can also use our Order 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.