Bulk Generate Barcodes

POST /v1/barcode/bulk renders up to 20 barcodes in one call and returns them as base64 PNGs in a single JSON response. It is the right endpoint when you are labelling a batch — a pallet of cartons, a sheet of shelf tags — and the wrong one when a single failure shouldn't sink the request.

Method Endpoint Items Format Styling
POST /v1/barcode/bulk 1 – 20 PNG only Per-item type, text, colours
POST /v1/barcode/generate 1 PNG or SVG Full, incl. module_height / quiet_zone

Base URL

https://barcode.toolkitapi.io

Authentication is via the X-API-Key header (or Authorization: Bearer).


Request

Field Type Required Constraints Description
items array yes 1 – 20 entries The barcodes to generate
format string no png (only value) Output format for the batch

Each entry in items:

Field Type Required Default Constraints Description
data string yes — ≤ 256 chars Payload to encode
barcode_type string no code128 one of 11 symbologies Symbology for this item
include_text boolean no true — Render the human-readable value
fg_color string no #000000 ≤ 9 chars, hex Bar colour
bg_color string no #ffffff ≤ 9 chars, hex Background colour

No per-item sizing in bulk

module_height and quiet_zone are not exposed on the bulk route. Every barcode in the batch renders with module_height = 15.0 mm and quiet_zone = 6.5 mm. If you need taller or tighter bars, call /v1/barcode/generate per item.

PNG only

format accepts the single literal png. SVG output is available only on the single-generate routes.


Examples

Three retail barcodes in one request

curl -X POST "https://barcode.toolkitapi.io/v1/barcode/bulk" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"data": "5901234123457", "barcode_type": "ean13"},
      {"data": "5901234123464", "barcode_type": "ean13", "include_text": false},
      {"data": "ABC-123", "barcode_type": "code128", "fg_color": "#0b3d91"}
    ]
  }'
import base64
import pathlib

import requests

items = [
    {"data": "5901234123457", "barcode_type": "ean13"},
    {"data": "5901234123464", "barcode_type": "ean13", "include_text": False},
    {"data": "ABC-123", "barcode_type": "code128", "fg_color": "#0b3d91"},
]

resp = requests.post(
    "https://barcode.toolkitapi.io/v1/barcode/bulk",
    headers={"X-API-Key": "YOUR_KEY", "Content-Type": "application/json"},
    json={"items": items},
    timeout=60,
)
resp.raise_for_status()
payload = resp.json()

out = pathlib.Path("labels")
out.mkdir(exist_ok=True)
for idx, entry in enumerate(payload["results"], start=1):
    # results are returned in request order, so index aligns with `items`
    (out / f"{idx:02d}-{entry['barcode_type']}.png").write_bytes(
        base64.b64decode(entry["image"])
    )

print(f"wrote {payload['total']} PNG(s)")
const items = [
  { data: "5901234123457", barcode_type: "ean13" },
  { data: "5901234123464", barcode_type: "ean13", include_text: false },
  { data: "ABC-123", barcode_type: "code128", fg_color: "#0b3d91" },
];

const resp = await fetch("https://barcode.toolkitapi.io/v1/barcode/bulk", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ items }),
});
if (!resp.ok) throw new Error(`bulk failed: ${resp.status}`);

const { total, results } = await resp.json();
const imgs = results.map((r) => `data:image/png;base64,${r.image}`); // render in order

Response

Field Type Description
total integer Number of barcodes generated (equals len(items) on success)
format string Always png
results array One entry per item, in request order

Each entry:

Field Type Description
data string The payload, echoed back
image string Base64-encoded PNG
barcode_type string Symbology used for this item
{
  "total": 3,
  "format": "png",
  "results": [
    { "data": "5901234123457", "image": "iVBORw0KGgo...", "barcode_type": "ean13" },
    { "data": "5901234123464", "image": "iVBORw0KGgo...", "barcode_type": "ean13" },
    { "data": "ABC-123", "image": "iVBORw0KGgo...", "barcode_type": "code128" }
  ]
}

Results are positional, not keyed by data

Entries carry data back for convenience, but the field you can rely on for matching is order. Duplicate data values are legal and produce two identical results — index, don't look up by payload.


All-or-nothing failure

Bulk generation aborts on the first item that fails. You get a 400 and no partial results — every barcode already rendered in the loop is discarded with the request.

{
  "detail": "Failed to generate barcode for '59012341234X7': Invalid EAN-13 ..."
}

The offending payload is truncated to the first 50 characters in the message so you can identify the bad row from logs.

This is deliberate: a partially-filled label sheet is worse than none, because the missing labels are easy to overlook on a print run. Practical implications:

  • Validate client-side first. Check digit counts, character sets, and length per symbology before submitting. GET /v1/barcode/types gives you the constraints programmatically — see Barcode Type Reference.
  • Bisect on failure. If a batch of 20 fails, binary-search the items array to isolate the bad entry, then retry the rest.
  • Keep items small in retry logic. A 20-item batch that fails repeatedly costs more round-trips than batched groups of 5.
def generate_batch(items, headers, session):
    """Shrink-and-retry around the all-or-nothing semantics."""
    if not items:
        return []
    try:
        r = session.post(
            "https://barcode.toolkitapi.io/v1/barcode/bulk",
            headers=headers, json={"items": items}, timeout=60,
        )
        r.raise_for_status()
        return r.json()["results"]
    except requests.HTTPError:
        if len(items) == 1:
            print("bad item:", items[0])
            return []
        mid = len(items) // 2
        return generate_batch(items[:mid], headers, session) + generate_batch(items[mid:], headers, session)

Cost and throughput

Batch where you can — one request is one billed call regardless of how many items it carries. Respect the 20-item ceiling; a 47-label run becomes 20 + 20 + 7, i.e. three calls.

The response holds every PNG as base64, so payload size scales with item count and data length. A 20-item batch of typical EAN-13s is roughly a few hundred kilobytes of JSON — fine for a service-to-service call, too heavy to hand straight to a mobile client on a slow link.

Errors

Status When Example body
400 Any item fails to render (bad data for its symbology, unparseable colour) {"detail": "Failed to generate barcode for 'ABC…': ..."}
401 Missing or invalid API key {"detail": "Unauthorized"}
422 items empty, more than 20 entries, unknown barcode_type, or format other than png Standard FastAPI validation payload
429 Rate limit exceeded {"detail": "Rate limit exceeded"}