Change order custom status via api

src/backend/InvenTree/InvenTree/api_version.py

@@ -1,11 +1,14 @@
 """InvenTree API version information."""
 
 # InvenTree API version
-INVENTREE_API_VERSION = 497
+INVENTREE_API_VERSION = 498
 """Increment this API version number whenever there is a significant change to the API that any clients need to know about."""
 
 INVENTREE_API_TEXT = """
 
+v498 -> 2026-05-30 : https://github.com/inventree/InvenTree/pull/11982
+   - An order's "status_custom_key" can be updated via PATCH API endpoint
+
 v497 -> 2026-05-27 : https://github.com/inventree/InvenTree/pull/12019
     - Adds "location" field to StockCount API endpoint
 

src/backend/InvenTree/order/models.py

@@ -589,6 +589,21 @@ def order_address(self):
         """Return the Address associated with this order."""
         return self.address or self.company.primary_address
 
+    @property
+    def status_text(self):
+        """Return the text representation of the current status. This will consider any custom status."""
+        if self.get_custom_status() is not None:
+            from generic.states.custom import (
+                get_logical_value as get_custom_state_logical_value,
+            )
+
+            custom_status = get_custom_state_logical_value(
+                self.get_custom_status(), model=self._meta.model_name
+            )
+            return custom_status.label
+        else:
+            return self.status_class.label(self.get_status())
+
     @classmethod
     def get_status_class(cls):
         """Return the enumeration class which represents the 'status' field for this model."""
@@ -691,11 +706,6 @@ def __str__(self):
         help_text=_('Purchase order status'),
     )
 
-    @property
-    def status_text(self):
-        """Return the text representation of the status field."""
-        return PurchaseOrderStatus.text(self.status)
-
     supplier = models.ForeignKey(
         Company,
         on_delete=models.SET_NULL,
@@ -1431,11 +1441,6 @@ def company(self):
         help_text=_('Sales order status'),
     )
 
-    @property
-    def status_text(self) -> str:
-        """Return the text representation of the status field."""
-        return SalesOrderStatus.text(self.status)
-
     customer_reference = models.CharField(
         max_length=64,
         blank=True,

src/backend/InvenTree/order/serializers.py

@@ -119,11 +119,19 @@
     )
 
     # Human-readable status text (read-only)
-    status_text = serializers.CharField(source='get_status_display', read_only=True)
+    status_text = serializers.CharField(read_only=True)
 
     # status field cannot be set directly
     status = serializers.IntegerField(read_only=True, label=_('Order Status'))
 
+    # can be set directly, but must be valid for the current order status
+    status_custom_key = serializers.IntegerField(
+        label=_('Custom Status Key'),
+        help_text=_('Update order status to a custom value for this logical value'),
+        allow_null=True,
+        default=None,
+    )
+
     # Reference string is *required*
     reference = serializers.CharField(required=True)
 
@@ -194,6 +202,31 @@
         self.Meta.model.validate_reference_field(reference)
         return reference
 
+    def validate_status_custom_key(self, value):
+        """Validate the status_custom_key field.
+
+        Ensure the custom status key is valid for the logical order status.
+        """
+        if value is None:
+            return value
+
+        from generic.states.custom import get_logical_value
+
+        if not isinstance(value, int):
+            raise ValidationError(_('Custom status key must be an integer'))
+
+        try:
+            custom_status = get_logical_value(
+                value, model=self.Meta.model._meta.model_name
+            )
+        except:
+            raise ValidationError(_('Invalid custom status key'))
+
+        if custom_status.logical_key is not self.instance.status:
+            raise ValidationError(_('Invalid custom status key for this order status'))
+
+        return value
+
     @staticmethod
     def annotate_queryset(queryset):
         """Add extra information to the queryset."""

src/backend/InvenTree/order/test_api.py

@@ -6,6 +6,7 @@
 from datetime import date, datetime, timedelta
 from typing import Optional
 
+from django.contrib.contenttypes.models import ContentType
 from django.core.exceptions import ValidationError
 from django.db import connection
 from django.test.utils import CaptureQueriesContext
@@ -16,7 +17,7 @@
 from rest_framework import status
 
 from common.currency import currency_codes
-from common.models import InvenTreeSetting
+from common.models import InvenTreeCustomUserStateModel, InvenTreeSetting
 from common.settings import set_global_setting
 from company.models import Company, SupplierPart, SupplierPriceBreak
 from InvenTree.unit_test import InvenTreeAPITestCase
@@ -240,6 +241,77 @@ def test_po_detail(self):
         self.assertEqual(data['pk'], 1)
         self.assertEqual(data['description'], 'Ordering some screws')
 
+    def test_po_status_custom_key_options(self):
+        """Test that status_custom_key is exposed as writable in options."""
+        self.assignRole('purchase_order.add')
+
+        response = self.options(self.LIST_URL, expected_code=200)
+        post = response.data['actions']['POST']
+
+        self.assertIn('status_custom_key', post)
+        self.assertEqual(post['status_custom_key']['required'], False)
+        self.assertEqual(post['status_custom_key']['read_only'], False)
+
+    def test_po_status_custom_key_patch_valid(self):
+        """Test patching a valid custom status key for the current PO status."""
+        self.assignRole('purchase_order.change')
+
+        po = models.PurchaseOrder.objects.get(pk=1)
+        self.assertEqual(po.status, PurchaseOrderStatus.PENDING.value)
+
+        custom_status = InvenTreeCustomUserStateModel.objects.create(
+            key=901,
+            name='PO Pending Custom',
+            label='PO Pending Custom',
+            color='secondary',
+            logical_key=PurchaseOrderStatus.PENDING.value,
+            model=ContentType.objects.get_for_model(models.PurchaseOrder),
+            reference_status='PurchaseOrderStatus',
+        )
+
+        url = reverse('api-po-detail', kwargs={'pk': po.pk})
+        response = self.patch(
+            url, {'status_custom_key': custom_status.key}, expected_code=200
+        )
+
+        self.assertEqual(response.data['status'], PurchaseOrderStatus.PENDING.value)
+        self.assertEqual(response.data['status_custom_key'], custom_status.key)
+
+    def test_po_status_custom_key_patch_invalid(self):
+        """Test patching an invalid custom status key for a PO."""
+        self.assignRole('purchase_order.change')
+
+        po = models.PurchaseOrder.objects.get(pk=1)
+        url = reverse('api-po-detail', kwargs={'pk': po.pk})
+
+        response = self.patch(url, {'status_custom_key': 999999}, expected_code=400)
+
+        self.assertIn('status_custom_key', response.data)
+
+    def test_po_status_custom_key_patch_wrong_logical_status(self):
+        """Test patching a custom key mapped to a different logical status."""
+        self.assignRole('purchase_order.change')
+
+        po = models.PurchaseOrder.objects.get(pk=1)
+        self.assertEqual(po.status, PurchaseOrderStatus.PENDING.value)
+
+        custom_status = InvenTreeCustomUserStateModel.objects.create(
+            key=902,
+            name='PO Placed Custom',
+            label='PO Placed Custom',
+            color='secondary',
+            logical_key=PurchaseOrderStatus.PLACED.value,
+            model=ContentType.objects.get_for_model(models.PurchaseOrder),
+            reference_status='PurchaseOrderStatus',
+        )
+
+        url = reverse('api-po-detail', kwargs={'pk': po.pk})
+        response = self.patch(
+            url, {'status_custom_key': custom_status.key}, expected_code=400
+        )
+
+        self.assertIn('status_custom_key', response.data)
+
     def test_po_reference(self):
         """Test that a reference with a too big / small reference is handled correctly."""
         # get permissions