Skip to main content
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

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:
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.