API: Identifiers

What It Does

The Identifiers API provides two RPCs for managing product identifiers: one for reading all identifiers (active and retired) and one for creating or updating identifiers.

Who It’s For

API integrators and automated systems that need to manage product identifiers programmatically.

Reading Identifiers

list_product_identifiers

Returns all identifiers for a product, including both active and retired entries.

Required inputs:

What it returns:

A JSON object containing:

1
{
2
  "ok": true,
3
  "product_id": "<uuid>",
4
  "identifiers": [
5
    {
6
      "identifier_type": "gtin",
7
      "identifier_value": "05060012345678",
8
      "identifier_value_normalized": "05060012345678",
9
      "status": "active",
10
      "created_at": "2026-01-15T10:00:00Z",
11
      "created_by": "<uuid>",
12
      "deactivated_at": null,
13
      "deactivated_by": null
14
    }
15
  ]
16
}

Key details:

• Results are ordered: active identifiers first, then most recently retired.
• Numeric types (GTIN, EAN, UPC) include both identifier_value (raw stored value) and identifier_value_normalized (digits-only presentation value).
• SKU values have the same raw and normalised value.

Authentication: Required. The caller must be authenticated and have access to the specified brand.

Writing Identifiers

set_product_identifier

Creates or updates an identifier for a product. If an active identifier of the same type already exists, it is retired and replaced.

Required inputs:

What it returns:

1
{
2
  "ok": true,
3
  "product_id": "<uuid>",
4
  "identifier_type": "gtin",
5
  "identifier_value": "05060012345678",
6
  "status": "active"
7
}

Key details:

• SKU: routed through the SKU alias swap mechanism with case-insensitive uniqueness.
• GTIN / EAN / UPC: routed through the numeric alias helper with digits-only normalisation.
• The previous active identifier (if any) is automatically retired.
• Cached fields (products.sku, products.gtin) are updated automatically via write-through.

Authentication: Required. The caller must be authenticated and hold an admin role for the specified brand.

Limits & Notes

• Both RPCs require authentication; they are not callable by unauthenticated or anonymous users.
• Write access requires the admin role — read access requires brand membership.
• Identifier type is case-insensitive on input but stored in a canonical form.
• An identifier value cannot be shared across products within the same brand and type while active.

FAQ