Shipping Rates configuration

Introduction

Shipping rates define the shipping tariffs applied by DJUST at checkout. Each rate associates a price (and optionally a free-shipping threshold) with a unique combination of logistic family, shipping zone, shipping type, and — in marketplace contexts — supplier.

In marketplace contexts, a rate can also be flagged as a default shipping fee: instead of targeting one supplier, it applies to every supplier that has no rate of its own for the same logistic family, zone and shipping type. See Default shipping fee.

Operators configure these rates via the DJUST Back-Office and the API described on this page. Once configured, they become the tariff source DJUST evaluates on every cart read to compute the shipping fees applied to each logistic order at checkout.

For the complete checkout flow (cart split, zone resolution, free-shipping mechanics, order validation snapshot), see the Shipping module overview.

Managing Shipping Rates from the Back-Office

Most operators manage shipping rates 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 → Shipping rates

List view

The list view displays all existing shipping rates with:

• Sorting — by creation date or last update
• Columns — Logistic family, Shipping zone, Shipping type, Supplier (marketplace only), Price, Free shipping threshold (displayed as "From X€"), Created at, Last updated
• Row actions — Edit, Delete

Filters

Refine the list with the filter panel:

Creating a rate

Click + Add a rate and fill in the form:

Editing a rate

Open the row action menu (⋯) and click Edit. All fields can be modified, provided the resulting combination remains unique.

Deleting a rate

Open the row action menu (⋯) and click Delete. Deletion is allowed even if past orders reference the rate — only future checkout calculations are affected.

Key Concepts

Price Line Dimensions

Each shipping price line is scoped by a combination of four dimensions:

Default Shipping Fee

In a marketplace, every supplier normally needs its own price line for each logistic family × shipping zone × shipping type combination it ships on. A supplier with no line for the combination requested at checkout has no price, and the customer's checkout is blocked. Maintaining one line per supplier, and adding new lines every time a supplier joins the marketplace, quickly becomes a burden.

A price line flagged isDefault: true acts as a safety net for a combination:

• It carries no supplierId and applies to any supplier that has no line of its own for the same logistic family × zone × type — including suppliers already present elsewhere in the matrix and suppliers created after the default line, with no change to the matrix.
• A supplier's own line always takes precedence. The default line only steps in where no supplier-specific price exists.
• A line targets either one supplier or all uncovered suppliers: a line carrying both supplierId and isDefault: true is rejected, and so is a marketplace line carrying neither.
• One default line per combination, enforced at creation and update, including in bulk payloads.
• price, francoAmount, cart split and fee calculation behave exactly as for a supplier-specific line. A default line at price: 0 is a valid way to offer free shipping to every unconfigured supplier.

The safety net is per combination: a combination with neither a supplier line nor a default line still blocks the checkout, as before. Existing supplier lines keep their behaviour.

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["📦 Logistic order<br>supplier S<br>family x zone x type"]:::sys
  B{"Line for<br>supplier S"}:::decision
  C{"Default line<br>isDefault true"}:::decision
  D["✅ Supplier price applied"]:::place
  E["✅ Default price applied"]:::place
  F["⛔ No price<br>checkout blocked"]:::stop

  A --> B
  B -->|"yes"| D
  B -->|"no"| C
  C -->|"yes"| E
  C -->|"no"| F

  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

Price and Franco Amount

How Shipping Fees Are Calculated at Checkout

When the Shipping module is enabled (shippingEnabled: true), DJUST resolves shipping fees dynamically from the configured price lines throughout the checkout. No API contract change is required on your side: the cart v2 and order DTOs expose the same fields and structure — only the values are now driven by the configured shipping price lines.

Logistic Orders

At checkout, the cart is split into logistic orders, and each logistic order carries its own shipping fees:

• E-commerce — one logistic order per logistic family.
• Marketplace — one logistic order per supplier × logistic family combination.

