Orders | Kevel Audience

Export order data to import into Kevel Audience.

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

There are 4 main use cases for importing orders into Kevel Audience:

Minimize under-Reporting of Kevel Ad Server Conversions

Kevel Audience enhances transactions by associating them with all reliable user identifiers. For example, if a user sees an ad tracked via an anonymous ID and later makes an offline purchase using a loyalty card, Kevel can link that purchase back to the original impression. This helps Retail Media customers avoid under-reporting conversions within their ecosystem.

Bootstrap Kevel Audience Using past Order Records

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.

Sync Kevel Audience Orders with Your CRM for Data Accuracy

Orders can change their state (for example, becoming canceled or refunded) without an explicit event from the user on the website. In these 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 keep Kevel Audience informed with accurate order information, order data is typically imported on a regular schedule.

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.

Troubleshooting

After an order import completes, including dry runs, the result may include warnings that highlight data quality issues. The questions below cover the most common ones.

Why does my import show a "heavy users" warning?
This warning appears when a single user ID accounts for ≥2% of the total orders in the file. The import still processes normally, but the affected user IDs are listed so the issue can be investigated before it affects segmentation or downstream systems. The most common cause is a mismatch in the user-identifier column — for example, a shared, placeholder, or system-generated value used instead of a unique per-user identifier. Profiles with an unusually high number of orders can skew segmentation results and strain downstream processing.

What to do: verify that the userId and userIdType columns contain the correct per-user identifiers for each row.

Why does my import show a "repeated order IDs" warning?
All line items for a given order must appear in consecutive rows. The importer closes an order as soon as a row with a different order ID is encountered; if the same order ID reappears later in the file, those rows are treated as an update to the already-closed order rather than part of the original. This has practical consequences: attribution forwarding only considers the first group of line items for each order. When ≥2% of the import's orders are affected, a warning is shown listing example order IDs.

What to do: ensure the file is sorted so that all rows belonging to the same order are grouped together before uploading.

Why are some imported orders generating orderUpdate events instead of orderPlace?
When an order ID is already known to Kevel Audience — for example, because a tracking event for that order was previously collected — the import is treated as an update to the existing order rather than a new placement. This generates an orderUpdate event instead of orderPlace. This is expected behavior when syncing CRM data with orders that were already tracked in real time. If the result is unexpected, verify that the orderId values in the import file match exactly the order IDs sent in tracking events. A mismatch (for example, a different format or prefix) will cause orders to appear new to the system even when they shouldn't.

Why aren't product details being updated after I refreshed the product feed?
Product feed enrichment only fills in attributes that are absent from the imported order — it never overwrites values already present in the file. Additionally, enrichment happens at import time using the product feed available then; updating the feed afterward does not retroactively update orders that have already been imported.

What to do: To apply a refreshed product feed to existing orders, re-import those orders. The new import will pick up the updated feed data for any attributes not supplied in the file itself.

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 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. See note below.
• 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 main order fields past the first row, those can be left empty as they will be ignored.
• 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.

Caution
All line items for the same order need to appear in consecutive rows in the CSV file. The appearance of a line item row, with a different order id from the previous rows, closes the order being ingested and completes the order ingestion process for it - including downstream event issuing of a new order event. If the same order id shows up later (even in the same file) with other line items, those will be treated as an update to the order, not part of the initial and original order event. This has practical consequences, for example, attribution forwarding will only consider the first set of line items that were ordered and not any subsequent rows.

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.