> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwoty.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Uniqueness constraints

> How Qwoty enforces data uniqueness during import.

## Overview

Qwoty enforces uniqueness on certain fields to prevent duplicate records and ensure data integrity. Understanding these constraints is essential for successful imports — especially when you want to update existing records rather than create new ones.

## Default unique fields

| Object              | Unique fields                                                                         |
| ------------------- | ------------------------------------------------------------------------------------- |
| **Master products** | `product_id`, `product_api_name`                                                      |
| **Products**        | `product_id`, `product_api_name`, `inventory[sku]` (when used as a deduplication key) |
| **Prices**          | `id`                                                                                  |
| **Customers**       | `id`, custom unique fields you define                                                 |

The `product_id`, `id` field (depending on the object) is Qwoty's internal identifier, auto-generated for each record. It uses UUID format (for example, `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`).

The `*_api_name` fields are human-readable, stable identifiers that you control. They're useful when migrating between environments or when you want a permanent reference that survives data resets.

## Custom unique fields

For [manageable objects](/user-guide/data-model/introduction#standard-vs-manageable-objects) like Customer and Contract Model, you can define additional unique fields under **Settings → Data → Data model**:

<Steps>
  <Step title="Open the object">
    Go to **Settings → Data → Data model** and click the manageable object.
  </Step>

  <Step title="Open the field">
    Click the field you want to make unique.
  </Step>

  <Step title="Mark as unique">
    Enable the **Unique** toggle in the field settings.
  </Step>
</Steps>

### Use cases for custom unique fields

* **External IDs** — store IDs from other systems (Salesforce ID, HubSpot ID, ERP customer code)
* **Business identifiers** — employee numbers, customer codes, internal product references
* **Alternative contact info** — VAT numbers, registration numbers

<Note>
  The field name `id` is reserved for Qwoty's internal UUID. Use a different name like `external_id`, `legacy_id`, or `erp_id` for identifiers from other systems.
</Note>

## Import behavior

### Creating new records

If a unique field value doesn't exist in Qwoty, a new record is created. Leave the ID column empty in your CSV — Qwoty generates a fresh UUID automatically.

### Updating existing records

If a unique field value matches an existing record, that record is **updated** with the new data. Only the columns present in your CSV are modified — other fields stay untouched.

<Tip>
  To update existing records reliably, **only map one unique field** (typically the ID). Mapping multiple unique fields at once can cause ambiguous matches.
</Tip>

### Duplicate detection during import

During the **Confirm** step, Qwoty validates your file:

* Duplicates within your file are flagged as validation errors
* Records with unique values that conflict with existing Qwoty records are flagged
* You can go back to the Mapping step or fix your source CSV before proceeding

Errors don't block the import — valid rows are still imported, and you can download the unimported rows after the import completes to fix and re-upload them.

## Best practices

1. **Remove duplicates** from your file before importing — sort by the unique field in your spreadsheet to spot them quickly
2. **Check for existing records** by exporting first, comparing against your file, and choosing whether to update or create
3. **Use external IDs** when migrating from other systems — they make round-trip imports straightforward
4. **Include the ID column** when you want to update existing records, and leave it empty when you want to create new ones

## Related

<CardGroup cols={2}>
  <Card title="Field mapping" icon="arrow-right-arrow-left" href="/user-guide/data-migration/reference/field-mapping">
    How fields are matched between your CSV and Qwoty.
  </Card>

  <Card title="Import relations" icon="link" href="/user-guide/data-migration/reference/import-relations">
    How to link records to their parents during import.
  </Card>

  <Card title="Data model" icon="diagram-project" href="/user-guide/data-model/introduction">
    Add custom fields and mark them as unique.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/user-guide/data-migration/reference/error-handling">
    What validation errors mean and how to fix them.
  </Card>
</CardGroup>