FAQs

Q1. What does an order need to be created?

POST /v1/orders requires orderinfo (ordertype, customerinfo.customerid), orderitems (each with id/skuid/pid, quantity, lineid, math incl. sale), order-level math (incl. total, sale), payments summing to total, and usertracking.createdby. Deep validators enforce per-mode price/tax/discount/payment reconciliation (see §7.4/7.5). New orders start at status Created.

Q2. How do I cancel an order and is there a time limit?

PATCH the order with cancelsource = User/Admin/SAP. Only Created/Created_Fulfilment are cancellable via REST. User must be within the cancel window (ORDER_CANCEL_WINDOW_HOURS, default 24h) and not Shipped/Delivered; Admin can always cancel; SAP unless Shipped/Delivered. If the submit-order Step Function is paused at CancelApproval, the cancel resumes it (that human task times out in ~20s prod / ~10s in-memory).

Q3. How is partial (item) cancellation triggered?

Same PATCH endpoint, with an orderitems[] array where every item has orderstatus="Cancelled". Allowed only when the order is in Created/In_Process/Created_Fulfilment/Partial_Cancelled/Freeze_Edit. Don’t mix with cancelsource (→ PARTIAL_CANCEL_MIXED_REQUEST).

Q4. What is the difference between PATCH /v1 and PATCH /v2 orders?

V1 uses a hardcoded status enum and always enforces workflow transitions (allowedPatchFields). V2 validates status against the instance’s allowedOrderStatuses (or the V1 set by default), and—if bypassWorkflowValidation=true—skips step-enforcement (allowing step-jumps) with only a terminal-state guard. Both are config-gated per tenant.

Q5. Is the V2 step-jump/bypass a global switch?

No. It is per-instance, read from instanceContext.properties.bypassWorkflowValidation. When set, the order-create/update payload also carries the flag, which makes the EventBridge rule drop the Step Function trigger so the workflow doesn’t run.

Q6. How are returns processed?

Create with POST /v1/orders/:orderId/returnOrder (parent must be returnable; status Return_Submitted). Advance via PATCH /v1/orders/:orderId/returns/:returnOrderId with action = accept → refund → collect (Return_Submitted → Return_Accepted → Return_Refunded → Return_Collected).

Q7. How do Replace/Exchange orders work?

They are created through POST /v1/orders with ordertype=Replace|Exchange and a parentorderid; the parent must be Shipped/Delivered. There is no dedicated /replacements/:id PATCH route (its error codes exist but the route is not wired). Return-collection for the child is signalled via PATCH …/return-collection/:childOrderId/callback or the returnCollected EventBridge event, which starts SF2.

Q8. What events does OMS emit and how are they gated?

It publishes EventBridge events (source is the service name, bus set by EVENT_BUS_NAME) for each workflow task and notification (e.g. PAYMENT_BLOCK, INVENTORY_SHIPMENT_UPDATE, ORDER_CONFIRMED, ORDER_SHIPPED, ORDER_CANCELLED, return/replace notifications). Publishing is skipped in in-memory mode, redirected when LOCAL_EVENT_ROUTER_URL is set, disabled at STAGE=test, and suppressed for bypass-workflow instances.

Q9. Which order can be deleted?

Only orders where deletable is true — i.e. all items are in terminal states (Cancelled, Return_Collected, Return_Expired). Otherwise ORDER_NOT_DELETABLE (422). Deletion is admin-scoped; for customer cancels use the PATCH cancel flow.

Q10. How is auth enforced and can it be bypassed locally?

Every business route runs authHook("<privilege>") → fastify.preauth (Cognito JWT + custom:privileges). SKIP_AUTH=true bypasses JWT only when no Bearer token is sent; if a token is present it is still validated. /health is unauthenticated.

Revision History
2026-08-05 | JP – Created the page and added the content.