QRbolt API
Create and manage QR codes, serialized GS1 Digital Links and Barcode Manager items with their 1D barcodes from your own systems: your ERP, PIM or packaging line. Everything the dashboard does for a code is available: code types, Design Studio styling, landing pages, password protection, and images. Account settings such as users, domains, GS1 prefixes, webhooks and billing stay in the dashboard.
Base URL https://api.qrbolt.com/v1. Every endpoint, with its scopes, headers and responses, is listed in the API reference, and the machine-readable OpenAPI document is at https://api.qrbolt.com/v1/openapi.json. The document names production as its only server, so when you point a test tool at it, give the tool the base URL you mean to call. Using the API means accepting the API Terms of Use.
Quickstart
- In the dashboard, open Settings ā API and create a key. Choose only the scopes your integration needs. The key is shown once; store it in your secret manager.
- Create a QR code:
curl https://api.qrbolt.com/v1/qr-codes \
-H "Authorization: Bearer $QRBOLT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1d3c2e-spring-promo" \
-d '{"name":"Spring promo","type":"URL","destinationUrl":"https://example.com/spring"}'The response is the code, including url, the address encoded in the QR code. Download the styled image with GET /v1/qr-codes/{id}/image?format=svg.
Keys and scopes
Send the key as Authorization: Bearer qrb_live_ā¦. A key looks like qrb_live_, 12 lowercase letters or digits, _ and a 43-character secret; the part before the secret is the key prefix you see in the dashboard. api.qrbolt.com accepts only qrb_live_ keys: a key starting with qrb_test_ is refused.
A key belongs to one organization and acts on behalf of the admin who created it, with that person's access as it is now. If the creator becomes read-only, the key loses qr:write, gs1:write and items:write; if they lose access to departments, so does the key. The key stops working when it is revoked or expires, when its creator leaves the organization, or when its department is deleted.
401 or 403. 401 unauthorized means the key was not accepted: missing, malformed, unknown, revoked, expired, a test key, or its creator, department or organization is no longer active. We never say which, so check the key in the dashboard. 403 means the key is valid but may not do this: insufficient-scope (the response lists requiredScopes), feature-not-enabled (the plan has no API access), gs1-not-enabled, or forbidden, for example a department the key cannot use. A key whose plan lacks Barcode Manager gets feature-not-enabled from the items endpoints (see Items: access and limits). Repeated requests with keys that are not accepted are rate limited per IP address.
Rotating a key gives it a new secret and the old secret stops working at once. Only the person who created a key can rotate it. To change keys without downtime, create a second key, deploy it, check that requests succeed with it (its last-used time in the dashboard updates within a minute), then revoke the old one.
| Scope | Allows |
|---|---|
qr:read | Read QR codes, presets and reference data (domains, departments, groups, assets) |
qr:write | Create, update and delete QR codes |
gs1:read | Read GS1 serials |
gs1:write | Issue and register GS1 Digital Links (also as jobs), change serial status |
images:read | Download QR images and export image ZIPs |
jobs:read | Read this key's jobs. Downloading results also needs gs1:read (GS1 jobs), images:read (image jobs), barcodes:read (barcode export jobs) or items:read (item import jobs) |
items:read | Read Barcode Manager items and declared GS1 prefixes |
items:write | Create, update, release, discontinue and renumber items, and import them as jobs |
barcodes:read | Download item barcodes (SVG, PNG, PDF) and export barcode files as jobs |
Department keys
A key can be limited to one department when it is created. It then reaches only that department's QR codes and serials: not unassigned codes, and not other departments. Codes it cannot see answer 404, as if they did not exist. It creates codes in its department (leave departmentId out, or send its own department) and cannot create unassigned codes or move a code out of the department. If its creator loses access to the department, the key stops working.
A key for the whole organization files a new code in its creator's primary (or only) department when departmentId is left out, or leaves it unassigned when the creator has no department. Send departmentId: null to make a code unassigned, visible to everyone in the organization.
GTINs belong to the whole organization, not to one department. If a department key issues or registers serials for a GTIN whose code is in another department, it gets 403 forbidden ("The code for this GTIN belongs to a department this API key cannot use"). The key learns that the GTIN is in use elsewhere in your organization, but nothing about that code or its serials. Serials already registered under a code the key cannot see are refused with 409 without naming them, also with onExisting: "skip".
Barcode Manager items and prefixes belong to the whole organization too: a department key reads and changes all of them.
Requests and headers
- Bodies are JSON of at most 5 MB, jobs included. Send
Content-Type: application/json(any+jsontype, such asapplication/merge-patch+json, is read as JSON too). A POST, PUT or PATCH whose body has another content type, or none, is refused withunsupported-media-typeand nothing changes; a request without a body is not affected. Invalid JSON getsbad-request, and a larger body getspayload-too-large: split it into several requests. - Unknown fields and unknown query parameters are refused with
validation-error, so a typo never goes unnoticed. Every problem is listed inerrors(see Errors). - Unknown paths, and methods a path does not support, answer
404 not-found. - Every response carries
X-Request-Id. Send your own (8 to 64 characters: letters, digits,.,_or-) to find a request in both your logs and ours; anything else is replaced by an id we make. Webhook events for your changes carry it too. X-Change-Noteon PATCH and DELETE of a QR code and on PATCH of a serial records why the change was made, in the activity log (the first 500 characters are kept; percent-encode non-ASCII text). If your organization requires change notes, those requests without one are refused withchange-note-required.- Reading or writing a QR code returns its version as
ETag. Send it back asIf-Matchon PATCH or DELETE and the write is refused with409 conflictif someone changed the code since you read it;currentVersiongives the version now. WithoutIf-Match, the last write wins. Theversionfield of a code works as well (If-Match: "7"), and a malformedIf-Matchgets400 bad-request. Only QR codes have versions: other resources ignoreIf-Match.
Errors
Errors use RFC 9457 application/problem+json. Branch on type; its slugs never change, and each one links to a page that explains it. Validation errors list each problem in errors. Every entry has pointer, an RFC 6901 JSON Pointer to the body member or to the query or path parameter (a ~ in a name is written ~0 and a / ~1). Most endpoints add a message, for example {"pointer": "/serials/41", "message": "Duplicate serial A1B2"}. Barcode Manager items add field, a stable code, its severity and sometimes params (see Items). Problems can carry further members, such as instance, reason (a stable sub-type of the problem), code or the numbers of a limit. Every response carries X-Request-Id; quote it when you contact us. The reference lists the error statuses each endpoint can return.
HTTP/1.1 402 Payment Required
Content-Type: application/problem+json
{
"type": "https://qrbolt.com/developers/errors/active-code-limit-exceeded",
"title": "Not enough active codes left in the subscription",
"status": 402,
"detail": "This request needs 1200 active codes but only 800 of 5000 are left. Add 400 more codes to the subscription, or archive codes you no longer use.",
"requested": 1200,
"remaining": 800,
"limit": 5000,
"shortfall": 400,
"requestId": "req_5f1c0e9b2a7d4c3e8f6a1b2c"
}Pagination
Paginated lists (QR codes, presets, serials, jobs and items) return { data, nextCursor, hasMore }, newest first, 25 items per page by default. Pass ?limit= (1 to 100) for another page size, and ?cursor=<nextCursor> for the next page; nextCursor is null on the last page. Cursors are opaque: pass them back unchanged. A malformed cursor gets invalid-cursor. To sync changes incrementally, filter QR codes or items with ?updatedSince= and an RFC 3339 date-time with a time zone, such as 2026-11-01T00:00:00Z or 2026-11-01T08:00:00+01:00; a date alone or a time without a zone is refused with validation-error at /updatedSince. The list stays in creation order, so keep the largest updatedAt you saw as the next starting point. Other filters of each list are in the reference.
Reference lists (/v1/domains, /v1/departments, /v1/groups, /v1/assets and /v1/prefixes) are not paginated: they return { data } with every entry.
Retries and idempotency
Send an Idempotency-Key header on POST requests: any unique string of 1 to 255 visible ASCII characters (no spaces); a malformed key gets 400 bad-request. Keys are kept per API key for 24 hours. If you retry with the same key, method, path, query string and body, you get the original status and body back with Idempotent-Replayed: true, and nothing is created twice. The order of JSON members does not matter. The same key with any other method, path, query or body is refused with idempotency-key-reuse, and a retry while the first request is still running gets idempotency-in-progress with Retry-After: 5: wait that many seconds and retry with the same key. A request that failed releases its key, so it can be retried with the same key. If a request is interrupted on our side before it finishes, its key stays held for up to 15 minutes. If we cannot store keys for a moment, a request that sends one gets 503 service-unavailable rather than risking a duplicate; retry it later.
A file, such as an item barcode, is never kept and does not hold its key: once it is sent, a retry with the same key renders it again (see barcode files). Responses over 64 KB, such as a large GS1 issue, are not kept either. A retry of one of those gets idempotency-response-unavailable: the first request succeeded and nothing is done again. originalStatus gives its status and resource points at what was created when there is a single resource; read the result from there instead of retrying. Each API key can keep a large but limited number and volume of idempotent responses per day. Past the volume, a retry gets idempotency-response-unavailable; past the number, requests are still served and protected while they run, but a retry after they finish is processed again. Move very high volumes into jobs.
Idempotency-Key is ignored on every method but POST: PUT, PATCH and DELETE are safe to repeat as they are. A PUT or PATCH sets the same values again, and a DELETE of a code that is already deleted answers 404. Use If-Match if a repeated write must not overwrite someone else's change.
Rate limits
Limits apply per API key and per account: all keys of an account share the account's limit. How much you can send depends on your plan. Writes count for more than reads and rendered images (QR images and item barcodes) for more still. Synchronous GS1 issue and register calls count by the number of links they carry, per hundred links, and never less than any other write.
Every response to a request the key is allowed to make tells you where you stand: RateLimit-Limit (the most you can send at once), RateLimit-Remaining, RateLimit-Reset (seconds until you are back to the full allowance) and RateLimit-Policy. Read these instead of hard-coding a number.
Over the limit you get 429 rate-limited with Retry-After in seconds. Wait at least that long, then retry with exponential backoff and random jitter so that parallel workers do not retry in lockstep. Use jobs for large batches instead of many small calls. If you need more capacity, contact us.
QR codes and images
POST /v1/qr-codes creates URL, PHONE, WIFI and VCARD codes; type TIME_BASED is refused there with validation-error at /type, so create those with POST /v1/qr-codes/time-based (below). Apply a design preset saved in the dashboard with presetId; fields you send win over the preset. GET /v1/presets lists the presets of the key's creator. Every new code counts toward the QR code limit of your plan; past it you get active-code-limit-exceeded. DELETE moves a code to the trash, where it can be restored from the dashboard. List codes with GET /v1/qr-codes (filter by type, sku, gtin, departmentId or updatedSince), read one with GET /v1/qr-codes/{id} and change it with PATCH; the reference lists every field.
The ids you need for a code come from GET /v1/domains (verified custom domains), /v1/departments, /v1/groups and /v1/assets (logos), all with qr:read. GET /v1/health needs no key: it answers 200 when the API is up and 503 when it is not.
Time-based codes (POST /v1/qr-codes/time-based) send scans to a different URL at different times. Each rule has a url, a startAt and an optional endAt, ISO 8601 date-times. A time with Z or an offset is that instant; one without (2026-11-02T08:00) is the wall-clock time in the code's timezone. A rule without endAt lasts until the next one starts. Outside every rule, scans go to defaultUrl. timezone is an IANA name such as Europe/Zagreb. A code has 1 to 24 rules, and rules may not overlap: overlapping rules or an unknown time zone are refused with 409 conflict. Change rules later with PATCH and timeBasedRules.
Images. GET /v1/qr-codes/{id}/image returns the code styled with its design and logo. format is png (default) or svg; size is 100 to 2000 pixels (default 600; an SVG scales freely). The ETag is a hash of the image: send it as If-None-Match and an unchanged image answers 304 with no body (send the ETag exactly as you received it). If the code has a logo that could not be rendered, the image comes without it and the response says X-QR-Logo: omitted; check for it before printing.
GS1: issue serialized links
Send a GTIN (UPC-A, EAN-8, EAN-13 or GTIN-14; the check digit is verified and the GTIN is stored as 14 digits), optionally a batch (AI 10, 1 to 20 characters of the GS1 character set, see below) and further Application Identifiers in attributes, and your serials. You get one GS1 Digital Link per serial on your verified domain. The first request for a GTIN (and batch) creates its product code from product: name and destinationUrl are required; landing page, description, design, logo (logoAssetId), group and department are optional. Later requests use the existing code and ignore product. Creating a product code needs a verified custom domain.
POST /v1/gs1/links
{
"gtin": "09506000134352",
"batch": "LOT7",
"attributes": { "17": "271231" },
"serials": ["SN0001", "SN0002"],
"product": { "name": "Widget 500 ml", "destinationUrl": "https://brand.example/widget" },
"metadata": { "erpOrder": "PO-42" }
}
201 Created
{
"object": "gs1_issue_result",
"productCreated": true,
"issued": [
{ "serial": "SN0001", "uri": "https://id.brand.example/01/09506000134352/10/LOT7/21/SN0001?17=271231", "source": "customer" },
{ "serial": "SN0002", "uri": "https://id.brand.example/01/09506000134352/10/LOT7/21/SN0002?17=271231", "source": "customer" }
],
"skipped": [],
"product": { "id": "ā¦", "url": "https://id.brand.example/01/09506000134352/10/LOT7?17=271231", ⦠}
}- Serials are 1 to 20 characters, unique within the request. Up to 1,000 per request; send more as a job. Serials and batches use the GS1 character set 82:
AtoZ,atoz,0to9and! " % & ' ( ) * + , - . / : ; < = > ? _. Spaces (also leading or trailing ones), other symbols and non-ASCII letters are refused withvalidation-errorand a pointer to each value, such as/serials/3or/batch. - No serials of your own? Send
"generate": { "count": 500 }instead ofserials(not both). We issue random, non-sequential serials of A to Z and 0 to 9 (length8 to 20, default 12) and record that they were generated. attributesare checked like the dashboard checks them, dates included (YYMMDD). AIs 01, 10 and 21 go ingtin,batchandserialsinstead.attributesis a flat map of AI code to value, up to 2 KB; unknown AIs are refused.metadata(up to 4 KB of JSON, nested at most 5 levels) is stored with every serial of the request.- A serial is unique per GTIN in your organization, whatever its batch. One that is already registered fails the request with
409and lists up to 100 of them inexistingSerials(detailgives the total). Send"onExisting": "skip"to issue the rest and list the existing ones inskipped. A clash with serials under a code the key cannot see, or with a request running at the same time, is also409, withoutexistingSerials. A product code with the same GTIN, batch and attributes in another QRbolt organization is409too ("This GTIN is not available"). - Every serial counts as an active code in your subscription, and so does every product code the request creates. A request that does not fit is refused before anything is issued, with
active-code-limit-exceededand the shortfall (see Errors). A plan without GS1 getsgs1-not-enabled.
GS1: register your own links
If your system already builds Digital Links, send them and we resolve them. Each link must use https on a domain you have verified in the dashboard, so that scans reach QRbolt, and must carry a 14-digit GTIN with a valid check digit and a serial (AI 21). Serials and batches in links follow the same character rules as for issuing. Encode a literal % in a serial as %25. Links are grouped by GTIN, batch and other AIs; each group needs a product code, created from product the first time. Every invalid link is reported in errors with its index, and nothing is registered. A serial that appears twice for the same GTIN fails the request with one error at /links. Duplicates, onExisting and the active-code limit work as for issuing. The response has one gs1_issue_result per product code in products; each uri is the link as we resolve it, on the product code's domain.
POST /v1/gs1/links/register
{
"links": [
"https://id.brand.example/01/09506000134352/10/LOT7/21/EXT-100?17=271231",
"https://id.brand.example/01/09506000134352/21/EXT-101"
],
"product": { "name": "Widget 500 ml", "destinationUrl": "https://brand.example/widget" }
}GS1: serials
List serials with GET /v1/gs1/serials (filter by gtin as 14 digits, or by status). Address one serial as /v1/gs1/serials/{gtin}/{serial}: the GTIN as 14 digits (pad shorter ones with leading zeros) and the serial percent-encoded, so a / in a serial is %2F. Each serial shows its scan count and first and last scan.
Recall or void a serial with PATCH and {"status": "recalled"} or "void"; set "active" to bring it back. Only active serials count as active codes: recalling or voiding one frees its code, and bringing it back uses one again (402 when none is left). PATCH can also replace its metadata. Each status change sends a serial.status_changed webhook, whose data.serial also has previousStatus.
How scans resolve
- A registered serial resolves through its product code: destination, landing page and design.
- A recalled or voided serial shows a notice page to the person scanning, instead of the product, also to clients that ask for a linkset.
- A serial we do not know resolves as if the link carried only the GTIN: to the code for the link's batch if there is one, otherwise to the GTIN's own code, and
404if there is neither. A serial registered under one batch, scanned in a link with a different batch, counts as unknown; a link without a batch still finds a serial registered under one. - Clients that want the links rather than a redirect send
Accept: application/linkset+json(or?linkType=allor?linkType=linkset) and get an RFC 9264 linkset. A linkset request is not a scan: it is not counted in analytics and does not change a serial's scan count or scan times. - While the organization's subscription is not active, scans get a JSON body with the GTIN and its attributes instead of a redirect.
Serialization and printing
For variable-data printing, give your printer the list of links, not images: printers render the QR code from each line. Issue large runs as a job and download the results as CSV (gtin,serial,uri,source,productId). For a small number of labels, fetch an image per serial with GET /v1/gs1/serials/{gtin}/{serial}/image, styled like its product code.
Items (Barcode Manager)
An item is a product, a packaging level of a product, or an internal code, with the 1D barcode that prints for it: the same items as the Barcodes grid in the dashboard, with the same rules. Items belong to the whole organization, so a department key reads and changes all of them. Changes appear in the activity log as made by the key.
curl https://api.qrbolt.com/v1/items \
-H "Authorization: Bearer $QRBOLT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: item-WID-500" \
-d '{"name":"Widget 500 ml","gtin":"assign","sku":"WID-500","category":"Widgets"}'
201 Created
{
"id": "ā¦",
"object": "item",
"kind": "GTIN_ITEM",
"name": "Widget 500 ml",
"description": null,
"gtin": "04012345000009",
"gtinDisplay": "4012345000009",
"sku": "WID-500",
"manufacturerName": null,
"manufacturerItemNumber": null,
"codeValue": null,
"symbology": "EAN13",
"symbologyOverride": null,
"level": "UNIT",
"parentId": null,
"packQuantity": null,
"status": "DRAFT",
"releasedAt": null,
"discontinuedAt": null,
"category": "Widgets",
"createdAt": "2026-11-07T09:00:00.000Z",
"updatedAt": "2026-11-07T09:00:00.000Z"
}| Field | Rules |
|---|---|
name | Required, up to 200 characters. |
description | Up to 2,000 characters. |
kind | GTIN_ITEM (carries a GTIN) or INTERNAL (an internal code without a GTIN). When you leave it out on create, it is GTIN_ITEM if you send a gtin and INTERNAL otherwise. |
gtin | A GTIN-8, -12, -13 or -14, or "assign" (see GTIN rules). Returned as 14 digits; gtinDisplay is the number as printed under the bars. Null for an internal item. |
sku | Up to 64 characters, unique in the organization when set. |
manufacturerName, manufacturerItemNumber | Up to 120 and 64 characters. The pair is unique in the organization (the name is compared without case). |
codeValue | Up to 48 characters. What the barcode of an internal item encodes when it differs from its SKU. |
symbology | EAN13, UPCA, UPCE, EAN8, ITF14, GS1_128, CODE128 or CODE39. Send it to choose; null goes back to the derived one (see GTIN rules). The response gives what prints in symbology and your choice, if any, in symbologyOverride. |
category | Up to 80 characters, free text for your own grouping and filters. |
parentId, level, packQuantity | Packaging levels, see below. packQuantity is 1 to 100,000. |
status, releasedAt, discontinuedAt | Read-only. Changed with the lifecycle calls below. |
Text is trimmed and control characters become spaces; an empty string is stored as null. Unknown fields are refused, as everywhere in the API.
Reading, creating and updating
GET /v1/itemslists items, newest first, with the usual pagination. Filter bysku,gtin(any length; it is checked like any GTIN),status,kind,category, orupdatedSinceto sync changes.skuandcategorymatch exactly; an empty or blank filter is refused rather than ignored. Discontinued items are included unless you filter by status.GET /v1/items/{id}andGET /v1/items/by-sku/{sku}read one item. Percent-encode the SKU in the path.POST /v1/itemscreates an item.PATCH /v1/items/{id}changes the fields you send: a field you leave out stays as it is, andnullclears it.name,kindandlevelcannot be null.PUT /v1/items/by-sku/{sku}is the sync path for an ERP or PIM: it creates the item when no item has this SKU (201, and thennameis required), and otherwise updates the fields you send, like PATCH (200). Askuin the body must match the path. Sending the same values again changes nothing, not evenupdatedAt, so it is safe to repeat.- Items are not deleted through the API. Only Drafts can be deleted, in the dashboard; discontinue an item instead.
Internal codes
An INTERNAL item has no GTIN. Its barcode encodes codeValue, or the SKU when there is no code value, so it needs one of the two. It prints as Code 128 (any printable ASCII) unless you choose CODE39 (A to Z, 0 to 9, space and - . $ / + %). Assigning a GTIN to an internal item makes it a GTIN_ITEM.
Packaging levels
An item without a parent is a UNIT. A pack or case of it is an item of its own, with parentId set to the unit (or to a pack), level PACK or CASE, and the number of units in packQuantity, which is then required. A unit can have packs and cases below it, and a pack can have cases; that is as deep as it goes. An item with levels below it cannot itself become a level, and the parent must be an item of your organization. A parentId without a level makes a new item a CASE; an existing pack or case keeps its level. level: UNIT together with a parent (the one you send, or the item's current one) is refused with validation-error and code: unitWithParent. Setting parentId to null makes the item a unit again and clears packQuantity.
Status
- A new item is
DRAFT. Its GTIN can still change, because nothing has been printed with it. LIVEmeans it has been released: byPOST /v1/items/{id}/release, by downloading or exporting its barcode artwork (through the API or the dashboard), or by creating a Digital Link for it in the dashboard.releasedAtrecords when. Its GTIN is now locked.POST /v1/items/{id}/discontinuemakes a Draft or Live itemDISCONTINUED. It stays listed and downloadable, a unit frees its place in the item limit, and its GTIN is never handed out again.POST /v1/items/{id}/reactivatebrings a discontinued item back: toLIVEif it was ever released, otherwise toDRAFT. A unit needs a free place in the item limit for this.
Each of these answers 200 with the item. They are safe to repeat: releasing an item that is not a Draft, discontinuing a discontinued item or reactivating one that is not discontinued changes nothing.
Errors
An item that breaks a rule is refused with validation-error, and nothing is saved. For items, each entry in errors has the JSON pointer like everywhere else, and names the field, a code, its severity (error or warning) and, for some codes, params:
{
"type": "https://qrbolt.com/developers/errors/validation-error",
"title": "Request validation failed",
"status": 400,
"detail": "The item breaks a Barcode Manager rule; see errors.",
"errors": [
{ "pointer": "/gtin", "field": "gtin", "code": "gtinCheckDigit", "severity": "error", "params": { "corrected": "4012345000016" } }
],
"requestId": "req_ā¦"
}Errors: nameRequired, tooLong (params.max), gtinInvalidCharacters, gtinInvalidLength, gtinCheckDigit, gtinAllZeros, gtinRequired, gtinLocked, duplicateGtin, duplicateSku, duplicateManufacturerItem, symbologyNotAllowed, barcodeValueRequired, codeValueInvalid, packQuantityRequired, parentInvalid and itemGone (the item was deleted meanwhile). Warnings never block a save, and are listed only when the request is refused for an error: outsidePrefix, gtinRange (a restricted, coupon, ISBN, ISSN, refund-receipt or variable-measure number), retiredGtin, discontinuedGtin (the number is on a discontinued item) and internalLooksLikeGtin. The API itself adds: blank (an empty or blank sku or category filter, or path SKU), tooLong (a path SKU over 64 characters), a GTIN code for a gtin filter that is not a valid GTIN, skuMismatch (the body sku of a PUT differs from the path), nameRequired (a PUT that creates without name), unknownPrefix (a prefix you have not declared), unitWithParent (see Packaging levels) and unknownLayout (an export layout). Two requests racing to save the same SKU, GTIN or manufacturer item number get 409 conflict for the one that loses.
Items: GTIN rules
- Send a GTIN-8, GTIN-12 (UPC-A), GTIN-13 (EAN) or GTIN-14 with its check digit; spaces, dots and hyphens are ignored. A wrong check digit is never corrected for you: it is refused with
gtinCheckDigit, andparams.correctedgives the number with the right check digit. The GTIN is stored as 14 digits and is unique in your organization, discontinued items included. - The barcode type is derived from the number unless you choose one: a GTIN-8 prints as EAN-8 (however you sent it, as 8 digits or padded with zeros), a GTIN-12 as UPC-A, a GTIN-13 as EAN-13, a GTIN-14 with indicator digit 1 to 8 (a pack or case) as ITF-14, and one with indicator 9 (a variable measure item) as GS1-128, which can carry the measure next to the GTIN.
symbology: nullalways goes back to this rule. You can choose another type that can carry the number (for example UPC-E for a GTIN-12 that can be zero-suppressed, or GS1-128); any other is refused withsymbologyNotAllowed. - Assign. Send
"gtin": "assign"and we pick the lowest free number in one of your declared prefixes and compute its check digit. A number is free when no item of your organization has it, whatever its status, it was never retired, and nobody is holding it while assigning in the dashboard.prefixchooses the prefix by its digits; without it we use your first declared Company Prefix, or your first declared single GTIN when you have no Company Prefix. A prefix you have not declared is refused withvalidation-error(code: unknownPrefix). With no prefix declared, the answer is409 conflictwithcode: NO_PREFIX; when the prefix has no free number left,409 conflictwithcode: PREFIX_FULL. If the save then fails, the number goes back. In an import, rows of one prefix get numbers in row order while it has free ones; only the rows left over are skipped withPREFIX_FULL. assignworks on create, on update and in imports. On an item that already has a GTIN it does nothing, so a sync that always sendsassignkeeps each item's number. On an internal item it assigns a number and makes the item aGTIN_ITEM.- Locked GTINs. The GTIN of an item that is
LIVEorDISCONTINUED, or that has a Digital Link, may already be printed. PATCH, PUT and imports cannot change it, or turn the item into an internal code: they are refused withgtinLocked. A Draft's GTIN can be changed freely. - Change number. To change a locked GTIN, call
POST /v1/items/{id}/change-numberwith the new GTIN and"confirm": true, the JSON boolean, because anything already printed still scans as the old number. Withoutconfirm, or withfalseor a string, the request is refused withvalidation-errorat/confirm. The new number is checked like any GTIN. The old number of a Live or discontinued item is retired: it is never assigned again, and an item that is given it gets theretiredGtinwarning. While the item has a Digital Link the change is refused with409 conflictandcode: HAS_DIGITAL_LINK; archive its Digital Link codes first. An internal item, or the number the item already has, is refused with400 bad-request.
curl https://api.qrbolt.com/v1/items/$ITEM_ID/change-number \
-H "Authorization: Bearer $QRBOLT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"gtin":"4012345000016","confirm":true}'Items: prefixes
Your GS1 Company Prefixes and single licensed GTINs are declared by an admin in the dashboard; the API reads them. GET /v1/prefixes lists them with their capacity:
{
"data": [
{
"id": "ā¦",
"object": "prefix",
"prefix": "4012345",
"kind": "COMPANY_PREFIX",
"label": "Main brand",
"verified": false,
"capacity": 100000,
"used": 1240,
"remaining": 98760
}
]
}A Company Prefix of L digits holds 10^(12 ā L) GTIN-13 numbers; a SINGLE_GTIN holds one. used counts the unit numbers (indicator digit 0) on your items in that prefix. remaining is an upper bound for assign, which also skips retired numbers and numbers reserved by someone assigning in the dashboard. A GTIN outside every declared prefix is allowed with the outsidePrefix warning. verified is false: QRbolt does not check prefix ownership with GS1.
Items: barcode files
POST /v1/items/{id}/barcode returns the item's barcode, sized to GS1 specifications, as an attachment. It is a POST because the download releases a Draft.
curl -X POST "https://api.qrbolt.com/v1/items/$ITEM_ID/barcode?format=pdf&magnification=1.2" \
-H "Authorization: Bearer $QRBOLT_API_KEY" \
-o widget.pdfformat:svg(default),pngorpdf.magnification: 0.8 to 2.0 (GS1 sizes 80% to 200%).digits:trueorfalse, the human-readable digits.dpi: 300 (default) or 600, for PNG. Withoutmagnificationordigits, the item's print settings from the dashboard apply, and 100% with digits when it has none.- Artwork leaving QRbolt releases the item: a
DRAFTbecomesLIVEand its GTIN locks. Releasing is a change, so for a Draft the key needsitems:writeas well asbarcodes:read. A key with onlybarcodes:readdownloads Live and discontinued items, and a Draft getsforbiddenwithreason: draft-release-needs-items-write. On a plan without Barcode Manager (after a downgrade) items are read-only: Live and discontinued items still download, and a Draft getsforbiddenwithreason: read-only-plan, whatever the key's scopes. - The response is not cached (
Cache-Control: no-store). It counts toward your rate limit like a rendered QR image. You may send anIdempotency-Key, but the file is never kept: once it is sent the key is free again, and a retry with the same key renders the file again. That is safe, because the item is already released and releasing it again changes nothing. A retry sent while the first download is still rendering getsidempotency-in-progress.
Items: import and export jobs
Import up to 10,000 items in one job with POST /v1/items/jobs/import (scope items:write). Each entry has the fields of an item, plus prefix for gtin: "assign". Each entry is matched to an existing item by SKU, then by GTIN, then by manufacturer and manufacturer item number; a match is updated with the fields sent, anything else is created.
curl https://api.qrbolt.com/v1/items/jobs/import \
-H "Authorization: Bearer $QRBOLT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pim-sync-2026-11-07" \
-d '{"items":[
{"sku":"WID-500","name":"Widget 500 ml","gtin":"assign"},
{"sku":"WID-500-C12","name":"Widget 500 ml, case of 12","gtin":"14012345000006","level":"CASE","packQuantity":12,"parentId":"ā¦"}
]}'- An import is not all or nothing. Valid entries are saved, in slices of 1,000; an entry with errors is skipped and reported. When the item limit is reached, entries that would create a unit are not processed, while updates go on.
- The results (
GET /v1/jobs/{id}/results, which also needsitems:read) are always JSON Lines, one line per entry in the order sent:{"row": 1, "status": "created", "id": "ā¦", "sku": "WID-500", "gtin": "04012345000009", "errors": []}.rowstarts at 1.statusiscreated,updated,unchanged,skipped(errorslists the issues, in the shape above with a pointer into the job body such as/items/3/gtin, or acodesuch asunknownPrefix,unitWithParent,NO_PREFIXorPREFIX_FULL) ornotProcessed(errorsholdscode: item-limit-exceeded, or why the import stopped).gtinis the number saved, or null when an assigned number was not used. - The job's
summarycounts each status and gives thebatchIdthat groups the import in the activity log, withlimitReachedwhen the item limit was reached andstoppedwhen the import stopped early. If a job fails after saving items, itserrorcarries thatsummary; list items withupdatedSinceto see what changed.
Export barcode files for up to 2,000 items with POST /v1/items/jobs/export (scope barcodes:read; your plan must include batch export, otherwise forbidden with reason: batch-export-not-enabled):
{ "ids": ["ā¦", "ā¦"], "output": "zip", "format": "pdf", "dpi": 300 }outputzip(default): one file per item informatpdf(default),svgorpng(dpi300 or 600), named<GTIN-14 or SKU>_<name>.<ext>, plusspec-sheet.pdf.labels: an A4 label-sheet PDF.layoutisa4-3x8(default),a4-3x7,a4-4x10,a4-2x7orcustom-CxRwith 1 to 10 columns and 1 to 20 rows.summary.tooSmallcounts the barcodes printed below the GS1 minimum size on that layout.spec: a spec-sheet PDF listing each item's number, barcode type, size and settings.- A ZIP or label sheet releases its items once the file is stored, like a single download, so if any item is a Draft the key also needs
items:write. This is checked when you submit and again when the job runs; without it you getforbiddenwithreason: draft-release-needs-items-write. A spec sheet releases nothing. - Every id must be an item of your organization when you submit (otherwise
404); items deleted before the job runs are left out. Download the file withGET /v1/jobs/{id}/results; it also needsbarcodes:readand is kept for 24 hours.
Items: access and limits
- The items endpoints need API access and a plan with Barcode Manager or Digital Link. Without one, they answer
feature-not-enabledwithreason: barcode-manager-not-enabled. After a downgrade, an organization that still has items can read them, list prefixes and download the barcodes of Live and discontinued items, but not change anything. Downloading a Draft's barcode would release it, so it is refused withreason: read-only-plan. - Scopes:
items:readto read items and prefixes;items:writeto create, update, release, discontinue, reactivate, change numbers and import;barcodes:readto download barcodes and export them, plusitems:writewhen that releases a Draft. A key whose creator is read-only losesitems:write. - Your plan sets how many items you can have. Only units count, products and internal codes alike, and only while they are not discontinued; packs and cases are free. A create, an import entry, a change that makes a level a unit, or a reactivation that would pass the limit is refused with
forbiddenandreason: item-limit-exceeded, with the numbers:
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
{
"type": "https://qrbolt.com/developers/errors/forbidden",
"title": "Forbidden",
"status": 403,
"detail": "Your plan allows 500 items (packaging levels are free). This needs 3 more: discontinue items you no longer use or upgrade your plan.",
"reason": "item-limit-exceeded",
"limit": 500,
"current": 499,
"requested": 4,
"shortfall": 3,
"requestId": "req_ā¦"
}Discontinue items you no longer use to free places, or upgrade the plan. Items over the limit after a downgrade stay editable and can be discontinued; only adding units is refused. Batch export (ZIP, label sheets and spec sheets) is included in some plans only.
Large batches (jobs)
Up to 1,000 items per request run synchronously. Send larger runs, up to 100,000 serials or links per job, to POST /v1/gs1/links/jobs or /v1/gs1/links/register/jobs, and image exports of up to 1,000 codes to POST /v1/images/jobs. A job body has the same fields and the same 5 MB limit as the synchronous request. Barcode Manager items have their own import and export jobs.
A GS1 job is checked when you submit it, like the synchronous request: the input, the product and verified domain for new product codes, and whether your subscription has room for its serials and new product codes (with onExisting: "skip", every serial is counted, including those that will be skipped). A job that cannot run is refused at once with the same error. You get 202 and a job whose status is queued, then running, then succeeded or failed. Poll GET /v1/jobs/{id} or subscribe to the job.completed and job.failed webhooks; GET /v1/jobs lists your jobs (filter by status). A job has its type (gs1_issue, gs1_register, images, item_import or barcode_export), progress (total and processed; it counts up for image and item import jobs, while a GS1 job shows 0 until it finishes), summary once it is done, resultsUrl and resultsExpireAt. A GS1 summary is {issued, skipped, products}, an image summary {images, failed}. A failed job has a problem in error.
Download GET /v1/jobs/{id}/results: CSV (default) or ?format=jsonl for GS1 jobs, a ZIP for image jobs. GS1 results list the issued links only; skipped serials are counted in summary.skipped. An image job succeeds even if some images fail: they are listed as {id, error} in errors.json inside the ZIP. Results are available once the job has succeeded (before that, 409) and can be downloaded for 7 days, barcode export files for 24 hours; resultsExpireAt says when. Then the file is deleted: the download answers 404 and resultsUrl becomes null. The input you sent with a job is deleted 7 days after the job finished. The job itself stays listed. Downloading results also needs the read scope of the job type, as listed in Keys and scopes. A GS1 job is all or nothing: if the subscription cannot fit it when it runs, it fails with the same shortfall details and issues nothing.
An organization can have 2 jobs queued or running at once, across all its keys; another submission is refused with 429 rate-limited and Retry-After: 30 until one of them finishes. A key sees only the jobs it submitted; any other job id is 404. A job runs with the key's rights at the time it runs: if the key was revoked, lost the scope it needs, or the plan no longer includes API access, the job fails without doing anything.
A running job reports that it is alive every minute. If the process running it stops (a crash or a restart) and nothing is heard from the job for 15 minutes, it is failed with worker-lost in error and a job.failed webhook, so you never poll forever. A slow job that is still running is never failed this way. Submit a lost job again; an item import may have saved some rows first, so list items with updatedSince to see what changed.
Webhooks
Add an HTTPS endpoint in Settings ā API ā Webhooks and choose events: job.completed, job.failed, qr_code.created, qr_code.updated, qr_code.deleted, serial.status_changed. An organization can have up to 10 endpoints. Addresses in private or internal networks are refused, and so are URLs with a user name or password.
We POST a JSON event with QRbolt-Event-Id, QRbolt-Event-Type and QRbolt-Signature: t=<unix>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw body> keyed with your endpoint's signing secret. Use the whole secret as the key, whsec_ prefix included. The body is id, object: "event", type, createdAt and data: data.job for job events, data.serial for serial.status_changed, and data.qrCode for qr_code.*. The Test button next to an endpoint sends a ping event. Requests come with User-Agent: QRbolt-Webhooks/1.0. Job events are sent for every job of the organization, whichever key submitted it. Issuing serials sends no event per serial, only qr_code.created for a new product code. Barcode Manager items send no events; sync them with updatedSince.
POST /your/webhook HTTP/1.1
Content-Type: application/json
QRbolt-Event-Id: evt_3f0c2a9d81b7e64c5a12d0ef
QRbolt-Event-Type: job.completed
QRbolt-Signature: t=1762425600,v1=5b2eā¦
{
"id": "evt_3f0c2a9d81b7e64c5a12d0ef",
"object": "event",
"type": "job.completed",
"createdAt": "2026-11-06T10:40:00.000Z",
"data": { "job": { "id": "ā¦", "object": "job", "status": "succeeded", ⦠} }
}Answer with any 2xx within 5 seconds and do the work afterwards. Redirects are not followed: a 3xx counts as a failure. A failed delivery is tried 8 times in all, with exponential backoff starting at 30 seconds, over about an hour. After 10 events in a row that failed every attempt (test pings included), the endpoint is disabled; turn it back on in the dashboard once your receiver works. While it is disabled, its pending retries stop and new events are not sent, and they are not replayed when you turn it back on. The dashboard lists recent deliveries, can resend one, and rotates the signing secret. Events can arrive more than once and out of order, so deduplicate on the event id.
Every change to a QR code emits a qr_code.* event, whoever made it: the API, the dashboard, imports, bulk edits, restores, GS1 workflows and QRbolt support. Events are sent within about a minute of the change. data.qrCode is the code as the API returns it, at the version the event records; shortCode and the scan stats are the current values. data.source says what made the change: api, dashboard, mobile_app, import, qrbolt_support, system, database or unknown. data.requestId is the id of the request that made the change (for API changes, the X-Request-Id of your request), and for API changes data.apiKeyPrefix names the key, so you can skip the echo of your own writes.
A code moved to the trash emits qr_code.deleted, and one restored from the trash emits qr_code.created. After a permanent delete that skipped the trash, shortCode, url and the scan stats are null. An endpoint only receives changes made after it was added.
import { createHmac, timingSafeEqual } from 'node:crypto';
// secret: the whole signing secret, including its whsec_ prefix.
// rawBody: the request body exactly as received (do not re-serialize JSON).
export function verifyQrboltSignature(secret, rawBody, header, toleranceSec = 300) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
const given = Buffer.from(parts.v1 ?? '', 'hex');
return given.length === expected.length && timingSafeEqual(given, expected);
}Versioning and changes
v1 only grows: new endpoints, optional fields, response fields and error types can be added, so ignore fields you do not know. Removing or changing anything needs a new version. Nothing in v1 is deprecated yet. A deprecated endpoint will be announced in the changelog, will answer with Deprecation and Sunset headers, and will stay available for at least 6 months after it is announced. Every change is listed in the changelog below.
Changelog
- 1.0.0: First version of the QRbolt API.