# Channel Order Statuses

There are two independent status fields on every Channel Order — **Order Status** and
**Payment Status**. They are set separately and can be in any combination.

---

## Order Status

**Enum file:** `plugins/webkul/channel-orders/src/Enums/OrderStatus.php`

| Value | Label | Colour | Meaning |
|-------|-------|--------|---------|
| `open` | Open | Blue | Order has been received and is awaiting fulfilment. Default for all newly imported orders. |
| `processed` | Processed | Green | Order has been fulfilled and dispatched. Set automatically when a Shopify order is imported with `fulfillment_status = fulfilled`, or manually when you process the order in Cydekick. `processed_at` is recorded at this point. |
| `cancelled` | Cancelled | Red | Order was cancelled. Set by the Shopify cancellation webhook, by the reconciliation pass in the sync job, or manually. `processed_at` is set to Shopify's actual `cancelled_at` date. |

### Where it appears
- **Open Orders** tab — shows only `open`
- **Processed Orders** tab — shows `processed` and `cancelled`
- **Order Sync** (Channels view) — all statuses visible; `cancelled` rows are struck-through with a grey **Void** pill

---

## Payment Status

**Enum file:** `plugins/webkul/channel-orders/src/Enums/PaymentStatus.php`

| Value | Label | Colour | Meaning |
|-------|-------|--------|---------|
| `unpaid` | Unpaid | Amber | Payment has not been taken. Covers Shopify statuses: `pending`, `partially_paid`, `refunded`, `voided`, or any status not explicitly mapped. |
| `paid` | Paid | Green | Payment has been successfully captured. Maps from Shopify `financial_status = paid`. |
| `authorized` | Authorized | Orange | Card has been authorised but payment not yet captured. Shopify takes the money when the order is fulfilled. Maps from Shopify `financial_status = authorized`. The authorisation expiry date is shown next to the badge when available. |

### Authorisation expiry
When an order arrives as `authorized`, Cydekick attempts to fetch the expiry date
from the Shopify Transactions API (`/orders/{id}/transactions.json`) and store it in
`authorisation_expires_at`. It is shown in the Open Orders list as **Exp dd Mon yyyy**
next to the orange badge.

**Important limitation:** `authorization_expires_at` is only populated by Shopify
when the store uses **Shopify Payments** as the payment gateway. Third-party gateways
(Stripe, Sagepay, PayPal, etc.) always return `null` for this field — this is a
Shopify API restriction, not a Cydekick bug. In those cases the badge shows
**Authorized** without an expiry date, which is the correct behaviour.

### How Shopify financial_status maps to Cydekick payment_status

| Shopify `financial_status` | Cydekick `payment_status` |
|---------------------------|--------------------------|
| `paid` | `paid` |
| `authorized` | `authorized` |
| `pending` | `unpaid` |
| `partially_paid` | `unpaid` |
| `refunded` | `unpaid` |
| `voided` | `unpaid` |
| anything else | `unpaid` |

This mapping lives in **one place only:**
`plugins/webkul/channels/src/Services/ShopifyOrderImporter.php`

Both the sync job and the webhook controller call that service, so any changes to the
mapping only need to be made there.

---

## Adding a New Payment Status

1. Add a new `case` to `PaymentStatus.php`
2. Add a label to `plugins/webkul/channel-orders/resources/lang/en/enums/payment-status.php`
3. Add a `getColor()` match arm
4. Update the `match()` in `ShopifyOrderImporter::createFromPayload()` to map the
   relevant Shopify `financial_status` value
5. Update the badge rendering in `OrderResource.php` — search for `$payColor` and
   `$payLabel`, there are three instances (mobile card view, desktop list view, and
   a second mobile view). Update all three.

---

## Files Summary

| File | Purpose |
|------|---------|
| `plugins/webkul/channel-orders/src/Enums/PaymentStatus.php` | Defines the enum cases, labels, and Filament colours |
| `plugins/webkul/channel-orders/src/Enums/OrderStatus.php` | Defines order status enum |
| `plugins/webkul/channel-orders/resources/lang/en/enums/payment-status.php` | Translation strings for payment status labels |
| `plugins/webkul/channel-orders/resources/lang/en/enums/order-status.php` | Translation strings for order status labels |
| `plugins/webkul/channels/src/Services/ShopifyOrderImporter.php` | Maps Shopify financial_status → Cydekick payment_status |
| `plugins/webkul/channel-orders/src/Filament/Resources/OrderResource.php` | Renders the badge in the list views (3 locations, search `$payColor`) |
| `plugins/webkul/channels/resources/views/filament/pages/order-sync.blade.php` | Renders the pill in the Order Sync channel view |