Price lines are evaluated per logistic order along the dimensions logistic family × shipping zone × shipping type (plus supplier in marketplace). In marketplace, the supplier's own line is used first; when the supplier has none, the default shipping fee line of the combination is used, if any.

Shipping Zone Resolution

The shipping zone is derived from the customer's shipping address:

• Priority is given to the address department.
• If no department is available, the zone is resolved from the postal code.

Free Shipping (Franco)

The francoAmount threshold is applied per logistic order, never on the global cart. When a logistic order reaches its threshold, its shipping fees drop to 0 — independently of the other logistic orders in the same cart.

The amount compared to the threshold depends on the tenant setting francoTaxBasis:

Configuring this setting is described in Free-shipping tax basis. Note that the setting only changes the comparison basis — the price configured on the price line stays tax-inclusive (TTC).

Where Shipping Fees Are Read

Shipping fees resolved from the matrix live on the logistic order (totalShippingFeesWithTax, totalShippingFeesWithoutTax, totalShippingTaxAmount), not on the order lines. For orders coming from direct checkout, the per-line shipping fields are not populated — see Where shipping fees are exposed.

Dynamic Recalculation

Shipping fees are recomputed on every cart read — GET /v2/shop/carts/{cartId} and GET /v2/shop/carts/{cartId}/lines — so the amounts always reflect the current price lines and the current shipping address in real time.

Selection and Snapshot

• Selecting a shipping type and committing the address — PUT /v2/shop/commercial-orders/{id}/shipping-information (ORDER-215) applies the corresponding shipping price line to the logistic order.
• Validating the order — the validation step (ORDER-212) freezes (snapshots) the shipping fees on each logistic order in the fields totalShippingFeesWithTax, totalShippingFeesWithoutTax, and totalShippingTaxAmount. If the shipping price lines changed between selection and validation, the price is recomputed at validation time and it is this new value that is frozen.

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 cart<br>GET /v2/shop/carts/{cartId}<br>fees recomputed"]:::read
  B["📦 Split into<br>logistic orders"]:::sys
  C{"Price line for<br>zone x type x family"}:::decision
  D["🔄 Select shipping type<br>PUT .../shipping-information"]:::update
  E["✅ Validate order<br>fees snapshot frozen"]:::place
  F["⛔ Checkout blocked<br>no shipping type offered"]:::stop

  A --> B --> C
  C -->|"supplier line or default line found"| D --> E
  C -->|"out of zone / no line"| F

  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

Blocking Cases at Checkout

Warnings During Checkout

Non-fatal and fatal conditions are surfaced through blockedLineInformation:

• Blocking — a reference cannot be found, or a shipping type has been made inactive.
• Informational — the price changed following a price line recalculation.

Key Endpoints

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

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 price lines<br>POST /v1/shipping-prices"]:::create
  B["📘 List / Get prices<br>GET /v1/shipping-prices"]:::read
  C["🔄 Update prices<br>PUT /v1/shipping-prices"]:::update
  D["➖ Delete obsolete lines<br>DELETE /v1/shipping-prices"]:::remove
  E["✅ Price lines ready<br>for checkout"]:::place

  A --> E
  E --> B
  E --> C --> E
  E --> D --> 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

Creating Shipping Price Lines (Bulk)

Create one or more shipping price lines in a single request. Each line is validated independently — valid lines are created and invalid lines are rejected with detailed error messages.

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

Request Body

An array of shipping price line objects:

Example

Two lines for one supplier, plus a default shipping fee line covering every other supplier on the express combination:

[
  {
    "logisticFamilyId": "standard",
    "shippingZoneId": "eu-west",
    "shippingTypeId": "express-24h",
    "supplierId": "supplier-001",
    "price": 12.50,
    "francoAmount": 150.00
  },
  {
    "logisticFamilyId": "standard",
    "shippingZoneId": "eu-west",
    "shippingTypeId": "standard",
    "supplierId": "supplier-001",
    "price": 5.99,
    "francoAmount": null
  },
  {
    "logisticFamilyId": "standard",
    "shippingZoneId": "eu-west",
    "shippingTypeId": "express-24h",
    "isDefault": true,
    "price": 15.00,
    "francoAmount": null
  }
]

