Generate a single QR code

curl --request POST \
  --url https://www.closient.com/products/api/v1/qr/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "expiry": "261231",
  "format": "svg",
  "gtin": "00012345678905",
  "lot": "LOT-A001",
  "serial": "SER-0001",
  "size": 400
}
'

import requests

url = "https://www.closient.com/products/api/v1/qr/"

payload = {
    "expiry": "261231",
    "format": "svg",
    "gtin": "00012345678905",
    "lot": "LOT-A001",
    "serial": "SER-0001",
    "size": 400
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    expiry: '261231',
    format: 'svg',
    gtin: '00012345678905',
    lot: 'LOT-A001',
    serial: 'SER-0001',
    size: 400
  })
};

fetch('https://www.closient.com/products/api/v1/qr/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.closient.com/products/api/v1/qr/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expiry' => '261231',
    'format' => 'svg',
    'gtin' => '00012345678905',
    'lot' => 'LOT-A001',
    'serial' => 'SER-0001',
    'size' => 400
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/products/api/v1/qr/"

	payload := strings.NewReader("{\n  \"expiry\": \"261231\",\n  \"format\": \"svg\",\n  \"gtin\": \"00012345678905\",\n  \"lot\": \"LOT-A001\",\n  \"serial\": \"SER-0001\",\n  \"size\": 400\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.closient.com/products/api/v1/qr/")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expiry\": \"261231\",\n  \"format\": \"svg\",\n  \"gtin\": \"00012345678905\",\n  \"lot\": \"LOT-A001\",\n  \"serial\": \"SER-0001\",\n  \"size\": 400\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/products/api/v1/qr/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expiry\": \"261231\",\n  \"format\": \"svg\",\n  \"gtin\": \"00012345678905\",\n  \"lot\": \"LOT-A001\",\n  \"serial\": \"SER-0001\",\n  \"size\": 400\n}"

response = http.request(request)
puts response.read_body

"<string>"

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

Generate a single QR code

Render a QR code for a GTIN with optional GS1 Application Identifiers (lot, serial, expiry). Returns the image bytes directly with the appropriate content-type (``image/svg+xml``, ``image/png``, ``application/pdf``, or ``application/postscript``). Single QR generation is synchronous because rendering is fast (<50ms) and cached. For batches, use ``POST /qr/bulk/``. **HRI (C-4395)**: pass ``hri`` (inline options), ``hri_preset`` (a saved preset name), or neither — in which case the calling organization's default preset applies automatically, if one is set. Composing HRI requires ``xdim_mm`` and does not support ``format='tif'``; ``format='png'`` additionally requires ``dpmm`` to map to 300 or 600 dpi. Omitting both and having no org default renders the bare symbol exactly as before this field existed. **Caching**: responses are deterministic given the request body **when ``hri`` is used** (or neither ``hri`` nor ``hri_preset`` is set and the org has no default preset) — cached ``public, max-age=2592000`` (30 days) with a strong ``ETag``. When a *named or default preset* supplies the HRI configuration, the response additionally depends on mutable per-organization state, so it is cached ``private`` instead. Clients sending ``If-None-Match`` with a matching ETag get ``304 Not Modified`` either way.

POST

products

api

curl --request POST \
  --url https://www.closient.com/products/api/v1/qr/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "expiry": "261231",
  "format": "svg",
  "gtin": "00012345678905",
  "lot": "LOT-A001",
  "serial": "SER-0001",
  "size": 400
}
'

import requests

url = "https://www.closient.com/products/api/v1/qr/"

payload = {
    "expiry": "261231",
    "format": "svg",
    "gtin": "00012345678905",
    "lot": "LOT-A001",
    "serial": "SER-0001",
    "size": 400
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    expiry: '261231',
    format: 'svg',
    gtin: '00012345678905',
    lot: 'LOT-A001',
    serial: 'SER-0001',
    size: 400
  })
};

