RetailID SDK

Official SDKs for integrating with Metrc RetailID.

RetailID enhances supply chain visibility through unique QR code labeling. Each label encodes a batch identifier and index into a compact, scannable URL—enabling product traceability, authenticity verification, and streamlined operations from production to point of sale.

Use these SDKs to encode and decode RetailID labels in your applications.

Available SDKs

Language	Package	Version	Install
JavaScript	@metrc/retailid	0.10.0	npm install @metrc/retailid
Python	retailid	0.10.0	pip install retailid
Java	retailid-sdk	1.0.0	Maven (see below)

Quick Examples

Encoding

Create a short URL from a batch ID and index:

• default domain in the SDK is 1A4.COM - we're using a demo domain for our examples so we pass in a custom domain

JavaScript

import { getShortUrl, ObjectId } from '@metrc/retailid';

const batchId = new ObjectId('ABCDEF012345670000027190');
const url = getShortUrl(batchId, 485, {domain: "d.1a4.com"});
// => "HTTPS://D.1A4.COM/10NOIEYKAJDG6CF0EXGJL"

Python

from retailid import ObjectId, get_short_url

batch_id = ObjectId('abcdef012345670000027190')
url = get_short_url(batch_id, 485, domain="d.1a4.com")
# => "HTTPS://D.1A4.COM/10NOIEYKAJDG6CF0EXGJL"

Java

import com.retailid.ObjectId;
import com.retailid.RetailId;

EncodeOptions customDomain = new EncodeOptions().setDomain("d.1a4.com");
ObjectId batchId = new ObjectId("abcdef012345670000027190");
String url = RetailId.encode(batchId, 485, customDomain);
// => "HTTPS://D.1A4.COM/10NOIEYKAJDG6CF0EXGJL"

Decoding

Parse a short URL back to its components:

JavaScript

import { RetailIdPair } from '@metrc/retailid';

const pair = new RetailIdPair('HTTPS://D.1A4.COM/10NOIEYKAJDG6CF0EXGJL');
console.log(pair.batchId.toHexString()); // "abcdef012345670000027190"
console.log(pair.index);                  // 485

Python

from retailid import RetailIdPair

pair = RetailIdPair('HTTPS://D.1A4.COM/10NOIEYKAJDG6CF0EXGJL')
print(pair.batch_id.to_hex_string())  # "ABCDEF012345670000027190"
print(pair.index)                      # 485

Java

import com.retailid.RetailIdPair;

RetailIdPair pair = new RetailIdPair("HTTPS://D.1A4.COM/10NOIEYKAJDG6CF0EXGJL");
System.out.println(pair.getBatchId().toHexString()); // "ABCDEF012345670000027190"
System.out.println(pair.getIndex());                  // 485

URL Formats

RetailID supports two encoding formats:

Format	URL Pattern	Case	Use
Base36	HTTPS://1A4.COM/<CODE>	Uppercase	Default, recommended
Base64	https://1a4.com/<CODE>	Mixed	Legacy support

Base36 encoding produces case-insensitive codes using only alphanumeric characters (0-9, A-Z), making them easier to type manually if needed.

Core Concepts

ObjectId

A 12-byte identifier compatible with MongoDB ObjectIds. The first 4 bytes encode a timestamp, which is used for validation.

VarInt

Variable-length integer encoding (LEB128). Small indices use fewer bytes, keeping URLs compact.

Installation

JavaScript / TypeScript

npm install @metrc/retailid

Works in Node.js and browsers. Provides TypeScript definitions.

Python

pip install retailid

Requires Python 3.9+. Zero production dependencies.

Java

Add to your pom.xml:

<dependency>
    <groupId>com.retailid</groupId>
    <artifactId>retailid-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Requires Java 11+. Zero production dependencies.

API Reference

See the individual SDK READMEs for complete API documentation:

• JavaScript SDK
• Python SDK
• Java SDK

License

MIT