karrio-server-manager 2026.1__py3-none-any.whl → 2026.1.3__py3-none-any.whl

karrio/server/manager/serializers/__init__.py

@@ -8,18 +8,18 @@ from karrio.server.manager.serializers.parcel import (
     ParcelSerializer,
     can_mutate_parcel,
 )
-from karrio.server.manager.serializers.customs import (
-    CustomsSerializer,
-    can_mutate_customs,
-)
 from karrio.server.manager.serializers.commodity import (
     CommoditySerializer,
     can_mutate_commodity,
 )
+
+# Product is a proxy of Commodity - use the same serializer
+ProductSerializer = CommoditySerializer
 from karrio.server.manager.serializers.rate import RateSerializer
 from karrio.server.manager.serializers.tracking import (
     TrackingSerializer,
     TrackerUpdateData,
+    TrackerEventInjectRequest,
     update_shipment_tracker,
     can_mutate_tracker,
     update_tracker,
@@ -37,6 +37,7 @@ from karrio.server.manager.serializers.shipment import (
     can_mutate_shipment,
     buy_shipment_label,
     fetch_shipment_rates,
+    compute_estimated_delivery,
 )
 from karrio.server.manager.serializers.pickup import (
     PickupData,

karrio/server/manager/serializers/address.py

@@ -1,7 +1,10 @@
 from rest_framework import status
 
 from karrio.server.core.serializers import AddressData, ShipmentStatus
-from karrio.server.serializers import owned_model_serializer
+from karrio.server.serializers import (
+    owned_model_serializer,
+    process_dictionaries_mutations,
+)
 from karrio.server.core.exceptions import APIException
 from karrio.server.manager import models
 from karrio.server.core import gateway
@@ -34,8 +37,11 @@ class AddressSerializer(AddressData):
     def update(
         self, instance: models.Address, validated_data: dict, **kwargs
     ) -> models.Address:
+        # Handle dictionary mutations for meta field
+        data = process_dictionaries_mutations(["meta"], validated_data, instance)
         changes = []
-        for key, val in validated_data.items():
+
+        for key, val in data.items():
             if getattr(instance, key) != val:
                 changes.append(key)
                 setattr(instance, key, val)

karrio/server/manager/serializers/commodity.py

@@ -2,7 +2,10 @@ from rest_framework import status
 
 from karrio.server.core.exceptions import APIException
 from karrio.server.core.serializers import CommodityData, ShipmentStatus
-from karrio.server.serializers import owned_model_serializer
+from karrio.server.serializers import (
+    owned_model_serializer,
+    process_dictionaries_mutations,
+)
 import karrio.server.manager.models as models
 
 
@@ -16,14 +19,18 @@ class CommoditySerializer(CommodityData):
     def update(
         self, instance: models.Commodity, validated_data: dict, **kwargs
     ) -> models.Commodity:
+        # Handle dictionary mutations for metadata and meta fields
+        data = process_dictionaries_mutations(
+            ["metadata", "meta"], validated_data, instance
+        )
         changes = []
 
-        for key, val in validated_data.items():
+        for key, val in data.items():
             if getattr(instance, key) != val:
                 changes.append(key)
                 setattr(instance, key, val)
 
-        instance.save()
+        instance.save(update_fields=changes)
         return instance
 
 
@@ -43,7 +50,7 @@ def can_mutate_commodity(
             code="state_error",
         )
 
-    if delete and order and len(order.line_items.all()) == 1:
+    if delete and order and len(order.line_items or []) == 1:
         raise APIException(
             f"Operation not permitted. The related order needs at least one line_item.",
             status_code=status.HTTP_409_CONFLICT,

karrio/server/manager/serializers/document.py

@@ -5,6 +5,7 @@ import karrio.server.serializers as serialiazers
 import karrio.server.core.exceptions as exceptions
 import karrio.server.core.serializers as core
 import karrio.server.core.gateway as gateway
+from karrio.server.core.utils import create_carrier_snapshot, resolve_carrier
 import karrio.server.manager.models as models
 
 
@@ -17,20 +18,28 @@ class DocumentUploadSerializer(core.DocumentUploadData):
         **kwargs,
     ) -> models.DocumentUploadRecord:
         shipment = validated_data.get("shipment")
-        carrier = validated_data.get("carrier") or getattr(
-            shipment, "selected_rate_carrier", None
-        )
+        # Resolve carrier from validated_data or from shipment's carrier snapshot
+        carrier = validated_data.get("carrier")
+        if carrier is None and shipment:
+            carrier = resolve_carrier(getattr(shipment, "carrier", None) or {}, context)
+
         tracking_number = getattr(shipment, "tracking_number", None)
         reference = validated_data.get("reference") or tracking_number
 
         payload = core.DocumentUploadData(validated_data).data
-        options = ({
-            "origin_country_code": shipment.shipper.country_code,
-            "origin_postal_code": shipment.shipper.postal_code,
-            "destination_country_code": shipment.recipient.country_code,
-            "destination_postal_code": shipment.recipient.postal_code,
-            **(payload.get("options") or {})
-        } if shipment else payload.get("options"))
+        shipper = getattr(shipment, "shipper", None) or {}
+        recipient = getattr(shipment, "recipient", None) or {}
+        options = (
+            {
+                "origin_country_code": shipper.get("country_code"),
+                "origin_postal_code": shipper.get("postal_code"),
+                "destination_country_code": recipient.get("country_code"),
+                "destination_postal_code": recipient.get("postal_code"),
+                **(payload.get("options") or {}),
+            }
+            if shipment
+            else payload.get("options")
+        )
 
         response = gateway.Documents.upload(
             {
@@ -49,7 +58,7 @@ class DocumentUploadSerializer(core.DocumentUploadData):
             options=response.options,
             meta=response.meta,
             shipment=shipment,
-            upload_carrier=carrier,
+            carrier=create_carrier_snapshot(carrier),
             created_by=context.user,
         )
 
@@ -64,12 +73,15 @@ class DocumentUploadSerializer(core.DocumentUploadData):
     ) -> models.DocumentUploadRecord:
         changes = []
 
+        # Resolve carrier from instance.carrier snapshot
+        carrier = resolve_carrier(instance.carrier, context)
+
         response = gateway.Documents.upload(
             {
                 "reference": getattr(instance.shipment, "tracking_number", None),
                 **core.DocumentUploadData(validated_data).data,
             },
-            carrier=instance.upload_carrier,
+            carrier=carrier,
             context=context,
         )
 
@@ -86,9 +98,11 @@ class DocumentUploadSerializer(core.DocumentUploadData):
         return instance
 
 
-def can_upload_shipment_document(shipment: models.Shipment):
-    carrier = getattr(shipment, "selected_rate_carrier", None)
-    capabilities = getattr(carrier, "capabilities", [])
+def can_upload_shipment_document(shipment: models.Shipment, context=None):
+    # Resolve carrier from carrier snapshot
+    carrier_snapshot = getattr(shipment, "carrier", None) or {}
+    carrier = resolve_carrier(carrier_snapshot, context) if carrier_snapshot else None
+    capabilities = getattr(carrier, "capabilities", []) if carrier else []
 
     if shipment is None:
         raise exceptions.APIException(

karrio/server/manager/serializers/manifest.py

@@ -1,10 +1,12 @@
 import typing
+from django.db.models import Q
 
 import karrio.server.core.gateway as gateway
 import karrio.server.manager.models as models
 import karrio.server.core.serializers as core
 import karrio.server.serializers as serializers
 import karrio.server.manager.serializers as manager
+from karrio.server.core.utils import create_carrier_snapshot
 
 DEFAULT_CARRIER_FILTER: typing.Any = dict(active=True, capability="manifest")
 
@@ -17,16 +19,17 @@ class ManifestSerializer(core.ManifestData):
         data = validated_data.copy()
         shipment_ids = list(set(data.pop("shipment_ids")))
         carrier_name = data["carrier_name"]
-        carrier = gateway.Carriers.first(
+        carrier = gateway.Connections.first(
             context=context,
             carrier_name=carrier_name,
             **{"raise_not_found": True, **DEFAULT_CARRIER_FILTER},
         )
 
+        # Filter shipments by carrier_code in carrier JSON snapshot
         shipments = models.Shipment.access_by(context).filter(
             id__in=shipment_ids,
             manifest__isnull=True,
-            selected_rate_carrier__carrier_code=carrier_name,
+            carrier__carrier_code=carrier_name,
         )
         shipment_identifiers = [_.shipment_identifier for _ in shipments]
 
@@ -74,7 +77,7 @@ class ManifestSerializer(core.ManifestData):
                 **payload,
                 "address": address,
                 "created_by": context.user,
-                "manifest_carrier": carrier,
+                "carrier": create_carrier_snapshot(carrier),
                 "options": data.get("options", {}),
                 "test_mode": response.manifest.test_mode,
                 "manifest": response.manifest.doc.manifest,

karrio/server/manager/serializers/parcel.py

@@ -49,7 +49,8 @@ class ParcelSerializer(ParcelData):
     def update(
         self, instance: models.Parcel, validated_data: dict, **kwargs
     ) -> models.Parcel:
-        data = process_dictionaries_mutations(["options"], validated_data, instance)
+        # Handle dictionary mutations for options and meta fields
+        data = process_dictionaries_mutations(["options", "meta"], validated_data, instance)
         changes = []
 
         for key, val in data.items():
@@ -76,7 +77,9 @@ def can_mutate_parcel(
             code="state_error",
         )
 
-    if delete and len(shipment.parcels.all()) == 1:
+    # Use JSON field for parcel count check
+    parcels = shipment.parcels or []
+    if delete and len(parcels) == 1:
         raise APIException(
             f"Operation not permitted. The related shipment needs at least one parcel.",
             status_code=status.HTTP_409_CONFLICT,

karrio/server/manager/serializers/pickup.py

@@ -7,8 +7,9 @@ from karrio.server.serializers import (
     Context,
     PlainDictField,
 )
-from karrio.server.core.gateway import Pickups, Carriers
+from karrio.server.core.gateway import Pickups, Connections
 from karrio.server.core.datatypes import Confirmation
+from karrio.server.core.utils import create_carrier_snapshot, resolve_carrier
 from karrio.server.core.serializers import (
     Pickup,
     AddressData,
@@ -70,32 +71,47 @@ class PickupSerializer(PickupRequest):
         required=False, validators=[address_exists], help_text="The pickup address"
     )
     tracking_numbers = serializers.StringListField(
-        required=True,
+        required=False,
         validators=[shipment_exists],
-        help_text="The list of shipments to be picked up",
+        help_text="The list of shipments to be picked up (optional if parcels_count provided)",
+    )
+    parcels_count = serializers.IntegerField(
+        required=False,
+        allow_null=True,
+        min_value=1,
+        help_text="The number of parcels to be picked up (alternative to linking shipments)",
     )
     metadata = PlainDictField(
         required=False, default={}, help_text="User metadata for the pickup"
     )
 
     def __init__(self, instance: models.Pickup = None, **kwargs):
+        self._shipments: typing.List[models.Shipment] = []
+
         if "data" in kwargs:
             data = kwargs.get("data").copy()
-
-            self._shipments: typing.List[models.Shipment] = (
-                models.Shipment.objects.filter(
-                    tracking_number__in=data.get("tracking_numbers", [])
+            tracking_numbers = data.get("tracking_numbers", [])
+
+            # Only fetch shipments if tracking_numbers provided
+            if tracking_numbers:
+                self._shipments = list(
+                    models.Shipment.objects.filter(
+                        tracking_number__in=tracking_numbers
+                    )
                 )
-            )
 
+            # Address resolution logic
             if data.get("address") is None and instance is None:
+                # Try to get address from linked shipments
                 address = next(
-                    (AddressData(s.shipper).data for s in self._shipments), None
+                    (s.shipper for s in self._shipments if s.shipper), None
                 )
             elif data.get("address") is None and instance is not None:
-                address = AddressData(instance.address).data
-            elif data.get("address") is str:
-                address = models.Shipment.objects.get(pk=data.get("address"))
+                # Use existing instance address
+                address = instance.address
+            elif isinstance(data.get("address"), str):
+                # Legacy: look up address by ID
+                address = models.Address.objects.get(pk=data.get("address"))
             else:
                 address = data.get("address")
 
@@ -109,12 +125,29 @@ class PickupSerializer(PickupRequest):
     def validate(self, data):
         validated_data = super(PickupRequest, self).validate(data)
 
-        if (
-            len(validated_data.get("tracking_numbers", [])) > 1
-            and validated_data.get("address") is None
-        ):
+        tracking_numbers = validated_data.get("tracking_numbers", [])
+        parcels_count = validated_data.get("parcels_count")
+        address = validated_data.get("address")
+
+        # Must have at least one source of parcel info
+        if not tracking_numbers and not parcels_count:
+            raise serializers.ValidationError(
+                "At least one of tracking_numbers or parcels_count must be provided",
+                code="required"
+            )
+
+        # Address required for standalone pickups (no tracking_numbers)
+        if not tracking_numbers and not address:
+            raise serializers.ValidationError(
+                "address is required when not linking to shipments",
+                code="required"
+            )
+
+        # Existing validation for multi-shipment pickups
+        if len(tracking_numbers) > 1 and address is None:
             raise serializers.ValidationError(
-                "address must be specified for multi-shipments pickup", code="required"
+                "address must be specified for multi-shipments pickup",
+                code="required"
             )
 
         return validated_data
@@ -124,30 +157,60 @@ class PickupSerializer(PickupRequest):
 class PickupData(PickupSerializer):
     def create(self, validated_data: dict, context: Context, **kwargs) -> models.Pickup:
         carrier_filter = validated_data["carrier_filter"]
-        shipment_identifiers = [
-            _
-            for shipment in self._shipments
-            for _ in set(
-                [
-                    *(shipment.meta.get("shipment_identifiers") or []),
-                    shipment.shipment_identifier,
-                ]
+        parcels_count = validated_data.get("parcels_count")
+        pickup_type = validated_data.get("pickup_type", "one_time")
+        recurrence = validated_data.get("recurrence") or {}
+
+        # Extract shipment identifiers only if shipments linked
+        shipment_identifiers = []
+        billing_number = None
+
+        if self._shipments:
+            shipment_identifiers = [
+                _
+                for shipment in self._shipments
+                for _ in set(
+                    [
+                        *(shipment.meta.get("shipment_identifiers") or []),
+                        shipment.shipment_identifier,
+                    ]
+                )
+            ]
+            # Extract billing_number from first shipment's meta (if available)
+            billing_number = next(
+                (s.meta.get("billing_number") for s in self._shipments if s.meta.get("billing_number")),
+                None,
             )
-        ]
-        carrier = Carriers.first(
+
+        carrier = Connections.first(
             context=context,
             **{"raise_not_found": True, **DEFAULT_CARRIER_FILTER, **carrier_filter},
         )
-        request_data = PickupRequest(
-            {
-                **validated_data,
-                "parcels": sum([list(s.parcels.all()) for s in self._shipments], []),
-                "options": {
-                    "shipment_identifiers": shipment_identifiers,
-                    **(validated_data.get("options") or {}),
-                },
-            }
-        ).data
+
+        # Determine parcels source
+        if self._shipments:
+            # Mode 1: Parcels from linked shipments
+            parcels_list = sum([(s.parcels or []) for s in self._shipments], [])
+        elif parcels_count:
+            # Mode 2: Generate placeholder parcels from count
+            parcels_list = [{"id": f"parcel_{i+1}"} for i in range(parcels_count)]
+        else:
+            parcels_list = []
+
+        # Build request data directly (address is now a JSON dict)
+        # Exclude non-serializable fields from request data
+        excluded_keys = {"created_by", "carrier_filter", "tracking_numbers", "parcels_count", "recurrence"}
+        filtered_data = {k: v for k, v in validated_data.items() if k not in excluded_keys}
+
+        request_data = {
+            **filtered_data,
+            "parcels": parcels_list,
+            "options": {
+                **({"shipment_identifiers": shipment_identifiers} if shipment_identifiers else {}),
+                **({"billing_number": billing_number} if billing_number else {}),
+                **(validated_data.get("options") or {}),
+            },
+        }
 
         response = Pickups.schedule(payload=request_data, carrier=carrier)
         payload = {
@@ -155,18 +218,26 @@ class PickupData(PickupSerializer):
             for key, value in Pickup(response.pickup).data.items()
             if key in models.Pickup.DIRECT_PROPS
         }
-        address = save_one_to_one_data(
-            "address", AddressSerializer, payload=validated_data, context=context
-        )
+
+        # Use the address from validated_data directly (JSON field)
+        address_data = validated_data.get("address") or {}
+
+        # Build meta with pickup_type and recurrence (stored in meta per PRD)
+        meta_data = {
+            **(payload.get("meta") or {}),
+            "pickup_type": pickup_type,
+            **({"recurrence": recurrence} if recurrence else {}),
+        }
 
         pickup = models.Pickup.objects.create(
             **{
                 **payload,
-                "address": address,
-                "pickup_carrier": carrier,
+                "address": address_data,
+                "carrier": create_carrier_snapshot(carrier),
                 "created_by": context.user,
                 "test_mode": response.pickup.test_mode,
                 "confirmation_number": response.pickup.confirmation_number,
+                "meta": meta_data,
             }
         )
         pickup.shipments.set(self._shipments)
@@ -219,6 +290,22 @@ class PickupUpdateData(PickupSerializer):
         help_text="The list of shipments to be picked up",
     )
 
+    def validate(self, data):
+        """Override validation for update - existing pickups don't need parcel source validation."""
+        # Skip the parent's tracking_numbers/parcels_count validation for updates
+        # The pickup already exists with its parcels, we're just updating details
+        validated_data = serializers.Serializer.validate(self, data)
+
+        # Only validate multi-shipment address requirement if tracking_numbers provided
+        tracking_numbers = validated_data.get("tracking_numbers", [])
+        if len(tracking_numbers) > 1 and validated_data.get("address") is None:
+            raise serializers.ValidationError(
+                "address must be specified for multi-shipments pickup",
+                code="required"
+            )
+
+        return validated_data
+
     def update(
         self, instance: models.Pickup, validated_data: dict, context: dict, **kwargs
     ) -> models.Tracking:
@@ -233,36 +320,74 @@ class PickupUpdateData(PickupSerializer):
             )
         ]
 
-        request_data = PickupUpdateRequest(
-            {
-                **PickupUpdateRequest(instance).data,
-                **validated_data,
-                "address": AddressData(
-                    {**AddressData(instance.address).data, **validated_data["address"]}
-                ).data,
-                "options": {
-                    "shipment_identifiers": shipment_identifiers,
-                    **(instance.meta or {}),
-                    **(validated_data.get("options") or {}),
-                },
-            }
-        ).data
+        # Merge existing address with updates (address is now a JSON field)
+        existing_address = instance.address or {}
+        address_updates = validated_data.get("address") or {}
+        merged_address = {**existing_address, **address_updates}
+
+        # Extract pickup_type and recurrence for meta
+        pickup_type = validated_data.get("pickup_type") or (instance.meta or {}).get("pickup_type", "one_time")
+        recurrence = validated_data.get("recurrence") or (instance.meta or {}).get("recurrence")
 
-        Pickups.update(payload=request_data, carrier=instance.pickup_carrier)
+        # Build base data from instance fields directly (not via serializer)
+        # Convert date to string for serializer validation
+        pickup_date = (
+            str(instance.pickup_date) if instance.pickup_date else None
+        )
+        base_data = {
+            "pickup_date": pickup_date,
+            "address": existing_address,
+            "parcels": instance.parcels,
+            "confirmation_number": instance.confirmation_number,
+            "ready_time": instance.ready_time,
+            "closing_time": instance.closing_time,
+            "instruction": instance.instruction,
+            "package_location": instance.package_location,
+            "options": instance.options or {},
+            "pickup_type": pickup_type,
+        }
+
+        # Extract billing_number from first shipment's meta (if available)
+        billing_number = next(
+            (s.meta.get("billing_number") for s in self._shipments if s.meta.get("billing_number")),
+            None,
+        )
+
+        # Build request data directly (data comes from trusted sources)
+        request_data = {
+            **base_data,
+            **validated_data,
+            "address": merged_address,
+            "options": {
+                "shipment_identifiers": shipment_identifiers,
+                **({"billing_number": billing_number} if billing_number else {}),
+                **(instance.meta or {}),
+                **(validated_data.get("options") or {}),
+            },
+        }
+
+        # Resolve carrier from snapshot for API call
+        carrier = resolve_carrier(instance.carrier, context)
+        Pickups.update(payload=request_data, carrier=carrier)
 
         data = validated_data.copy()
         for key, val in data.items():
+            # Skip address and meta-stored fields - they need special handling
+            if key in ("address", "pickup_type", "recurrence"):
+                continue
             if key in models.Pickup.DIRECT_PROPS:
                 setattr(instance, key, val)
-                validated_data.pop(key)
 
-        save_one_to_one_data(
-            "address",
-            AddressSerializer,
-            instance,
-            payload=validated_data,
-            context=context,
-        )
+        # Always set the merged address (preserves existing fields while applying updates)
+        instance.address = merged_address
+
+        # Update meta with pickup_type and recurrence
+        existing_meta = instance.meta or {}
+        instance.meta = {
+            **existing_meta,
+            "pickup_type": pickup_type,
+            **({"recurrence": recurrence} if recurrence else {}),
+        }
 
         instance.save()
         return instance
@@ -274,12 +399,14 @@ class PickupCancelData(serializers.Serializer):
     )
 
     def update(
-        self, instance: models.Pickup, validated_data: dict, **kwargs
+        self, instance: models.Pickup, validated_data: dict, context: Context = None, **kwargs
     ) -> Confirmation:
         request = PickupCancelRequest(
             {**PickupCancelRequest(instance).data, **validated_data}
         )
-        Pickups.cancel(payload=request.data, carrier=instance.pickup_carrier)
+        # Resolve carrier from snapshot for API call
+        carrier = resolve_carrier(instance.carrier, context)
+        Pickups.cancel(payload=request.data, carrier=carrier)
         instance.delete()
 
         return instance