Business Rules

• In marketplace contexts, a line targets either one supplier (supplierId) or every uncovered supplier (isDefault: true): exactly one of the two is required, and sending both is rejected (F-E-040).
• In non-marketplace (single-vendor) contexts, supplierId is forbidden and isDefault is ignored.
• The combination of (logisticFamilyId, shippingZoneId, shippingTypeId, supplierId) must be unique across all shipping price lines.
• At most one default shipping fee line per (logisticFamilyId, shippingZoneId, shippingTypeId) combination, including within the same bulk payload.

Response — 201 Created

The response contains a singleWarningReportDtos array with one entry per input item. Successful items have detail: null; rejected items have detail containing the error message. The overall request always returns 201 — item-level failures do not fail the whole request.

{
  "singleWarningReportDtos": [
    { "id": "row-001", "detail": null },
    { "id": "row-002", "detail": "F_E_002 - At least one resource does not exist in Djust system. shippingZoneId=zone-idf" }
  ]
}

Errors

Getting a Shipping Price Line

GET /v1/shipping-prices/{id}
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Path Parameters

Response — 200 OK

{
  "id": "sp-001",
  "logisticFamilyId": "standard",
  "logisticFamilyName": "Standard",
  "shippingZoneId": "eu-west",
  "shippingZoneName": "EU West",
  "shippingTypeId": "express-24h",
  "shippingTypeName": "Express 24h",
  "supplierId": "supplier-001",
  "supplierName": "Acme Supplies",
  "isDefault": false,
  "price": 12.50,
  "francoAmount": 150.00,
  "createdAt": "2026-06-01T10:00:00Z",
  "updatedAt": "2026-06-01T10:00:00Z"
}

A default shipping fee line is returned with isDefault: true and supplierId / supplierName at null, so it can be told apart from a supplier line without ambiguity:

{
  "id": "sp-default-express",
  "logisticFamilyId": "standard",
  "logisticFamilyName": "Standard",
  "shippingZoneId": "eu-west",
  "shippingZoneName": "EU West",
  "shippingTypeId": "express-24h",
  "shippingTypeName": "Express 24h",
  "supplierId": null,
  "supplierName": null,
  "isDefault": true,
  "price": 15.00,
  "francoAmount": null,
  "createdAt": "2026-09-01T09:00:00Z",
  "updatedAt": "2026-09-01T09:00:00Z"
}

Errors

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

Listing Shipping Price Lines

Retrieve a paginated, filterable list of shipping price lines.

GET /v1/shipping-prices
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Query Parameters

All filters are combined with AND logic. Multi-valued filters (e.g. logisticFamilyIds=a,b) match any of the listed values (OR within the filter).

Response — 200 OK

{
  "content": [
    {
      "id": "sp-001",
      "logisticFamilyId": "standard",
      "logisticFamilyName": "Standard",
      "shippingZoneId": "eu-west",
      "shippingZoneName": "EU West",
      "shippingTypeId": "express-24h",
      "shippingTypeName": "Express 24h",
      "supplierId": "supplier-001",
      "supplierName": "Acme Supplies",
      "isDefault": false,
      "price": 12.50,
      "francoAmount": 150.00,
      "createdAt": "2026-06-01T10:00:00Z",
      "updatedAt": "2026-06-01T10:00:00Z"
    },
    {
      "id": "sp-default-express",
      "logisticFamilyId": "standard",
      "logisticFamilyName": "Standard",
      "shippingZoneId": "eu-west",
      "shippingZoneName": "EU West",
      "shippingTypeId": "express-24h",
      "shippingTypeName": "Express 24h",
      "supplierId": null,
      "supplierName": null,
      "isDefault": true,
      "price": 15.00,
      "francoAmount": null,
      "createdAt": "2026-09-01T09:00:00Z",
      "updatedAt": "2026-09-01T09:00:00Z"
    }
  ],
  "numberOfElements": 2,
  "number": 0,
  "size": 20,
  "sort": ["createdAt:desc"],
  "first": true,
  "last": true,
  "empty": false
}

