Bulk Update Custom Fields on Logistic Order Lines

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

Introduction

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

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.

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
    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:

[
  {
    "logisticOrderLineId": "line-ref-001",
    "customFields": [
      {
        "customFieldId": "MY_CUSTOM_FIELD_EXT_ID",
        "customFieldValue": "new-value"
      },
      {
        "customFieldId": "ANOTHER_CF",
        "customFieldValue": null
      }
    ]
  },
  {
    "logisticOrderLineId": "line-ref-002",
    "customFields": [
      {
        "customFieldId": "MY_CUSTOM_FIELD_EXT_ID",
        "customFieldValue": "42"
      }
    ]
  }
]

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).

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-E-001 — required field(s) missing or invalid (422)

Related Endpoints