Generate a lot or serial run

curl --request POST \
  --url https://www.closient.com/products/api/v1/lots/runs/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "template_id": "<string>",
  "gtin": "<string>",
  "quantity": 5000000,
  "lot_id": "<string>",
  "tag": "<string>",
  "force_async": false,
  "idempotency_key": "<string>"
}
'

import requests

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

payload = {
    "template_id": "<string>",
    "gtin": "<string>",
    "quantity": 5000000,
    "lot_id": "<string>",
    "tag": "<string>",
    "force_async": False,
    "idempotency_key": "<string>"
}
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({
    template_id: '<string>',
    gtin: '<string>',
    quantity: 5000000,
    lot_id: '<string>',
    tag: '<string>',
    force_async: false,
    idempotency_key: '<string>'
  })
};

fetch('https://www.closient.com/products/api/v1/lots/runs/', 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/lots/runs/",
  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([
    'template_id' => '<string>',
    'gtin' => '<string>',
    'quantity' => 5000000,
    'lot_id' => '<string>',
    'tag' => '<string>',
    'force_async' => false,
    'idempotency_key' => '<string>'
  ]),
  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/lots/runs/"

	payload := strings.NewReader("{\n  \"template_id\": \"<string>\",\n  \"gtin\": \"<string>\",\n  \"quantity\": 5000000,\n  \"lot_id\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"force_async\": false,\n  \"idempotency_key\": \"<string>\"\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/lots/runs/")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"template_id\": \"<string>\",\n  \"gtin\": \"<string>\",\n  \"quantity\": 5000000,\n  \"lot_id\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"force_async\": false,\n  \"idempotency_key\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"template_id\": \"<string>\",\n  \"gtin\": \"<string>\",\n  \"quantity\": 5000000,\n  \"lot_id\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"force_async\": false,\n  \"idempotency_key\": \"<string>\"\n}"

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

{
  "id": "<string>",
  "template_id": "<string>",
  "template_version": 123,
  "scope_key": "<string>",
  "gtin": "<string>",
  "quantity": 123,
  "generated_ids": [
    "<string>"
  ],
  "soft_collision_count": 123,
  "hard_collisions": [
    {
      "position": 123,
      "generated_id": "<string>",
      "conflicts_with_lot_id": "<string>",
      "conflicts_with_serial_id": "<string>",
      "conflicts_with_run_id": "<string>"
    }
  ],
  "created": "2023-11-07T05:31:56Z",
  "first_id": "<string>",
  "last_id": "<string>",
  "counter_state_before": 123,
  "counter_state_after": 123,
  "chunks_done": 123,
  "chunks_total": 123,
  "created_by_id": "<string>",
  "queued_at": "2023-11-07T05:31:56Z",
  "generating_started_at": "2023-11-07T05:31:56Z",
  "committed_at": "2023-11-07T05:31:56Z",
  "discarded_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "discard_reason": ""
}

{
  "id": "<string>",
  "template_id": "<string>",
  "template_version": 123,
  "scope_key": "<string>",
  "gtin": "<string>",
  "quantity": 123,
  "generated_ids": [
    "<string>"
  ],
  "soft_collision_count": 123,
  "hard_collisions": [
    {
      "position": 123,
      "generated_id": "<string>",
      "conflicts_with_lot_id": "<string>",
      "conflicts_with_serial_id": "<string>",
      "conflicts_with_run_id": "<string>"
    }
  ],
  "created": "2023-11-07T05:31:56Z",
  "first_id": "<string>",
  "last_id": "<string>",
  "counter_state_before": 123,
  "counter_state_after": 123,
  "chunks_done": 123,
  "chunks_total": 123,
  "created_by_id": "<string>",
  "queued_at": "2023-11-07T05:31:56Z",
  "generating_started_at": "2023-11-07T05:31:56Z",
  "committed_at": "2023-11-07T05:31:56Z",
  "discarded_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "discard_reason": ""
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "detail": "<string>",
  "run_id": "<string>",
  "hard_collisions": [
    {
      "position": 123,
      "generated_id": "<string>",
      "conflicts_with_lot_id": "<string>",
      "conflicts_with_serial_id": "<string>",
      "conflicts_with_run_id": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

Lots

Generate a lot or serial run

Reserve a contiguous block of identifiers. Lot templates: small batches run inline and return 201 with a reserved run; batches above the async threshold (or force_async=true) return 202 with a queued run a Celery worker completes. A sync hard collision returns 409 with the hard_collisions payload. Serial templates (target_field=serial, C-2712): always async — up to 10,000,000 per run — and always return 202 with a queued run; poll GET /lots/runs/{id}/ or subscribe to the SSE stream for the outcome, and export the reserved serials via GET /lots/runs/{id}/serials.csv|.jsonl. In every case the failed_collision run is persisted and linkable.

POST

products

api

lots

runs

Generate a lot or serial run

curl --request POST \
  --url https://www.closient.com/products/api/v1/lots/runs/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "template_id": "<string>",
  "gtin": "<string>",
  "quantity": 5000000,
  "lot_id": "<string>",
  "tag": "<string>",
  "force_async": false,
  "idempotency_key": "<string>"
}
'

import requests

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

payload = {
    "template_id": "<string>",
    "gtin": "<string>",
    "quantity": 5000000,
    "lot_id": "<string>",
    "tag": "<string>",
    "force_async": False,
    "idempotency_key": "<string>"
}
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({
    template_id: '<string>',
    gtin: '<string>',
    quantity: 5000000,
    lot_id: '<string>',
    tag: '<string>',
    force_async: false,
    idempotency_key: '<string>'
  })
};

fetch('https://www.closient.com/products/api/v1/lots/runs/', 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/lots/runs/",
  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([
    'template_id' => '<string>',
    'gtin' => '<string>',
    'quantity' => 5000000,
    'lot_id' => '<string>',
    'tag' => '<string>',
    'force_async' => false,
    'idempotency_key' => '<string>'
  ]),
  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/lots/runs/"

	payload := strings.NewReader("{\n  \"template_id\": \"<string>\",\n  \"gtin\": \"<string>\",\n  \"quantity\": 5000000,\n  \"lot_id\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"force_async\": false,\n  \"idempotency_key\": \"<string>\"\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/lots/runs/")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"template_id\": \"<string>\",\n  \"gtin\": \"<string>\",\n  \"quantity\": 5000000,\n  \"lot_id\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"force_async\": false,\n  \"idempotency_key\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"template_id\": \"<string>\",\n  \"gtin\": \"<string>\",\n  \"quantity\": 5000000,\n  \"lot_id\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"force_async\": false,\n  \"idempotency_key\": \"<string>\"\n}"

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

{
  "id": "<string>",
  "template_id": "<string>",
  "template_version": 123,
  "scope_key": "<string>",
  "gtin": "<string>",
  "quantity": 123,
  "generated_ids": [
    "<string>"
  ],
  "soft_collision_count": 123,
  "hard_collisions": [
    {
      "position": 123,
      "generated_id": "<string>",
      "conflicts_with_lot_id": "<string>",
      "conflicts_with_serial_id": "<string>",
      "conflicts_with_run_id": "<string>"
    }
  ],
  "created": "2023-11-07T05:31:56Z",
  "first_id": "<string>",
  "last_id": "<string>",
  "counter_state_before": 123,
  "counter_state_after": 123,
  "chunks_done": 123,
  "chunks_total": 123,
  "created_by_id": "<string>",
  "queued_at": "2023-11-07T05:31:56Z",
  "generating_started_at": "2023-11-07T05:31:56Z",
  "committed_at": "2023-11-07T05:31:56Z",
  "discarded_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "discard_reason": ""
}

{
  "id": "<string>",
  "template_id": "<string>",
  "template_version": 123,
  "scope_key": "<string>",
  "gtin": "<string>",
  "quantity": 123,
  "generated_ids": [
    "<string>"
  ],
  "soft_collision_count": 123,
  "hard_collisions": [
    {
      "position": 123,
      "generated_id": "<string>",
      "conflicts_with_lot_id": "<string>",
      "conflicts_with_serial_id": "<string>",
      "conflicts_with_run_id": "<string>"
    }
  ],
  "created": "2023-11-07T05:31:56Z",
  "first_id": "<string>",
  "last_id": "<string>",
  "counter_state_before": 123,
  "counter_state_after": 123,
  "chunks_done": 123,
  "chunks_total": 123,
  "created_by_id": "<string>",
  "queued_at": "2023-11-07T05:31:56Z",
  "generating_started_at": "2023-11-07T05:31:56Z",
  "committed_at": "2023-11-07T05:31:56Z",
  "discarded_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "discard_reason": ""
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "detail": "<string>",
  "run_id": "<string>",
  "hard_collisions": [
    {
      "position": 123,
      "generated_id": "<string>",
      "conflicts_with_lot_id": "<string>",
      "conflicts_with_serial_id": "<string>",
      "conflicts_with_run_id": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

Authorizations

X-API-Key

string

header

required

Body

application/json

Request body for POST /lots/runs/.

template_id

string

required

Template to generate against (id as UUID or shortuuid).

gtin

string

required

GTIN of the product the generated lots belong to.

quantity

integer

required

How many identifiers to generate. Lots cap at 100,000; serial templates (target_field=serial) accept up to 10,000,000 and always run async.

Required range: 1 <= x <= 10000000

lot_id

string | null

Lot (id as UUID or shortuuid) the generated serials belong to. Optional for serial templates (target_field=serial, C-4103) — a serialized unit may be unbatched (its identity is the SGTIN, GTIN + serial); omit to mint serials with no lot. Ignored for lot templates.

tag

string | null

Scope tag — required when the template's scope_kind is tag.

Maximum string length: 128

force_async

boolean

default:false

Force the Celery async path even for a small batch (returns a queued run).

idempotency_key

string | null

Optional client request id. A repeat within 5 minutes returns the existing run.

Maximum string length: 128

Response

Created

A generation run and its outcome.

string

required

Run id (22-char shortuuid). Use in /lots/runs/{id}/ paths.

template_id

string

required

Template this run generated against.

template_version

integer

required

Template version pinned at generation time.

scope_key

string

required

Counter scope key derived from the template's scope_kind.

gtin

string

required

GTIN of the product the generated lots belong to.

quantity

integer

required

Number of identifiers requested.

status

enum<string>

required

Lifecycle state of the run.

Available options:

queued,

generating,

reserved,

committed,

discarded,

failed_collision

generated_ids

string[]

required

Denormalized list of identifiers rendered by this run.

soft_collision_count

integer

required

Random-source retries that resolved during generation.

hard_collisions

HardCollisionOut · object[]

required

Populated only on failed_collision runs; empty otherwise.

Show child attributes

created

string<date-time>

required

Creation timestamp (ISO-8601).

first_id

string | null

First identifier in the reserved block; null until reserved.

last_id

string | null

Last identifier in the reserved block; null until reserved.

counter_state_before

integer | null

Counter value (post-reset) before this run advanced it.

counter_state_after

integer | null

Counter value after this run; null on failed_collision.

chunks_done

integer | null

Async progress: chunks written so far.

chunks_total

integer | null

Async progress: total chunks the run will write.

created_by_id

string | null

User id that created the run; null if the user was deleted.

queued_at

string<date-time> | null

When the async run was enqueued.

generating_started_at

string<date-time> | null

When the worker began generating.

committed_at

string<date-time> | null

When the run was committed.

discarded_at

string<date-time> | null

When the run was discarded.

failed_at

string<date-time> | null

When the run failed on a hard collision.

discard_mode

enum<string> | null

rollback or burn on a discarded run; null otherwise.

Available options:

rollback,

burn

discard_reason

string

default:""

Free-text reason recorded when the run was discarded.

List lot runs Read a lot run

Overview

Account

Products

Brands

Locations

Retailers

Search

GS1 Digital Link

EPCIS 2.0

Integrations

Billing

Scanner

Compliance

Certifications

Sustainability

Notifications

Dashboard

Content

Signals

Generate a lot or serial run

Authorizations

Body

Response