Logistic Families

Introduction

Logistic families allow operators to categorize products according to their shipping and handling constraints. For example, you can create families for fragile items, oversized goods, hazardous materials, or standard parcels. These categories are then used by the delivery module to apply appropriate shipping rules and carrier selection.

Managing Logistic Families from the Back-Office

Most operators manage logistic families directly from the DJUST Back-Office. The API described below performs the same actions and is intended for integrators.

Where to find it

Settings →Shipping fee management → Logistic families

List view

The list view displays all existing logistic families with:

• Search — free-text on name and id (case- and accent-insensitive)
• Sorting — by name, creation date (createdAt), or last update (updatedAt)
• Columns — Name (with the external ID as a secondary line), Description, Linked (number of classification categories attached to the family)
• Row actions — Edit, Delete (delete disabled for the Default family)

Filters

Refine the list with the filter panel:

Creating a logistic family

Click Create logistic family and fill in the form:

Attaching classification categories

Classification categories are attached to a logistic family exclusively from the family's create/edit modal — the reverse operation (attaching from the classification page) is not available in the Back-Office.

Each classification category can belong to only one logistic family at a time. When you attach a category already assigned to another custom family, the Back-Office displays a warning identifying the family that will lose the category, then silently moves it on save.

Categories not explicitly attached to any custom family remain in the "Default" logistic family.

Editing a logistic family

Open a family to edit its Name, Description, or Classification categories. The External ID is locked once created. The Default family cannot be edited.

Deleting a logistic family

Deletion is blocked if the family is still referenced in the shipping price matrix. The Back-Office displays an error and lists the associated price rows. Remove them first, then retry the deletion.

The Default family cannot be deleted. When a custom family is deleted, its attached categories are automatically reassigned to the Default family.

Logistic Families on Orders

Cart Split at Checkout

At checkout, the cart is split into logistic orders based on the triplet (supplier, shipping delay, logistic family). A cart that mixes several logistic families for the same supplier and the same shipping delay therefore produces one logistic order per family.

The family of each line is resolved from the classification of its product, with a fallback to the "Default" logistic family when no explicit attachment exists.

flowchart LR
  %% Styles (Readme)
  classDef create   fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef read     fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;
  classDef decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef place    fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
  classDef sys      fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;

  A["🧾 Cart at checkout"]:::sys
  B{{"📦 Group by<br>supplier + shipping delay<br>+ logistic family"}}:::decision
  C["✅ Logistic order<br>Family A"]:::place
  D["✅ Logistic order<br>Family B"]:::place

  A --> B
  B --> C
  B --> D

  style A rx:8,ry:8
  style C rx:8,ry:8
  style D rx:8,ry:8

Logistic Family Fields on Order Responses

The consultation responses of a logistic order (both Front Office and Back Office) carry the resolved family at the root level:

• These fields are always returned, whether or not the shipping module is enabled.
• Commercial orders — which may regroup several logistic families — are not enriched with these fields.
• Logistic orders created before this capability remain fully functional; the fields are optional and backward-compatible (they may be null on legacy orders without a family).

Key Endpoints

All endpoints require dj-client: OPERATOR and dj-api-key headers.

Creating a Logistic Family

POST /v1/logistic-families
dj-client: OPERATOR
dj-api-key: {{apiKey}}
Content-Type: application/json

Request Body

Example

{
  "id": "fragile-items",
  "name": "Fragile Items",
  "description": "Products requiring careful handling and special packaging"
}

Response — 201 Created

{
  "id": "fragile-items"
}

Errors

Updating a Logistic Family

Updates apply a full replacement of the modifiable fields (name and description). The id is immutable and cannot be changed.

PUT /v1/logistic-families/{id}
dj-client: OPERATOR
dj-api-key: {{apiKey}}
Content-Type: application/json

Request Body

Example

{
  "name": "Fragile & Delicate Items",
  "description": "Products requiring careful handling, special packaging, and temperature control"
}

