Bulk Update Custom Fields on Logistic Order Lines

This page explains how to update custom field values and set an externalId on multiple logistic order lines in a single API call, using the partial success pattern.

Introduction

When managing logistic orders with many lines, updating them one at a time is inefficient. The bulk update endpoint lets you update 1 to 100 logistic order lines in a single request, reducing the number of API calls and simplifying integration logic.

For each line you can:

• Set custom field values — replace the values of one or more custom fields.
• Assign an externalId — attach your own reference to the line, so you can later retrieve it by that reference instead of the DJUST identifier.

Each entry must contain at least one of customFieldValues or externalId.

This endpoint follows a partial success model: each line is processed independently. Valid lines are updated, while lines with errors are skipped and reported as warnings in the response.

Key Concepts

Partial Success Pattern

Unlike traditional all-or-nothing endpoints, this endpoint processes each line independently:

• Valid lines are updated successfully.
• Invalid lines are skipped — their errors are returned as warnings in the response body.
• The HTTP response is always 200 OK as long as the request structure is valid.

An empty warnings array means all lines were updated successfully.

Custom Field Identification

Each custom field in the request body is identified by its customFieldId, which corresponds to the custom field's EXTERNAL_ID. This is the identifier you defined when creating the custom field, not the internal DJUST ID.

Clearing a Custom Field Value

To remove a value from a custom field, omit the customFieldValue property or set it to null. The platform will clear the existing value for that custom field on the targeted line.

External ID on a Line

The optional externalId lets you attach your own reference to a logistic order line, so you can retrieve that line later using your reference instead of the DJUST identifier.

• The value must be unique across the tenant — across all logistic order lines. A line carrying an externalId already in use is skipped and reported with warning F-W-040; the other valid lines are still updated.
• Setting an externalId on a line that already has one overwrites the existing value.
• Allowed characters are the RFC 3986 unreserved set: letters, digits, -, ., _, and ~.

Typical Workflow

sequenceDiagram
    participant Client
    participant DJUST as DJUST API

    Client->>DJUST: PATCH /v1/shop/logistic-orders/{logisticOrderId}/lines
    Note right of Client: Body: array of lines with custom fields and/or externalId
    DJUST->>DJUST: Validate each line independently
    DJUST-->>Client: 200 OK (warnings array)
    Note left of DJUST: Empty warnings = full success

Key Endpoint

Path parameter:

• logisticOrderId — the logistic order identifier (type: REFERENCE)

Query parameter (optional):

• locale — used when updating translatable custom fields

Scoping:

• dj-store and dj-store-view headers are supported for store-level filtering.

Request and Response

Request Body

The request body is an array of objects, each targeting one logistic order line. Every entry must contain at least one of customFieldValues or externalId.

[
  {
    "logisticOrderLineId": "line-ref-001",
    "externalId": "PO-2026-0042-L1",
    "customFieldValues": [
      {
        "customFieldId": "MY_CUSTOM_FIELD_EXT_ID",
        "customFieldValue": "new-value"
      },
      {
        "customFieldId": "ANOTHER_CF",
        "customFieldValue": null
      }
    ]
  },
  {
    "logisticOrderLineId": "line-ref-002",
    "externalId": "PO-2026-0042-L2"
  }
]

Successful Response (200 — all lines updated)

{
  "warnings": []
}

Partial Success Response (200 — some lines failed)

{
  "warnings": [
    {
      "code": "F-W-001",
      "message": "Logistic order line not found",
      "details": [
        {
          "field": "logisticOrderLineId",
          "value": "line-ref-999"
        }
      ]
    }
  ]
}

Validation Rules

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[📦 Receive request] --> B{Structural<br>validation}
  B -->|Empty body or<br>more than 100 lines<br>or duplicate lineIds| C[422 Error]
  B -->|Valid structure| D[Process each<br>line independently]
  D --> E{Line valid?}
  E -->|Yes| F[✅ Update custom fields]
  E -->|No| G[⚠️ Add to warnings]
  F --> H[200 OK<br>warnings array]
  G --> H

  style A rx:8,ry:8
  style C rx:8,ry:8
  style D rx:8,ry:8
  style F rx:8,ry:8
  style G rx:8,ry:8
  style H rx:8,ry:8

  B:::decision
  C:::stop
  D:::sys
  E:::decision
  F:::place
  G:::stop
  H:::ok
  A:::read

Structural Validations (→ 422)

These reject the entire request:

• Request body is empty or missing.
• More than 100 lines in the array.
• A logisticOrderLineId appears more than once in the request.

Per-Line Validations (→ warning)

These affect only the individual line:

• The logisticOrderLineId does not exist in the targeted logistic order.
• The customFieldId does not reference a valid custom field (by EXTERNAL_ID).
• The externalId is already used by another logistic order line in the tenant — warning F-W-040.

Best Practices

• Batch your updates — group custom field changes for multiple lines into a single request (up to 100 lines) to minimize API calls.
• Check the warnings array — always inspect the response, even on 200. An empty warnings array confirms full success.
• Use EXTERNAL_ID for custom fields — the customFieldId field expects the custom field's EXTERNAL_ID, not an internal identifier.
• Handle translatable fields — pass the locale query parameter when updating custom fields that support translations.

Common Mistakes

Error and Warning Codes

For the full list of error and warning codes, see:
Error / Warning codes

Most relevant codes for this endpoint:

• F-W-001 — line not found in the logistic order
• F-W-004 — custom field not found
• F-W-040 — externalId already used by another line
• F-E-001 — required field(s) missing or invalid (422)

Related Endpoints