Orders¶

Orders are the core transaction record in Vectis. Every completed checkout produces an order that tracks line items, pricing, tax, shipping, and fulfillment status.

Checkout Flow¶

The checkout pipeline runs these steps in sequence:

graph LR
    A[Cart] --> B[Promotions Evaluated]
    B --> C[Shipping Calculated]
    C --> D[Tax Calculated]
    D --> E[Payment Processed]
    E --> F[Order Created]

1. Cart finalized — all line items, quantities, and the shipping address are set.
2. Promotions evaluated — discount rules and coupon codes are matched. Allocations are computed per line item.
3. Shipping calculated — carrier strategies return rates for the selected method.
4. Tax calculated — all registered tax strategies run; per-line tax lines are written.
5. Payment processed — the payment strategy authorizes or charges the payment method based on the configured capture mode.
6. Order created — the cart converts to an order with immutable line-level snapshots of price, tax, and discount.

Order State Machine¶

Orders follow a configurable state machine. The default EmpireOrderProcess defines these states:

Transitions¶

Transitions are guarded — a Fulfilled order cannot jump back to Created. Side-effects (void/refund, emails, Redpanda events, ERP sync) fire on each transition.

Key automatic behaviors:

• Cancel → auto void/refund: Transitioning any order to Cancelled automatically voids authorized transactions or refunds captured ones.
• Refund → auto refund: Transitioning from Fulfilled to Refunded automatically refunds all captured transactions.
• Fraud release → AwaitingFulfillment: Releasing a fraud hold transitions from HeldForReview to AwaitingFulfillment.

Order Totals¶

Every order stores five monetary totals:

Order Modification¶

Orders in an editable state with payment_status="authorized" can be modified:

1. Add lines — specify a variant ID and quantity.
2. Remove lines — remove existing line items.
3. Update quantities — change the quantity on existing lines.

When an order is modified:

• Totals are recalculated (subtotal, grand total, base amounts).
• The existing authorization is voided.
• A new authorization is placed for the updated grand total.
• An order.modified event is recorded.

This is available to admins and B2B buyers via the modifyOrder mutation. Only authorized (not captured) orders can be modified.

Admin Order Creation¶

Staff can create orders directly from the admin panel:

1. Navigate to Orders → Create Order.
2. Select an account and channel.
3. Add line items by variant ID.
4. Set addresses, shipping, and notes.
5. Choose a saved card or payment method with capture mode.

See Payments → Admin Order Creation for details.

B2B Features¶

Vectis orders support several B2B-specific capabilities:

• PO numbers — buyers attach a purchase order reference at checkout. The PO number appears on invoices and in admin search.
• Approval workflows — orders from accounts with approval rules enter a PendingApproval state. Authorized approvers confirm or reject via the admin panel or API.
• Payment terms — accounts configured with net-30, net-60, or custom terms create orders without immediate payment. The order records the terms and due date.
• Location-scoped cards — saved payment methods can be scoped per location for B2B accounts with multiple sites.

Multi-Currency¶

Orders store dual amounts on every monetary field:

• Transacted amount — the currency the buyer paid in (e.g., 100.00 MXN).
• Base amount — the equivalent in your base currency (e.g., 5.88 USD).

The exchange rate is locked at checkout time and stored on the order. Subsequent rate fluctuations do not affect existing orders.

Fraud Handling¶

Orders flagged by gateway fraud filters (Authorize.net FDS) enter the HeldForReview state. The admin can:

• Release the hold — approves the transaction and moves the order to AwaitingFulfillment.
• Cancel the order — voids the held transaction.

See Payments → Fraud Filter Handling for the full workflow.

Admin Panel¶

From Orders in the admin panel you can:

• Search and filter by status, date range, account, PO number, or order ID.
• View order detail — line items with per-line tax breakdown, discount allocations, and fulfillment status.
• Transition status — move an order to its next valid state. Invalid transitions are blocked by the state machine.
• View payment transactions — authorizations, captures, voids, refunds with gateway details. Capture authorized transactions, void, or refund directly from the transaction panel.
• Release fraud holds — approve transactions flagged by gateway fraud filters.
• Modify orders — add/remove/update line items on authorized orders with automatic reauthorization.
• Create orders — build orders from scratch for B2B customers with saved card charging.
• Add internal notes — staff-only notes attached to the order timeline.