Order Statuses

Order statuses track where an order is in its lifecycle. yStore ships with 21 default statuses covering every stage from payment pending to complete, cancelled, or refunded.

Navigate to yStore → Orders → Order Statuses to manage statuses.

Default statuses

These statuses are installed automatically. Their handles are fixed (system statuses) — you can customize the label, color, and description, but the handle cannot be changed.

The color swatch shown in the table is displayed as a badge next to the status in the order list and order detail view.

#	Label	Handle	Color	Fulfills	Notifies	Description
1	Pending ⭐	pending	🔵 #38bec9	—	✓	Order received, awaiting payment confirmation or review. This is the default status for new orders.
2	Pending Payment	pending_payment	🟢 #84cc16	—	✓	Order placed but payment not yet captured or authorized.
3	Payment Review	payment_review	🟢 #22c55e	—	✓	Payment requires manual verification before processing.
4	Payment Failed	payment_failed	🔴 #ef4444	—	✓	Latest payment attempt was declined or expired.
5	Suspected Fraud	fraud	🩷 #e8368f	—	✗	Order flagged for unusual activity. Customer is not notified by default.
6	Processing	processing	🔵 #03a9f4	—	✓	Payment confirmed, order being prepared for fulfillment.
7	Backordered	backordered	🟠 #fb923c	—	✓	Some items temporarily out of stock, awaiting replenishment.
8	Awaiting Fulfillment	awaiting_fulfillment	🔵 #0ea5e9	—	✓	Items picked and queued for packing or production.
9	Ready to Ship	ready_to_ship	🟦 #00897b	—	✓	Packed and ready for carrier pickup or handoff.
10	Partially Shipped	partially_shipped	🟦 #00897b	—	✓	At least one shipment sent; additional items still pending.
11	Shipped	shipped	🔵 #1565c0	—	✓	Order left the warehouse and is in transit.
12	Out for Delivery	out_for_delivery	🟦 #0d9488	—	✓	Carrier has the package on the vehicle for final delivery.
13	Delivered	delivered	🔵 #1565c0	✓	✓	Carrier confirmed delivery to the customer destination.
14	Ready for Pickup	ready_for_pickup	🟦 #14b8a6	—	✓	Order staged at pickup location, awaiting customer.
15	Complete	complete	🟢 #4caf50	✓	✓	Delivered successfully, all post-delivery tasks done.
16	Return Requested	return_requested	🟠 #f97316	—	✓	Customer requested return, awaiting approval.
17	Returned	returned	🟠 #f97316	—	✓	Returned items received and being inspected/restocked.
18	Refunded	refunded	🟣 #6366f1	—	✓	Payment partially or fully returned to the customer.
19	Closed	closed	🔘 #607d9f	—	✓	Finalized administratively (after refunds or adjustments).
20	Canceled	canceled	🔴 #9f1239	—	✓	Order voided before items were shipped.
21	On Hold	holded	🟣 #a855f7	—	✓	Temporarily paused (inventory issue, customer follow-up).

⭐ Default = new orders start with this status Fulfills ✓ = marks the order as fulfilled (stops stock decrementing retries) Notifies ✓/✗ = whether the customer receives an email on this status by default

Status workflow

A typical order lifecycle flows through these statuses:

Pending
  └── Payment received → Processing
        └── Packed → Ready to Ship
              └── Handed to carrier → Shipped
                    └── Delivered (fulfills order)
                          └── Complete (fulfills order)

Alternative paths:
  Pending → Payment Failed → (customer retries or order canceled)
  Any status → On Hold → (resume to previous or cancel)
  Any pre-ship status → Canceled
  Post-delivery → Return Requested → Returned → Refunded → Closed

Status flags explained

Each status has four behavioral flags:

Flag	Description
Mark as Default	New orders start with this status. Only one status can be default at a time.
Notifies Customer	When an order moves to this status and "Notify customer" is checked, an email is sent using the status-change email template.
Fulfills the Order	Marks the order as fulfilled. Relevant for stock management and reporting. Delivered and Complete have this on by default.
Archive Status	Archived orders are hidden from the default order list view (they can still be found via search and filters).
Visible	Hidden statuses don't appear in the status picker — useful for internal-use statuses you set programmatically.

Changing an order's status

From the order detail view:

1. Click Change Status in the top action bar.
2. Select the new status from the dropdown.
3. Optionally add a note (shown in order history).
4. Toggle Notify Customer on or off.
5. Click Save.

Or use the quick status badge in the right-side panel for a faster one-click change without notes.

Status change emails

The "Notify Customer" checkbox only sends an email if the target status has Notifies Customer enabled. Even if you check the box, no email is sent for statuses with customer notifications disabled (e.g., Suspected Fraud).

Creating a custom status

1. Go to yStore → Orders → Order Statuses.
2. Click New Status.
3. Fill in:
   • Label — what admins and customers see (e.g., "Awaiting Documents")
   • Handle — a unique, lowercase, underscore-separated identifier (e.g., awaiting_documents). Used in automation flows and API filters.
   • Color — pick from the color palette or enter a hex value
   • Description — internal note explaining when this status is used
4. Set the behavioral flags.
5. Drag to reorder in the status list.
6. Save.

Handle in automation flows

Use the status handle when filtering orders in GraphQL (getCustomerOrders) or when building automation flow conditions (e.g., "order status is awaiting_documents"). The handle never changes even if you rename the label.

Reordering statuses

Statuses appear in the dropdown in the order defined here. Drag and drop rows in yStore → Orders → Order Statuses to reorder them. The order also affects the status picker in the order edit slideout.

System status restrictions

Default statuses installed by yStore (marked isSystemDefault: true in metadata) have restricted fields:

• The handle cannot be changed
• The status cannot be deleted

You can still change the label, color, description, and all behavioral flags on system statuses.

Using status handles in code

Reference statuses by handle in PHP events, flow conditions, and GraphQL:

// In a PHP event listener
if ($event->statusTo === 'shipped') {
    // send tracking email
}

# In GraphQL — filter orders by status
query {
    getCustomerOrders(limit: 10) {
        orders {
            number
            status { handle label color }
        }
    }
}