Response — 204 No Content

No response body.

Retrieving a Logistic Family

GET /v1/logistic-families/{id}
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Path Parameters

Response — 200 OK

{
  "id": "fragile-items",
  "name": "Fragile Items",
  "description": "Products requiring careful handling and special packaging",
  "system": false,
  "classificationCategoriesCount": 3,
  "createdAt": "2026-03-05T10:30:00Z",
  "updatedAt": "2026-03-05T10:30:00Z"
}

Errors

Deleting a Logistic Family

Permanently deletes a logistic family. All classification categories attached to this family are automatically reassigned to the "Default" logistic family.

DELETE /v1/logistic-families/{id}
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Path Parameters

Rules

• The Default logistic family cannot be deleted — the request returns 403.
• Deletion is blocked if the family is still referenced in the shipping price matrix. Remove those price lines first.

Response — 204 No Content

No response body.

Errors

For the complete list of error codes, refer to Error / Warning codes.

Listing Logistic Families

Retrieve a paginated list of logistic families with optional filters and sorting.

GET /v1/logistic-families
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Query Parameters

Response — 200 OK

{
  "content": [
    {
      "id": "fragile-items",
      "name": "Fragile Items",
      "description": "Products requiring careful handling and special packaging",
      "system": false,
      "classificationCategoriesCount": 3,
      "createdAt": "2026-03-05T10:30:00Z",
      "updatedAt": "2026-03-05T10:30:00Z"
    },
    {
      "id": "default",
      "name": "Default",
      "description": null,
      "system": true,
      "classificationCategoriesCount": 12,
      "createdAt": "2026-01-10T08:00:00Z",
      "updatedAt": "2026-01-10T08:00:00Z"
    }
  ],
  "number": 0,
  "size": 20,
  "numberOfElements": 2,
  "first": true,
  "last": true,
  "empty": false
}

Errors

For the complete list of error codes, refer to Error / Warning codes.

Attaching Classification Categories

Attach one or more classification categories to a logistic family using their external IDs. This determines which shipping rules apply to products in those categories.

PATCH /v1/logistic-families/{logisticFamilyId}/classification-categories
dj-client: OPERATOR
dj-api-key: {{apiKey}}
Content-Type: application/json

Request Body

Rules

• A classification category can only belong to one logistic family at a time. If a category is already attached to another custom family, it is automatically reassigned and a F_W_038 warning is emitted.
• Sending an empty array or null for classificationCategoryIds is accepted and returns 200 OK with an empty warnings array.
• Identifiers must be external IDs of classification categories.

Example

{
  "classificationCategoryIds": ["CAT-FRAGILE", "CAT-GLASS"]
}

Response — 200 OK

The response contains a warnings array. A warning is emitted only for categories that were reassigned from a previous non-system family. Categories that were previously unattached (or attached to the Default family) do not generate a warning.

{
  "warnings": [
    {
      "classificationCategoryId": "CAT-FRAGILE",
      "code": "F_W_038",
      "message": "Category CAT-FRAGILE has been moved from logistic family bulky-items to logistic family fragile-items.",
      "previousLogisticFamilyId": "bulky-items"
    }
  ]
}

Empty when no reassignment occurred:

{ "warnings": [] }

Errors

For the complete list of error codes, refer to Error / Warning codes.

Replacing Classification Categories

Replaces the entire list of classification categories attached to a logistic family. This is a full replacement — categories not included in the request that were previously attached to this family fall back to the "Default" logistic family.

PUT /v1/logistic-families/{logisticFamilyId}/classification-categories
dj-client: OPERATOR
dj-api-key: {{apiKey}}
Content-Type: application/json

Request Body

Rules

• Categories previously attached to this family and not included in the request are automatically reassigned to the Default family.
• Categories currently attached to another custom family and included in the request are silently reassigned to this family.
• Sending an empty array [] detaches all categories — they all fall back to the Default family.

Example

​

