API reference

QRbolt API v1.0.0. Base URL https://api.qrbolt.com. Machine-readable: openapi.json. Every operation also accepts X-Request-Id, and every error is application/problem+json (see Errors). Rules that apply across endpoints, such as rate limits, idempotency and jobs, are in the guide.

Health

Service health (no API key needed)

GET /v1/healthno API key

Answers 200 with {"status":"ok"} while the API can serve requests, and 503 when it cannot.

No API key needed.

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 ยท application/json ยท object

    Headers: X-Request-Id

  • default Error (problem+json) ยท application/problem+json ยท Problem

QR codes

Create a QR code (URL, PHONE, WIFI, VCARD)

POST /v1/qr-codes

Scope: qr:write

type TIME_BASED is refused here (400 validation-error at /type): create time-based codes with POST /v1/qr-codes/time-based.

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Request body (JSON)

  • name stringrequired

    min length 1 ยท max length 255

  • customDomainId string

    A verified custom domain of the account (GET /v1/domains).

    pattern ^c[a-z0-9]{24}$

  • groupId string

    A group of the account (GET /v1/groups).

    pattern ^c[a-z0-9]{24}$

  • description string

    max length 2000

  • slug string

    max length 100 ยท pattern ^[a-zA-Z0-9_-]+$

  • showLandingPage boolean
  • departmentId string

    The department that owns the code (GET /v1/departments). Omit it to use the default: a department key's own department, otherwise the primary (or only) department of the key's creator, or none if they have no department. Send null to leave the code unassigned and visible to the whole organization; a department key cannot.

    pattern ^c[a-z0-9]{24}$ ยท nullable

  • isPasswordProtected boolean
  • password string

    min length 6 ยท max length 128

  • isSuspended boolean
  • type string

    URL (default), PHONE, WIFI or VCARD. Time-based codes have their own endpoint.

    one of: URL, PHONE, WIFI, VCARD, TIME_BASED

  • destinationUrl string

    max length 2048

  • ssid string

    max length 32

  • security string

    WIFI codes: the network's security type.

    one of: WPA, WEP, nopass

  • hidden boolean

    WIFI codes: whether the network is hidden.

  • vcardFirstName string

    max length 255

  • vcardLastName string

    max length 255

  • vcardFullName string

    max length 255

  • vcardOrganization string

    max length 255

  • vcardTitle string

    max length 255

  • vcardEmail string (email)

    max length 254

  • vcardPhone string

    max length 255

  • vcardMobile string

    max length 255

  • vcardWorkPhone string

    max length 255

  • vcardFax string

    max length 255

  • vcardWebsite string (uri)

    max length 2048

  • vcardAddress string

    max length 500

  • vcardCity string

    max length 255

  • vcardState string

    max length 255

  • vcardPostalCode string

    max length 255

  • vcardCountry string

    max length 255

  • vcardNote string

    max length 2000

  • logoAssetId string

    max length 64

  • designOptions object
  • presetId string

    Apply a design preset saved in the dashboard (GET /v1/presets). The preset fills designOptions and logoAssetId where the request leaves them out; values sent in the request win. An id the key cannot see is a validation error on /presetId.

Responses

  • 201 Success ยท application/json ยท QrCode

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, ETag, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 402 active-code-limit-exceeded: the request needs more active codes than the plan has left; requested, remaining, limit and shortfall give the numbers. Nothing was created. ยท application/problem+json ยท Problem
  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

List QR codes

GET /v1/qr-codes

Scope: qr:read

Parameters

  • limit query ยท integer Items per page (min 1 ยท max 100 ยท default 25)
  • cursor query ยท string Opaque cursor from the previous page (nextCursor), passed back unchanged. A malformed cursor is refused with 400 invalid-cursor. (max length 512)
  • type query ยท string (one of: URL, PHONE, WIFI, TIME_BASED, VCARD)
  • updatedSince query ยท string (date-time) Only codes changed at or after this instant, for incremental sync. An RFC 3339 date-time with a time zone, e.g. 2026-11-01T00:00:00Z.
  • sku query ยท string Only codes with this SKU. (max length 100)
  • gtin query ยท string Only GS1 codes for this GTIN, as 14 digits (pad shorter GTINs with leading zeros). (pattern ^\d{14}$)
  • departmentId query ยท string Only codes in this department (GET /v1/departments). (pattern ^c[a-z0-9]{24}$)
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท object

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Create a time-based QR code

POST /v1/qr-codes/time-based

Scope: qr:write

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Request body (JSON)

  • name stringrequired

    min length 1 ยท max length 255

  • timezone stringrequired

    An IANA time zone name, such as Europe/Zagreb. An unknown name is refused with 409.

    min length 1 ยท max length 64

  • customDomainId string

    A verified custom domain of the account (GET /v1/domains).

    pattern ^c[a-z0-9]{24}$

  • groupId string

    A group of the account (GET /v1/groups).

    pattern ^c[a-z0-9]{24}$

  • description string

    max length 2000

  • slug string

    max length 100 ยท pattern ^[a-zA-Z0-9_-]+$

  • showLandingPage boolean
  • departmentId string

    The department that owns the code (GET /v1/departments). Omit it to use the default: a department key's own department, otherwise the primary (or only) department of the key's creator, or none if they have no department. Send null to leave the code unassigned and visible to the whole organization; a department key cannot.

    pattern ^c[a-z0-9]{24}$ ยท nullable

  • isPasswordProtected boolean
  • password string

    Password that protects the landing page (isPasswordProtected).

    min length 6 ยท max length 128

  • isSuspended boolean
  • defaultUrl string (uri)required

    Where scans go when no rule is active.

    max length 2048

  • rules array of TimeBasedRuleDtorequired

    min items 1 ยท max items 24

  • presetId string

    Apply a design preset saved in the dashboard (GET /v1/presets). The preset fills designOptions and logoAssetId where the request leaves them out; values sent in the request win. An id the key cannot see is a validation error on /presetId.

