Search, Filter & Sort Logistic Orders

What this covers

How a storefront lists Logistic Orders — the "My orders" screens — with server-side filtering and sorting through ORDER-550 (POST /v1/shop/logistic-orders).

At a glance

This is a buyer (shop) surface. Criteria are sent in the request body; pagination and sorting are sent as query parameters.

Sorting rule (global): invalid sort entries are silently ignored. The valid entries of the same request are still applied and the call returns 200.

Default sort: without any sort criteria, the most recently created orders come first. This default is stable, so pagination is deterministic.

Key concepts

Sorting

Both field:direction (recommended) and field,direction are accepted, and asc / desc are available on every sortable field. Sort keys are accepted in camelCase; the snake_case form remains functional.

Sortable fields

id, reference, externalId, status, paymentStatus, paymentOption, createdAt, updatedAt, orderOrigin, incidentDeclared, channel, shippingType

Sortable price fields

totalPriceWithTax, totalPriceWithoutTax, totalTaxAmount, totalProductWithTax, totalProductWithoutTax, totalProductTaxAmount, totalShippingFeesWithTax, totalShippingFeesWithoutTax, totalShippingTaxAmount

✅

Tip: An unknown sort key no longer fails the whole request. sort=reference:asc&sort=notAField:desc sorts by reference and ignores the second key.

Sorting on a custom field value

Orders can also be sorted on the value of one of their custom fields, using the key cf.<identifier> where the identifier is either the DJUST identifier of the custom field or its external one.

• One custom field key per request. If several are sent, the first is honoured and the following ones are ignored.
• Orders with no value for that custom field come last, in both directions.
• Comparison depends on the type: NUMBER and METRIC values are ordered as numbers, DATE values written in ISO form chronologically, and everything else as text — ignoring case and accents.
• The key is ignored when no custom field carries the identifier, or when that custom field holds media.

📘

Note: Sorting on a custom field value is available on the storefront surface only.

# Orders sorted by the PRIORITY custom field, then by creation date
POST /v1/shop/logistic-orders?sort=cf.PRIORITY:asc&sort=createdAt:desc&page=0&size=20

Filters

Order identifier

orderIdentifier matches the order reference, its external identifier or its DJUST identifier — a single field to back an "order number" search box, with no need to know which identifier the buyer typed.

{ "locale": "fr", "orderIdentifier": "ORD-000123" }

Order origin

orderOrigin restricts the list to one or more origins: CART, SUPPLIER_QUOTE, ORDER, EXTERNAL_ORDER. The filter is applied before pagination, which is how external orders are kept out of a storefront screen without paging through them client-side.

{ "locale": "fr", "orderOrigin": ["CART", "SUPPLIER_QUOTE"] }

Custom field criteria

Three criteria lists are available, one per level:

Each entry is a { customFieldId, value } pair. The combination rules are:

• Several values on the same custom field → combined with a logical OR.
• Different custom fields → combined with a logical AND.
• Custom fields of type MEDIA are not searchable and are excluded from filtering.

{
  "locale": "fr",
  "orderLogisticCustomFieldValueCriteria": [
    { "customFieldId": "PRIORITY", "value": "HIGH" },
    { "customFieldId": "CHANNEL", "value": "B2B" },
    { "customFieldId": "CHANNEL", "value": "B2C" }
  ]
}

Reads as: PRIORITY = HIGH AND (CHANNEL = B2B OR CHANNEL = B2C).

Other criteria

Processing pipeline

flowchart LR
  IN[📘 Request<br>body criteria + query sort]:::sys --> SC[Scope resolution<br>account • store]:::sys
  SC --> IDF[Apply orderIdentifier<br>reference • externalId • id]:::read
  IDF --> ORG[Apply orderOrigin]:::read
  ORG --> CF[Apply custom field criteria<br>OR inside • AND across]:::read
  CF --> ST[Apply status and date filters]:::read
  ST --> SO{Sort keys provided}:::decision
  SO -->|No| DEF[Default sort<br>newest orders first]:::sys
  SO -->|Yes| VAL[Keep valid keys<br>ignore the others]:::sys
  DEF --> PG[Paginate]:::sys
  VAL --> PG
  PG --> OUT[✅ Paginated logistic orders]:::place

  %% 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;

  style IN rx:8,ry:8
  style SC rx:8,ry:8
  style IDF rx:8,ry:8
  style ORG rx:8,ry:8
  style CF rx:8,ry:8
  style ST rx:8,ry:8
  style SO rx:8,ry:8
  style DEF rx:8,ry:8
  style VAL rx:8,ry:8
  style PG rx:8,ry:8
  style OUT rx:8,ry:8

Example scenario

A "My orders" screen showing shipped orders of two suppliers, searched by order number and sorted by total amount excluding tax.

POST /v1/shop/logistic-orders?sort=totalProductWithoutTax:desc&page=0&size=20&nbPreviewLines=3
dj-client: ACCOUNT
dj-api-key: <your-api-key>
Content-Type: application/json

{
  "locale": "fr",
  "orderIdentifier": "2026-08",
  "logisticStatus": ["SHIPPED"],
  "supplierIds": ["SUP-01", "SUP-02"],
  "orderOrigin": ["CART"],
  "creationDateFrom": "2026-08-01T00:00:00.000Z"
}

Best practices

• Filter server-side, always. Every criterion on this page is applied before pagination. Loading all orders and filtering in the browser defeats the pagination and degrades on large accounts.
• Use orderIdentifier for a single search box. One field covers the reference, the external identifier and the DJUST identifier.
• Exclude external orders with orderOrigin, not by post-filtering a page of results — otherwise your page sizes become inconsistent.
• Send one custom field sort key at most. Additional ones are silently dropped, so a screen relying on two of them will not behave as expected.
• Rely on the default sort for stable pagination. Do not add a random tie-breaker of your own.

Common mistakes

Error codes

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

API quicklinks

• Search Logistic Orders — ORDER-550
• Get a Logistic Order by id — ORDER-501
• List Commercial Orders — ORDER-560 — see Search, Filter & Sort Orders