Orders & refunds
Orders and refunds are received via webhooks and screened against configurable rules. Only flagged ones go to manual review; the rest are auto-approved.
Order processing
orders/paid (HMAC-verified) is received, stored, and screened with the rules in order-review.yml.
| Rule | Flags when | Default |
|---|---|---|
highValue |
total_price ≥ a per-currency threshold (e.g. JPY ≥ 100,000) |
on |
flaggedFinancialStatus |
financial_status is pending/authorized/partially_paid |
on |
largeQuantity |
a single line quantity ≥ maxLineQuantity (default 10) |
on |
newCustomer |
orders_count ≤ maxOrdersCount |
off |
addressMismatch |
billing and shipping countries differ | on |
enabled: false auto-approves everything. Missing/broken config never blocks processing (fail-open).
Workflow: Order Review (approve) → Fulfill Order (enter tracking → ship). On shipment, commerce:tracking_number etc. are recorded, and with the Admin API enabled the fulfillment is written back to Shopify via fulfillmentCreateV2 (failures are recorded only and never break the workflow).
Status: received → review_pending → approved → fulfillment_pending → fulfilled (or error).
Refund processing
refunds/create (a notice that Shopify has already executed the refund) is received and screened. This is for audit and fraud monitoring — it never moves money and never writes back to Shopify.
| Rule | Flags when | Default |
|---|---|---|
highRefundValue |
the refund amount ≥ a per-currency threshold (e.g. JPY ≥ 50,000) | on |
fullRefund |
the refund amount ≥ the original order's total_price |
on |
noRestock |
items were returned but none restocked | on |
After review, the refund facts are recorded and the original order is updated: commerce:refunded_amount / commerce:refund_count / commerce:source_status (refunded / partially_refunded), guarded by commerce:order_updated against double application.
Status: received → review_pending → resolved (or error).
Tasks & notifications
Review tasks are handled in the Webtop Tasks app, and notifications go to the channels in notifications.yml (Slack / Discord / Teams / LINE / webhook / email). Forms highlight the flagged reasons.
The status model
There are two axes: commerce:status (the ingestion processing lifecycle) and commerce:source_status (a mirror of Shopify's business status). See the Overview and Operations tools for details.