Shipping Types

Introduction

Shipping types are the delivery modes proposed to customers at checkout (e.g. "Express", "Standard", "Click & Collect"). They are one of the building blocks of the DJUST shipping module and are later referenced in the shipping price matrix.

Managing Shipping Types from the Back-Office

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

List view

The list view displays all existing shipping types with:

• Search — free-text on name and id (case- and accent-insensitive)
• Sorting — by name, creation date, or last update
• Row actions — Edit, Delete

Creating a shipping type

Click on "Create shipping type" and fill in the form :

• Name (required) — Display name (up to 255 characters). May be shown to customers at checkout.
• Description — Additional context (up to 10,000 characters).
• ID — Custom identifier. Auto-generated if left blank. Immutable after creation. Must be unique.

Editing a shipping type

Only Name and Description can be modified. The ID is locked once the shipping type is created.

Deleting a shipping type

Deletion is blocked if the shipping type 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.

Using the API

The API mirrors the Back-Office actions above. It is intended for integrators building automated flows or a custom Back-Office.

Key Endpoints

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

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"
    }
  ],
  "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.

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

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

Typical Workflow

flowchart LR
  classDef create fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef place fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
  classDef ok fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;

  A["➕ Create shipping type<br>POST /v1/shipping-types"]:::create
  B["🧩 Reference in the<br>shipping price matrix"]:::place
  C["🛒 Displayed to customers<br>at checkout"]:::ok

  A --> B --> C

Best Practices

1. Use meaningful custom IDs — if you provide a custom id, make it descriptive and consistent (e.g. express-24h, standard-3d, click-and-collect). Once created, the ID cannot be changed.
2. Keep names clear for checkout — shipping type names may be displayed to customers during checkout. Use clear, business-friendly labels.

Common Mistakes