Orders

Export your CRM orders and import them into the CDP. Additionally, orders can be augmented with additional information - or corrected with more up-to-date data- that might not be available in your CRM.

Use Cases

Importing orders into the CDP has 3 main use cases, as described below.

Bootstrap Your System with Historic Order Data

Importing orders plays an important role when bootstrapping a system. While Kevel Audience builds user profiles with attributes produced from the users' interaction with the website, businesses usually have a lot of information on orders placed before events are collected. These orders can add valuable information to produce user attributes. The attributes that benefit the most from a bootstrap from past orders are the ones related to the next purchase predictions, RFM and lifetime value. The attributes related to the likelihood to buy are produced using different types of events from the users' interaction with the website (besides the actual purchases), so they don't benefit much from an import of orders previously unseen in the system.

Ensure the Orders Used by the CDP Are in Sync with Your CRM Orders

Orders can change their state (for example, becoming canceled or refunded) without an explicit event from the user on the website. In those scenarios, periodic import of orders from your CRM backend can help Kevel Audience have a more accurate view of existing orders.

Complement Order Information Collected by Tracking Events with Details Private to the CRM Backend

Sometimes, the data available when producing events to be collected by Kevel Audience lacks some details that are private and, therefore, not directly accessible by the website. Typical scenarios are information missing from specific line items (like product-related data) or incomplete payment information due to actions that happen after the event is triggered. To ensure that Kevel Audience has access to relevant order details, CDP users should set up a periodic import of orders.

Order Events from Imports

Order imports generate order events. If the order is unknown, an orderPlace is generated. Otherwise, if the import provides new information, for example, the status of a line item is updated, an orderUpdate event is generated.

Considering the provided product ID, events generated from order imports are enriched if a product feed is available. Only omitted attributes are added from the product feed. Attributes available on the import are kept on the event and are not replaced by data from the product feed.

Formats

We currently have support for the following 1st and 3rd party formats:

Supported schemas

• Kevel Audience CSV
• Shopify CSV

Kevel Audience CSV

This format is intended for order imports using CSV, where each line is an Order is serialized to CSV. You can download an example file here.

Relevant notes:

• The export file should be encoded using UTF-8.
• All line items for the same order must be listed sequentially. Otherwise, only the last sequential line items of the order will be persisted;
• Given an order with an arbitrary number of rows, only the first row is used to extract Order details and all rows are used to extract Line item details. This means that Orders with more than 1 Line item do not need to populate the order columns for all columns and can be left empty.
• If the provided userId is not hashed (E.g. idType=email), you can configure the import to hash it (to a idType=email_sha256) beforehand.
• The userId field is validated accordingly to the type specified in userIdType field. You can find more information about user ID types in the User Identifiers documentation.

