Bulk QR Codes: Create Hundreds at Once or by API

The whole job has six steps:

1. Build the spreadsheet, one row per code.
2. Choose static or dynamic for the batch.
3. Generate the codes with a library or an API.
4. Prepare the print files in the format your printer wants.
5. Test a sample of every batch, printed.
6. Track each code against its row.

The spreadsheet is the part people rush, and the part that causes most reprints. Give every row:

• An ID that never changes. Use a naming convention such as campaign, location, placement. If people will ever type the ID, leave out characters that look alike, such as 0 and O, or 1, l and I.
• A destination per row. Pointing every code at one page with the ID in the URL is easier to maintain than thousands of separate pages. Add UTM tags if you measure in web analytics; see UTM tracking for print.
• Short URLs. Every extra character can push the code to a denser version with smaller modules.

Then decide static or dynamic. Static codes are free and permanent but fixed. Dynamic codes can be repointed and counted, but depend on the provider’s service.

For static codes you do not need a service at all. The open-source qrcode package for Node.js turns a CSV file into one SVG per row. Save your sheet as codes.csv with an id,url header, then run:

// make-codes.js  (npm install qrcode, Node.js 18 or later)
// Simple CSV only: no commas inside values. Use a CSV parser for real data.
const fs = require('node:fs');
const QRCode = require('qrcode');

const rows = fs.readFileSync('codes.csv', 'utf8')
  .trim()
  .split(/\r?\n/)
  .slice(1) // skip the header row
  .map(line => line.split(',').map(cell => cell.trim()));

async function main() {
  fs.mkdirSync('out', { recursive: true });
  for (const [id, url] of rows) {
    await QRCode.toFile(`out/${id}.svg`, url, {
      errorCorrectionLevel: 'M', // L, M, Q or H
      margin: 4,                 // quiet zone, in modules
    });
  }
  console.log(`Wrote ${rows.length} files`);
}

main().catch(err => { console.error(err); process.exit(1); });

In our test it wrote 1,000 SVG files in about four seconds. SVG is vector, so it prints sharply at any size. Change the extension to .png and add a width in pixels if your printer wants raster images. Level M suits most print; use H only when something covers part of the code. The error correction guide explains why. For a handful of codes, the free QR code generator is quicker.

Printing a different code on every piece is called variable data printing. There are two ways to feed it:

• One image per row. You supply a folder of files named by ID, and the layout pulls in the right file for each record.
• Encoded at print time. You supply the spreadsheet, and the printer’s software, or your layout tool, draws each code from the URL column. Adobe InDesign’s Data Merge, for example, can create QR codes from a data column.

Ask your printer which they prefer before you generate anything: file format, naming, resolution, and whether the order of rows must match the print sequence. Keep the 4-module quiet zone in the layout, and size the codes with the size guide.

• Check the files. Decode every generated image with a decoding library and compare the result with its row. This catches copy-and-paste and encoding mistakes.
• Scan printed samples from every sheet or roll: the first, the last and a few at random. For runs of a few hundred, scan every one.
• Check alignment. In a mail merge, the classic failure is the code for row 41 printed beside the address for row 42. Scan a few pieces and compare the result with the name or number printed on them.
• Check destinations. Run every URL through a link checker so no code lands on a 404 page.
• Check dynamic codes are live and on a plan that keeps them active for the life of the print.

With static codes, give each row a unique URL or UTM tags and read the visits in your web analytics. With dynamic codes, the QR service counts scans for each code, and metadata ties each one back to its store, SKU or batch. How QR scan tracking works explains what those counts can and cannot tell you.

Polling for stats has a cost at scale. Checking the analytics of 5,000 codes once a day is 150,000 API requests a month. Checking weekly is about 22,000. Webhooks avoid the polling: the service sends your server a message for each scan as it happens.

CirculateQR has no CSV bulk upload in the dashboard. Bulk creation goes through the API. Batch creation needs a read and write key, which comes with the Stealth plan (100,000 requests a month, unlimited dynamic codes). The Artisan plan gets read-only keys (10,000 requests a month), enough to list codes and read analytics but not to create them. Call the API from your server, never from browser code, because the key is a secret.

Send up to 1,000 codes per request to POST https://circulateqr.com/api/v1/qr/batch:

Authorization: Bearer cqr_live_YOUR_KEY
Content-Type: application/json

{
  "codes": [
    { "destination": "https://example.com/stores/042", "name": "S26-042-WIN", "metadata": { "store": "042" } },
    { "destination": "https://example.com/stores/043", "name": "S26-043-WIN", "metadata": { "store": "043" } }
  ]
}

type defaults to DYNAMIC. The response lists what was created, matched to your rows by index:

{
  "created": 2, "failed": 0, "total": 2,
  "results": [
    { "index": 0, "id": "uuid", "shortId": "abc123", "name": "S26-042-WIN",
      "destination": "https://example.com/stores/042",
      "shortUrl": "https://circulateqr.com/go/abc123", "createdAt": "..." },
    { "index": 1, "id": "uuid", "shortId": "def456", ... }
  ]
}

• Partial failures. Each item is processed on its own. Failed items appear in an errors list such as { "index": 1, "error": "destination is required" }, and the rest are still created. Retry only the failed rows.
• Limits. Each batch call counts as one request toward the monthly quota. The API docs also list a per-minute rate limit (10,000 requests a minute on Stealth); over it, the API returns 429 with a Retry-After header.
• Print files. Each code is stored as a plain 512 px PNG, but the batch response returns links, not artwork. Render print files from each shortUrl with the script above, so you control size, format and quiet zone.
• Changes later. PATCH /api/v1/qr/:id changes a code’s destination, name or status; the printed short link stays the same. DELETE is a soft delete: the code is deactivated, not erased.
• Scan events. Webhooks post each scan to your server, signed with HMAC-SHA256, and failed deliveries are retried.

Plans and quotas are on the pricing page, and every endpoint is in the API docs.