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.
client_id, the unique identifier for your client configuration.
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. This value is required.
If an order with the specified .order.id does not exist, a new 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.
.order.customer.id is your unique and stable customer identifier. This value is required.
.order.items[].id is your unique and stable product SKU. If the order item ID matches a product ID
in the current product feed, the product details will be filled in
automatically.
.order.items[].delivery_date specifies the date 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. This value is required to enable review collection for the order item.
It is also possible to override the product details from the product feed 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://...",
"properties": {
"color" : "green",
}
}
]
}
}
If the order item ID is not found in the product feed the order item will be set as unreviewable, unless the product details are provided in the API request.
.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.
.order.items[].properties can contain key-value pairs that specify custom properties for the order item. This is typically used to add additional attributes, such as color and size.
Create or update multiple orders by making one POST /v1/orders request per order.
Make sure to read and follow the instructions around Rate limiting when you make multiple request in a short period of time.
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.
$ 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"
}
]
}
]
}
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
}
]
}
}
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.
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=..."
}
}
client_id, the unique identifier for your client configuration.
{
"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"
}
]
}
}