ORDER-560 - Retrieve paginated list of commercial orders

GET https://example.com/v2/shop/commercial-orders

Returns the paginated list of commercial orders for the caller.

User scoping

• Only ACCOUNT clients are allowed for this front-office route.
  
  

Store scoping

• Effective store is the dj-store header if provided, otherwise the tenant default store.
  
• The caller must belong to the effective store; otherwise 403.
  
  

Visibility

• Results are limited to the caller’s authorised perimeter (store membership + role).
  
  

Locales

• locale (IETF BCP 47) is required and drives label localisation in the response.
  
  

Scope

• Returns commercial order headers with snapshots and price summaries (no full logistic detail).
  
• Each item includes sourceType and sourceId so the client can report/filter by order source (e.g., Operation).
  
• Logistic details may be partially included via nbPreviewLines.
  
  

Filters

• AND between different keys; OR between values of the same key.
  
• Unknown or malformed values are silently ignored; empty lists mean no filter.
  
• Supported filters: connectedUserOnly, customerAccountIds, isValidated, nbPreviewLines, sourceTypes, sourceIds, cf.
  
  

Custom field filtering (cf)

• Filters only apply to commercial order custom fields.
  
• Format: <CF_EXTERNAL_ID>|<CF_VALUE>.
  
• AND between different CF external IDs; OR between multiple values of the same CF.
  
• Invalid entries or non-applicable CFs are ignored (no 400).
  
  

Sorting

• Server-side sorting uses sort=field:direction. Multiple criteria supported (comma-separated).
  
• Supported fields: createdAt, validatedAt, updatedAt, sourceType, sourceId, reference.
  
• Default: createdAt:desc then reference:asc as tie-breaker for stability.
  
• Invalid/malformed sort entries are silently ignored; valid ones are still applied.
  
• When sorting by reference, collation is case-insensitive and locale-aware.
  
  
• Null handling: null values are always placed last, regardless of sort direction.
  
  

Errors

• 401 Unauthorized (missing/invalid token).
  
• 403 Forbidden (role or store not allowed).
  
• Other errors follow Djust’s error catalog.