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.

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.

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