Errors

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

Updating Shipping Price Lines (Bulk)

Update one or more existing price lines. This is a full replacement of all modifiable fields. Each line is validated independently.

PUT /v1/shipping-prices
dj-client: OPERATOR
dj-api-key: {{apiKey}}
Content-Type: application/json

Request Body

An array of objects, each including the id of the line to update and the new field values:

Business Rules

• id identifies the shipping price line to update and is immutable.
• All other fields are fully replaced by the request body (full update, not partial). A supplier line can therefore be turned into a default shipping fee line, and vice versa, by changing supplierId / isDefault.
• In marketplace contexts, exactly one of supplierId or isDefault: true is required; both together are rejected (F-E-040). In non-marketplace contexts, supplierId is forbidden and isDefault is ignored.
• The combination of (logisticFamilyId, shippingZoneId, shippingTypeId, supplierId) must remain unique across all shipping price lines, and at most one default shipping fee line may exist per (logisticFamilyId, shippingZoneId, shippingTypeId) combination.

Example

[
  {
    "id": "sp-001",
    "logisticFamilyId": "standard",
    "shippingZoneId": "eu-west",
    "shippingTypeId": "express-24h",
    "supplierId": "supplier-001",
    "price": 14.00,
    "francoAmount": 200.00
  }
]

Response — 200 OK

The response contains a singleWarningReportDtos array with one entry per input item. Successful items have detail: null; rejected items have detail containing the error message.

{
  "singleWarningReportDtos": [
    { "id": "row-001", "detail": null },
    { "id": "row-002", "detail": "F_E_002 - At least one resource does not exist in Djust system. id=row-002" }
  ]
}

Errors

Deleting Shipping Price Lines (Bulk)

Delete one or more price lines by ID. Each deletion is processed independently — a failure on one line does not block the others.

DELETE /v1/shipping-prices
dj-client: OPERATOR
dj-api-key: {{apiKey}}
Content-Type: application/json

Request Body

An array of price line IDs to delete:

["sp-001", "sp-002"]

Response — 200 OK

The response contains a singleWarningReportDtos array with one entry per input item. Successful deletions have detail: null; items that could not be found have detail containing the error message.

{
  "singleWarningReportDtos": [
    { "id": "row-001", "detail": null },
    { "id": "row-999", "detail": "F_E_002 - At least one resource does not exist in Djust system. id=row-999" }
  ]
}

Errors

Not-found items are reported per-item in the response detail field (with code F_E_002), not as an HTTP status.

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

Best Practices

1. Use bulk operations — create, update, and delete operations all support bulk payloads. Batch your changes to minimize API calls.
2. Set up dimensions first — create your logistic families, shipping zones, and shipping types before populating the price lines. Missing references cause F-E-002 errors.
3. Use francoAmount for free shipping — instead of setting price: 0 for large orders, use the francoAmount threshold to automatically waive shipping fees above a certain order value.
4. Filter with dimension IDs — when reviewing the price lines, use the multi-valued filters (e.g. shippingZoneIds=eu-west,eu-east) to narrow results efficiently.
5. Add a default shipping fee line per combination (marketplace) — one isDefault: true line per logistic family × zone × type guarantees that a supplier without its own line, including one onboarded later, never blocks the checkout. Keep supplier-specific lines for the suppliers that need a different price: they always take precedence.
6. Audit the safety net with isDefault=true — list the default lines to spot the combinations that are still uncovered.

Common Mistakes

Error Reference

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