Responses

  • 201 Success ยท application/json ยท QrCode

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, ETag, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 402 active-code-limit-exceeded: the request needs more active codes than the plan has left; requested, remaining, limit and shortfall give the numbers. Nothing was created. ยท application/problem+json ยท Problem
  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

Get a QR code

GET /v1/qr-codes/{id}

Scope: qr:read

Parameters

  • id path ยท stringrequired
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท QrCode

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, ETag

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Update a QR code

PATCH /v1/qr-codes/{id}

Scope: qr:write

Parameters

  • id path ยท stringrequired
  • X-Change-Note header ยท string Why the change is made, recorded with it in the activity log (up to 500 characters; percent-encode non-ASCII text). Required when the organization requires change notes: without it the request is refused with change-note-required.
  • If-Match header ยท string The version from the ETag (or the version field) of the code you read. The write is refused with 409 conflict if the code changed since; without it, last write wins.
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Request body (JSON)

  • name string

    min length 1 ยท max length 255

  • destinationUrl string

    max length 2048

  • description string

    max length 2000

  • ssid string

    max length 32

  • security string

    WIFI codes: the network's security type.

    one of: WPA, WEP, nopass

  • hidden boolean

    WIFI codes: whether the network is hidden.

  • showLandingPage boolean
  • departmentId string

    Move the code to this department (GET /v1/departments), or send null to make it unassigned and visible to the whole organization. Omit it to leave the department unchanged. A department key cannot move a code out of its department.

    pattern ^c[a-z0-9]{24}$ ยท nullable

  • isPasswordProtected boolean
  • password string

    min length 6 ยท max length 128

  • isSuspended boolean
  • defaultUrl string (uri)

    max length 2048

  • timezone string

    max length 64

  • timeBasedRules array of TimeBasedRuleDto

    min items 1 ยท max items 24

  • vcardFirstName string

    max length 255

  • vcardLastName string

    max length 255

  • vcardFullName string

    max length 255

  • vcardOrganization string

    max length 255

  • vcardTitle string

    max length 255

  • vcardEmail string (email)

    max length 254

  • vcardPhone string

    max length 255

  • vcardMobile string

    max length 255

  • vcardWorkPhone string

    max length 255

  • vcardFax string

    max length 255

  • vcardWebsite string (uri)

    max length 2048

  • vcardAddress string

    max length 500

  • vcardCity string

    max length 255

  • vcardState string

    max length 255

  • vcardPostalCode string

    max length 255

  • vcardCountry string

    max length 255

  • vcardNote string

    max length 2000

  • customDomainId string

    nullable

  • slug string

    max length 100 ยท pattern ^[a-zA-Z0-9_-]+$ ยท nullable

  • groupId string

    pattern ^c[a-z0-9]{24}$ ยท nullable

  • logoAssetId string

    max length 64 ยท nullable

  • designOptions object

    nullable

Responses

  • 200 Success ยท application/json ยท QrCode

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, ETag

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Delete a QR code

DELETE /v1/qr-codes/{id}

Scope: qr:write

Parameters

  • id path ยท stringrequired
  • X-Change-Note header ยท string Why the change is made, recorded with it in the activity log (up to 500 characters; percent-encode non-ASCII text). Required when the organization requires change notes: without it the request is refused with change-note-required.
  • If-Match header ยท string The version from the ETag (or the version field) of the code you read. The write is refused with 409 conflict if the code changed since; without it, last write wins.
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 204

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Get the styled QR image (PNG or SVG)

GET /v1/qr-codes/{id}/image

Scope: images:read

Parameters

  • id path ยท stringrequired
  • format query ยท string (one of: png, svg ยท default "png")
  • size query ยท integer Square size in pixels (PNG). SVG scales freely, so size only sets its viewBox. (min 100 ยท max 2000 ยท default 600)
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • If-None-Match header ยท string The ETag of the image you have. If it is unchanged the answer is 304 with no body.

Responses

  • 200 Success ยท image/png, image/svg+xml ยท string (binary)

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, ETag, X-QR-Logo

  • 304 Not modified: the image matches If-None-Match
  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Reference data

List verified custom domains

GET /v1/domains

Scope: qr:read

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท object

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

List departments visible to this key

GET /v1/departments

Scope: qr:read

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท object

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

List QR code groups

GET /v1/groups

Scope: qr:read

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท object

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

List logo assets uploaded in the dashboard

GET /v1/assets

Scope: qr:read

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท object

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

GS1 Digital Link

Issue serialized GS1 Digital Links (up to 1,000)

POST /v1/gs1/links

Scope: gs1:write

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Request body (JSON)

  • serials array of string

    Customer serials (AI 21), the usual case. Provide these or generate, not both.

    min items 1 ยท max items 1,000

  • generate GenerateSerialsV1Dto
    • count integerrequired

      min 1 ยท max 1000

    • length integer

      Characters per serial (A-Z, 0-9). 12 gives ~62 bits of randomness.

      min 8 ยท max 20 ยท default 12

  • gtin stringrequired

    UPC-A (12), EAN-8, EAN-13 or GTIN-14 digits; the check digit must be right.

    pattern ^\d{8}$|^\d{12,14}$

  • batch string

    AI 10 lot or batch.

    min length 1 ยท max length 20

  • attributes object

    Further GS1 Application Identifiers for every link, as AI code to value, e.g. { "17": "271231" } (expiry YYMMDD). Each value is checked against its AI (dates must be real dates); unknown AIs and 01, 10 or 21 are refused.

  • product Gs1ProductV1Dto
    • name stringrequired

      min length 1 ยท max length 200

    • destinationUrl string (uri)required

      max length 2048 ยท pattern ^[Hh][Tt][Tt][Pp][Ss]?://

    • description string

      max length 1000

    • showLandingPage boolean
    • designOptions object
    • logoAssetId string

      A logo asset uploaded in the dashboard (GET /v1/assets).

      max length 64

    • departmentId string

      pattern ^c[a-z0-9]{24}$ ยท nullable

    • groupId string

      pattern ^c[a-z0-9]{24}$

  • onExisting string

    What to do with serials already registered: fail the request with 409 (default) or skip them.

    one of: error, skip

  • metadata object

    Free-form traceability references stored with every serial in this request.

