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
.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.
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"
}
]
}
}