{
  "classificationCategoryIds": ["CAT-FRAGILE", "CAT-GLASS", "CAT-CERAMIC"]
}

Response — 204 No Content

No response body.

Errors

For the complete list of error codes, refer to Error / Warning codes.

Detaching Classification Categories

Detach one or more classification categories from a logistic family. Detached categories fall back to the "Default" logistic family.

DELETE /v1/logistic-families/{logisticFamilyId}/classification-categories
dj-client: OPERATOR
dj-api-key: {{apiKey}}
Content-Type: application/json

Request Body

Example

{
  "classificationCategoryIds": ["CAT-GLASS"]
}

Response — 204 No Content

No response body.

Errors

For the complete list of error codes, refer to Error / Warning codes.

Listing Classification Categories of a Logistic Family

Retrieve the classification categories currently attached to a logistic family. The response is paginated using the standard DJUST pagination parameters (page, size).

By default, when no explicit category attachment has been made, all tenant classification categories are implicitly associated with the "Default" logistic family. This endpoint returns them all in that case.

The id field returned for each category corresponds to the external ID of the classification category.

GET /v1/logistic-families/{logisticsFamilyId}/classification-categories
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Query Parameters

Response — 200 OK

{
  "content": [
    { "id": "cat-001", "name": "Verres et cristaux" },
    { "id": "cat-002", "name": "Porcelaine" }
  ],
  "numberOfElements": 2,
  "number": 0,
  "size": 20,
  "first": true,
  "last": true,
  "empty": false
}

Errors

Getting Logistic Family Assignments for Classifications

Query which logistic family is currently assigned to a set of classification categories. This is useful for displaying current assignments in a UI or for checking before reassigning a category.

GET /v1/logistic-families/assignments?classificationCategoryIds=cat-001,cat-002
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Query Parameters

Rules

• Every classification always has a logistic family (at minimum the system default) — the response is never null for a known category.
• Unknown classification IDs are silently omitted from the response (Tolerant Reader pattern).
• The logisticFamily.system flag indicates whether the assigned family is the system-managed default (true) or a custom family (false).
• This endpoint is not paginated — it returns all results in a single response.

Response — 200 OK

{
  "assignments": [
    {
      "classificationCategoryId": "cat-001",
      "logisticFamily": {
        "id": "fragile-items",
        "name": "Fragile Items",
        "system": false
      }
    },
    {
      "classificationCategoryId": "cat-002",
      "logisticFamily": {
        "id": "default",
        "name": "Default",
        "system": true
      }
    }
  ]
}

Errors

For the complete list of error codes, refer to Error / Warning codes.

Typical Workflow

flowchart LR
  %% Styles (Readme)
  classDef create   fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef read     fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;
  classDef update   fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#0c4a6e;
  classDef add      fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef remove   fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
  classDef decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef place    fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
  classDef sys      fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;
  classDef ok       fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef stop     fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;

  A["➕ Create logistic family<br>POST /v1/logistic-families"]:::create
  B["📦 Family available"]:::place
  F["📘 Check current assignments<br>GET .../assignments"]:::read
  C["🔗 Attach categories<br>PATCH .../classification-categories"]:::add
  D["🔄 Update family<br>PUT /v1/logistic-families/id"]:::update
  E["📘 List categories<br>GET .../classification-categories"]:::read

  A --> B --> F --> C
  B --> D --> B
  B --> E

  style A rx:8,ry:8
  style B rx:8,ry:8
  style C rx:8,ry:8
  style D rx:8,ry:8
  style E rx:8,ry:8
  style F rx:8,ry:8

Best Practices

1. Use meaningful custom IDs — if you provide a custom id, make it descriptive and consistent (e.g. fragile-items, oversized-goods). Once created, the ID cannot be changed.
2. Plan your family structure — define your logistic families before attaching categories. Rethinking the structure later requires reassigning categories.
3. Do not modify the Default family — it is system-managed and serves as the fallback for unassigned products.

Common Mistakes