Responses

  • 201 Success ยท application/json ยท Gs1IssueResult

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 402 active-code-limit-exceeded: the request needs more active codes than the plan has left; requested, remaining, limit and shortfall give the numbers. Nothing was created. ยท application/problem+json ยท Problem
  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

Register Digital Links created in your system (up to 1,000)

POST /v1/gs1/links/register

Scope: gs1:write

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Request body (JSON)

  • links array of stringrequired

    Serialized GS1 Digital Links (with AI 21) on a verified domain of the account, https only.

    min items 1 ยท max items 1,000

  • product Gs1ProductV1Dto
    • name stringrequired

      min length 1 ยท max length 200

    • destinationUrl string (uri)required

      max length 2048 ยท pattern ^[Hh][Tt][Tt][Pp][Ss]?://

    • description string

      max length 1000

    • showLandingPage boolean
    • designOptions object
    • logoAssetId string

      A logo asset uploaded in the dashboard (GET /v1/assets).

      max length 64

    • departmentId string

      pattern ^c[a-z0-9]{24}$ ยท nullable

    • groupId string

      pattern ^c[a-z0-9]{24}$

  • onExisting string

    What to do with serials already registered: fail the request with 409 (default) or skip them.

    one of: error, skip

  • metadata object

    Free-form traceability references stored with every serial in this request.

Responses

  • 201 Success ยท application/json ยท Gs1RegisterResult

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 402 active-code-limit-exceeded: the request needs more active codes than the plan has left; requested, remaining, limit and shortfall give the numbers. Nothing was created. ยท application/problem+json ยท Problem
  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

List serials

GET /v1/gs1/serials

Scope: gs1:read

Parameters

  • limit query ยท integer Items per page (min 1 ยท max 100 ยท default 25)
  • cursor query ยท string Opaque cursor from the previous page (nextCursor), passed back unchanged. A malformed cursor is refused with 400 invalid-cursor. (max length 512)
  • gtin query ยท string (pattern ^\d{14}$)
  • status query ยท string (one of: active, recalled, void)
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท object

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Get a serial

GET /v1/gs1/serials/{gtin}/{serial}

Scope: gs1:read

Path: the GTIN as 14 digits and the serial percent-encoded (a / in a serial is %2F).

Parameters

  • gtin path ยท stringrequired
  • serial path ยท stringrequired
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท Serial

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Recall, void or re-activate a serial, or replace its metadata

PATCH /v1/gs1/serials/{gtin}/{serial}

Scope: gs1:write

Re-activating a recalled or void serial uses an active code again, so it can be refused with 402.

Parameters

  • gtin path ยท stringrequired
  • serial path ยท stringrequired
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • X-Change-Note header ยท string Why the change is made, recorded with it in the activity log (up to 500 characters; percent-encode non-ASCII text). Required when the organization requires change notes: without it the request is refused with change-note-required.

Request body (JSON)

  • status string

    one of: active, recalled, void

  • metadata object

Responses

  • 200 Success ยท application/json ยท Serial

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 402 active-code-limit-exceeded: the request needs more active codes than the plan has left; requested, remaining, limit and shortfall give the numbers. Nothing was created. ยท application/problem+json ยท Problem
  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Get the QR image for a serial

GET /v1/gs1/serials/{gtin}/{serial}/image

Scope: images:read

Parameters

  • gtin path ยท stringrequired
  • serial path ยท stringrequired
  • format query ยท string (one of: png, svg ยท default "png")
  • size query ยท integer Square size in pixels (PNG). SVG scales freely, so size only sets its viewBox. (min 100 ยท max 2000 ยท default 600)
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • If-None-Match header ยท string The ETag of the image you have. If it is unchanged the answer is 304 with no body.

Responses

  • 200 Success ยท image/png, image/svg+xml ยท string (binary)

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, ETag, X-QR-Logo

  • 304 Not modified: the image matches If-None-Match
  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Jobs

Issue Digital Links asynchronously (up to 100,000)

POST /v1/gs1/links/jobs

Scope: gs1:write

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Request body (JSON)

  • serials array of string

    Customer serials (AI 21), the usual case. Provide these or generate, not both.

    min items 1 ยท max items 100,000

  • generate GenerateSerialsJobV1Dto
    • count integerrequired

      min 1 ยท max 100000

    • length integer

      Characters per serial (A-Z, 0-9). 12 gives ~62 bits of randomness.

      min 8 ยท max 20 ยท default 12

  • gtin stringrequired

    UPC-A (12), EAN-8, EAN-13 or GTIN-14 digits; the check digit must be right.

    pattern ^\d{8}$|^\d{12,14}$

  • batch string

    AI 10 lot or batch.

    min length 1 ยท max length 20

  • attributes object

    Further GS1 Application Identifiers for every link, as AI code to value, e.g. { "17": "271231" } (expiry YYMMDD). Each value is checked against its AI (dates must be real dates); unknown AIs and 01, 10 or 21 are refused.

  • product Gs1ProductV1Dto
    • name stringrequired

      min length 1 ยท max length 200

    • destinationUrl string (uri)required

      max length 2048 ยท pattern ^[Hh][Tt][Tt][Pp][Ss]?://

    • description string

      max length 1000

    • showLandingPage boolean
    • designOptions object
    • logoAssetId string

      A logo asset uploaded in the dashboard (GET /v1/assets).

      max length 64

    • departmentId string

      pattern ^c[a-z0-9]{24}$ ยท nullable

    • groupId string

      pattern ^c[a-z0-9]{24}$

  • onExisting string

    What to do with serials already registered: fail the request with 409 (default) or skip them.

    one of: error, skip

  • metadata object

    Free-form traceability references stored with every serial in this request.

