⚙️ Introduction

This job allows the creation and update of Orders via CSV import or API Connector.

You can:

• Create new External Orders
• Add Order Lines to existing Orders
• Update existing Order Lines
• Update the status of an Order
• Remove Order Lines
• Create or update Custom Fields on Order Logistics and Order Lines
• Set the shipping and billing addresses of an Order, field by field or by external identifier

📂 Import model

CSV Structure

The CSV file must contain one row per Order Line. Multiple rows may belong to the same Order Logistic.

API Connector

The API Connector sends data as a JSON payload. The JSON must always be a list of objects, regardless of the use case (create, update, delete).

[
  {
    "orderExternalId": "string",
    "orderReference": "string",
    "orderStatus": "string",
    "accountExternalId": "string",
    "customerExternalId": "string",
    "supplierExternalId": "string",
    "shippingAddressFullName": "string",
    "shippingAddressCountry": "string",
    "shippingAddressStreetName": "string",
    "shippingAddressCity": "string",
    "shippingAddressZipCode": "string",
    "shippingAddressState": "string",
    "shippingAddressAdditional": "string",
    "billingAddressFullName": "string",
    "billingAddressCountry": "string",
    "billingAddressStreetName": "string",
    "billingAddressCity": "string",
    "billingAddressZipCode": "string",
    "billingAddressState": "string",
    "billingAddressAdditional": "string",
    "orderLines": [
      {
        "orderLineExternalId": "string",
        "orderLineId": "string",
        "offerPriceExternalId": "string",
        "variantExternalId": "string",
        "variantName": "string",
        "variantDescription": "string",
        "classificationExternalId": "string",
        "orderLineQuantity": 0,
        "netUnitPrice": 0,
        "grossUnitPrice": 0,
        "taxAmount": 0,
        "markOrderLineForDeletion": false
      }
    ]
  }
]

📋 Fields

Order Identification

Each order must be identified using at least one of the following fields:

If both are provided, Order Reference takes precedence.

Order Line Identification

Each order line must be identified using at least one of the following fields:

To create a new line, Order Line External Id is required.
To update an existing line, provide at least one of these fields.

🧠 Key Business Rules

Use cases and required fields

Create an External Order

Required fields: Order External Id, Account External Id, Customer External Id, Supplier External Id, Order Line External Id, Offer Price External Id (or Variant External Id), Order Line Quantity, Net Unit Price.

Update an External Order or its Lines

Required fields: Order External Id (or Order Reference), Order Line External Id (or Order Line Id).

Update an Internal Order

An Internal Order is an order created natively in DJUST (not imported from an external system). You can update it by providing Order Reference to identify it, along with the fields to update. Order External Id and Order Line External Id can be set on an Internal Order at any time.

Update an Order Status

Provide Order External Id (or Order Reference) and set Order Status to the desired target status.

Status updates are allowed regardless of the current status of the order, as long as the transition moves forward in the order lifecycle:

• ✅ Moving forward is accepted — e.g. SHIPPED → COMPLETED.
• ❌ Moving backward is rejected — e.g. SHIPPED → DRAFT_ORDER.

This makes it possible to progress an order across several import files — for example, ship it in one file and complete it in a later one.

The order lifecycle sequence used as the reference for "forward" is described in Order lifecycle and statuses.

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 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 stop     fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;

  A[📦 Order Status<br>in the import file] --> B{Direction of the<br>transition}
  B -->|Backward| S[⛔ Rejected<br>e.g. SHIPPED to DRAFT_ORDER]
  B -->|Forward| C{Target is a<br>locking status}
  C -->|Any other status| D[✅ Status updated]
  C -->|SHIPPED or COMPLETED| E{Other operations<br>on the same order}
  E -->|All succeeded| F[✅ Status updated<br>order lines locked]
  E -->|At least one failed| G[⛔ Status not applied<br>error in the execution report]

  class A sys
  class B decision
  class C decision
  class E decision
  class D place
  class F place
  class S stop
  class G stop
  style A rx:8,ry:8
  style D rx:8,ry:8
  style F rx:8,ry:8
  style S rx:8,ry:8
  style G rx:8,ry:8

Order lines are not required for status-only updates. A minimal payload containing only the order identifier and the new status is sufficient. When no order lines are provided, existing lines, addresses, and custom fields are preserved unchanged.

Data format

• Net Unit Price and Gross Unit Price must be numeric, using a dot (.) as decimal separator. Example: 12.50
• Order Line Quantity must be a positive integer. Example: 3

Uniqueness

