How to Send Orders via the API Resource v1/event
Order data is transmitted to our system via the resource v1/orders that has a number of limitations:
- Fixed fields that are determined by the specification;
- Impossible to add custom fields;
- Order parameters cannot be used to build segments.
You can overcome them with the resource v1/event that can be used to replace or complement v1/orders. By using it, you’ll be able to:
- Transmit more data with additional fields;
- Use segmentation by events and their parameters, for example, sort out contacts who bought a particular item within a week;
- Expand/receive RFM segmentation by order without additional usage of v1/orders.
Important! To save orders in the system, you need to set up segmentation by events as the event contains a contact identifier. It can be determined based on the default or conditional parameters.
How to Use v1/event to Send Orders
For example, you can set up identification by unique token. The order will not be saved until these parameters are transmitted to the system. If you don’t set your own parameters, the system will search the identifier based on default parameters (email, phone, etc.).
You can send v1/event only for the existing contact. To send the order for a new contact, first import this contact into the system via:
- v1/contacts;
- v1/orders.
To send an order, you need to specify the event type. Choose the type from the below table based on the order status.
Event type | Description |
orderCreated | Creates the order with the status indicated in the array |
orderUpdated | Updates the order |
orderDelivered | Changes the order status to DELIVERED |
orderCancelled | Changes the order status to CANCELLED |
orderCreated
To create an order, name the parameters as indicated here and fill in the required parameters. If any of the required parameters isn’t filled, the event is ignored and the order will not be sent.
Note. You can optionally add the field items with products included in the order. Item values should be transmitted as a JSON string. A one-level nested array is supported. This means that if you transmit one more array or object in the items array, it will remain serialized. Such data isn’t ignored, but you won’t be able to use it as it’s transmitted in the string.
Example:
{
"eventTypeKey": "orderCreated",
"keyValue": "380501234567",
"params": [{
"name": "phone",
"value": "380501234567"
}, {
"name": "externalOrderId",
"value": "12345679"
}, {
"name": "externalCustomerId",
"value": "AV13760"
}, {
"name": "totalCost",
"value": "258.0"
}, {
"name": "status",
"value": "INITIALIZED"
}, {
"name": "date",
"value": "2020-05-14T10:11:00"
}, {
"name": "items",
"value": "[{\"externalItemId\":\"200600\",\"name\":\"Super Device\",\"category\":\"devices\",\"quantity\":1,\"cost\":990,\"url\":\"http:\/\/example.com\/item\/200600\",\"imageUrl\":\"http:\/\/example.com\/item\/200600\/image.png\",\"description\":\"High quality\"}]"
}]
}
Important!
To save the event assigned to the contact, you need to know what event parameter contains the identifier. By default, the system searches for the following parameters excluding the register: ContactId, Contact_id, Email, EmailAddress, UserEmail, ContactEmail, Phone, SMS, PhoneNumber, PushToken, ContactKey, Contact_key. All values, except for the email address, are mapped including the register.
📌 Pay attention
If you want to show product data in an email, you need to use products in the event.
{
"eventTypeKey": "orderCreated",
"keyValue": "380501234567",
"params": [{
"name": "phone",
"value": "380501234567"
}, {
"name": "externalOrderId",
"value": "12345679"
}, {
"name": "externalCustomerId",
"value": "AV13760"
}, {
"name": "totalCost",
"value": "258.0"
}, {
"name": "status",
"value": "INITIALIZED"
}, {
"name": "date",
"value": "2020-05-14T10:11:00"
}, {
"name": "items",
"value": "[{\"externalItemId\":\"200600\",\"name\":\"Super Device\",\"category\":\"devices\",\"quantity\":1,\"cost\":990,\"url\":\"http:\/\/example.com\/item\/200600\",\"imageUrl\":\"http:\/\/example.com\/item\/200600\/image.png\",\"description\":\"High quality\"}]"
},
{
"name": "products",
"value": "{\"array\":[{\"externalItemId\":\"200600\",\"name\":\"Super Device\",\"category\":\"devices\",\"quantity\":1,\"cost\":990,\"url\":\"http:\/\/example.com\/item\/200600\",\"imageUrl\":\"http:\/\/example.com\/item\/200600\/image.png\",\"description\":\"High quality\"}]}"
}]
}
orderUpdated
- Updates the order that has the parameter externalOrderId filled.
- If the transmitted order doesn’t exist in the system, it’s created anyway.
- The parameters must be named as indicated here. If the order is to be created, the orderCreated requirements apply.
orderDelivered
- Changes the order status to DELIVERED.
- If the order does not exist, it is ignored.
orderCancelled
- Changes the order status to CANCELLED.
How to Use v1/event to Transfer Data to the Recommendation System
If you transfer events to our CDP from the application or website and also have integration with recommendation systems (abandoned browses, carts, etc.), you can transfer data to both services without additional action.
This way, you’ll be able to implement event segmentation without transferring data separately to different services.
Types of events to transfer different data:
Type | Description |
pageViewed | View of the page |
productViewed | View of the product card |
productCategoryViewed | View of the category |
cartUpdated | Change of the cart items |
An example of an event for transmitting information about the visited page by the user, as a link can be specified (deeplinks & Universal links) when using a mobile application:
{
"eventTypeKey": "pageViewed",
"keyValue": "example@email.com",
"params": [
{
"name": "phone",
"value": "380501234567"
},
{
"name": "email",
"value": "example@email.com"
},
{
"name": "page",
"value": "{\"location\":\"https://example.com\"}"
}
]
}
where
Parameter | Type | Description |
phone |
String |
Phone number in international format |
|
String |
Email address |
page |
String |
Location |
location |
String |
Page url or deeplink |
To rank items/categories properly and send triggers for abandoned browses, you need to send a request that specifies which card the user is currently viewing, as well as its price and availability. To do this, you need to send the productViewed event.
{
"eventTypeKey": "productViewed",
"keyValue": "example@email.com",
"params": [
{
"name": "phone",
"value": "411786452"
},
{
"name": "email",
"value": "example@email.com"
},
{
"name": "product",
"value": "{\"productId\":\"WS01-L-Green\",\"price\":45.5,\"isInStock\":1,\"someProductProperty\":[\"green\"]}]}"
},
{
"name": "currencyCode",
"value": "USD"
}
]
}
where
Parameter | Type | Description |
phone |
String |
Phone number in international format |
|
String |
Email address |
product |
String |
Product data |
productId |
String |
Product ID |
quantity |
Double | Quantity of items |
price |
Double |
Price per item |
isInStock (optional) |
Int |
Product availability Can have two values:
|
someProductProperty (optional) |
Array of strings |
Transfers additonal values separated by a coma |
currencyCode (optional) |
String |
Currency |
For triggers Website visit with a category view, without product card view and Website visit without a category view, you need to send the event productCategoryViewed that specifies what category the user is currently viewing.
{
"eventTypeKey": "productCategoryViewed",
"keyValue": "example@email.com",
"params": [
{
"name": "phone",
"value": "7411324763"
},
{
"name": "email",
"value": "example@email.com"
},
{
"name": "category",
"value": "{\"productCategoryId\":\"Mugs\"}"
}
]
}
where
Parameter | Type | Description |
phone |
String | Phone number in international format |
|
String | Email address |
category |
String |
Category description |
productCategoryId |
String |
Category |
The event (with new recycleStateId) is sent when the user changes items in the cart.
{
"eventTypeKey": "cartUpdated",
"keyValue": "example@email.com",
"params": [
{
"name": "phone",
"value": "73456712"
},
{
"name": "email",
"value": "example@email.com"
},
{
"name": "products",
"value": "[{\"productId\":\"WS01-L-Green\",\"quantity\":1,\"price\":45.5}]"
},
{
"name": "currencyCode",
"value": "USD"
},
{
"name": "recycleStateId",
"value": "d59c6e6d-4123-4b0e-8c32-15f0656a8c60"
}
]
}
where
Parameter | Type | Description |
phone |
String | Phone number in international format |
|
String | Email address |
products (required is the cart isn't empty) |
Array of strings |
Data on items in the cart |
productId |
String |
Product ID |
quantity |
Double | Quantity of items |
price |
Double |
Price per item |
name (optional) |
String |
Product name |
category (optional) |
String |
Product category |
discount (optional) |
String |
Discount amount per item |
someProductProperty (optional) |
Array of strings |
Transfers additonal values separated by a coma |
recycleStateId |
String |
Unique ID connects cart events to the purchase Generated of random numbers and Latin letters |
currencyCode (optional) |
String |
Currency |