Responses

  • 202 Success ยท application/json ยท Job

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 402 active-code-limit-exceeded: the request needs more active codes than the plan has left; requested, remaining, limit and shortfall give the numbers. Nothing was created. ยท application/problem+json ยท Problem
  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

Register links asynchronously (up to 100,000)

POST /v1/gs1/links/register/jobs

Scope: gs1:write

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Request body (JSON)

  • links array of stringrequired

    Serialized GS1 Digital Links (with AI 21) on a verified domain of the account, https only.

    min items 1 ยท max items 100,000

  • product Gs1ProductV1Dto
    • name stringrequired

      min length 1 ยท max length 200

    • destinationUrl string (uri)required

      max length 2048 ยท pattern ^[Hh][Tt][Tt][Pp][Ss]?://

    • description string

      max length 1000

    • showLandingPage boolean
    • designOptions object
    • logoAssetId string

      A logo asset uploaded in the dashboard (GET /v1/assets).

      max length 64

    • departmentId string

      pattern ^c[a-z0-9]{24}$ ยท nullable

    • groupId string

      pattern ^c[a-z0-9]{24}$

  • onExisting string

    What to do with serials already registered: fail the request with 409 (default) or skip them.

    one of: error, skip

  • metadata object

    Free-form traceability references stored with every serial in this request.

Responses

  • 202 Success ยท application/json ยท Job

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 402 active-code-limit-exceeded: the request needs more active codes than the plan has left; requested, remaining, limit and shortfall give the numbers. Nothing was created. ยท application/problem+json ยท Problem
  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

Export QR images as a ZIP (up to 1,000 codes)

POST /v1/images/jobs

Scope: images:read

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Request body (JSON)

  • ids array of stringrequired

    QR code ids to render; duplicates are rendered once.

    min items 1 ยท max items 1,000

  • format string

    one of: png, svg ยท default "png"

  • size integer

    Square size in pixels of each image.

    min 100 ยท max 2000 ยท default 600

Responses

  • 202 Success ยท application/json ยท Job

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

Import items asynchronously (up to 10,000)

POST /v1/items/jobs/import

Scope: items:write

Creates or updates Barcode Manager items, matched by sku, then gtin, then manufacturer and item number. Not all or nothing: valid rows are saved, rows with errors are skipped, and once the item limit is reached rows that would add a unit are notProcessed while updates go on. The results are JSON Lines, one line per row: row, status (created, updated, unchanged, skipped or notProcessed), id, sku, gtin and errors (a rule error has a pointer into the job body, such as /items/3/gtin). Rows with gtin "assign" get numbers in row order while the prefix has them; the rest are skipped with PREFIX_FULL. The job summary counts each status and gives the batchId.

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Request body (JSON)

  • items array of ImportItemV1Dtorequired

    Items to create or update, matched to existing items by sku, then gtin, then manufacturer and item number (up to 10000)

    min items 1

Responses

  • 202 Success ยท application/json ยท Job

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

Export barcode files asynchronously (up to 2,000 items)

POST /v1/items/jobs/export

Scope: barcodes:read

A ZIP of files plus a spec sheet, an A4 label-sheet PDF, or a spec-sheet PDF. A ZIP or label sheet releases its items (a DRAFT becomes LIVE and its GTIN locks), so when any requested item is a DRAFT it also needs items:write; without it the request, or the job when it runs, is refused with the forbidden problem type and reason draft-release-needs-items-write. A spec sheet releases nothing and needs barcodes:read only.

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Request body (JSON)

  • ids array of stringrequired

    Item ids (up to 2000). Each must be an item of your organization when you submit; items deleted before the job runs are left out.

    min items 1

  • output string

    zip: one file per item plus a spec sheet; labels: an A4 label-sheet PDF; spec: a spec-sheet PDF. zip and labels release the items, which for a DRAFT needs the items:write scope. Needs a plan with batch barcode export. The file is kept for 24 hours.

    one of: zip, labels, spec ยท default "zip"

  • format string

    File format inside a zip

    one of: svg, png, pdf ยท default "pdf"

  • dpi number

    one of: 300, 600 ยท default 300

  • layout string

    Label layout for output labels: a4-3x8, a4-3x7, a4-4x10, a4-2x7 or custom-CxR (1 to 10 columns, 1 to 20 rows)

    max length 20 ยท default "a4-3x8"

Responses

  • 202 Success ยท application/json ยท Job

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

List jobs

GET /v1/jobs

Scope: jobs:read

The jobs this key submitted, newest first.

Parameters

  • limit query ยท integer Items per page (min 1 ยท max 100 ยท default 25)
  • cursor query ยท string Opaque cursor from the previous page (nextCursor), passed back unchanged. A malformed cursor is refused with 400 invalid-cursor. (max length 512)
  • status query ยท string Only jobs with this status (one of: queued, running, succeeded, failed)
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท object

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Get a job

GET /v1/jobs/{id}

Scope: jobs:read

Poll until status is succeeded or failed. A job whose worker stopped mid-run (a crash or restart) is failed after 15 minutes without a heartbeat, with error type worker-lost and a job.failed webhook; a slow job that is still running is never failed this way. Results and the job input are deleted after their retention (see the results download); the job stays listed.

