Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideLegal TermsGitHubDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide

Import data using CSV

You can import your customer, product, order, event and custom data into Optimizely Data Platform (ODP) using CSV files. You should use this method for historical data uploads rather than ongoing data synchronization.

Upload data

To upload your data with a CSV file:

  1. Go to Account Settings > Integrations.
  2. Click Upload CSV.
  3. You can drag and drop your file onto the page or click browse to search for the file on your device.

📘

Note

Each file you upload must meet the format and naming requirements described below.

File format requirements

️ Warning

Values that are blank ("") or null will DELETE the field value.

For example, if you upload a file with a gender column and there is a customer record without that column filled, that will erase what is presently on the customer record.

  • Values must be encoded with UTF-8.
  • Values must be comma-delimited.
  • Records must end with a newline (\n), and no carriage return (\r) or newline (\n) may exist within a record.
  • Optionally, values must be quoted using double quote (") characters. You must quote any field containing a double quote. The escape character for an embedded quote is a second quote character. (For example: "Customers think this product is ""Amazing!""")
  • Each record must contain exactly the same number of fields as the header does,
  • Date/time fields must be formatted as follows:
Date FormatExample
Unix timestamp/epoch1435708800
ISO 86012019-04-11T18:43:29+00:00
2019-04-11T18:43:29Z
2019-04-11
%Y-%m-%d %H:%M:%S%:z2014-09-01 13:34:08+00:00
%Y-%m-%d %H:%M:%S2014-09-01 13:34:08
%m/%d/%y %H:%M09/01/14 13:34
%m/%d/%y %H:%M:%S09/01/14 13:34:08
%m/%d/%Y %H:%M:%S09/01/2014 13:34:08
%m/%d/%Y %H:%M09/01/2014 13:34

🚧

Caution

If time and time zone are not provided, the time is assumed to be 12 AM UTC.

Error handling

Any record that contains an invalid field is ignored. If more than 1% of the data is invalid, the entire file is rejected. Go to Account Settings > Activity Log to view the status of the uploads. On that page, you can view any errors generated and successful upload entries.

File name requirements and example CSV files

📘

Note

The example files are simple examples. See the ODP schema section to learn about available default and custom fields and objects.

ObjectFile name prefixExample fileComments
Customerszaius_customerszaius_customers_example.csv
Productszaius_productszaius_products_example.csv
Orderszaius_orderszaius_orders_example.csvSee the Orders fields section
Eventszaius_eventszaius_events_example.csvUse an identifier field, such as order_id, to properly associate the event with a customer profile.
Listszaius_list Upload to a Single List
zaius_list_yourlistidhere.csv

Upload to Multiple Lists
zaius_list_example.csv
See the Lists imports section
Customzaius_customobjectzaius_customobject_example.csvReplace customobject with the name of the custom object. All custom object updates must include the primary key (or keys in the case of composite keys) in the file (for example, id).

Orders fields

Orders in ODP are represented both as Events and as Orders objects. The Events object stores item-level fields, meaning products that a customer purchased. The Orders object stores top-level order fields, meaning the order total, taxes, discounts and customer information. Format the file using one of the following options:

  • (Recommended) Repeat the top-level order fields for each line item in a purchase. The top-level fields must be identical on each row of the purchase.
  • Leave the top-level order field blank after the first row for each subsequent line in the purchase and only provide shared and item-level fields.
FieldShared/top-level/item-levelComments
actionsharedvalue should be one of the following:
`purchase refund return cancel`
order_idsharedrequired
tssharedrequired
identifiersharedany identifier is accepted
totaltop-level
discounttop-level
subtotaltop-level
taxtop-level
shippingtop-level
coupon_codetop-level
first_nametop-level
last_nametop-level
bill_addresstop-level
ship_addresstop-level
item_product_iditem-levelone row per line item
item_skuitem-levelone row per line item
item_priceitem-levelone row per line item
item_quantityitem-levelone row per line item
item_discountitem-levelone row per line item
item_subtotalitem-levelone row per line item

🚧

Caution

You cannot update order item-level fields (and the associated events) in the future; only top-level fields (for refunds, returns, cancellations).

📘

Note

Prefix all custom event fields with item_ to indicate the field exists on the Events object. Otherwise, ODP assumes you are attempting to update the Orders object.

Lists imports

  • Use an identifier field, such as email, in the CSV file. Optionally, include an action field (subscribe or unsubscribe). If you do not include an action column, ODP assumes a subscription for each email.
  • Only some accounts have the optional customer_id field. If your account does not have this field, do not include it in your import file. Additionally, if an email value is available, do not use the optional customer_id field. Only use the customer_id field when an email is not available.
  • A list import does not update the customer record with new or changed attributes, it just adds customers to a list/subscription.. To update the customer record with new or changed attributes, use the Customers import.

Import marketing consent data

In ODP, marketing consent is an attribute of each identifier (for example, each email address), not the entire customer profile, and is not updated by the customer data import.

To import marketing consent data, see Understand marketing consent. File names for consent imports begin with zaius_events. If no value is provided for consent (null), consent is implied.