Orders API

The Orders API is used to add or update order, which can be used to trigger automatic review invitiation emails. This is a new version of this API, please also look at the the order feeds documentation for more information and options.

POST /v1/orders (Add/update order)

Request parameters

client_id, the unique identifier for your client configuration.

Request body

Set the Content-Type to application/json and post data similar to:

{
  "order": {
    "id": "O123",
    "customer": {
      "id": "C001",
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    "items": [
      {
        "id": "P001-02-BLK",
        "delivery_date": "2022-01-01"
      }
    ]
  }
}

.order.id is your unique and stable order identifer

.order.customer.id is your unique and stable customer identifier

.order.items[].id is your unique and stable product SKU. Must match an ID in the current product feed.

If the .order.id does not exist, the order will be created in the TestFreaks system. If it already exists, it will be updated, but it will only add or update items, not delete items. See below for how to cancel an order item.

Product details are typically provided by the product feed but can be overridden by posting to the API. For example:

{
  "order": {
    "items": [
      {
        "id": "P001-02-BLK",
        "delivery_date": "2022-01-01",
        "reviewable": true,
        "family_id": "P001",
        "name": "Product name",
        "category": "Category name",
        "url": "https://...",
        "image_url": "https://..."
      }
    ]
  }
}

.order.items[].reviewable is set if the item has a corresponding entry in the product feed. Only reviewable items can take part in review collection, so use this property to cancel individual items or to enable review collection for items that are not part of the product feed.

Response body

You will receive the full order object in return. Do not rely on fields not documented below.

If .errors is set, it’s a list of errors.

Example

$ curl -u "sk_token:" -H "Content-Type: application/json" -X POST \
-d '{
  "order": {
    "id": "O123",
    "customer": {
      "id": "C001",
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    "items": [
      {
        "id": "P001-02-BLK",
        "family_id": "P001",
        "name": "Product name",
        "category": "Category name",
        "delivery_date": "2021-01-01",
        "url": "https://...",
        "reviewable": true
      }
    ]
  }
}' https://api.testfreaks.com/v1/orders?client_id=example.com
{
  "data": [
    {
      "id": "O123",
      "created_at": "2021-01-04T13:08:00Z",
      "updated_at": "2021-01-04T13:08:00Z",
      "customer": {
        "id": "C001",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "opt_out": false,
        "updated_at": "2021-01-04T13:08:00Z",
        "created_at": "2021-01-04T13:08:00Z"
      },
      "items": [
        {
          "id": "P001-02-BLK",
          "family_id": "P001",
          "name": "Product name",
          "category": "Category name",
          "delivery_date": "2021-01-01",
          "url": "https://...",
          "image_url": null,
          "deleted": false,
          "reviewable": true,
          "created_at": "2021-01-04T13:08:00Z",
          "updated_at": "2021-01-04T13:08:00Z"
        }
      ]
    }
  ]
}

Cancelling order items

Request body

Individual order items can be cancelled by setting the reviewable property to false. For example:

{
  "order": {
    "id": "O123",
    "customer": {
      "id": "C001"
    },
    "items": [
      {
        "id": "P001-02-BLK",
        "reviewable": false
      }
    ]
  }
}

GET /v1/orders (List orders)

Request parameters

limit, how many orders per page, default 100, maximum 1000.

client_id, the unique identifier for your client configuration.

created_after (optional) set to YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ (ISO-8601) to filter orders on created timestamp. For example, 2021-10-01T13:00:00Z

customer_id (optional) for filtering orders on a specific Customer ID.

customer_email (optional) for filtering orders on a specific Customer email address.

after, used for pagination.

Response body

If .links.next is set, additional pages are available by following the link.

If .errors is set, it’s a list of errors.

{
  "data": [
    {
      "id": "O123",
      "created_at": "2021-01-04T13:08:00Z",
      "updated_at": "2021-01-04T13:08:00Z",
      "customer": {
        "id": "C001",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "opt_out": false,
        "updated_at": "2021-01-04T13:08:00Z",
        "created_at": "2021-01-04T13:08:00Z"
      },
      "items": [
        {
          "id": "P001-02-BLK",
          "family_id": "P001",
          "name": "Product name",
          "category": "Category name",
          "delivery_date": "2021-01-01",
          "url": "https://...",
          "image_url": null,
          "deleted": false,
          "reviewable": true,
          "created_at": "2021-01-04T13:08:00Z",
          "updated_at": "2021-01-04T13:08:00Z"
        }
      ]
    }
  ],
  "links": {
    "next": "https://api.testfreaks.com/v1/orders?after=..."
  }
}

GET /v1/orders/<order-id> (Get order details by order ID)

Request parameters

client_id, the unique identifier for your client configuration.

Response body

{
  "data": {
      "id": "O123",
      "created_at": "2021-01-04T13:08:00Z",
      "updated_at": "2021-01-04T13:08:00Z",
      "customer": {
        "id": "C001",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "opt_out": false,
        "updated_at": "2021-01-04T13:08:00Z",
        "created_at": "2021-01-04T13:08:00Z"
      },
      "items": [
        {
          "id": "P001-02-BLK",
          "family_id": "P001",
          "name": "Product name",
          "category": "Category name",
          "delivery_date": "2021-01-01",
          "url": "https://...",
          "image_url": null,
          "deleted": false,
          "reviewable": true,
          "created_at": "2021-01-04T13:08:00Z",
          "updated_at": "2021-01-04T13:08:00Z"
        }
      ]
  }
}