Parameters

  • id path ยท stringrequired
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท Job

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Download job results (CSV, JSONL or ZIP)

GET /v1/jobs/{id}/results

Scope: jobs:read

Downloading results also needs gs1:read (GS1 jobs), images:read (image jobs), barcodes:read (barcode export jobs) or items:read (item import jobs). Item import results are one JSON line per input row (row, status, id, sku, gtin, errors) whatever the format. Results are kept for 7 days (barcode export artwork for 24 hours), then deleted: the download is 404 and resultsUrl becomes null; the job itself stays listed.

Parameters

  • id path ยท stringrequired
  • format query ยท string GS1 jobs: csv (default) or jsonl. Ignored for other job types: image and barcode export jobs return a file, item import jobs always JSON Lines. (one of: csv, jsonl)
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท text/csv, application/x-ndjson, application/zip, application/pdf ยท string

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Design presets

List design presets

GET /v1/presets

Scope: qr:read

The Design Studio presets of the admin who created this API key, newest first. Presets belong to a user, so a key sees its creator's presets.

Parameters

  • limit query ยท integer Items per page (min 1 ยท max 100 ยท default 25)
  • cursor query ยท string Opaque cursor from the previous page (nextCursor), passed back unchanged. A malformed cursor is refused with 400 invalid-cursor. (max length 512)
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท object

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Get a design preset

GET /v1/presets/{id}

Scope: qr:read

Parameters

  • id path ยท stringrequired Preset id
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท Preset

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Items (Barcode Manager)

List items

GET /v1/items

Scope: items:read

Newest first. Filter by sku, gtin, status, kind, category or updatedSince (for sync). Deleted items do not appear: only Drafts can be deleted (in the dashboard, or by undoing a save or import), and their numbers were never printed. Discontinued items stay listed with status DISCONTINUED.

Parameters

  • limit query ยท integer Items per page (min 1 ยท max 100 ยท default 25)
  • cursor query ยท string Opaque cursor from the previous page (nextCursor), passed back unchanged. A malformed cursor is refused with 400 invalid-cursor. (max length 512)
  • sku query ยท string (min length 1 ยท max length 64)
  • gtin query ยท string Any GTIN length (min length 1 ยท max length 32)
  • status query ยท string Default: every status (one of: DRAFT, LIVE, DISCONTINUED)
  • kind query ยท string (one of: GTIN_ITEM, INTERNAL)
  • category query ยท string (min length 1 ยท max length 80)
  • updatedSince query ยท string (date-time) Only items changed at or after this instant, for incremental sync. An RFC 3339 date-time with a time zone, e.g. 2026-11-01T00:00:00Z, as for QR codes.
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท object

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Create an item

POST /v1/items

Scope: items:write

New items are DRAFT. Send gtin "assign" to take the lowest free GTIN from a declared prefix (prefix chooses it); with no prefix declared the answer is 409 conflict with code NO_PREFIX, and with a full prefix code PREFIX_FULL. Rule violations are 400 validation-error with field, code and severity in errors.

Only units count toward the plan item limit (packs and cases are free); past it the answer is 403 forbidden with reason item-limit-exceeded and the shortfall.

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Request body (JSON)

  • name string

    Product or item name

    max length 200

  • description string

    Free text

    max length 2000 ยท nullable

  • kind string

    GTIN_ITEM carries a GTIN; INTERNAL is an internal code (Code 128 or Code 39) with no GTIN. Defaults from whether a gtin is given.

    one of: GTIN_ITEM, INTERNAL

  • gtin string

    GTIN-8, -12, -13 or -14 with its check digit, or "assign" for the next free number from your GS1 Company Prefix (see prefix), also on update and in imports. A released (LIVE) item, or one a Digital Link carries, keeps its GTIN: change it with POST /items/{id}/change-number.

    max length 32 ยท nullable

  • prefix string

    With gtin "assign": the declared prefix to assign from (its digits). Defaults to the first declared Company Prefix, or the first single GTIN when there is none. A prefix that is not declared is refused (code unknownPrefix).

    max length 14

  • sku string

    Your stock-keeping unit; unique in the account when set

    max length 64 ยท nullable

  • manufacturerName string

    max length 120 ยท nullable

  • manufacturerItemNumber string

    The maker or supplier item number; unique per manufacturer in the account

    max length 64 ยท nullable

  • codeValue string

    Barcode value of an internal item when it differs from its SKU. An internal item needs a codeValue or a sku.

    max length 48 ยท nullable

  • symbology string

    The barcode type to print, when it can carry the item (symbologyNotAllowed otherwise). Null derives it: GTIN-13 EAN13, GTIN-12 UPCA, a GTIN sent as 8 digits EAN8, a GTIN-14 with indicator 1 to 8 ITF14, internal items CODE128.

    one of: EAN13, UPCA, UPCE, EAN8, ITF14, GS1_128, CODE128, CODE39 ยท nullable

  • category string

    max length 80 ยท nullable

  • parentId string

    The unit (or pack) this packaging level belongs to, an item of your organization. null makes the item a UNIT again and clears packQuantity.

    max length 64 ยท nullable

  • level string

    PACK or CASE under a parent; UNIT without one. A UNIT can have packs and cases below it, a PACK only cases. A parentId without a level makes a CASE.

    one of: UNIT, PACK, CASE

  • packQuantity integer

    Units in this pack or case; required when parentId is set

    min 1 ยท max 100000 ยท nullable

Responses

  • 201 Success ยท application/json ยท Item

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

Get an item by SKU

GET /v1/items/by-sku/{sku}

Scope: items:read

Parameters

  • sku path ยท stringrequired The SKU, percent-encoded; 1 to 64 characters, matched as stored (trimmed)
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท Item

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Create or update an item by SKU

PUT /v1/items/by-sku/{sku}

Scope: items:write

