This article provides guidelines for importing and using customer order data in BlueConic, including storing data in profile properties and creating events on the profile timeline.
Profile properties that hold order data
There are no out-of-box order profile properties. The following list offers a best practice for loading order data into profile properties.
Name | ID | Type | Description |
Order date/time (all) | orderDateTimeAll | Date time | All order dates |
Order date/time (first order) | firstOrderDateTime | Date time | Date of the first order |
Order date/time (most recent) | orderDateTime | Date time | Date of the last order |
Order ID (most recent) | orderID | Text | For anonymous orders, the Order ID can be used as a unique identifier |
Ordered product categories (most recent order) | orderedProductCategories | Text | Product categories of the most recent order |
Ordered product categories (all) | orderedProductCategoriesAll | Text | Product categories for all orders |
Order timeline event type
The order event type can be loaded into BlueConic using this URL: https://plugins.blueconic.net/eventtype_order/index.xml.
While the properties of the default type can not be changed, the default order event type can be extended. Contact your Customer Success Manager for more information.
Property | Type | Description |
event_id | TEXT | Event ID generated by BlueConic or the connection |
order_id | TEXT | Order ID |
order_date | DATE | Date of the order |
affiliation | TEXT | The store or affiliation where the transaction occurred |
total_revenue | DECIMAL | Total revenue including shipping and tax, discounts, and promotions and coupons |
quantity | NUMBER | Total number of products ordered |
revenue | DECIMAL | Revenue excluding shipping and tax, including promotions and coupons |
shipping | DECIMAL | Shipping cost in absolute currency |
tax | DECIMAL | Tax in absolute currency |
discount | DECIMAL | Discount in absolute currency |
coupon | TEXT | Coupons used |
promotion | TEXT | Promotions that are active for this order |
currency | TEXT | Currency used for the transaction |
tag | TEXT | Tags to be used for filtering and searching |
product | ARRAY | All order lines in the order |
product.id | TEXT | Internal product ID of product ordered |
product.sku | TEXT | Product SKU |
product.upc | TEXT | Product UPC |
product.category | TEXT | Product Category |
product.name | TEXT | Name of the product |
product.variant | TEXT | Variant of the product (e.g. white, black, 32 GB, etc.) |
product.brand | TEXT | Brand of the product |
product.listprice | DECIMAL | List Price of order line (list price * number of items) |
product.netprice | DECIMAL | Net price paid for this order line |
product.quantity | NUMBER | Number of products ordered |
product.coupon | TEXT | Coupon used for this order line |
product.promotion | TEXT | Promotion used for this product (e.g. free shipping or 10% percent off) |
product.tag | TEXT | Product tags to be used for filtering and searching |
product.shippingcost | DECIMAL | Shipping cost for the product in absolute currency |
product.shippingdate | DATE | Expected date of shipment of this order line |
product.deliverydate | DATE | Expected date of delivery of this order line |
product.position | TEXT | Position of the product (for example which level in store, or place in search or page) |
product.url | TEXT | Webpage that gives more information about the product |
product.image_url | TEXT | URL that shows an image of the product |
Order refund timeline event type
Order refunds have to be imported as separate timeline events in BlueConic. The order refund event type can be loaded into BlueConic using this URL: https://plugins.blueconic.net/eventtype_order_refund/index.xml
Property | Display Name | Type | Description |
event_id | Event Identifier | TEXT | Event ID generated by BlueConic |
source_order_id | Source Order | TEXT | Source Order ID from the original order |
status | Refund Status | TEXT | One of 'order_refund_requested', 'order_returned', 'order_refunded' |
refund_id | Refund Identifier | TEXT | Reference ID of a specific refund process |
quantity | Quantity | NUMBER | Number of items refunded |
total_value | Refund Value | DECIMAL | Total value of refunded order |
currency | Currency | TEXT | Currency used for the refund |
product |
| - | All products returned and refunded |
product.id | Product ID | TEXT | Internal product ID of product ordered |
product.sku | Product SKU | TEXT | Product SKU |
product.upc | Product UPC | TEXT | Product UPC |
product.category | Product Category | TEXT | Product Category |
product.name | Product Name | TEXT | Name of the product |
product.variant | Product Variant | TEXT | Variant of the product (eg white, black, 32GB, etc.) |
product.brand | Product Brand | TEXT | Brand of the product |
product.netprice | Product Net Price | DECIMAL | Net price paid for this orderline |
product.quantity | Product Quantity | NUMBER | Number of products ordered |
product.url | Product URL | TEXT | Webpage that gives more information about the product |
product.image_url | Product Image URL | TEXT | URL that shows an image of the product |
FAQs
Can I use order data with AI Workbench?
Yes, the following prebuilt notebooks use order events stored on the profile's timeline:
Customer lifetime value (CLV) notebook: Based on the order history, you can extrapolate what you expect customers to spend on you for a given time frame.
Recency, frequency, and monetary (RFM) value notebook: For each variable, customers are divided into groups (low frequency, mid frequency, high frequency, for example).
What are the file requirements for importing CSV order data?
CSV files must be UTF-8 encoded and follow RFC 4180 standards. Key formatting rules include:
Fields without double quotes cannot contain double quotes.
Values with double quotes, delimiters, line breaks, or spaces must be enclosed in double quotes.
If a field contains double quotes, they must be escaped by preceding them with another double quote.
How can I prevent duplicate order events when importing data?
Each order event must have a unique identifier to avoid duplicates when importing the same order feed multiple times. Ideally, the order feed includes a unique order ID, which can be mapped to the order event ID during import. If a unique ID isn’t available, you may need to combine multiple columns or develop a data processor plugin to generate one.
How should order data be structured for import?
Ideally, order data is split into two files:
Order Header File – Contains aggregated order details (total quantity, total revenue) and PII data (name, address, email, customer ID).
Order Details File – Includes line-by-line product details, such as retail price, paid price, quantity, and shipping date.
If order data is delivered in a single file, ensure that:
Each product has a separate line in the CSV file.
Order lines are grouped by Order ID to maintain data integrity.
This structure ensures a clear separation of order summaries and item-level details while preventing data inconsistencies.
How can I import order refunds into BlueConic?
A separate import goal must be set up for order refund events. There are two ways to configure this:
Separate Order Refund Feed – Ideally consists of two files: a header and an item file. If using a single file, a data processor is required to roll up the data.
Refunds in the Regular Order Feed – A data processor plugin is needed to separate refund orders from regular orders. This processor must be activated for both the regular and refund import goals.
For assistance, contact your Customer Success Manager.