Manage barcodes

When to use this. Barcodes are the pool of EAN barcode values held for your organisation and assigned to SKUs and style assortments elsewhere in the product lifecycle. Use these endpoints to fill the pool with the values you have been issued, look up which are still free, correct a mistyped value before it is used, and remove values you no longer need. Linking a barcode to a SKU or a style assortment happens in the assign flows on the style, not through these endpoints.

The workflow

A barcode is an organisation-level value with a single writable field, the barcode text itself. The usual path is to load new values into the pool, find the free ones when you assign barcodes to a style’s SKUs, and tidy up the pool while values are still unassigned. Once a barcode is linked to a SKU or a style assortment it can no longer be renamed or deleted.

Add barcodes to the pool

POST /api/barcodes with an array of { "barcode": "..." } objects. Up to 200 values are created in one all-or-nothing transaction, and every new barcode starts unlinked.

Find free or linked barcodes

GET /api/barcodes with linkedToSku and linkedToStyleAssortment to list barcodes that are already assigned or still free. Follow pagination.cursor (or increment pageNumber) until hasMore is false. Read a single barcode with GET /api/barcodes/{id}.

Correct a free barcode

PUT /api/barcodes/{id} with the new barcode value, or PATCH /api/barcodes/{id} with a JSON Patch that replaces /barcode. To correct several at once, send an array of { "id", "barcode" } objects to PUT /api/barcodes.

Remove unused barcodes

DELETE /api/barcodes/{id} for one barcode, or DELETE /api/barcodes?ids=10435&ids=10436 for several in one all-or-nothing call. Deletion is permanent.

Walkthrough

Add barcodes to the pool, then list the pool to see which values are free. Both responses use the standard envelope; the list adds pagination. Add two new EAN-13 values to the pool:

curl -X POST "https://service.my.delogue.com/api/barcodes" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Auth-Token: Bearer YOUR_API_KEY" \
  -d '[
    { "barcode": "5710000000041" },
    { "barcode": "5710000000058" }
  ]'

const res = await fetch("https://service.my.delogue.com/api/barcodes", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Auth-Token": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify([
    { barcode: "5710000000041" },
    { barcode: "5710000000058" },
  ]),
});
const { data } = await res.json();

{
  "status": "success",
  "code": "barcodes_created",
  "data": [
    {
      "id": 10435,
      "barcode": "5710000000041",
      "properties": []
    },
    {
      "id": 10436,
      "barcode": "5710000000058",
      "properties": []
    }
  ]
}

List the pool and read the linkage flags off each row:

curl "https://service.my.delogue.com/api/barcodes" \
  -H "Accept: application/json" \
  -H "X-Auth-Token: Bearer YOUR_API_KEY"

const res = await fetch("https://service.my.delogue.com/api/barcodes", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "X-Auth-Token": "Bearer YOUR_API_KEY",
  },
});
const { data } = await res.json();

{
  "status": "success",
  "code": "barcodes_retrieved",
  "data": [
    {
      "id": 10432,
      "barcode": "5710000000010",
      "properties": [
        "linkedToSku"
      ]
    },
    {
      "id": 10433,
      "barcode": "5710000000027",
      "properties": [
        "linkedToSku",
        "linkedToStyleAssortment"
      ]
    },
    {
      "id": 10434,
      "barcode": "5710000000034",
      "properties": []
    }
  ],
  "pagination": {
    "hasMore": true,
    "cursor": "eyJJZCI6MTA0MzR9"
  }
}

Each row carries a properties array: linkedToSku appears when the barcode is linked to a SKU, and linkedToStyleAssortment when it is linked to a style assortment. An empty array means the barcode is free, so you can still rename or delete it. Newly created barcodes always come back with an empty array.

Field reference

The fields on a barcode, and the fields you send when creating or renaming one:

