⚙️ 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

📂 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",
    "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.

Shipping and Billing Addresses

When an External Order is created via import, its addresses are resolved as follows:

• Shipping address: if at least one Shipping Address field is provided, the address is built from the imported values (see the conditionally required fields above). Otherwise, the first shipping address associated with the Account is used.
• Billing address: it is always the first billing address associated with the Account. The Orders import does not expose any billing address field, so the billing address cannot be set or overridden from the import file.

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.