# Importing transactions

### Overview

Importing transactions is an easy way to load large amounts of transactional data into UbiQuity. Rather than adding records manually against each contact, you prepare your data in a spreadsheet, export it as a CSV, and work through the import wizard.

Each transaction in your import must be linked to an existing contact in your database. UbiQuity uses a lookup field during the import to match each row to the correct contact.

To access the import screen, go to **Database > Manage Transactional Data** and select the transactional database you want to import into. Then go to **Manage Imports**, and click **Import Transactions.**

<figure><img src="/files/3kyYcYJbbA2CjS8sccRq" alt="A screenshot of the Import Transactions screen, accessed via Database then Manage Transactional Data then Manage Imports."><figcaption><p>The Import Trasnsactions screen, accessed via Database then Manage Transactional Data then Manage Imports.</p></figcaption></figure>

***

### Before you start

* Your file should be in CSV or text format. Excel workbooks are not supported — save your file as a CSV before importing.
* Your file should ideally have column headings in the first row.
* Every row in your import must correspond to an existing contact in your database. Rows that cannot be matched to a contact will be rejected.
* Check that your data is clean and consistent. UbiQuity validates data against field types during the import, and rows that do not match will be rejected.

***

### Step 1 — Select import Source

On the Import Source screen, select **Import from a file** and upload your CSV or text file. Confirm whether your the first row in your file contains field names.

<figure><img src="/files/DJsVSUTjDFqJH5kbHa6M" alt="A screenshot of the Import Source screen showing the import type selector, file upload, and a data preview."><figcaption><p>The Import Source screen showing the import type selector, file upload, and a data preview.</p></figcaption></figure>

***

### Step 2 — Map your fields

This step has two parts.

**Select lookup fields** — Choose the fields UbiQuity will use to identify which contact each transaction belongs to. This could be the contact's Reference ID, or another unique field in your database such as a Customer ID or Email Address.

**Map imported fields** — Match the remaining columns in your file to the correct fields in your transactional database. You can ignore columns that are not needed, map to existing fields, or create new fields directly from this screen.

<figure><img src="/files/mYA9mY9K1mzCYW4EbyEw" alt="A screenshot of the Field Mapping screen showing Lookup Fields mapping and Import Fields mapping, as well as a Data Preview below."><figcaption><p>The Field Mapping screen showing Lookup Fields mapping and Import Fields mapping, as well as a Data Preview below.</p></figcaption></figure>

***

### Step 3 — Analysing Data

UbiQuity analyses your data before making any changes. Rows that do not meet the required criteria are identified and rejected at this stage.

Rows are rejected here if the data does not match the expected field type — for example, text being imported into a number field.

If you see rejections at this stage you can download the error list and either cancel to fix your file and start again, or continue and download the errors at the end.

<figure><img src="/files/vy9M9nU0b1HTXkUSVLkD" alt="A screenshot of the Analysing Data screen showing the valid rows and invalid rows, and progress status."><figcaption><p>The Analysing Data screen showing the valid rows and invalid rows, and progress status.</p></figcaption></figure>

***

### Step 4 — Select update type

Choose how UbiQuity should handle the records in your file:

* **Append/Update** — Adds any transactions that do not already exist, and updates those that do. This is the most commonly used option.
* **Append** — Only adds new transactions. Any transaction that already exists will be skipped.
* **Update** — Only updates existing transactions. Any transaction that does not already exist will be skipped.

<figure><img src="/files/FDioAlqd9rNN04pbCAwA" alt="A screenshot of the Update Type screen showing the three import options — Append/Update, Append, and Update."><figcaption><p>The Update Type screen showing the three import options — Append/Update, Append, and Update.</p></figcaption></figure>

**Matching fields**

For Append/Update and Update imports, select the fields UbiQuity will use to identify whether a transaction already exists. This should be the unique field or fields set on your transactional database — for example, a unique transaction ID or order number.

<figure><img src="/files/UVOVTzhI3X22u1g5NSWd" alt="A screenshot of the Select Matching Fields screen with Order Number selected as the matching field."><figcaption><p>The Select Matching Fields screen with Order Number selected as the matching field.</p></figcaption></figure>

**Importing blank values**

If your file contains blank values for some fields, choose how UbiQuity handles them:

* **Preserve existing data** — Blank values in the file are ignored and existing values are kept.
* **Import blank values** — Blank values in the file will overwrite existing values.

<figure><img src="/files/2F0YjoSVKTXervRwJUfZ" alt="A screenshot of the Importing Blank Values screen showing the two options for handling blank fields in the import file."><figcaption><p>The Importing Blank Values screen showing the two options for handling blank fields in the import file.</p></figcaption></figure>

***

### Step 5 — Indexing Data

Indexing is the second stage where rows can be rejected. Rows fail here due to duplication issues rather than data formatting problems.

This happens when your file contains two rows with the same matching field values, or when a row matches multiple transactions already in the database. UbiQuity cannot determine which row to keep, so all affected rows are rejected.

As with the Analysing Data stage, you can download the error list and either cancel to fix your file or continue and review errors at the end.

<figure><img src="/files/4Z4zK3wDP3vgChZtj7Sr" alt="A screenshot of the Indexing Data screen showing the rows to insert, update and skip, and progress status."><figcaption><p>The Indexing Data screen showing the rows to insert, update and skip, and progress status.</p></figcaption></figure>

***

### Step 6 — Confirm

The final screen shows a full summary of your import before it runs, including the update type, matching criteria, blank value handling, and a mapping table showing how each column will be handled.

Review the details carefully, then confirm to run the import.

<figure><img src="/files/aqWRmEgBCgqz0QBkFhe9" alt="A screenshot of the Confirm Import Details screen showing a summary of import settings and a field mapping table."><figcaption><p>The Confirm Import Details screen showing a summary of import settings and a field mapping table.</p></figcaption></figure>

<figure><img src="/files/dcNvxtYR70vWsHbJ9T19" alt="A screenshot of the Import Contacts confirmation dialog where you type ACCEPT to run the import."><figcaption><p>The Import Contacts confirmation dialog where you type ACCEPT to run the import.</p></figcaption></figure>

**Import progress**

Once the import is running, the progress screen will show when it has completed, including a breakdown of rows inserted, updated, and skipped.

If any rows were skipped, an error file will be available to download at the bottom of the page. This file is only available for 7 days after the import.

<figure><img src="/files/BxKO9h6VlxAkba3n7olr" alt="A screenshot of the import progress screen showing the rows inserted, updated and skipped, with progress status."><figcaption><p>The import progress screen showing the rows inserted, updated and skipped, with progress status.</p></figcaption></figure>

***

### **Frequently asked questions**

**Why are rows being rejected during the analysing stage?** This is caused by data in your file not matching the field type in the transactional database. For example, importing text into a number field. Check the error file for details on which rows failed and why.

**Why are rows being rejected during the indexing stage?** This is caused by duplicate matching field values in your file, or a row matching multiple existing transactions in the database. UbiQuity cannot determine which row to keep, so all affected rows are rejected. Check your file for duplicates on the matching field.

**What should I select for matching fields?** Use the unique field or fields set on your transactional database. You can find these under **Database > Manage Transactional Data > Edit Database Fields** at the bottom of the page.

**What happens if a row cannot be matched to a contact?** Rows that cannot be matched to a contact in your database will be rejected. Make sure the lookup field values in your import file correspond to contacts that already exist in UbiQuity. You may need to import or update your contacts first before importing transactions.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ubiquity.co.nz/documentation/data-and-integrations/imports/importing-transactions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.