Units

What is a unit?

A unit is the digital identity of a single physical item - its digital twin and its certificate of authenticity. Even if two items are identical SKUs (same product, same size, same color), each one is its own unit with its own identity, its own chip, and its own issuance history. Units live inside a collection. A collection defines the group (a product line, a drop, a release); a unit is one item within it.

Why units matter

Register items. Create a unit for each physical item when it enters your workflow - before it ships, before it’s paired to a chip.
Map to your inventory. Use external_id to tie each unit back to your own SKU, order line, or serial number. Filter lists by external_id to look up units without storing Endstate IDs.
Track issuance. A unit’s collection.token.status tells you whether the item has been issued - pending means the unit exists but has no chip yet; active means a chip is paired and the unit has a collection.token.serial within its collection.
Verify on tap. When a user taps an NFC chip, the API returns the unit record attached to it. That record is what you display, validate, or act on.

Unit object

string (UUID)

The unit’s unique identifier. Stable; use this as your durable reference in Endstate.

string | null

Your own identifier for this item - SKU, order line ID, serial number, or any string you choose. Must be unique within your environment if provided. Null if not set.

string | null

A human-readable label for the item (e.g. "Black Hoodie - Size M"). Optional; null if not set.

string | null

A plain-text description of the item. Null if not set.

object | null

Free-form JSON you attach to this unit. Use this for any item-level metadata that does not have a dedicated field - color, size, batch number, custom fields. No enforced schema; store whatever your integration needs.

string | null

Where a user is sent after tapping this unit’s chip. Overrides the collection and organization-default redirects. Null if not set - resolution then falls through to the collection redirect, then your organization default. See Tap redirects.

string (ISO-8601)

When the unit was created.

object

The collection this unit belongs to.

Show collection fields

string (UUID)

The collection’s unique identifier.

string | null

The collection’s name.

string | null

Your identifier for the collection, if set.

object

Registry details for the collection - address (string), chain_id (integer), and status (deploying, active, or failed). See Collections for what each field means.

object

The unit’s issuance status within this collection.

Show token fields

string

The unit’s issuance status. pending - the unit has no chip paired yet. active - a chip is paired and the unit has been issued a serial number within the collection.

integer | null

The unit’s serial number within its collection. Assigned when collection.token.status becomes active. Null while still pending. Serial numbers are assigned in the order items are issued.

array

The NFC chips paired to this unit. Most units have exactly one chip; the array is empty until a chip is paired.

Show chip fields

string

The chip’s identifier (10 hex characters). This is the value that appears in the tap URL.

boolean

true for test chips used in integration testing without hardware. false for chips on real physical items.

integer

The number of times this chip has been successfully verified.

string (ISO-8601)

When the chip was paired to this unit.

Create a unit

POST /v1/units

string (UUID)

required

The ID of the collection this unit belongs to. The collection must already be provisioned (contract.status: "active"). Required.

string

Your own identifier for this item. Must be unique within your environment. Optional.

string

A human-readable label for the item. Optional.

string

A plain-text description of the item (1–10,000 characters). Optional.

object

Free-form JSON metadata to attach to the unit. Optional.

string

Where a user is sent after tapping this unit’s chip. Must be a valid absolute URL. Optional - you can also set or change it later with PATCH /v1/units/ {unit_id}. See Tap redirects.

Example

await endstate.units.create({
  collectionId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  externalId: "sku-hoodie-black-m-001",
  name: "Black Hoodie - Size M",
  attributes: { color: "black", size: "M" },
});

curl https://api2.endstate.io/v1/units \
  -X POST \
  -H "Authorization: Bearer end_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": "sku-hoodie-black-m-001",
    "name": "Black Hoodie - Size M",
    "attributes": { "color": "black", "size": "M" }
  }'

Response

{
  "id": "8e1a7f50-90ab-4cde-f012-3456789abcde",
  "external_id": "sku-hoodie-black-m-001",
  "name": "Black Hoodie - Size M",
  "description": null,
  "attributes": { "color": "black", "size": "M" },
  "redirect_url": null,
  "created_at": "2026-05-14T10:30:00.000Z",
  "collection": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Summer Drop 2026",
    "external_id": null,
    "contract": {
      "address": "0x1111111111111111111111111111111111111111",
      "chain_id": 84532,
      "status": "active"
    },
    "token": {
      "status": "pending",
      "serial": null
    }
  },
  "chips": []
}

