Importing transactions

Importing transactional data

By importing transactions to Synerise, you can prepare analyses of transactions. The output of the import is transaction.charge events generated on the profile cards of customers indicated in the imported file.

Requirements

• You need user permissions that grants you access to Simple Imports or/and Automation
• Prepare a .csv file that contains the data presented in the table below. If you use different names, you will be able to map them to the correct parameters during the import process.
  • Each row in the CSV represents one product. If an order contains multiple products, include one row per product and use the same orderId on each of those rows. The system groups rows by orderId and builds a single transaction.charge event with a products array.
  • All rows sharing the same orderId must be placed consecutively in the file. If rows from the same order are not grouped, the system will generate separate transactions instead of a single one.
  • Transaction-level fields (such as revenue, value, source) should be repeated identically on every row belonging to the same order.

For the full list of accepted values and formats, see the API reference.

• File requirements:

  • Spaces and special characters in the column headers are not allowed.
  • .csv files must be UTF-8 encoded.
  • If you don't have a value for an optional field, omit the column entirely rather than leaving the cell empty or setting it to null.
    • For numeric or composite fields (for example, discountAmount.amount, discountAmount.currency), leaving the cell empty while the column is present causes the entire row to fail import.
    • For custom attributes (for example, metadata.*), leaving the cell empty while the column is present clears any existing value for that attribute, the same as sending null. For Synerise-native attributes, sending null resets the attribute to its default value.
    • If only some rows in your file need a value for an optional field, split them into separate import files: one where the column is fully populated, and one where the column is omitted entirely.
  • Maximum file size: 200 MB.

• To add the original dates for transactions, include the recordedAt parameter in ISO 8601 format, otherwise, the transaction will be added with the date of the import. The following formats are supported:

  • UTC time with a Z suffix (for example, 2025-10-01T12:02:06Z)
  • Time with a timezone offset (for example, 2025-10-01T14:02:06+02:00 for UTC+2 or 2025-10-01T04:02:06-08:00 for UTC-8). All times are converted to UTC when saved in the database.
  If you send a transaction with a future timestamp, the timestamp is rejected and replaced with the time of import.

Tips for preparing a CSV file

• Recommended file metacharacters:
  • A character that splits columns (delimiter): ,
  • A character that is used to contain the text (quotation mark): "
  • A character (escape character) that changes the default interpretation of a sign or string followed by the escape character: /
• For more details about parameters and their accepted formats, click here.

Procedure

Selecting the file for import

In this part of the process, you will upload a file from your device.

1. Go to Data Modeling Hub > Imports > New import.
2. As the data type for import, select Transactions.
3. As the import method, select one of the following options:

   • Import a local file - To import a single .csv file to Synerise.

   • Import in Automation - To import a .csv, .json, .jsonl, and .xml files and execute periodical imports.

     Local FileAutomation

     1. Upload the .csv file by using the + Upload file or drop one here field.
     2. Optionally, you can customize the file metacharacters by clicking the arrow down icon.
        1. From the Delimiter dropdown, select the character that marks the end of a column.
        2. From the Quotation mark dropdown list, select the characters that contain the text or data type.
        3. From the Escape character dropdown lists, select the character which changes the default interpretation of a character or a string followed by the escape character.
     3. To proceed to the next step, click the Next button.

     Mapping the columns with parameters in Synerise

     In this part of the process, you will connect the columns from the file with their counterparts (the existing parameters) in Synerise. This way, you will point which parameters in Synerise will contain the event information from the imported file.
     During mapping, you can:

     • exclude parameters from the import.
     • create new event parameters in Synerise to map the data in the input file to them. Note that all custom parameters will be imported as additional transaction parameters.

     Remember that you can't add new columns to the imported file while mapping.

     1. Next to the file column name, from the dropdown list, select the corresponding parameter in Synerise. Perform this step for all columns in your file.
     2. To exclude a parameter from import, next to the column name, click this icon:
        Result: The icon changes to
     3. To proceed to the summary of the import, click Next.

     Counting revenue

     In this part of the process, optionally, you can enable automatic calculation of the revenue which is the multiplication of the item quantity by its price.

     1. Enable the Calculate revenue option.
     2. In the Product unit price field, from the dropdown list select the name of the column that contains the price of a single piece of an item.
     3. Confirm by clicking Next. Result: The summary of the import is displayed.
     4. After checking the import summary, to start the import, click Run import.
        Result: The output of the import is transaction.charge events generated on the profile cards of customers indicated in the imported file.

     Launching import

     After steps described above you'll be redirected to the mapping summary. If it's correct, to launch the import, click Run import.

     1. Select the method of delivering the file:
        • Local File - This option allows you to upload a file from your device.
        • SFTP protocol - This option allows you to upload a file from a server using the SFTP protocol.
        • HTTPS protocol - This option allows you to upload a file from a server using the HTTPS protocol.
        • Amazon S3 - This option allows you to upload a file from Amazon S3 bucket.
        • Azure - This option allows you to upload a file from Azure Blob Storage.
        • Google Cloud Storage - This option allows you to upload a file from Google Cloud Storage.
     2. Click Go to import template.
     3. Define the settings of the Scheduled Run node.
     4. Depending on the method of delivering the file, configure the settings of Local File or the Get File node that uses HTTP protocol or the Get File node that uses SFTP protocol.
     5. If the data requires modification, configure the settings of the Data Transformation node. If you have prepared the transformation rules for the data structure of the imported file, select it from the dropdown list. If not, create it from scratch.
        You can remove this node if your data doesn't require transformation.
     6. The rest of the nodes in the default template don't require any further configuration.
     7. If your workflow is ready, click Save & Run.