Creates the item when no item has this SKU (201; name is then required), otherwise updates the fields sent, like PATCH (200). A sku in the body must match the path. The ERP sync path.

Not covered by Idempotency-Key: resending the same values changes nothing, not even updatedAt.

Parameters

  • sku path ยท stringrequired The SKU, percent-encoded; 1 to 64 characters, matched as stored (trimmed)
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Request body (JSON)

  • name string

    Product or item name

    max length 200

  • description string

    Free text

    max length 2000 ยท nullable

  • kind string

    GTIN_ITEM carries a GTIN; INTERNAL is an internal code (Code 128 or Code 39) with no GTIN. Defaults from whether a gtin is given.

    one of: GTIN_ITEM, INTERNAL

  • gtin string

    GTIN-8, -12, -13 or -14 with its check digit, or "assign" for the next free number from your GS1 Company Prefix (see prefix), also on update and in imports. A released (LIVE) item, or one a Digital Link carries, keeps its GTIN: change it with POST /items/{id}/change-number.

    max length 32 ยท nullable

  • prefix string

    With gtin "assign": the declared prefix to assign from (its digits). Defaults to the first declared Company Prefix, or the first single GTIN when there is none. A prefix that is not declared is refused (code unknownPrefix).

    max length 14

  • sku string

    Your stock-keeping unit; unique in the account when set

    max length 64 ยท nullable

  • manufacturerName string

    max length 120 ยท nullable

  • manufacturerItemNumber string

    The maker or supplier item number; unique per manufacturer in the account

    max length 64 ยท nullable

  • codeValue string

    Barcode value of an internal item when it differs from its SKU. An internal item needs a codeValue or a sku.

    max length 48 ยท nullable

  • symbology string

    The barcode type to print, when it can carry the item (symbologyNotAllowed otherwise). Null derives it: GTIN-13 EAN13, GTIN-12 UPCA, a GTIN sent as 8 digits EAN8, a GTIN-14 with indicator 1 to 8 ITF14, internal items CODE128.

    one of: EAN13, UPCA, UPCE, EAN8, ITF14, GS1_128, CODE128, CODE39 ยท nullable

  • category string

    max length 80 ยท nullable

  • parentId string

    The unit (or pack) this packaging level belongs to, an item of your organization. null makes the item a UNIT again and clears packQuantity.

    max length 64 ยท nullable

  • level string

    PACK or CASE under a parent; UNIT without one. A UNIT can have packs and cases below it, a PACK only cases. A parentId without a level makes a CASE.

    one of: UNIT, PACK, CASE

  • packQuantity integer

    Units in this pack or case; required when parentId is set

    min 1 ยท max 100000 ยท nullable

Responses

  • 200 Success ยท application/json ยท Item

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 201 Created: no item had this SKU ยท application/json ยท Item

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Get an item

GET /v1/items/{id}

Scope: items:read

Parameters

  • id path ยท stringrequired
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท Item

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Update an item

PATCH /v1/items/{id}

Scope: items:write

Absent fields are left as they are; null clears a field. The GTIN of a LIVE or DISCONTINUED item, or of one with a Digital Link, is locked (validation-error code gtinLocked): change it with change-number. gtin "assign" gives a number only to an item without one.

Parameters

  • id path ยท stringrequired
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Request body (JSON)

  • name string

    Product or item name

    max length 200

  • description string

    Free text

    max length 2000 ยท nullable

  • kind string

    GTIN_ITEM carries a GTIN; INTERNAL is an internal code (Code 128 or Code 39) with no GTIN. Defaults from whether a gtin is given.

    one of: GTIN_ITEM, INTERNAL

  • gtin string

    GTIN-8, -12, -13 or -14 with its check digit, or "assign" for the next free number from your GS1 Company Prefix (see prefix), also on update and in imports. A released (LIVE) item, or one a Digital Link carries, keeps its GTIN: change it with POST /items/{id}/change-number.

    max length 32 ยท nullable

  • prefix string

    With gtin "assign": the declared prefix to assign from (its digits). Defaults to the first declared Company Prefix, or the first single GTIN when there is none. A prefix that is not declared is refused (code unknownPrefix).

    max length 14

  • sku string

    Your stock-keeping unit; unique in the account when set

    max length 64 ยท nullable

  • manufacturerName string

    max length 120 ยท nullable

  • manufacturerItemNumber string

    The maker or supplier item number; unique per manufacturer in the account

    max length 64 ยท nullable

  • codeValue string

    Barcode value of an internal item when it differs from its SKU. An internal item needs a codeValue or a sku.

    max length 48 ยท nullable

  • symbology string

    The barcode type to print, when it can carry the item (symbologyNotAllowed otherwise). Null derives it: GTIN-13 EAN13, GTIN-12 UPCA, a GTIN sent as 8 digits EAN8, a GTIN-14 with indicator 1 to 8 ITF14, internal items CODE128.

    one of: EAN13, UPCA, UPCE, EAN8, ITF14, GS1_128, CODE128, CODE39 ยท nullable

  • category string

    max length 80 ยท nullable

  • parentId string

    The unit (or pack) this packaging level belongs to, an item of your organization. null makes the item a UNIT again and clears packQuantity.

    max length 64 ยท nullable

  • level string

    PACK or CASE under a parent; UNIT without one. A UNIT can have packs and cases below it, a PACK only cases. A parentId without a level makes a CASE.

    one of: UNIT, PACK, CASE

  • packQuantity integer

    Units in this pack or case; required when parentId is set

    min 1 ยท max 100000 ยท nullable

Responses

  • 200 Success ยท application/json ยท Item

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Mark an item as released (Live)

POST /v1/items/{id}/release

Scope: items:write

DRAFT becomes LIVE and its GTIN locks. Downloading or exporting its barcode does this too. An item that is not a DRAFT is returned unchanged.