Column	Required	Type	Description	Details	Example
orderId	Required	String	Order identifier	Must be unique by Order	or123
userIdType	Required	String	The type of user identifier (e.g. "email")	Check the User Identifiers documentation	email
userId	Required	String	The user identifier		john@email.com
currency	Required	String	The currency used in monetary values	Check the supported currencies	EUR
total	Required	Double	Total value of the order with all discounts already considered, including subtotal, tax and shipping	total = subtotal + tax + shipping	102.5
subtotal	Required	Double	The value of the order, when tax and shipping are excluded	subtotal = total - tax - shipping	85
tax	Required	Double	The total applied tax value for the order		11.5
shipping	Required	Double	The total shipping costs for the order		6
discount	Required	Double	The total discounted value for the order		5
refund	Required	Double	The total refunded value for the order		0
paymentMethod		String	The payment method		Visa
shippingMethod		String	The shipping method		UPS
shippingCountry		String	The destination country		France
source		String	Source from where the order was placed. Examples are web, phone call, POS.
promotions		List of Strings	Vouchers applied in the purchase.	Strings separated by ;	WINTERSALE
createdAt	Required	DateTime	When the order was created	Date format: ISO-8601	2020-09-16T10:38:06+0100
lastUpdated		DateTime	When the order was last updated	Date format: ISO-8601	2020-09-16T20:13:31+0100
custom_<name...>		String	Attribute name and value to be imported as custom field	These columns can be specified multiple times with different names with the "custom_" prefix. The imported order will have those attribute names (without the "custom_" prefix) and respective values as custom fields. For example, "custom_color" will be mapped to "customFields.color" in the order.
lineItem_id		String	A unique identifier for the line item within the order		li125zc
lineItem_productId	Required	String	Product identifier		p125zc
lineItem_itemGroupId		String	Identifier for a group of products that come in different versions (variants)		p125
lineItem_name		String	Product name		My Product
lineItem_sku	Required	String	Product SKU		p125zc-5
lineItem_brand		String	Product brand		Nike
lineItem_category		String	Product category		Men > Shirts > Short Sleeve Shirts
lineItem_categoriesList		List of Strings	A hierarchically sorted list of the sub-categories that this product belongs to. The first item on this list should be the most general sub-category, while the last should be the most specific. Any item on this list should correspond to a sub-category of the item immediately preceding it.	Strings separated by ;	Men;Shirts;Short Sleeve Shirts
lineItem_currency	Required	String	The currency used in monetary values	Check the supported currencies	EUR
lineItem_total	Required	Double	Total value of the line item with all discounts already considered, including subtotal, tax and shipping	total = subtotal + tax + shipping	102.5
lineItem_subtotal	Required	Double	The value of the line item, when tax and shipping are excluded	subtotal = total - tax - shipping	85
lineItem_tax	Required	Double	The total applied tax value for the line item		11.5
lineItem_shipping	Required	Double	The total shipping costs for the line item		6
lineItem_discount	Required	Double	The total discounted value for the line item		5
lineItem_refund	Required	Double	The total refunded value for the line item		0
lineItem_quantity	Required	Double	Quantity of items purchased from this line item		1.0
lineItem_promotions		List of Strings	Vouchers applied in the purchase or displayed together with the product	Strings separated by ;	WINTERSALE
lineItem_adult		Boolean	Whether the product includes sexually suggestive content.	Must be true or false. Defaults to false	false
lineItem_subscriptionDuration		Long	If the purchase relates to a subscription, captures the subscription duration, in milliseconds.		15552000000
lineItem_size		String	Product size		S
lineItem_sizeSystem		String	Country of the size system used by your product.		EU
lineItem_status	Required	String	Line item status. placed the order has been placed but the item is yet to be paid paid the item has been paid but not yet delivered fulfilled the item has been paid and delivered refunded the item has been refunded cancelled the order has been modified to exclude this line item	Supported status: placed, paid, fulfilled, refunded, cancelled	fulfilled

This example file shows how each field can be used.

Shopify CSV

Kevel Audience supports CSV order exports from Shopify. The documentation for generating a Shopify export can be found here. Please ensure you select Export orders to export all order information instead of Export transaction histories, which only exports the transactions.

Relevant notes:

• Shopify uses the Name column to distinguish between different orders inside the CSV file, so it must be unique per Order;
• All Line items for the same Order must be listed sequentially;
• Given an order with an arbitrary number of rows, only the first row is used to extract Order details and all rows are used to extract Line item details. This means that Orders with more than 1 Line item do not need to populate the order columns for all columns and can be left empty.
• If the provided userId is not hashed (e.g. idType=email), you can configure the import to hash it (to a idType=email_sha256) beforehand.
• The email field is validated as an email.
• It's important that the extracted order identifier from the shopify import matches the orderId provided via tracking events. When importing, you'll be able to select which field to use as the order identifier between the Id and Name columns.

Kevel Audience will consider the following attributes while importing a Shopify file:

Column	Required	Type	Details
Name	Required	String	Must be unique by Order and can be the same as Id (Can be used as an order identifier)
Email	Required	String
Id	Required	String	(Can be used as an order identifier)
Currency	Required	String	Check the supported currencies
Total	Required	Double
Subtotal	Required	Double
Taxes	Required	Double
Payment Method		String
Financial Status	Required	String	Supported status: authorized, paid, partially_paid, pending, refunded, partially_refunded, voided
Refunded Amount	Required	Double
Discount Amount	Required	Double
Discount Code		String
Shipping Method		String
Shipping Country		String
Shipping	Required	Double
Source		String
Created at	Required	DateTime	Date format: yyyy-MM-dd HH:mm:ss Z
Paid at		DateTime	Date format: yyyy-MM-dd HH:mm:ss Z
Fulfilled at		DateTime	Date format: yyyy-MM-dd HH:mm:ss Z
Lineitem quantity	Required	Double
Lineitem name	Required	String
Lineitem price	Required	Double
Lineitem discount	Required	Double
Lineitem fulfillment status	Required	String	Supported status: pending, partial, restocked, fulfilled
Lineitem sku	Required	String
Vendor		String