# RFID API Guide

## Purpose

Yellow Dog supports RFID capabilities through third-party integration partners. To enable
accurate interpretation of RFID tags printed by Yellow Dog, we expose the identifier values
used as the basis for EPC (Electronic Product Code) generation.

This guide explains how Yellow Dog uses RFID tags to encode and detect unique EPC values.
It also explains how each Yellow Dog EPC value has a GTIN component which can be
retrieved from the **epcGTIN** property now available through our Item API endpoints.

## How Yellow Dog EPC Tags Use GTIN

Each RFID label printed by Yellow Dog contains an EPC value encoded into the RFID tag’s
EPC memory bank. This EPC value consists of a two part code:

- A GTIN payload (epcGTIN)
- A serial/sequence number to uniquely identify each tag instance


### Example

- GTIN: 10000000017999
- Serial/sequence number: 100000000004


The resulting EPC memory bank value will be encoded as:

- HEX: 30340000006369d74876e804


This corresponds to the EPC URI:

- urn:epc:tag:sgtin-96:1.0000000.101799.100000000004


## What is epcGTIN?

The epcGTIN property appearing in Yellow Dog API endpoints refers to the
**GTIN payload** component of EPC values stored in RFID tags printed by Yellow Dog.
Each GTIN14 value is associated with only one item.

Since each item may be referenced by more than one GTIN14 value, the epcGTIN property
is an array of GTIN14 values associated with that item.

This array includes:

- The current GTIN used for newly printed RFID labels
- Any historical GTIN values previously used for that same item


Integrators should use these GTIN values when decoding EPCs read from Yellow Dog RFID tags.

## Important Notes

### GTIN14 is Not the Yellow Dog SKU

The GTIN14 value is a unique identifier stored per item in the Yellow Dog database.

- Depending on the Yellow Dog system configuration, the generated GTIN-14 value
may match the Yellow Dog item SKU
- It is used specifically as part of RFID EPC generation


## API Availability

- The epcGTIN field is available in api responses from fetch API version 3.27.0 and above
(Feb 2026).
- The epcGTIN field is available only for database version 377 and above with a build code ≥
2025.12.24.
- This is the first release where the GTIN schema exists.


## Supported API Endpoints

The following endpoints now return epcGTIN property with an array of strings when the
expand=GTIN is included in the request:

- GET /stores/:id/items
- GET /items
- GET /items/:id


## Response Format

The API returns epcGTIN as an array of GTIN14 strings.

### Example


```json
[
  {
    "id""description": "abcdx0":,
    "itemDesc abcdx0",

    ... additional prexisting fields

    "epcGTIN": [
      "10001000012457"
    ]
  },
  {
    "id": "beefx0",
    "description": "itemDesc beefx0",

    ... additional prexisting fields

    "epcGTIN": [
      "10001000012487",
      "10000000045687"
    ]
  }
]
```

## Integration Workflow

When interacting with Yellow Dog-generated RFID tags, integrators should:

1. Read the EPC memory bank from the RFID tag
2. Decode the EPC into its URI or component fields
3. Extract the GTIN value
4. Look up that GTIN in the integrator’s system mapping
5. Resolve it back to the Yellow Dog ItemID or SKU
6. Use other Yellow Dog API endpoints for item-level operations


## Summary

The epcGTIN field enables integrators to correctly interpret Yellow Dog RFID tags by
exposing the GTIN payloads used in EPC creation.

This ensures consistent mapping between RFID reads and Yellow Dog item identities
across all supported API endpoints.