Shipping

Introduction

The DJUST Shipping module gives operators a centralized, dimension-based way to compute shipping fees dynamically at checkout. When enabled, shipping costs are no longer embedded in each offer — they are resolved from a configurable price matrix that combines logistic families, shipping zones, shipping types, and (in marketplace contexts) suppliers.

This page covers the module at a glance: how to enable it, its building blocks, and how it drives fees at checkout. Each building block has its own dedicated page for management details.

Enabling the Shipping Module

The module is toggled per tenant via the shippingEnabled configuration setting.

Free-Shipping Tax Basis

Each price line can carry a free-shipping threshold (francoAmount) — the amount above which shipping fees drop to 0 for the logistic order. The francoTaxBasis OMS setting defines which amount of the logistic order that threshold is compared to.

The default value is TTC. Existing tenants therefore keep strictly the same behaviour — no action is required to stay on the previous logic.

Reading and Updating the Setting

GET /v1/settings/oms returns francoTaxBasis among the OMS settings (excerpt):

{
  "francoTaxBasis": "TTC"
}

PATCH /v1/settings/oms accepts francoTaxBasis in the request body. Allowed values: HT, TTC.

{
  "francoTaxBasis": "HT"
}

Where Shipping Fees Are Exposed

When the module is active, the logistic order is the source of truth for shipping fees: they are resolved per logistic order (from the price matrix), not line by line.

As a result, the per-line shipping fields carried by logistic order lines — shippingPriceWithTaxes, shippingPriceWithoutTaxes and shippingTaxAmount — are no longer populated for orders coming from direct checkout. Read the shipping amount at logistic order level instead: totalShippingFeesWithTax, totalShippingFeesWithoutTax and totalShippingTaxAmount.

Orders created from a quote keep exposing shipping per line, because on quote workflows the shipping amount is entered line by line.

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["🧾 Read a logistic order<br>ORDER-501 or ADM-ORDER-501"]:::read
  B{"Order origin"}:::decision
  C["📦 Shipping read on the<br>logistic order totals"]:::place
  D["🧾 Shipping read on<br>each order line"]:::sys

  A --> B
  B -->|"direct checkout"| C
  B -->|"quote"| D

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

Read endpoints concerned: ORDER-501 (shop) and ADM-ORDER-501 (admin).

Scope

The Shipping module applies only to tenants using DJUST's native shipping — either e-commerce or native marketplace setups.

Access & Permissions

All administration endpoints require dj-client: OPERATOR and a valid dj-api-key header. In the Back-Office, users with the operator role can access the shipping settings.

The Building Blocks

The Shipping module articulates around 4 building blocks, each with its own DJUST resource and management page:

Matrix dimensions — e-commerce vs marketplace

Each row in the price matrix is one unique combination of dimensions. The number of dimensions depends on your DJUST setup:

• In an e-commerce (single-vendor) setup, the matrix combines 3 dimensions: logistic family × shipping zone × shipping type.
• In a marketplace (multi-supplier) setup, a 4th dimension is added — the supplier. Each supplier has its own set of price lines alongside the other three axes.

E-commerce — 3 dimensions

flowchart LR
  classDef brick fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;
  classDef matrix fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef ok fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;

  Z["📍 Shipping Zones"]:::brick
  T["🚚 Shipping Types"]:::brick
  F["📦 Logistic Families"]:::brick
  M["🧮 Price Matrix"]:::matrix
  C["🛒 Shipping fees<br>at checkout"]:::ok

  Z --> M
  T --> M
  F --> M
  M --> C

  style Z rx:8,ry:8
  style T rx:8,ry:8
  style F rx:8,ry:8
  style M rx:8,ry:8
  style C rx:8,ry:8

Marketplace — 4 dimensions (supplier added)

flowchart LR
  classDef brick fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;
  classDef supplier fill:#fff7ed,stroke:#ea580c,stroke-width:2px,color:#7c2d12;
  classDef matrix fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef ok fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;

  Z["📍 Shipping Zones"]:::brick
  T["🚚 Shipping Types"]:::brick
  F["📦 Logistic Families"]:::brick
  S["🏪 Suppliers"]:::supplier
  M["🧮 Price Matrix<br>(one row per supplier<br>combination)"]:::matrix
  C["🛒 Shipping fees<br>at checkout"]:::ok

  Z --> M
  T --> M
  F --> M
  S --> M
  M --> C

  style Z rx:8,ry:8
  style T rx:8,ry:8
  style F rx:8,ry:8
  style S rx:8,ry:8
  style M rx:8,ry:8
  style C rx:8,ry:8