[change] Delivery address

CHANGELOG.md

@@ -11,9 +11,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - [#9604](https://github.com/inventree/InvenTree/pull/9604) - refactors user API endpoint to be less ambiguous
 - [#11893](https://github.com/inventree/InvenTree/pull/11893) bumps Node environment to version 24 LTS - this is only relevant if you build the frontend assets yourself
+- [#9303](https://github.com/inventree/InvenTree/pull/9303) - Purchase Orders, Return Orders, and Transfer Orders now require an *internal* address (one not linked to any company) for their `address` field. Previously these orders accepted any company-linked address. Any existing orders with a company-linked address set will fail validation on next save and must have their address field cleared or updated to an internal address.
 
 ### Added
 
+- [#9303](https://github.com/inventree/InvenTree/pull/9303) - adds support for *internal addresses* — addresses that belong to your own organisation rather than to an external company. Internal addresses are managed from the Admin Center and are used as delivery addresses on Purchase Orders, Return Orders, and Transfer Orders. A new `?internal=true/false` filter has been added to the address list API endpoint to distinguish internal from company-linked addresses. If no explicit address is set on an order, the primary internal address is used as a fallback.
+
+### Changed
+
 - [#12019](https://github.com/inventree/InvenTree/pull/12019) adds a "location" field to the StockCount API endpoint, allowing users to specify a location when performing a stock count. This field is optional, and if not provided, the stock count will be performed without changing the location of the stock item. If a location is provided, the stock item(s) will be moved to the specified location as part of the stock count operation.
 - [#12011](https://github.com/inventree/InvenTree/pull/12011) adds a "creation_date" field to the StockItem API endpoint, allowing users to track when each stock item was created. This field is read-only and is automatically set to the current date and time when a new stock item is created.
 - [#12000](https://github.com/inventree/InvenTree/pull/12000) adds support for auto-allocation of stock items against sales orders. This includes both backend and frontend changes, allowing users to trigger auto-allocation via the API or through the UI. The auto-allocation process will attempt to allocate available stock items to the sales order line items, based on the specified stock sorting and allocation rules.

docs/docs/concepts/company.md

@@ -56,7 +56,7 @@ A *contact* can be assigned to orders, (such as [purchase orders](../purchasing/
 ### Addresses
 
 A company can have multiple registered addresses for use with all types of orders.
-An address is broken down to internationally recognised elements that are designed to allow for formatting an address according to user needs.
+An address is broken down to internationally recognized elements that are designed to allow for formatting an address according to user needs.
 Addresses are composed differently across the world, and InvenTree reflects this by splitting addresses into components:
 
 | Field | Description |
@@ -97,10 +97,41 @@ Each company can have exactly one (1) primary address.
 This address is the default shown on the company profile, and the one that is automatically suggested when creating an order.
 Marking a new address as primary will remove the mark from the old primary address.
 
+!!! info "Effective order address"
+    When an order ([Sales Order](../sales/sales_order.md)) has no explicit address assigned, InvenTree uses the customer's primary address as the effective delivery address. This fallback ensures that reports and shipping labels always have an address to render, even if none was explicitly chosen on the order.
+
 #### Managing Addresses
 
 Addresses can be accessed by the <span class='badge inventree nav main'>{{ icon("map-2") }} Addresses</span> navigation tab, from the company detail page.
 
 Here, the addresses associated with the company are listed, and can be added, edited, or deleted.
 
 {{ image("concepts/edit_address.png", "Edit Address") }}
+
+### Internal Addresses
+
+In addition to addresses linked to external companies, InvenTree supports **internal addresses** — addresses that belong to your own organization rather than to any external company.
+
+Internal addresses are used when the delivery destination is one of your own sites rather than a customer or supplier location. Orders that use internal addresses include:
+
+| Order Type | Address Meaning |
+| --- | --- |
+| [Purchase Order](../purchasing/purchase_order.md) | Optional delivery destination for incoming goods |
+| [Return Order](../sales/return_order.md) | Optional location to which returned items are sent |
+| [Transfer Order](../stock/transfer_order.md) | Optional destination for an internal stock transfer |
+
+!!! info "Sales Orders use external addresses"
+    [Sales Orders](../sales/sales_order.md) are addressed to the *customer*, so they use addresses linked to the customer company, not internal addresses.
+
+#### Managing Internal Addresses
+
+Internal addresses are managed from the **Admin Center**, under the *Internal Addresses* panel. Only staff users can create, edit, or delete internal addresses.
+
+Each internal address uses the same fields as a company address (Title, Line 1, Line 2, Postal Code, City, Province, Country).
+
+#### Primary Internal Address
+
+One internal address can be marked as the **primary** address. This address is the default suggestion when assigning a delivery address to a new order. Marking a different address as primary will automatically remove the mark from the previous primary address.
+
+!!! info "Effective order address"
+    When a Purchase Order, Return Order, or Transfer Order has no explicit address assigned, InvenTree falls back to the primary internal address as the effective delivery address. This ensures that reports and shipping documents always have an address to render. If no internal address exists at all, the effective address is blank.

src/backend/InvenTree/company/api.py

@@ -105,16 +105,29 @@ class ContactDetail(RetrieveUpdateDestroyAPI):
     serializer_class = ContactSerializer
 
 
+class AddressFilter(FilterSet):
+    """Custom API filters for the Address list endpoint."""
+
+    class Meta:
+        """Metaclass options."""
+
+        model = Address
+        fields = ['company']
+
+    internal = rest_filters.BooleanFilter(
+        label=_('Internal Address'), field_name='company', lookup_expr='isnull'
+    )
+
+
 class AddressList(DataExportViewMixin, ListCreateDestroyAPIView):
     """API endpoint for list view of Address model."""
 
     queryset = Address.objects.all()
     serializer_class = AddressSerializer
+    filterset_class = AddressFilter
 
     filter_backends = SEARCH_ORDER_FILTER
 
-    filterset_fields = ['company']
-
     ordering_fields = ['title']
 
     ordering = 'title'

src/backend/InvenTree/company/migrations/0080_alter_address_company.py

@@ -0,0 +1,27 @@
+# Generated by Django 5.2.14 on 2026-05-31 03:39
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0079_auto_20260212_1054"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="address",
+            name="company",
+            field=models.ForeignKey(
+                blank=True,
+                help_text="Select company",
+                null=True,
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="addresses",
+                to="company.company",
+                verbose_name="Company",
+            ),
+        ),
+    ]

src/backend/InvenTree/company/models.py

@@ -332,7 +332,7 @@ class Address(InvenTree.models.InvenTreeModel):
     """An address represents a physical location where the company is located. It is possible for a company to have multiple locations.
 
     Attributes:
-        company: Company link for this address
+        company: Company link for this address (null if this is an *internal* address, not associated with a company)
         title: Human-readable name for the address
         primary: True if this is the company's primary address
         line1: First line of address
@@ -403,6 +403,8 @@ def get_api_url():
         on_delete=models.CASCADE,
         verbose_name=_('Company'),
         help_text=_('Select company'),
+        null=True,
+        blank=True,
     )
 
     title = models.CharField(

src/backend/InvenTree/order/migrations/0120_alter_purchaseorder_address_and_more.py

@@ -0,0 +1,67 @@
+# Generated by Django 5.2.14 on 2026-05-31 04:14
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0080_alter_address_company"),
+        ("order", "0119_transferorderlineitem_line_int"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="purchaseorder",
+            name="address",
+            field=models.ForeignKey(
+                blank=True,
+                help_text="Address for this order",
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="+",
+                to="company.address",
+                verbose_name="Address",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="returnorder",
+            name="address",
+            field=models.ForeignKey(
+                blank=True,
+                help_text="Address for this order",
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="+",
+                to="company.address",
+                verbose_name="Address",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="salesorder",
+            name="address",
+            field=models.ForeignKey(
+                blank=True,
+                help_text="Address for this order",
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="+",
+                to="company.address",
+                verbose_name="Address",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="transferorder",
+            name="address",
+            field=models.ForeignKey(
+                blank=True,
+                help_text="Address for this order",
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="+",
+                to="company.address",
+                verbose_name="Address",
+            ),
+        ),
+    ]

src/backend/InvenTree/order/models.py

@@ -311,6 +311,7 @@ class Order(
 
     - PurchaseOrder
     - SalesOrder
+    - ReturnOrder
 
     Attributes:
         reference: Unique order number / reference / code
@@ -328,6 +329,7 @@ class Order(
     REQUIRE_RESPONSIBLE_SETTING = None
     UNLOCK_SETTING = None
     IMPORT_ID_FIELDS = ['reference']
+    INTERNAL_ADDRESS: bool = True
 
     class Meta:
         """Metaclass options. Abstract ensures no database table is created."""
@@ -420,16 +422,29 @@ def clean(self):
                 'start_date': _('Start date must be before target date'),
             })
 
-        # Check that the referenced 'address' matches the correct 'company'
-        if (
-            hasattr(self, 'company')
-            and self.company
-            and self.address
-            and (self.address.company != self.company)
-        ):
-            raise ValidationError({
-                'address': _('Address does not match selected company')
-            })
+        self.clean_address()
+
+    def clean_address(self):
+        """Check that the address field is valid."""
+        if self.INTERNAL_ADDRESS:
+            # Check that the address is an 'internal' address (i.e. not linked to a company)
+            if self.address and self.address.company:
+                raise ValidationError({
+                    'address': _(
+                        'Address must be an internal address (not linked to a company)'
+                    )
+                })
+        else:
+            # Check that the referenced 'address' matches the correct 'company'
+            if (
+                hasattr(self, 'company')
+                and self.company
+                and self.address
+                and (self.address.company != self.company)
+            ):
+                raise ValidationError({
+                    'address': _('Address does not match selected company')
+                })
 
     def clean_line_item(self, line):
         """Clean a line item for this order.
@@ -572,7 +587,7 @@ def is_overdue(self):
         blank=True,
         null=True,
         verbose_name=_('Address'),
-        help_text=_('Company address for this order'),
+        help_text=_('Address for this order'),
         related_name='+',
     )
 
@@ -586,8 +601,18 @@ def company(self):
 
     @property
     def order_address(self):
-        """Return the Address associated with this order."""
-        return self.address or self.company.primary_address
+        """Return the Address associated with this order.
+
+        - If this is an 'internal' order (i.e. INTERNAL_ADDRESS = True), fall back to the primary internal address.
+        - Otherwise, we can fall back to the primary address of the associated company if no address is specified on the order itself.
+        """
+        if self.INTERNAL_ADDRESS:
+            return (
+                self.address
+                or Address.objects.filter(company=None, primary=True).first()
+            )
+        else:
+            return self.address or self.company.primary_address
 
     @classmethod
     def get_status_class(cls):
@@ -1337,6 +1362,9 @@ class SalesOrder(TotalPriceMixin, Order):
     STATUS_CLASS = SalesOrderStatus
     UNLOCK_SETTING = 'SALESORDER_EDIT_COMPLETED_ORDERS'
 
+    # SalesOrder address must point to the external company (customer)
+    INTERNAL_ADDRESS = False
+
     class Meta:
         """Model meta options."""