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.

This guide explains how to create and manage logistic families via the DJUST API.

Key Concepts

What is a Logistic Family

A logistic family is a grouping label that describes a class of products with similar shipping constraints. Each family has:

Default Family

A system-managed "Default" logistic family exists on every tenant. It cannot be created, modified, or deleted via the API. Products not explicitly assigned to a family belong to this default family.

Classification Category Attachment

Logistic families can be associated with classification categories to define which shipping rules apply to which product categories. A classification category can only be attached to one logistic family at a time. If a category is already attached to another family, it is automatically detached from the previous one and reassigned to the new family.

Creating or updating a family does not automatically attach categories to it — use the dedicated endpoint described below.

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",
  "name": "Fragile Items",
  "description": "Products requiring careful handling and special packaging"
}

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.

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

⚠️

Warning: The name query parameter has been replaced by the unified search parameter, which matches on both the name and the external ID — the same behavior as on the classification-categories list endpoint. Integrations still sending name must migrate to search.

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
}

✅

Tip: The system flag identifies the system-managed "Default" family (true), and classificationCategoriesCount gives the number of classification categories attached to each family without additional lookups.

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/{logisticsFamilyId}/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 family, it is automatically reassigned.
• Sending an empty array or null for classificationCategoryIds returns 204 with no changes applied.
• Identifiers must be external IDs of classification categories.

Example

{
  "classificationCategoryIds": ["CAT-FRAGILE", "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-FRAGILE",
      "name": "Fragile Items"
    },
    {
      "id": "CAT-GLASS",
      "name": "Glassware"
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "number": 0,
  "size": 20
}

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 system flag in each response item indicates whether the 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

[
  {
    "classificationCategoryId": "cat-001",
    "logisticFamilyId": "fragile-items",
    "logisticFamilyName": "Fragile Items",
    "system": false
  },
  {
    "classificationCategoryId": "cat-002",
    "logisticFamilyId": "default",
    "logisticFamilyName": "Default",
    "system": true
  }
]

✅

Tip: Use this endpoint as a pre-check before reassigning a category. If a category is already attached to a non-system family different from your target, you may want to warn the user before proceeding.

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

Error Reference

For the complete list of DJUST error and warning codes, refer to the dedicated page:
Error / Warning codes

Related Documentation

• Shipping Zones and Types
• Shipping Price Matrix
• Order Lifecycle and Statuses
• Introduction to DJUST OMS