Create 500 codes from your ERP

One code per product, shelf, room or asset, created from the system that already knows them. This guide creates a batch, fetches the artwork for print, and shows how to keep it current.

Before you start

• A read and write key from Settings, Developers.
• Optional: a saved template id from GET /templates, so every code carries your design. Without one, codes get the default look.
• The plan's batch ceiling: 100 rows on PRO, 500 on Business (GET /me reports it as limits.bulkBatch). A batch also has to fit under the workspace's active-code ceiling.

1. Build the rows

One row per code. name and url are required; tags, utm and gps are optional. Put the identifier your system uses into the name and, if the destination should know it, into the URL.

{
  "rows": [
    { "name": "SKU 10432 Espresso beans 250 g", "url": "https://shop.example.com/p/10432", "tags": ["beans", "retail"] },
    { "name": "SKU 10433 Espresso beans 1 kg", "url": "https://shop.example.com/p/10433", "tags": ["beans", "retail"] }
  ],
  "templateId": "tpl_3f9a",
  "newFolderName": "Retail packaging, autumn run",
  "scanHost": "acme.kuikco.de"
}

• newFolderName creates a folder for the batch; folderId files it into an existing one. Exactly one of the two.
• scanHost prints every code on your branded host instead of kuikco.de/p/. It is fixed once the codes exist.
• Bulk creation is limited to ten batches per ten minutes per key, on top of the write budget.

2. Create the batch

Send an Idempotency-Key derived from your own run id, so a retried request after a timeout returns the same batch instead of a second one.

curl -X POST https://api.kuikcode.com/v1/codes/bulk \
  -H "Authorization: Bearer kc_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-run-2026-09-06-01" \
  -d @batch.json

{
  "folderId": "f_8Ka2",
  "created": 2,
  "codes": [
    { "id": "K02bEPC2SmtopwPr6S-jt", "shortCode": "Ab3dE9xYz", "name": "SKU 10432 Espresso beans 250 g" },
    { "id": "Zq9vX1mN4kLp8rTb2cWd0", "shortCode": "Cd4eF0aBc", "name": "SKU 10433 Espresso beans 1 kg" }
  ]
}

Batches are all or nothing: a row with a bad URL fails the whole request with 400 invalid_request and a param such as rows.7.url. Fix the row and send again with the same key.

Store each id next to the SKU in your system. That mapping is what makes every later step a single call.

3. Fetch the artwork for print

Every code's designed artwork is one GET away. png and jpg take a size from 256 to 4096 pixels; svg is vector for the printer.

curl "https://api.kuikcode.com/v1/codes/K02bEPC2SmtopwPr6S-jt/image?format=svg" \
  -H "Authorization: Bearer kc_live_..." -o 10432.svg

The first render of a code takes a few seconds; repeats are cached until the design changes. Loop over the batch with a small concurrency and you have a folder of print files named after your SKUs.

4. Keep it in sync

• A product moves: PATCH /codes/{id} with the new destination, see Change where a printed code points.
• A product is discontinued: PATCH /codes/{id} with { "archived": true }. The printed code shows a neutral "no longer active" page and stops counting against your plan.
• A new product: POST /codes for one, or another batch into the same folderId.
• Reporting: GET /analytics/summary?folderId=f_8Ka2 for the batch's totals, or GET /scans?folderId=f_8Ka2 for the raw rows.

GS1 products

For retail packaging that must also scan at the till, the same batch can be a GS1 batch: each row carries gs1 with the GTIN and optional lot, serial and attributes, and prints as a GS1 Digital Link on your GS1 host. See GS1 batches; the request body is documented in the reference.