Shipping Zones and Types

Introduction

The DJUST delivery module allows operators to configure shipping rules based on geographical areas and delivery modes. Two foundational concepts support this configuration:

• Shipping zones — geographical areas (e.g. "France Metropolitan", "EU", "North America") used to define where shipping rules apply.
• Shipping types — delivery modes proposed to customers at checkout (e.g. "Express", "Standard", "Click & Collect").

Together with logistic families, these entities form the building blocks of DJUST shipping rule configuration.

This guide covers how to create, manage, and configure shipping zones and types via the DJUST API.

Key Concepts

Shipping Zones

A shipping zone represents a geographical area used to scope shipping pricing and rules. Each zone has:

A shipping zone can contain locations — countries and, for France, individual departments. This allows fine-grained geographical scoping per zone.

Shipping Types

A shipping type represents a delivery mode that can be proposed to customers. Each type has:

✅

Tip: There is no system-default shipping type. All shipping types are created explicitly by the operator.

Key Endpoints

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

Creating a Shipping Zone

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

Request Body

Example

{
  "id": "eu-west",
  "name": "EU West",
  "description": "Western European countries including France, Spain, Portugal, and Benelux"
}

Response — 201 Created

{
  "id": "eu-west"
}

Errors

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

Updating a Shipping Zone

Applies a full replacement of the modifiable fields (name and description). The id is immutable, and the zone's locations are not affected by this call — manage them with the dedicated locations endpoints.

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

Path Parameters

Request Body

Example

{
  "name": "EU West - Updated",
  "description": "Western European countries including France, Spain, Portugal, Benelux, and Ireland"
}

Response — 204 No Content

No response body.

Errors

Deleting a Shipping Zone

Permanently deletes a shipping zone. Deletion is blocked if any line of the shipping price matrix still references the zone — remove those price lines first.

DELETE /v1/shipping-zones/{id}
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Path Parameters

Response — 204 No Content

No response body.

Errors

⚠️

Warning: You must remove every shipping price matrix line referencing this zone before it can be deleted.

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

Adding Locations to a Shipping Zone

After creating a shipping zone, you can define its geographical scope by adding locations — countries and, for France, individual departments.

PATCH /v1/shipping-zones/{shippingZoneId}/locations
dj-client: OPERATOR
dj-api-key: {{apiKey}}
Content-Type: application/json

Path Parameters

Request Body

The request body is an array of location objects. Each location has:

Rules

• department type is only allowed for countryCode: "FR". Using it for any other country returns F-E-012.
• A country or department can only belong to one shipping zone at a time. If it is already assigned to another zone, it is automatically transferred to the new zone.
• A zone can combine foreign countries and individual French departments.

Example

[
  {
    "type": "country",
    "countryCode": "DE"
  },
  {
    "type": "country",
    "countryCode": "FR",
    "excludedDepartments": ["971", "972", "973", "974", "976"]
  },
  {
    "type": "department",
    "countryCode": "FR"
  }
]

Response — 204 No Content

No response body.

Errors

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

Removing Locations from a Shipping Zone

Remove one or more locations (countries or departments) from an existing shipping zone.

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

Path Parameters

Request Body

The request body is an array of location objects to remove, using the same structure as when adding locations.

Example

[
  {
    "type": "country",
    "countryCode": "DE"
  }
]

Response — 204 No Content

No response body.

Errors

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

Listing the Locations of a Shipping Zone

Retrieve the geographical scope currently attached to a shipping zone — the countries and, for France, the individual departments. Excluded departments are reported alongside the country they belong to.

GET /v1/shipping-zones/{shippingZoneId}/locations
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Path Parameters

Response — 200 OK

{
  "locations": [
    {
      "type": "country",
      "countryCode": "DE"
    },
    {
      "type": "country",
      "countryCode": "FR",
      "excludedDepartments": ["971", "972", "973", "974", "976"]
    },
    {
      "type": "department",
      "countryCode": "FR",
      "departmentCode": "2A"
    }
  ]
}

Errors

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

Listing Shipping Zones