Parameters

  • id path ยท stringrequired
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Responses

  • 200 Success ยท application/json ยท Item

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

Discontinue an item

POST /v1/items/{id}/discontinue

Scope: items:write

A DRAFT or LIVE item becomes DISCONTINUED. It stays listed and downloadable, a unit frees its place in the plan item limit, and its GTIN is never handed out again. A discontinued item is returned unchanged.

Parameters

  • id path ยท stringrequired
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Responses

  • 200 Success ยท application/json ยท Item

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

Reactivate a discontinued item

POST /v1/items/{id}/reactivate

Scope: items:write

Back to LIVE if the item was ever released, otherwise to DRAFT. An item that is not discontinued is returned unchanged.

A reactivated unit needs a free place in the item limit (403 forbidden, reason item-limit-exceeded).

Parameters

  • id path ยท stringrequired
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Responses

  • 200 Success ยท application/json ยท Item

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

Change the GTIN of an item

POST /v1/items/{id}/change-number

Scope: items:write

The way to change a locked GTIN. Requires confirm: true (the JSON boolean); without it, or with false or a string, the answer is 400 validation-error at /confirm. The new number is checked like any GTIN (400 validation-error). For a LIVE or DISCONTINUED item the old number is retired and never assigned again. Refused with 409 conflict and code HAS_DIGITAL_LINK while the item has a Digital Link, and with 400 bad-request for an internal item or the current number.

Parameters

  • id path ยท stringrequired
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Request body (JSON)

  • gtin stringrequired

    The new GTIN-8, -12, -13 or -14, with its check digit

    max length 32

  • confirm booleanrequired

    Must be the JSON boolean true: anything already printed will scan as the old number. Missing, false or anything else is 400 validation-error at /confirm.

Responses

  • 200 Success ยท application/json ยท Item

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 413 payload-too-large: the body is over 5 MB ยท application/problem+json ยท Problem
  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

Get the barcode file (SVG, PNG or PDF)

POST /v1/items/{id}/barcode

Scope: barcodes:read

Print-sized to GS1 specifications, returned as an attachment. Without magnification or digits, the item print settings from the dashboard apply (100% with digits when it has none). Artwork leaving QRbolt releases the item: a DRAFT becomes LIVE and its GTIN locks. barcodes:read is enough for LIVE and DISCONTINUED items; a DRAFT also needs items:write, and without it the request is refused with the forbidden problem type and reason draft-release-needs-items-write.

Idempotency-Key is accepted but holds nothing: the file is never kept, and the key is released when the file is sent, so a retry with the same key renders the file again (releasing a Draft twice changes nothing). A duplicate sent while the first is still rendering gets idempotency-in-progress. On a plan without Barcode Manager (read-only after a downgrade) a DRAFT is refused with reason read-only-plan.

Parameters

  • id path ยท stringrequired
  • format query ยท string (one of: svg, png, pdf ยท default "svg")
  • magnification query ยท number GS1 magnification (0.8 to 2.0). Default: the item print settings, else 1 (min 0.8 ยท max 2 ยท default 1)
  • digits query ยท string Human-readable digits. Default: the item print settings, else true (one of: true, false ยท default "true")
  • dpi query ยท number PNG resolution (one of: 300, 600 ยท default 300)
  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)
  • Idempotency-Key header ยท string Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key. (min length 1 ยท max length 255 ยท pattern ^[\x21-\x7e]+$)

Responses

  • 200 Success ยท image/svg+xml, image/png, application/pdf ยท string (binary)

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy, Idempotent-Replayed

  • 400 validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required ยท application/problem+json ยท Problem
  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 404 not-found: the resource does not exist, or this key cannot see it ยท application/problem+json ยท Problem
  • 409 conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable ยท application/problem+json ยท Problem

    Headers: Retry-After

  • 415 unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed. ยท application/problem+json ยท Problem
  • 422 idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 503 service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff. ยท application/problem+json ยท Problem
  • default Error (problem+json) ยท application/problem+json ยท Problem

List declared GS1 prefixes with remaining capacity

GET /v1/prefixes

Scope: items:read

Prefixes are declared by an admin in the dashboard. Not paginated: every prefix is listed. capacity is 10^(12 - L) for a Company Prefix of L digits and 1 for a single GTIN.

remaining is an upper bound for gtin "assign", which also skips retired numbers and numbers being assigned in the dashboard.

Parameters

  • X-Request-Id header ยท string Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make. (pattern ^[A-Za-z0-9._-]{8,64}$)

Responses

  • 200 Success ยท application/json ยท object

    Headers: X-Request-Id, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • 401 unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active ยท application/problem+json ยท Problem

    Headers: WWW-Authenticate

  • 403 insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export) ยท application/problem+json ยท Problem
  • 429 rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter. ยท application/problem+json ยท Problem

    Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy

  • default Error (problem+json) ยท application/problem+json ยท Problem

Objects

QrCode

  • id string
  • object string

    one of: qr_code

  • version integer

    Current version of the code. Send it as If-Match (the ETag header carries it too) to make PATCH or DELETE conditional.

    nullable

  • type string

    one of: URL, PHONE, WIFI, VCARD, TIME_BASED, GS1_DIGITAL_LINK

  • name string
  • description string

    nullable

  • url string (uri)

    The address encoded in the QR code

    nullable

  • shortCode string
  • destinationUrl string

    Where a scan goes: a URL, or the phone number of a PHONE code. Null for WIFI and VCARD.

    nullable

  • customDomainId string

    nullable

  • slug string

    nullable

  • departmentId string

    nullable

  • sku string

    nullable

  • landingPage object
    • enabled boolean
  • security object
    • passwordProtected boolean
    • suspended boolean
    • flaggedMalicious boolean

      nullable

  • design object
    • designOptions object

      nullable

    • logoAssetId string

      nullable

  • wifi object
    • ssid string

      nullable

    • security string

      nullable

    • hidden boolean
  • vcard object
  • timeBased object
    • defaultUrl string
    • timezone string
    • rules array of object
  • gs1 object
    • gtin string
    • attributes object
    • status string

      one of: active, archived

  • stats object
    • totalScans integer
    • firstScannedAt string (date-time)

      nullable

    • lastScannedAt string (date-time)

      nullable

  • createdAt string (date-time)
  • updatedAt string (date-time)

