Order Lookup

Overview

Support rapid operational lookup to retrieve commercial transaction records — Process Records (IAO) of Shopify orders (ODR-005: orders are Processes/Occurrents, not Objects). Returns filtered transaction participation records and artifact identifiers. Excludes non-relevant items (warranty, digital, reshipment).

Goal: One-call information retrieval API for UI workflows — returns normalized Process Record + MaterialArtifact resolution.

Main success scenario

[IAO: Information retrieval of Process Records | BFO: Occurrent records queried by identifier]

1. Person bearing Role enters order identifier in the UI
2. POST /api/orders/lookup with query
3. API validates Access
4. API queries commercial_transaction_record by order_id OR order_number
5. API fetches matching transaction_participation_record and applies exclusion filters
6. Returns artifact_identifiers, quantities, titles; optionally joins material_artifact for metadata

DTOs

Request:

{
  "query": "1000123456",
  "query_type": "auto"
}

Response:

{
  "order": {
    "order_id": "...",
    "order_number": "...",
    "process_initiated_at": "ISO8601"
  },
  "line_items": [
    {
      "artifact_identifier": "...",
      "quantity": 1,
      "title": "...",
      "excluded": false
    }
  ]
}

Exception flows

IssueOccurrence	FallbackStep
Process Record not found	Return 404-style error
Multiple matches for order_number	Return ambiguous results; require disambiguation
Raw data stale	Optionally fall back to Shopify live query (with rate-limit protection)

API endpoint

• POST /api/orders/lookup — interactive, target p99 < 200ms

Acceptance criteria

• PASS: Given known order ID/number, API returns correct artifact_identifiers from transaction_participation_record; excluded items are filtered out
• FAIL: Returns excluded items; misses valid items; full table scan exceeding latency expectations