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

# External reference

> Use your own system's code, such as the SKU, to find and sync items.

Your system knows the SKU, the procedure code or the product id, not Need Alert's `id`. The item's `external_reference` field holds that code, so you don't need to keep your own map between the two systems.

## Rules

* Up to **100 characters**, free text. It isn't translated.
* **Unique per unit** among non-archived items. The same code may exist in different units: each shop has its own item.
* The match is **exact and case-sensitive**: `SKU-123` and `sku-123` are different references.
* Archiving the item frees the reference for a new item.
* Accepted on item `POST` and `PATCH`; `null` removes the reference.

## Find an item

```bash theme={null}
curl "$API/establishments/12/items?external_reference=SKU-123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

The filter is exact, not a search: `data` comes with one item or empty. For a search by name, use the `search` parameter.

## Conflict

Creating or editing an item with a reference another non-archived item of the same unit already uses answers **409**:

```json theme={null}
{
  "message": "Another item of this unit already uses this external reference.",
  "code": "item_external_reference_taken"
}
```

This also holds when two processes create the same item at the same time: one gets **201**, the other **409**.

## Pattern: find, otherwise create

To sync your product list:

**1. Look up by reference**

`GET /establishments/{establishment}/items?external_reference=<code>`.

**2. If it exists, update**

`PATCH /establishments/{establishment}/items/{item}` with what changed (`translations`, `status`, `queue_type`).

**3. If it doesn't, create**

`POST /establishments/{establishment}/items` with `external_reference` and an `Idempotency-Key`. A **409** here means another process created the item between your lookup and the creation: look it up again.

**4. When the product is discontinued, archive**

`DELETE /establishments/{establishment}/items/{item}` archives the item (it isn't deleted) and frees the reference.

In the dashboard, the field appears as **External reference (SKU)** in the item form. See the full walkthrough in [Use cases](https://docs.needalert.app/en/api/use-cases.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.