Shipping Zones

Introduction

Shipping zones are geographical areas (e.g. "France Metropolitan", "EU", "North America") used to scope shipping rules and pricing. They define where delivery is offered and at which conditions, before being referenced in the shipping price matrix.

Managing Shipping Zones from the Back-Office

Most operators manage shipping zones 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 zones

List view

The list view displays all existing shipping zones with:

• Search — free-text on name and id (case- and accent-insensitive)
• Sorting — by name, creation date, or last update
• Row actions — Edit, Delete
• Each row shows the number of locations attached to the zone

Creating a shipping zone

Click "Create zone" and fill in the form:

Managing locations

Locations define the geographical scope of the zone. Add them from the Locations section of the zone editor.

Each location can be one of four types:

The last three modes are Back-Office shortcuts for France — they all resolve into an explicit list of French department codes at the API level. See Adding Locations to a Shipping Zone for the underlying schema.

Editing a shipping zone

Only Name and Description can be modified. The ID is locked. Locations are managed separately (see above).

Deleting a shipping zone

Deletion is blocked if the shipping zone is still referenced in the shipping price matrix. The Back-Office displays an error and lists the associated price rows. Remove them first, then retry the deletion.

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

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. The rules are simple:

• Foreign countries are added as a whole (one entry per country).
• France (FR) must be added as individual departments — France cannot be added as a whole country.

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

Path Parameters

Request Body

Business Rules

• France must be added as individual departments — you cannot add FR as a whole country.
• If a country or department is already assigned to another shipping zone, it is automatically moved to the current one — the previous zone loses it silently (a warning is returned).
• Re-adding a location already present in this zone is idempotent (no error).

Example — Foreign countries

{
  "locations": [
    { "countryCode": "BE" },
    { "countryCode": "DE" },
    { "countryCode": "ES" }
  ]
}

Example — French departments

{
  "locations": [
    { "countryCode": "FR", "departmentCodes": ["75", "92", "93"] }
  ]
}

Example — Mixed

{
  "locations": [
    { "countryCode": "BE" },
    { "countryCode": "FR", "departmentCodes": ["59", "62"] }
  ]
}

Response — 200 OK

The response contains a warnings array reporting every location moved from another zone. Empty if no reassignment occurred.

{
  "warnings": [
    {
      "countryCode": "FR",
      "departmentCode": "75",
      "code": "F_W_039",
      "message": "Location 75 has been moved from shipping zone zone-corse to shipping zone zone-idf.",
      "previousShippingZoneId": "zone-corse"
    }
  ]
}

Errors

Removing Locations from a Shipping Zone

Remove one or more locations from an existing shipping zone. The request follows the same structure as adding locations.

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

Path Parameters

Request Body

Business Rules

• An empty locations array is accepted and performs no modification.
• Removing a location not currently in the zone is silently idempotent (no error).
• A location currently attached to another shipping zone is left untouched.
• After removal, if the customer destination is no longer covered by any zone, the checkout process will be blocked for that destination.

Example — Remove a foreign country

{
  "locations": [
    { "countryCode": "BE" }
  ]
}

Example — Remove French departments

{
  "locations": [
    { "countryCode": "FR", "departmentCodes": ["75", "92"] }
  ]
}

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 all locations attached to a shipping zone. The response is not paginated.

Locations are grouped by country:

• An entire foreign country is represented by countryCode alone (no departmentCodes).
• France is represented by countryCode: "FR" together with the list of assigned departmentCodes.

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

Path Parameters

Response — 200 OK

{
  "locations": [
    { "countryCode": "FR", "departmentCodes": ["75", "92"] },
    { "countryCode": "BE" },
    { "countryCode": "DE" }
  ]
}

Zone with no locations:

{ "locations": [] }

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",
      "locationsCount": 5,
      "createdAt": "2026-06-01T10:00:00Z",
      "updatedAt": "2026-06-10T14:30:00Z"
    },
    {
      "id": "north-america",
      "name": "North America",
      "description": "US and Canada",
      "locationsCount": 2,
      "createdAt": "2026-05-15T08:30:00Z",
      "updatedAt": "2026-05-15T08:30:00Z"
    }
  ],
  "numberOfElements": 2,
  "number": 0,
  "size": 20,
  "first": true,
  "last": true,
  "empty": false
}

Errors

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

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",
  "locationsCount": 5,
  "createdAt": "2026-06-01T10:00:00Z",
  "updatedAt": "2026-06-10T14:30:00Z"
}

Errors

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

Best Practices

1. Use meaningful custom IDs — if you provide a custom id, make it descriptive and consistent (e.g. eu-west, metropolitan-france, dom-tom). Once created, the ID cannot be changed.
2. Design your zone map with the price matrix in mind — a shipping zone is a pricing bucket in the shipping price matrix. Design zones so each represents a distinct pricing area.
3. Plan French department coverage carefully — even when using the Back-Office shortcut "Whole France", the zone stores the explicit list of French departments. Since a department can only belong to one zone, plan the coverage before splitting France across multiple zones.
4. Watch for silent reassignments — when adding a location already assigned to another zone, it is transferred silently (a F_W_039 warning is returned). Always check the warnings array in the API response, or the reassignment banner in the Back-Office.
5. Keep zone names business-friendly — they are shown to operators in the shipping price matrix and other Back-Office screens. Use clear, unambiguous labels.

Common Mistakes