Field	What it means at Delogue
`barcode`	The barcode value, e.g. an EAN-13 number.
`id`	Unique identifier of the barcode.
`properties`	Linkage flags present on the barcode. Contains linkedToSku when the barcode is linked to a SKU and linkedToStyleAssortment when it is linked to a style assortment. Maintained by the system and read-only.

Request bodies

Field	Sent on	What it means at Delogue
`barcode`	`POST /api/barcodes`, `PUT /api/barcodes/{id}`, `PUT /api/barcodes`	The barcode value, such as a 13-digit EAN number. Required, unique within the organisation (case-insensitive) and at most 255 characters. No format rule is applied.
`id`	`PUT /api/barcodes` only	Unique identifier of the barcode to rename. Required on every element of a bulk update body, and each id may appear only once. On `PUT /api/barcodes/{id}` the route id is used and the body carries no id.

properties (linkedToSku, linkedToStyleAssortment) is not part of any request body: a new barcode is always created unlinked, and the flags change only when the barcode is linked to or unlinked from a SKU or style assortment. A body that supplies them is rejected.

A rename changes the text of an existing barcode and keeps its id. It is only allowed while the barcode is free: one already linked to a SKU or a style assortment returns 409, so unlink it on the style first, or create a new barcode instead. Renaming a barcode to the value it already has is a no-op and returns 200.

PUT /api/barcodes/{id} is a full replace, but barcode is the only writable field, so the body is always { "barcode": "..." }. PATCH /api/barcodes/{id} takes an RFC 6902 JSON Patch document (Content-Type: application/json-patch+json), e.g. [{ "op": "replace", "path": "/barcode", "value": "5710000000065" }]; an omitted field keeps its value, and clearing barcode to null or empty is a 400 because it is required.

The bulk calls are all-or-nothing and capped at 200 barcodes per request. On PUT /api/barcodes each id may appear once. A batch can pass a value along a chain (one item takes a value another item in the same batch is renaming away from), but two items that exchange values return 409. DELETE /api/barcodes takes the ids as repeated ids query parameters or a comma-separated list. Both return the affected barcodes in request order.

Roles & permissions

Barcodes belong to designer (brand) organisations with the Barcodes module enabled. Reading them requires read access to the barcodes permission, and creating, renaming and deleting them requires write access, typically granted through the SKU-Barcodes role. Supplier accounts, and organisations without the module, receive a 403 on every barcode endpoint. You can only read and change your own organisation’s barcodes.

When things go wrong

Errors use the standard envelope (status: "error", a code, and error.details[]). See Errors & responses for the full list of codes and how to resolve them. Common cases for barcodes:

400: barcode is missing, empty or longer than 255 characters, a bulk request is empty or has more than 200 entries, an id is repeated in a bulk request, or cursor was sent together with a filter or pageSize/pageNumber on the list.
403: the barcode belongs to another organisation, or your account cannot use barcodes.
404: the barcode id does not exist. In a bulk request, a missing id takes precedence over one belonging to another organisation.
409: the barcode value already exists in your organisation or is repeated in the batch, the barcode is linked to a SKU or a style assortment (rename and delete), two items in a bulk rename exchange values, or a PATCH targets /id or fails a test operation. Bulk errors name the offending index in error.details[].
422: a PATCH operation cannot be applied to the barcode.

What to call next

Style SKUs

See the SKUs barcodes are assigned to: GET /api/skus.

Styles

Work with the styles whose SKUs and assortments barcodes attach to.

Authentication

How to get and send your X-Auth-Token API key.

Getting Started

Concepts

Guides

The workflow

Walkthrough

Field reference

Request bodies

Roles & permissions

When things go wrong

What to call next

Style SKUs

Styles

Authentication

​The workflow

​Walkthrough

​Field reference

​Request bodies

​Roles & permissions

​When things go wrong

​What to call next

Style SKUs

Styles

Authentication

The workflow

Walkthrough

Field reference

Request bodies

Roles & permissions

When things go wrong

What to call next