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/typesgives you the constraints programmatically — see Barcode Type Reference. - Bisect on failure. If a batch of 20 fails, binary-search the
itemsarray to isolate the bad entry, then retry the rest. - Keep
itemssmall 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"} |
Related¶
- Generate Barcode — single barcode with full styling control
- Decode Barcode — verify what you generated
- Bulk Generate & Decode — end-to-end batch workflow
- Barcode Type Reference — constraints to validate against before batching