Serial

  • object string

    one of: gs1_serial

  • gtin string
  • serial string
  • batch string

    nullable

  • status string

    one of: active, recalled, void

  • source string

    one of: customer, generated

  • productId string
  • metadata object

    nullable

  • stats object
    • scanCount integer
    • firstScannedAt string (date-time)

      nullable

    • lastScannedAt string (date-time)

      nullable

  • statusChangedAt string (date-time)

    nullable

  • createdAt string (date-time)

Gs1IssueResult

  • object string

    one of: gs1_issue_result

  • product QrCode
    • id string
    • object string

      one of: qr_code

    • version integer

      Current version of the code. Send it as If-Match (the ETag header carries it too) to make PATCH or DELETE conditional.

      nullable

    • type string

      one of: URL, PHONE, WIFI, VCARD, TIME_BASED, GS1_DIGITAL_LINK

    • name string
    • description string

      nullable

    • url string (uri)

      The address encoded in the QR code

      nullable

    • shortCode string
    • destinationUrl string

      Where a scan goes: a URL, or the phone number of a PHONE code. Null for WIFI and VCARD.

      nullable

    • customDomainId string

      nullable

    • slug string

      nullable

    • departmentId string

      nullable

    • sku string

      nullable

    • landingPage object
      • enabled boolean
    • security object
      • passwordProtected boolean
      • suspended boolean
      • flaggedMalicious boolean

        nullable

    • design object
      • designOptions object

        nullable

      • logoAssetId string

        nullable

    • wifi object
      • ssid string

        nullable

      • security string

        nullable

      • hidden boolean
    • vcard object
    • timeBased object
      • defaultUrl string
      • timezone string
      • rules array of object
    • gs1 object
      • gtin string
      • attributes object
      • status string

        one of: active, archived

    • stats object
      • totalScans integer
      • firstScannedAt string (date-time)

        nullable

      • lastScannedAt string (date-time)

        nullable

    • createdAt string (date-time)
    • updatedAt string (date-time)
  • productCreated boolean
  • issued array of object
  • skipped array of string

Gs1RegisterResult

  • object string

    one of: gs1_register_result

  • products array of Gs1IssueResult

Job

  • id string
  • object string

    one of: job

  • type string

    one of: gs1_issue, gs1_register, images, barcode_export, item_import

  • status string

    one of: queued, running, succeeded, failed

  • progress object
    • total integer
    • processed integer
  • summary object

    nullable

  • error Problem

    Problem details (RFC 9457) when the job failed. type worker-lost when the process running it stopped (no heartbeat for 15 minutes); submit the job again.

    nullable

  • resultsUrl string

    Set once the job has succeeded, until its results are deleted at resultsExpireAt

    nullable

  • createdAt string (date-time)
  • startedAt string (date-time)

    nullable

  • completedAt string (date-time)

    nullable

  • resultsExpireAt string (date-time)

    nullable

Preset

  • id string
  • object string

    one of: preset

  • name string
  • designOptions object

    Design Studio options, in the same shape as a QR code designOptions

    nullable

  • logoAssetId string

    Logo asset of this organization; null when the preset has none or its logo is not this organization's

    nullable

  • createdAt string (date-time)
  • updatedAt string (date-time)

Problem

  • type string (uri)required

    one of: https://qrbolt.com/developers/errors/validation-error, https://qrbolt.com/developers/errors/bad-request, https://qrbolt.com/developers/errors/invalid-cursor, https://qrbolt.com/developers/errors/change-note-required, https://qrbolt.com/developers/errors/unauthorized, https://qrbolt.com/developers/errors/insufficient-scope, https://qrbolt.com/developers/errors/feature-not-enabled, https://qrbolt.com/developers/errors/gs1-not-enabled, https://qrbolt.com/developers/errors/forbidden, https://qrbolt.com/developers/errors/not-found, https://qrbolt.com/developers/errors/conflict, https://qrbolt.com/developers/errors/idempotency-in-progress, https://qrbolt.com/developers/errors/idempotency-key-reuse, https://qrbolt.com/developers/errors/idempotency-response-unavailable, https://qrbolt.com/developers/errors/active-code-limit-exceeded, https://qrbolt.com/developers/errors/payload-too-large, https://qrbolt.com/developers/errors/unsupported-media-type, https://qrbolt.com/developers/errors/rate-limited, https://qrbolt.com/developers/errors/internal-error, https://qrbolt.com/developers/errors/worker-lost, https://qrbolt.com/developers/errors/service-unavailable

  • title stringrequired
  • status integerrequired
  • detail string
  • instance string
  • requestId string
  • reason string

    A stable sub-type of the problem, for example barcode-manager-not-enabled (feature-not-enabled), item-limit-exceeded, draft-release-needs-items-write, read-only-plan or batch-export-not-enabled (forbidden), not-eligible or limit-not-set (gs1-not-enabled).

  • code string

    A stable code on some conflicts: NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK for Barcode Manager items.

  • errors array of object

    Validation errors (type validation-error). Every entry has pointer, a JSON Pointer (RFC 6901, with ~ and / escaped as ~0 and ~1) to the body member or the query or path parameter. Most endpoints add message; Barcode Manager item rules add field, code, severity and sometimes params.