Container Code Validation in Node.js — ISO 6346 Explained

1. What is ISO 6346?

ISO 6346 is an international standard that defines the coding, identification, and marking of shipping containers used in intermodal freight transport. Published by the International Organization for Standardization, it assigns each container a globally unique 11-character code consisting of letters and digits.

The standard is maintained by the Bureau International des Containers (BIC), which operates the global registry of owner codes. Every container manufacturer, leasing company, and shipping line must register its owner code with BIC before putting containers into service.

In logistics software, container codes appear in bills of lading, customs declarations, terminal operating systems, and vessel manifests. A single transposition error can route a container to the wrong yard, delay customs clearance, or generate phantom inventory.

2. Anatomy of a container code

An ISO 6346 container code has exactly 11 characters, split into four parts:

3. The mod-11 check digit algorithm

ISO 6346 uses a weighted mod-11 algorithm. Each of the first 10 characters is assigned a numeric value, multiplied by a power-of-2 weight, and the sum modulo 11 produces the check digit. If the result is 10, it is mapped to 0.

Let's walk through CSQU3054383:

// containerCheckDigit.js — ISO 6346 mod-11 check digit
function validateContainerCode(code) {
  code = code.toUpperCase().replace(/[\s-]/g, '');
  if (!/^[A-Z]{3}[UJZR]\d{7}$/.test(code)) return false;

  // Letter-to-number mapping: A=10, B=12, C=13, ... (skip multiples of 11)
  function charValue(ch) {
    if (ch >= '0' && ch <= '9') return parseInt(ch, 10);
    const n = ch.charCodeAt(0) - 'A'.charCodeAt(0);
    // value = 10 + n + floor((n + 8) / 10) — skips 11, 22, 33
    return 10 + n + Math.floor((10 + n) / 11);
  }

  let sum = 0;
  for (let i = 0; i < 10; i++) {
    sum += charValue(code[i]) * Math.pow(2, i);
  }

  const checkDigit = sum % 11 % 10; // if mod-11 gives 10, map to 0
  return checkDigit === parseInt(code[10], 10);
}

console.log(validateContainerCode('CSQU3054383')); // true  ✓
console.log(validateContainerCode('CSQU3054384')); // false ✗ wrong check digit
console.log(validateContainerCode('MAEU1234567')); // checks dynamically

4. Category codes — U, J, Z, R

The fourth character of a container code identifies the type of equipment. ISO 6346 defines four category identifiers:

5. Why container code validation matters

6. The production-ready solution

The IsValid Container Code API validates the format, computes the ISO 6346 mod-11 check digit, and returns the parsed components — owner code, category, serial number, and check digit — in a single call.

Full parameter reference and response schema: Container Code Validation API docs →

7. Node.js code example

import { createClient } from '@isvalid-dev/sdk';

const iv = createClient({ apiKey: process.env.ISVALID_API_KEY });

// ── Example usage ────────────────────────────────────────────────────────────

const result = await iv.containerCode('CSQU3054383');

if (!result.valid) {
  console.log('Invalid container code');
} else {
  console.log('Owner code:', result.ownerCode);       // → 'CSQ'
  console.log('Category:', result.categoryName);       // → 'Freight container'
  console.log('Serial:', result.serialNumber);         // → '305438'
  console.log('Check digit:', result.checkDigit);      // → '3'
}

// Validate container codes in a vessel manifest
async function processManifest(containers) {
  const results = [];

  for (const entry of containers) {
    if (!entry.containerCode) {
      results.push({ ...entry, status: 'missing' });
      continue;
    }

    const check = await validateContainerCode(entry.containerCode);

    if (!check.valid) {
      results.push({ ...entry, status: 'invalid' });
      continue;
    }

    results.push({
      ...entry,
      containerCode: entry.containerCode.toUpperCase().replace(/[\s-]/g, ''),
      ownerCode: check.ownerCode,
      category: check.categoryName,
      serialNumber: check.serialNumber,
      status: 'valid',
    });
  }

  return results;
}

8. cURL example

Validate a standard freight container:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/container-code?value=CSQU3054383"

Validate a container with an invalid check digit:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/container-code?value=CSQU3054380"

Validate a reefer container:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/container-code?value=TRIU4567890"

9. Understanding the response

Valid container code:

{
  "valid": true,
  "ownerCode": "CSQ",
  "categoryCode": "U",
  "categoryName": "Freight container",
  "serialNumber": "305438",
  "checkDigit": "3"
}

Invalid container code:

{
  "valid": false
}

10. Edge cases — tanks, reefers, and more

// The critical line in the check digit calculation:
const checkDigit = sum % 11 % 10; // double-mod handles 10 → 0