fetch('https://www.closient.com/products/api/v1/qr/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.closient.com/products/api/v1/qr/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expiry' => '261231',
    'format' => 'svg',
    'gtin' => '00012345678905',
    'lot' => 'LOT-A001',
    'serial' => 'SER-0001',
    'size' => 400
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/products/api/v1/qr/"

	payload := strings.NewReader("{\n  \"expiry\": \"261231\",\n  \"format\": \"svg\",\n  \"gtin\": \"00012345678905\",\n  \"lot\": \"LOT-A001\",\n  \"serial\": \"SER-0001\",\n  \"size\": 400\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.closient.com/products/api/v1/qr/")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expiry\": \"261231\",\n  \"format\": \"svg\",\n  \"gtin\": \"00012345678905\",\n  \"lot\": \"LOT-A001\",\n  \"serial\": \"SER-0001\",\n  \"size\": 400\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/products/api/v1/qr/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expiry\": \"261231\",\n  \"format\": \"svg\",\n  \"gtin\": \"00012345678905\",\n  \"lot\": \"LOT-A001\",\n  \"serial\": \"SER-0001\",\n  \"size\": 400\n}"

response = http.request(request)
puts response.read_body

"<string>"

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

Authorizations

X-API-Key

string

header

required

Body

application/json

Request body for the synchronous single-QR endpoint.

Encodes a GS1 Digital Link URL as a QR code. The gtin is the only required identifier; lot, serial, and expiry are GS1 Application Identifier values that, when present, are appended to the Digital Link path/query so a phone scan resolves to the most specific instance available.

gtin

string

required

GTIN barcode (GTIN-8, 12, 13, or 14, with or without separators). Normalized to GTIN-14 server-side before encoding into the Digital Link URL.

Required string length: 8 - 17

Pattern: ^[\d\s\-]{8,17}$

lot

string | null

Optional GS1 AI(10) lot/batch identifier — 1-20 printable ASCII chars, no spaces. Encoded into the Digital Link path as /10/{lot}. When present alongside serial, both are added (lot before serial).

Required string length: 1 - 20

Pattern: ^[\x21-\x7E]{1,20}$

serial

string | null

Optional GS1 AI(21) serial identifier — 1-20 printable ASCII chars, no spaces. Encoded into the Digital Link path as /21/{serial}. Use serial for unit-level traceability when each item carries a unique tag.

Required string length: 1 - 20

Pattern: ^[\x21-\x7E]{1,20}$

expiry

string | null

Optional GS1 AI(17) expiry date as YYMMDD — exactly 6 digits (e.g. 261231 for 2026-12-31). Encoded into the Digital Link query as ?17={expiry}.

Required string length: 6

Pattern: ^\d{6}$

format

enum<string>

default:png

Output image format. svg for resolution-independent vector output; png for raster output sized by size; pdf for single-page vector PDF (path operators in the content stream — for print houses that scale to label size at the press, not in the browser); eps for PostScript vector output that packaging-design tools ingest into Illustrator.

Available options:

svg,

png,

pdf,

eps,

tif

size

integer

default:400

Target image side length in pixels (50-2000). QR codes are square, so this is both width and height. For format='svg', format='pdf', and format='eps' the value is treated as the target width in SVG user units / PostScript points (1pt = 1/72 inch ≈ 0.353mm), so a 400-unit symbol is roughly 140mm wide. Ignored when xdim_mm is set — X-dimension-correct sizing supersedes the pixel heuristic.

Required range: 50 <= x <= 2000

cmyk

boolean

default:false

Emit CMYK process colours instead of RGB. Only valid with format='eps' — any other format returns 422. Use for print houses that ingest the EPS directly into a CMYK workflow, avoiding an RGB→CMYK conversion that can shift module ink density.

xdim_mm

number | null

Target physical X-dimension (module width) in millimetres. When set, the symbol is sized so each module is exactly this wide on the printed surface (via Zint --scalexdimdp), size is ignored, and physical-size metadata travels with the file (PNG pHYs chunk, TIF resolution IFD tags, SVG width/height in mm). GS1 recommends 0.625 mm for consumer packaging; 0.495 mm is the GS1 minimum. Null keeps the legacy pixel-heuristic sizing.

Required range: 0.1 <= x <= 10

dpmm

number

default:11.81

Device resolution in dots per millimetre, used only when xdim_mm is set. Default 11.81 (300 dpi), matching the label/flexo presses we target. Affects the raster pixel grid for PNG/TIF; vector outputs (SVG/EPS) carry physical units regardless. When hri composes onto format='png', this must round to 300 or 600 dpi — HRI legibility enforcement runs through the print-export pipeline, which only supports those two raster resolutions.

Required range: 1 <= x <= 200

hri

HRIOptions · object | null

Human Readable Interpretation configuration to compose onto the symbol (C-4395) — placement, layout, notation and typography. Takes precedence over hri_preset and the organization's default preset. Composing HRI requires xdim_mm to be set (legibility is evaluated against a physical size); omit both to render the bare symbol exactly as before this field existed.

Show child attributes

Example:

{
  "enabled": true,
  "layout": "single_line",
  "notation": "bracketed_ai",
  "placement": "below",
  "pos_profile": false,
  "typography": {
    "alignment": "center",
    "font_family": "OCR-B",
    "font_size": 24,
    "leading": 1.2
  }
}

hri_preset

string | null

Name of a saved HRI preset (see POST /hri-presets/) to apply instead of specifying hri inline. Resolved against the calling organization; unknown names return 422. Ignored when hri is set.

Maximum string length: 128

Response

The response is of type file.

Overview

Account

Products

Brands

Locations

Retailers

Search

GS1 Digital Link

EPCIS 2.0

Integrations

Billing

Scanner

Compliance

Certifications

Sustainability

Notifications

Dashboard

Analytics

Agent

Substances

BYOS

Content

Signals

Generate a single QR code

Authorizations

Body

Response