The unit is returned at the top level, like every single-resource response - see Response shape. It is created with collection.token.status: "pending"; no serial is assigned yet - that happens when a chip is paired. See Lifecycle below.

Update a unit

PATCH /v1/units/{unit_id}

string

Your own identifier for this item. Must be unique within your environment; a value another unit already uses returns unit.already_exists, and the unit does not change. Cannot be cleared.

string

A human-readable label for the item. Send null to clear.

string

A plain-text description of the item (1–10,000 characters). Send null to clear.

object

Free-form JSON metadata for the unit. Replaces the full attribute set - there is no merge, so send every key you want to keep. Send null to clear.

string

Where a user is sent after tapping this unit’s chip. Send null to clear. See Tap redirects.

Example

await endstate.units.update("8e1a7f50-90ab-4cde-f012-3456789abcde", {
  externalId: "sku-hoodie-black-m-002",
  attributes: { color: "black", size: "M", serial: "SN-0002" },
});

curl -X PATCH https://api2.endstate.io/v1/units/8e1a7f50-90ab-4cde-f012-3456789abcde \
  -H "Authorization: Bearer end_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "sku-hoodie-black-m-002",
    "attributes": { "color": "black", "size": "M", "serial": "SN-0002" }
  }'

Response

{
  "id": "8e1a7f50-90ab-4cde-f012-3456789abcde",
  "external_id": "sku-hoodie-black-m-002",
  "name": "Black Hoodie - Size M",
  "description": null,
  "attributes": { "color": "black", "size": "M", "serial": "SN-0002" },
  "redirect_url": null,
  "created_at": "2026-05-14T10:30:00.000Z",
  "collection": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Summer Drop 2026",
    "external_id": null,
    "contract": {
      "address": "0x1111111111111111111111111111111111111111",
      "chain_id": 84532,
      "status": "active"
    },
    "token": {
      "status": "pending",
      "serial": null
    }
  },
  "chips": []
}

Send only the fields to change - a field you leave out keeps its value. The body must contain at least one field; an empty body returns validation.failed. All sent fields change in one write, or none change.

Lifecycle

Units move through a simple two-state lifecycle:

Create the unit

POST /v1/units - the unit is created with collection.token.status: "pending" and an empty chips array. No serial number yet.

Pair a chip

POST /v1/chips with unit_id and the chip’s identifiers. Pairing links the physical item to its digital record and triggers issuance.

Unit is issued

Issuance is asynchronous. Poll GET /v1/units/{unit_id} until collection.token.status is "active". When active, collection.token.serial holds the unit’s serial number within the collection.

Poll GET /v1/units/{unit_id} to check issuance status.

Endpoints

Method	Path	Description
`POST`	`/v1/units`	Create a unit
`GET`	`/v1/units`	List units (cursor-paginated; filter by `external_id`, `collection_id`, `status` or `chip`)
`GET`	`/v1/units/{unit_id}`	Fetch a single unit by ID - API key or session token
`PATCH`	`/v1/units/{unit_id}`	Update a unit’s content and `redirect_url`
`POST`	`/v1/units/{unit_id}/chip-replacements`	Replace the unit’s chip (until the unit is claimed)
`GET`	`/v1/units/{unit_id}/chip-replacements/{replacement_id}`	Poll a chip replacement’s status
`POST`	`/v1/units/{unit_id}/claims`	Claim the unit - session token required
`POST`	`/v1/units/{unit_id}/transfers`	Transfer the unit - session token required

These endpoints take an API key, with two exceptions: claim and transfer creation require a session token (status polling takes either), and the single-unit fetch accepts either credential - a session token reads only the unit it was issued for. See Credentials for header format and credential types. For full request/response schemas, see the API reference.

Next steps

Chips

Pair an NFC chip to a unit to complete its digital record and trigger issuance.

Collections

Understand how collections group units and define the serial-number namespace.

Tap redirects

Send a user to your own destination after they tap this unit’s chip.

Get started

Settings

Core concepts

API conventions

Updates

What is a unit?

Why units matter

Unit object

Create a unit

Example

Update a unit

Example

Lifecycle

Endpoints

Next steps

Chips

Collections

Tap redirects

​What is a unit?

​Why units matter

​Unit object

​Create a unit

​Example

​Update a unit

​Example

​Lifecycle

​Endpoints

​Next steps

Chips

Collections

Tap redirects

What is a unit?

Why units matter

Unit object

Create a unit

Example

Update a unit

Example

Lifecycle

Endpoints

Next steps