Retrieve a paginated list of shipping zones with optional filters and sorting.

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

Query Parameters

Response — 200 OK

{
  "content": [
    {
      "id": "eu-west",
      "name": "EU West",
      "description": "Western European countries including France, Spain, Portugal, and Benelux",
      "locationCount": 5,
      "createdAt": "2026-06-01T10:00:00Z",
      "updatedAt": "2026-06-10T14:30:00Z"
    },
    {
      "id": "north-america",
      "name": "North America",
      "description": "US and Canada",
      "locationCount": 2,
      "createdAt": "2026-05-15T08:30:00Z",
      "updatedAt": "2026-05-15T08:30:00Z"
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "number": 0,
  "size": 20
}

Retrieving a Shipping Zone

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

Path Parameters

Response — 200 OK

{
  "id": "eu-west",
  "name": "EU West",
  "description": "Western European countries including France, Spain, Portugal, and Benelux",
  "locationCount": 5,
  "createdAt": "2026-06-01T10:00:00Z",
  "updatedAt": "2026-06-10T14:30:00Z"
}

Errors

Creating a Shipping Type

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

Request Body

Example

{
  "id": "express-24h",
  "name": "Express 24h",
  "description": "Next business day delivery for eligible items"
}

Response — 201 Created

{
  "id": "express-24h"
}

Errors

Retrieving a Shipping Type

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

Path Parameters

Response — 200 OK

{
  "id": "express-24h",
  "name": "Express 24h",
  "description": "Next business day delivery for eligible items",
  "createdAt": "2026-06-01T10:00:00Z",
  "updatedAt": "2026-06-01T10:00:00Z"
}

Errors

Listing Shipping Types

Retrieve a paginated list of shipping types with optional filters and sorting.

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

Query Parameters

Response — 200 OK

{
  "content": [
    {
      "id": "express-24h",
      "name": "Express 24h",
      "description": "Next business day delivery for eligible items",
      "createdAt": "2026-06-01T10:00:00Z",
      "updatedAt": "2026-06-01T10:00:00Z"
    },
    {
      "id": "standard",
      "name": "Standard Delivery",
      "description": "Delivery within 3-5 business days",
      "createdAt": "2026-05-15T08:30:00Z",
      "updatedAt": "2026-05-20T14:00:00Z"
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "number": 0,
  "size": 20
}

Updating a Shipping Type

Applies a full replacement of the modifiable fields (name and description). The id is immutable.

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

Path Parameters

Request Body

Example

{
  "name": "Express 24h - Premium",
  "description": "Next business day delivery with premium packaging"
}

Response — 204 No Content

No response body.

Errors

Deleting a Shipping Type

Permanently deletes a shipping type. Deletion is blocked if the shipping type is still referenced in the shipping price matrix.

DELETE /v1/shipping-types/{id}
dj-client: OPERATOR
dj-api-key: {{apiKey}}

Path Parameters

Response — 204 No Content

No response body.

Errors

⚠️

Warning: You must remove all shipping price matrix lines referencing this shipping type before it can be deleted.

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 shipping zones<br>POST /v1/shipping-zones"]:::create
  A2["📦 Add locations<br>PATCH .../locations"]:::add
  B["➕ Create shipping types<br>POST /v1/shipping-types"]:::create
  C["➕ Create logistic families<br>POST /v1/logistic-families"]:::create
  D["🔗 Attach categories<br>to logistic families"]:::add
  E["✅ Configure shipping<br>price matrix"]:::place

  A --> A2 --> E
  B --> E
  C --> D --> E

  style A rx:8,ry:8
  style A2 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

Best Practices

1. Use meaningful custom IDs — if you provide a custom id, make it descriptive and consistent (e.g. eu-west, express-24h). Once created, the ID cannot be changed.
2. Plan your zone structure — define your geographical zones before setting up shipping rules. Restructuring later requires recreating zones.
3. Keep names clear for checkout — shipping type names may be displayed to customers during checkout. Use clear, business-friendly labels.

Common Mistakes

Related Documentation

• Logistic Families
• Shipping Price Matrix
• Introduction to DJUST OMS