• Order External Id and Order Line External Id must be unique across all orders.

Import execution order

The processing of imported data does not follow a strict FIFO order. If the same Order Line appears multiple times within a single import with different values, the final result may not reflect the last occurrence. Avoid sending duplicate Order Lines with conflicting updates within the same import execution.

Dependencies

• If both Offer Price External Id and Variant External Id are provided, the variant must exist in DJUST and be linked to the provided offer.
• If any shipping address field is provided (including Shipping Address State or
  Shipping Address (Additional)), then Full Name, Country, Street Name, City
  and Zip Code all become required. The imported address fully replaces the Account
  address: State or Additional alone cannot complement it.
• The same rule applies to the billing address fields, independently from the shipping ones.
  Providing only Billing Address City, for example, rejects the line with F-E-001.
• Shipping Address External Id and Billing Address External Id must reference an address
  that already exists in the tenant. An unknown identifier rejects the line.

Shipping and Billing Addresses

Both the shipping address and the billing address of an Order can be set from the import, at creation as well as on update. The two addresses are resolved independently, following the same three-level rule.

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[📦 Address columns<br>of the imported row]:::sys --> B{Address External Id<br>provided}
  B -->|Yes| C{Known in<br>the tenant}
  C -->|Yes| D[✅ Existing address attached<br>detailed fields ignored]:::place
  C -->|No| E[⛔ Line rejected]:::stop
  B -->|No| F{At least one<br>detailed field}
  F -->|Yes| G{The five required<br>fields are filled}
  G -->|Yes| H[✅ Address built<br>from the imported values]:::place
  G -->|No| I[⛔ Line rejected<br>code F-E-001]:::stop
  F -->|No| J[✅ First address<br>of the customer account]:::place

  class B decision
  class C decision
  class F decision
  class G decision
  style A rx:8,ry:8
  style D rx:8,ry:8
  style E rx:8,ry:8
  style H rx:8,ry:8
  style I rx:8,ry:8
  style J rx:8,ry:8

Examples

A one-off billing address, imported field by field

[
  {
    "orderExternalId": "ERP-2026-00123",
    "accountExternalId": "ACC-0042",
    "supplierExternalId": "SUP-01",
    "shippingAddressFullName": "ACME Retail — Warehouse North",
    "shippingAddressCountry": "FR",
    "shippingAddressStreetName": "12 rue des Lilas",
    "shippingAddressCity": "Lille",
    "shippingAddressZipCode": "59000",
    "billingAddressFullName": "ACME Retail — Accounting",
    "billingAddressCountry": "FR",
    "billingAddressStreetName": "3 avenue de la Gare",
    "billingAddressCity": "Paris",
    "billingAddressZipCode": "75008",
    "billingAddressAdditional": "Floor 4",
    "orderLines": [
      {
        "orderLineExternalId": "ERP-2026-00123-1",
        "offerPriceExternalId": "OP-RC-EX3A",
        "orderLineQuantity": 3,
        "netUnitPrice": 117.45
      }
    ]
  }
]

Both addresses are built from the imported values and carried by the order. The customer account is left untouched.

Addresses designated by their external identifier (file import)

Both GLNs must already exist in the tenant; otherwise the row is rejected.

Store View Assignment

When an External Order is created via import, it is automatically assigned to the default store view of the default store.

However, in a multi-store context, you can target a specific store by configuring the storeExternalIds parameter on the import job (via POST /v2/mapper/jobs or PUT /v1/mapper/jobs/{jobId}). When a store is configured on an Order import job, all imported orders are automatically assigned to the default store view of the specified store.

Update rules based on Order Logistic status

Custom Fields on Order Logistics and Order Lines

You can create or update Custom Field values on Order Logistics and Order Lines through this import job. Custom Fields allow you to enrich orders with business-specific metadata such as invoice numbers, tracking codes, or internal references.

Custom Field updates on orders are allowed regardless of the Order Logistic status — including SHIPPED, COMPLETED, or CANCELED. This means you can enrich or correct metadata at any point in the order lifecycle without being blocked by the logistic progression.

General requirements

• An Order must contain at least one Order Line when creating a new order. For status-only updates on existing orders, order lines can be omitted.
• An Order Line from an External Order can reference a product not imported in DJUST.
• An External Order must reference at least one Supplier and one Account existing in DJUST.

⚠️ Common mistakes

🧾 Error codes

For the full reference of functional codes, see Error / Warning codes.

The most relevant code when importing addresses is F-E-001 — a required field is missing or blank.