Barcode Types Reference

GET /v1/barcode/types returns the live registry of supported 1D symbologies. This page explains each entry, the data each one accepts, and how the API handles checksums — so you can pick the right barcode_type on the first try instead of debugging a 400.

Endpoint

GET /v1/barcode/types

Base URL: https://barcode.toolkitapi.io

Requires an X-API-Key header. Returns:

{
  "total": 11,
  "types": [
    {
      "name": "ean13",
      "description": "EAN-13 — European Article Number (retail)",
      "data_format": "12 or 13 digits (checksum auto-calculated)",
      "max_length": 13
    }
  ]
}

Supported symbologies

barcode_type Standard Accepted data max_length
code128 Code 128 Any ASCII characters none
code39 Code 39 A-Z, 0-9, space, - . $ / + % none
ean13 EAN-13 12 or 13 digits (checksum auto-calculated) 13
ean8 EAN-8 7 or 8 digits (checksum auto-calculated) 8
ean14 EAN-14 13 or 14 digits (checksum auto-calculated) 14
upca UPC-A 11 or 12 digits (checksum auto-calculated) 12
isbn13 ISBN-13 12 or 13 digits starting with 978/979 13
isbn10 ISBN-10 9 or 10 characters (digits + optional X check) 10
issn ISSN 7 or 8 digits for periodicals 8
pzn PZN (Pharmazentralnummer) 6 or 7 digits 7
itf Interleaved 2 of 5 Even number of digits none

Note

max_length is null for code128, code39, and itf — but the request body still caps data at 256 characters (BarcodeGenerateRequest.data, max_length=256). A longer value fails schema validation with 422 before the encoder is ever called.

Checksum behaviour

For the numeric retail and book symbologies the check digit is computed for you. Pass the short form and the API appends it:

Type You send Encoded
ean13 12 digits 13 digits, check digit added
ean8 7 digits 8 digits
ean14 13 digits 14 digits
upca 11 digits 12 digits
isbn13 12 digits 13 digits
issn 7 digits 8 digits
pzn 6 digits 7 digits

If you send the full-length form the API accepts it only when the trailing digit is already the correct checksum. Send a wrong check digit and the encoder raises a validation error (400) rather than silently "fixing" it.

code128, code39, and itf have no numeric checksum requirement; itf is otherwise strict about even length — pad with a leading zero.

Choosing a type

Use case Type Why
Internal asset tags, arbitrary strings code128 Dense, full ASCII, no length bookkeeping
Legacy industrial / logistics scanners code39 Widely supported by old readers; uppercase only
Retail products (EU) ean13 Required on EU retail packaging
Small retail packaging ean8 Fits tiny labels
Cartons / pallets / outer cases ean14 (or itf) GS1 logistics standard
Retail products (North America) upca Required on NA retail packaging
Books isbn13 (modern), isbn10 (legacy) Printed on back covers
Magazines / journals issn Periodical identifier
Pharmaceuticals (Germany) pzn German pharma standard
Numeric cartons read by ITF scanners itf Fixed-width numeric encoding

Request parameters (for context)

Barcode type is one field of a larger generate request:

Field Type Default Description
data string — Data to encode, max 256 chars
barcode_type string code128 One of the 11 types above
format string png png or svg
include_text boolean true Render human-readable text under the bars
fg_color string #000000 Bar colour, hex (max 9 chars — #RRGGBBAA allowed)
bg_color string #ffffff Background colour, hex
module_height number 15.0 Bar height in mm, 5.0–50.0
quiet_zone number 6.5 Quiet zone width in mm, 0.0–20.0

Full endpoint documentation: Barcodes.

Examples

List available types

curl "https://barcode.toolkitapi.io/v1/barcode/types" \
  -H "X-API-Key: YOUR_KEY"
const resp = await fetch("https://barcode.toolkitapi.io/v1/barcode/types", {
  headers: { "X-API-Key": "YOUR_KEY" },
});
const { total, types } = await resp.json();
console.log(`${total} symbologies`);
for (const t of types) console.log(t.name.padEnd(8), t.data_format);
from toolkitapi import Barcode

with Barcode(api_key="tk_...") as bc:
    catalog = bc.types()
    for t in catalog["types"]:
        print(f'{t["name"]:<8} {t["data_format"]}')

Generate with a computed check digit

# 12 digits in — the API appends the EAN-13 check digit
curl -X POST "https://barcode.toolkitapi.io/v1/barcode/generate" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": "400638133393", "barcode_type": "ean13", "format": "png", "module_height": 20}'
from toolkitapi import Barcode

with Barcode(api_key="tk_...") as bc:
    # ISBN-13 for a book — send 12 digits, checksum is appended
    result = bc.generate(
        data="978030640615",
        barcode_type="isbn13",
        format="svg",
        include_text=True,
    )
    open("book.svg", "w").write(result["svg"])
const resp = await fetch("https://barcode.toolkitapi.io/v1/barcode/generate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    data: "012345678905",       // UPC-A: 11 digits + computed check
    barcode_type: "upca",
    format: "png",
  }),
});
const { image } = await resp.json();
const buf = Buffer.from(image, "base64");

Compute a check digit yourself (pre-flight validation)

def ean13_check_digit(payload: str) -> str:
    """Return the EAN-13/UPC-A/ISBN-13 check digit for a 12-digit payload."""
    if len(payload) != 12 or not payload.isdigit():
        raise ValueError("payload must be exactly 12 digits")
    total = sum((3 if i % 2 else 1) * int(d) for i, d in enumerate(payload))
    return str((10 - total % 10) % 10)

print(ean13_check_digit("400638133393"))  # '0' → full code 4006381333930

Errors

Status Condition
400 Data not encodable for the chosen symbology (bad chars, wrong length, odd-length itf, wrong check digit)
422 Schema violation — data over 256 chars, unknown barcode_type, out-of-range module_height/quiet_zone
401 Missing or invalid API key

Testing

  1. Generate with your production symbology and the same data lengths you expect in the wild.
  2. Decode the output with POST /v1/barcode/decode (or POST /v1/qr/decode) to confirm round-trip fidelity.
  3. Print at the real label size and scan with the actual hardware and a phone camera — quiet_zone under ~5 mm is the most common cause of scan failures at small sizes.

See also

  • Barcodes — generate endpoint and styling options
  • Bulk & Decode — batch generation and image decoding
  • QR Codes — 2D codes with logos and custom module shapes