Search, Filter & Sort Orders

What this covers

How buyers list Commercial Orders, which filters are commonly used, how sorting works, and what the response contains (header-level only) in API ORDER-560 .

At a glance

This is a buyer (shop) surface - dj-client=ACCOUNT is required.

Listing returns header-level Commercial Orders (aggregates, counts, snapshots), not lines.

Sorting rule (global): malformed sort entries are silently ignored; the request still succeeds (200).

Scope note:

• When customerAccountIds is provided, ignore the single-account context implied by headers and resolve scope from the provided Account IDs only. Each Account ID must be linked to the connected user.

🧭 Result shape (summary)

Each item in the list (and the read-one API) returns header-level data, e.g.:

• id, reference, createdAt, updatedAt, validatedAt
• orderLogisticPrices (aggregated), productCount, lineCount
• customerAccountSnapshot, customerUserSnapshot
• (Optional) logisticOrders identifiers

Lines are not included in the list/read-one payloads; use the Lines endpoints when needed.

Examples

# Multi-account for a manager (ignore header account)
GET /v2/shop/commercial-orders?customerAccountIds=ACC-100,ACC-200&isValidated=true

# Restrict to connected user’s orders within the listed accounts
GET /v2/shop/commercial-orders?customerAccountIds=ACC-100,ACC-200&connectedUserOnly=true

# Provenance: only orders started from Operations OP-2025-001 or OP-2025-007
GET /v2/shop/commercial-orders?sourceTypes=OPERATION&sourceIds=OP-2025-001,OP-2025-007

🧪 Filters

The listing supports a set of filters documented in the API Reference. Multi-account and provenance filters:

• customerAccountIds (optional, multi) - list of Account IDs to include.

  When present, ignore header account and filter on these Accounts.

• connectedUserOnly (optional, boolean) - when true, restrict results to orders placed by the connected user within the Accounts in customerAccountIds.

  If customerAccountIds is absent, this flag has no effect (default shop behavior already scopes to the connected user).

• isValidated (optional, boolean) - when true, return orders that have progressed beyond draft (i.e., validated/placed); when false, return still-draft orders.

  (This is a progress view derived from child Logistic Orders, not a Commercial Order status.)

• sourceTypes (optional, multi) — e.g., OPERATION, QUOTE, ORDER, CART (CART/ORDER are not available yet).

  If one or more values are given, include orders whose sourceType is in the list (OR logic).

• sourceIds (optional, multi) — list of source identifiers (e.g., Operation IDs).

  If provided with sourceTypes, include orders whose (sourceId ∈ list) AND (sourceType ∈ list).

  If provided without sourceTypes, include orders whose (sourceId ∈ list) regardless of type.

• Identifiers & references: by id or business reference (idType=REFERENCE when using the read-one API).
• Timestamps: createdAt, updatedAt, validatedAt (time when all child Logistics moved to CREATED).
• Scope: Account, Store, Store-view (from headers).
• Provenance: initialized from Quote or from Operation.
• Counts / totals: productCount, lineCount, and aggregated price fields (under orderLogisticPrices).

Do not introduce new query parameters in integrations. Use only those defined in the API Reference.

↕️ Sorting

• Format follows the platform convention (e.g., sort=field:direction and multi-sort comma-separated).
• Invalid/malformed sort entries are ignored silently; the request still returns 200 with valid sorts applied.
• Typical sortable fields include: createdAt, updatedAt, validatedAt, reference, productCount, lineCount, and aggregated price fields (e.g., orderLogisticPrices.totalPriceWithoutTax).

📄 Pagination

• Standard pagination as documented in the API Reference (page/size or cursor-based).
• Responses expose the usual pagination metadata (total, next/prev, etc.).

🧰 Processing pipeline

flowchart LR
  IN[Request<br>headers + query]:::sys --> SC[Scope resolution<br>dj-client=ACCOUNT]:::sys
  SC --> ACC[Resolve Accounts<br>customerAccountIds?]:::sys
  ACC -->|Yes| LINK[Check linkage<br>IDs belong to connected user?]:::sys
  ACC -->|No| DEF[Use header-scope account]:::sys
  LINK -->|No| ERR403[403 Forbidden<br>Unlinked account ids]:::stop
  LINK -->|Yes| FACC[Use provided account set]:::sys
  DEF --> FACC
  FACC --> PROV[Apply provenance filters<br>sourceTypes • sourceIds]:::sys
  PROV --> VAL[Apply isValidated<br>progress view]:::sys
  VAL --> SO[Sort entries<br>ignore malformed silently]:::sys
  SO --> PG[Paginate]:::sys
  PG --> OUT[Return header-level items<br>aggregates • counts • snapshots]:::ok

  %% ---------- Styles ----------
  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 ACC rx:8,ry:8
  style LINK rx:8,ry:8
  style DEF rx:8,ry:8
  style FACC rx:8,ry:8
  style PROV rx:8,ry:8
  style VAL rx:8,ry:8
  style SO rx:8,ry:8
  style PG rx:8,ry:8
  style OUT rx:8,ry:8
  style ERR403 rx:8,ry:8

🧯 Troubleshooting

🔗 API quicklinks

• List Commercial Orders - ORDER-560
• Get Commercial Order by id - ORDER-500 - supports idType=REFERENCE