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

karrio/server/manager/migrations/0083_pickup_status.py

@@ -0,0 +1,23 @@
+# Generated by Django 5.2.10 on 2026-01-31
+# Adds status field to Pickup for lifecycle management
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("manager", "0082_shipment_fees"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="pickup",
+            name="status",
+            field=models.CharField(
+                db_index=True,
+                default="scheduled",
+                max_length=25,
+            ),
+        ),
+    ]

karrio/server/manager/models.py

@@ -472,6 +472,7 @@ class Pickup(core.OwnedEntity):
         "created_by",
         "metadata",
         "meta",
+        "status",
         "address",  # Embedded JSON field
         "carrier",  # Carrier snapshot
     ]
@@ -496,6 +497,11 @@ class Pickup(core.OwnedEntity):
     closing_time = models.CharField(max_length=5, blank=False)
     instruction = models.CharField(max_length=250, null=True, blank=True)
     package_location = models.CharField(max_length=250, null=True, blank=True)
+    status = models.CharField(
+        max_length=25,
+        default="scheduled",
+        db_index=True,
+    )
 
     # ─────────────────────────────────────────────────────────────────
     # EMBEDDED JSON FIELDS

karrio/server/manager/serializers/__init__.py

@@ -43,6 +43,7 @@ from karrio.server.manager.serializers.pickup import (
     PickupData,
     PickupUpdateData,
     PickupCancelData,
+    can_mutate_pickup,
 )
 from karrio.server.manager.serializers.document import (
     DocumentUploadSerializer,

karrio/server/manager/serializers/pickup.py

@@ -1,5 +1,7 @@
 import typing
 
+from rest_framework import status as http_status
+
 from karrio.server import serializers
 from karrio.server.serializers import (
     owned_model_serializer,
@@ -12,17 +14,54 @@ 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,
+    PickupStatus,
     AddressData,
     PickupRequest,
     PickupUpdateRequest,
     PickupCancelRequest,
 )
+import karrio.server.core.exceptions as exceptions
 from karrio.server.manager.serializers import AddressSerializer
 import karrio.server.manager.models as models
 
 DEFAULT_CARRIER_FILTER: typing.Any = dict(active=True, capability="pickup")
 
 
+def can_mutate_pickup(
+    pickup: models.Pickup,
+    update: bool = False,
+    cancel: bool = False,
+    payload: dict = None,
+):
+    # Allow metadata-only updates regardless of status
+    if update and [*(payload or {}).keys()] == ["metadata"]:
+        return
+
+    # Cannot update cancelled pickups
+    if update and pickup.status == PickupStatus.cancelled.value:
+        raise exceptions.APIException(
+            f"The pickup is '{pickup.status}' and cannot be updated",
+            code="state_error",
+            status_code=http_status.HTTP_409_CONFLICT,
+        )
+
+    # Cannot update or cancel closed pickups
+    if (update or cancel) and pickup.status == PickupStatus.closed.value:
+        raise exceptions.APIException(
+            f"The pickup is '{pickup.status}' and cannot be modified",
+            code="state_error",
+            status_code=http_status.HTTP_409_CONFLICT,
+        )
+
+    # Cannot update picked_up pickups (but can cancel)
+    if update and pickup.status == PickupStatus.picked_up.value:
+        raise exceptions.APIException(
+            f"The pickup is '{pickup.status}' and cannot be updated",
+            code="state_error",
+            status_code=http_status.HTTP_409_CONFLICT,
+        )
+
+
 def shipment_exists(value):
     validation = {
         key: models.Shipment.objects.filter(tracking_number=key) for key in value
@@ -34,11 +73,18 @@ def shipment_exists(value):
             f"Shipment with the tracking numbers: {invalids} not found", code="invalid"
         )
 
-    if any(val.first().shipment_pickup.exists() for val in validation.values()):
+    if any(
+        val.first().shipment_pickup.exclude(
+            status__in=["cancelled", "closed"]
+        ).exists()
+        for val in validation.values()
+    ):
         scheduled = [
             key
             for key, val in validation.items()
-            if val.first().shipment_pickup.exists() is True
+            if val.first().shipment_pickup.exclude(
+                status__in=["cancelled", "closed"]
+            ).exists()
         ]
         raise serializers.ValidationError(
             f"The following shipments {scheduled} are already scheduled for pickups",
@@ -156,11 +202,21 @@ class PickupSerializer(PickupRequest):
 @owned_model_serializer
 class PickupData(PickupSerializer):
     def create(self, validated_data: dict, context: Context, **kwargs) -> models.Pickup:
-        carrier_filter = validated_data["carrier_filter"]
+        carrier_filter = validated_data.get("carrier_filter") or {}
+        carrier_code = validated_data.get("carrier_code")
+        options = validated_data.get("options") or {}
+        connection_id = options.get("connection_id")
         parcels_count = validated_data.get("parcels_count")
         pickup_type = validated_data.get("pickup_type", "one_time")
         recurrence = validated_data.get("recurrence") or {}
 
+        # Build carrier filter from body fields when no URL-based filter provided
+        if not carrier_filter:
+            if carrier_code:
+                carrier_filter["carrier_name"] = carrier_code
+            if connection_id:
+                carrier_filter["carrier_id"] = connection_id
+
         # Extract shipment identifiers only if shipments linked
         shipment_identifiers = []
         billing_number = None
@@ -199,7 +255,7 @@ class PickupData(PickupSerializer):
 
         # 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"}
+        excluded_keys = {"created_by", "carrier_filter", "carrier_code", "tracking_numbers", "parcels_count", "recurrence"}
         filtered_data = {k: v for k, v in validated_data.items() if k not in excluded_keys}
 
         request_data = {
@@ -212,7 +268,7 @@ class PickupData(PickupSerializer):
             },
         }
 
-        response = Pickups.schedule(payload=request_data, carrier=carrier)
+        response = Pickups.schedule(payload=request_data, carrier=carrier, context=context)
         payload = {
             key: value
             for key, value in Pickup(response.pickup).data.items()
@@ -368,7 +424,7 @@ class PickupUpdateData(PickupSerializer):
 
         # Resolve carrier from snapshot for API call
         carrier = resolve_carrier(instance.carrier, context)
-        Pickups.update(payload=request_data, carrier=carrier)
+        Pickups.update(payload=request_data, carrier=carrier, context=context)
 
         data = validated_data.copy()
         for key, val in data.items():
@@ -406,7 +462,8 @@ class PickupCancelData(serializers.Serializer):
         )
         # Resolve carrier from snapshot for API call
         carrier = resolve_carrier(instance.carrier, context)
-        Pickups.cancel(payload=request.data, carrier=carrier)
-        instance.delete()
+        Pickups.cancel(payload=request.data, carrier=carrier, context=context)
+        instance.status = PickupStatus.cancelled.value
+        instance.save(update_fields=["status", "updated_at"])
 
         return instance

karrio/server/manager/tests/test_pickups.py

@@ -1,5 +1,4 @@
 import json
-import logging
 from unittest.mock import patch, ANY
 from django.urls import reverse
 from rest_framework import status
@@ -8,7 +7,6 @@ from karrio.server.manager.tests.test_shipments import TestShipmentFixture
 from karrio.server.core.utils import create_carrier_snapshot
 import karrio.server.manager.models as models
 
-
 class TestFixture(TestShipmentFixture):
     def setUp(self) -> None:
         super().setUp()
@@ -43,7 +41,6 @@ class TestFixture(TestShipmentFixture):
         self.shipment.carrier = create_carrier_snapshot(self.carrier)
         self.shipment.save()
 
-
 class TestPickupSchedule(TestFixture):
     def test_schedule_pickup(self):
         url = reverse(
@@ -73,6 +70,7 @@ class TestPickupSchedule(TestFixture):
 
             self.assertEqual(response.status_code, status.HTTP_201_CREATED)
             self.assertEqual(response_data["confirmation_number"], "27241")
+            self.assertEqual(response_data["status"], "scheduled")
 
     def test_schedule_pickup_validation_no_source(self):
         """Test that validation fails when neither tracking_numbers nor parcels_count is provided."""
@@ -162,7 +160,6 @@ class TestPickupSchedule(TestFixture):
             self.assertEqual(response_data["recurrence"]["frequency"], "weekly")
             self.assertIn("monday", response_data["recurrence"]["days_of_week"])
 
-
 class TestPickupDetails(TestFixture):
     def setUp(self) -> None:
         super().setUp()
@@ -209,6 +206,372 @@ class TestPickupDetails(TestFixture):
             self.assertEqual(response.status_code, status.HTTP_200_OK)
             self.assertDictEqual(response_data, PICKUP_CANCEL_RESPONSE)
 
+class TestPickupStatusLifecycle(TestFixture):
+    """Tests for pickup status lifecycle transitions."""
+
+    def setUp(self) -> None:
+        super().setUp()
+        self.pickup: models.Pickup = models.Pickup.objects.create(
+            address=self.address_data,
+            carrier=create_carrier_snapshot(self.carrier),
+            created_by=self.user,
+            test_mode=True,
+            pickup_date="2020-10-25",
+            ready_time="13:00",
+            closing_time="17:00",
+            instruction="Should not be folded",
+            package_location="At the main entrance hall",
+            confirmation_number="00110215",
+            pickup_charge={"name": "Pickup fees", "amount": 0.0, "currency": "CAD"},
+        )
+        self.pickup.shipments.set([self.shipment])
+
+    def test_pickup_created_with_scheduled_status(self):
+        """New pickups should default to 'scheduled' status."""
+        self.assertEqual(self.pickup.status, "scheduled")
+
+    def test_cancel_sets_cancelled_status(self):
+        """Cancelling a pickup sets status to 'cancelled' instead of deleting."""
+        url = reverse(
+            "karrio.server.manager:shipment-pickup-cancel",
+            kwargs=dict(pk=self.pickup.pk),
+        )
+
+        with patch("karrio.server.core.gateway.utils.identity") as mock:
+            mock.return_value = CANCEL_RETURNED_VALUE
+            response = self.client.post(url, {})
+            response_data = json.loads(response.content)
+
+            self.assertEqual(response.status_code, status.HTTP_200_OK)
+            self.assertEqual(response_data["status"], "cancelled")
+
+            # Pickup should still exist in the database
+            self.pickup.refresh_from_db()
+            self.assertEqual(self.pickup.status, "cancelled")
+
+    def test_cancelled_pickup_still_exists(self):
+        """Cancelled pickups are not deleted from the database."""
+        url = reverse(
+            "karrio.server.manager:shipment-pickup-cancel",
+            kwargs=dict(pk=self.pickup.pk),
+        )
+
+        with patch("karrio.server.core.gateway.utils.identity") as mock:
+            mock.return_value = CANCEL_RETURNED_VALUE
+            self.client.post(url, {})
+
+        # Pickup should still be queryable
+        pickup = models.Pickup.objects.get(pk=self.pickup.pk)
+        self.assertEqual(pickup.status, "cancelled")
+
+    def test_schedule_creates_with_scheduled_status(self):
+        """Scheduling a pickup via API creates it with 'scheduled' status."""
+        # Free the shipment from the existing pickup so it can be re-scheduled
+        self.pickup.shipments.clear()
+
+        url = reverse(
+            "karrio.server.manager:shipment-pickup-request",
+            kwargs=dict(carrier_name="canadapost"),
+        )
+
+        with patch("karrio.server.core.gateway.utils.identity") as mock:
+            mock.return_value = SCHEDULE_RETURNED_VALUE
+            response = self.client.post(f"{url}", PICKUP_DATA)
+            response_data = json.loads(response.content)
+
+            self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+            self.assertEqual(response_data["status"], "scheduled")
+
+class TestPickupStatusFilter(TestFixture):
+    """Tests for pickup status filtering."""
+
+    def setUp(self) -> None:
+        super().setUp()
+        # Create pickups with different statuses
+        self.scheduled_pickup = models.Pickup.objects.create(
+            address=self.address_data,
+            carrier=create_carrier_snapshot(self.carrier),
+            created_by=self.user,
+            test_mode=True,
+            pickup_date="2020-10-25",
+            ready_time="13:00",
+            closing_time="17:00",
+            confirmation_number="SCH001",
+            status="scheduled",
+        )
+        self.cancelled_pickup = models.Pickup.objects.create(
+            address=self.address_data,
+            carrier=create_carrier_snapshot(self.carrier),
+            created_by=self.user,
+            test_mode=True,
+            pickup_date="2020-10-26",
+            ready_time="13:00",
+            closing_time="17:00",
+            confirmation_number="CAN001",
+            status="cancelled",
+        )
+        self.closed_pickup = models.Pickup.objects.create(
+            address=self.address_data,
+            carrier=create_carrier_snapshot(self.carrier),
+            created_by=self.user,
+            test_mode=True,
+            pickup_date="2020-10-27",
+            ready_time="13:00",
+            closing_time="17:00",
+            confirmation_number="CLO001",
+            status="closed",
+        )
+
+    def test_filter_by_scheduled_status(self):
+        url = reverse("karrio.server.manager:shipment-pickup-list")
+
+        response = self.client.get(f"{url}?status=scheduled")
+        response_data = json.loads(response.content)
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        confirmation_numbers = [r["confirmation_number"] for r in response_data["results"]]
+        self.assertIn("SCH001", confirmation_numbers)
+        self.assertNotIn("CAN001", confirmation_numbers)
+        self.assertNotIn("CLO001", confirmation_numbers)
+
+    def test_filter_by_cancelled_status(self):
+        url = reverse("karrio.server.manager:shipment-pickup-list")
+
+        response = self.client.get(f"{url}?status=cancelled")
+        response_data = json.loads(response.content)
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        confirmation_numbers = [r["confirmation_number"] for r in response_data["results"]]
+        self.assertIn("CAN001", confirmation_numbers)
+        self.assertNotIn("SCH001", confirmation_numbers)
+
+    def test_filter_by_multiple_statuses(self):
+        url = reverse("karrio.server.manager:shipment-pickup-list")
+
+        response = self.client.get(f"{url}?status=scheduled&status=closed")
+        response_data = json.loads(response.content)
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        confirmation_numbers = [r["confirmation_number"] for r in response_data["results"]]
+        self.assertIn("SCH001", confirmation_numbers)
+        self.assertIn("CLO001", confirmation_numbers)
+        self.assertNotIn("CAN001", confirmation_numbers)
+
+class TestPickupGuardrails(TestFixture):
+    """Tests for pickup status guardrails preventing invalid mutations."""
+
+    def setUp(self) -> None:
+        super().setUp()
+        self.pickup: models.Pickup = models.Pickup.objects.create(
+            address=self.address_data,
+            carrier=create_carrier_snapshot(self.carrier),
+            created_by=self.user,
+            test_mode=True,
+            pickup_date="2020-10-25",
+            ready_time="13:00",
+            closing_time="17:00",
+            instruction="Should not be folded",
+            package_location="At the main entrance hall",
+            confirmation_number="00110215",
+            pickup_charge={"name": "Pickup fees", "amount": 0.0, "currency": "CAD"},
+        )
+        self.pickup.shipments.set([self.shipment])
+
+    def test_update_cancelled_pickup_returns_409(self):
+        """Cannot update a cancelled pickup."""
+        self.pickup.status = "cancelled"
+        self.pickup.save(update_fields=["status"])
+
+        url = reverse(
+            "karrio.server.manager:shipment-pickup-details",
+            kwargs=dict(pk=self.pickup.pk),
+        )
+
+        response = self.client.post(url, PICKUP_UPDATE_DATA)
+
+        self.assertEqual(response.status_code, status.HTTP_409_CONFLICT)
+
+    def test_update_closed_pickup_returns_409(self):
+        """Cannot update a closed pickup."""
+        self.pickup.status = "closed"
+        self.pickup.save(update_fields=["status"])
+
+        url = reverse(
+            "karrio.server.manager:shipment-pickup-details",
+            kwargs=dict(pk=self.pickup.pk),
+        )
+
+        response = self.client.post(url, PICKUP_UPDATE_DATA)
+
+        self.assertEqual(response.status_code, status.HTTP_409_CONFLICT)
+
+    def test_cancel_closed_pickup_returns_409(self):
+        """Cannot cancel a closed pickup."""
+        self.pickup.status = "closed"
+        self.pickup.save(update_fields=["status"])
+
+        url = reverse(
+            "karrio.server.manager:shipment-pickup-cancel",
+            kwargs=dict(pk=self.pickup.pk),
+        )
+
+        response = self.client.post(url, {})
+
+        self.assertEqual(response.status_code, status.HTTP_409_CONFLICT)
+
+    def test_recancel_returns_409(self):
+        """Re-cancelling an already cancelled pickup returns 409."""
+        self.pickup.status = "cancelled"
+        self.pickup.save(update_fields=["status"])
+
+        url = reverse(
+            "karrio.server.manager:shipment-pickup-cancel",
+            kwargs=dict(pk=self.pickup.pk),
+        )
+
+        response = self.client.post(url, {})
+
+        self.assertEqual(response.status_code, status.HTTP_409_CONFLICT)
+
+    def test_update_picked_up_pickup_returns_409(self):
+        """Cannot update a picked_up pickup."""
+        self.pickup.status = "picked_up"
+        self.pickup.save(update_fields=["status"])
+
+        url = reverse(
+            "karrio.server.manager:shipment-pickup-details",
+            kwargs=dict(pk=self.pickup.pk),
+        )
+
+        response = self.client.post(url, PICKUP_UPDATE_DATA)
+
+        self.assertEqual(response.status_code, status.HTTP_409_CONFLICT)
+
+    def test_cancel_picked_up_pickup_allowed(self):
+        """Can cancel a picked_up pickup (but not update it)."""
+        self.pickup.status = "picked_up"
+        self.pickup.save(update_fields=["status"])
+
+        url = reverse(
+            "karrio.server.manager:shipment-pickup-cancel",
+            kwargs=dict(pk=self.pickup.pk),
+        )
+
+        with patch("karrio.server.core.gateway.utils.identity") as mock:
+            mock.return_value = CANCEL_RETURNED_VALUE
+            response = self.client.post(url, {})
+
+            self.assertEqual(response.status_code, status.HTTP_200_OK)
+
+    def test_metadata_update_allowed_on_cancelled(self):
+        """Metadata-only updates are allowed regardless of status."""
+        self.pickup.status = "cancelled"
+        self.pickup.save(update_fields=["status"])
+
+        url = reverse(
+            "karrio.server.manager:shipment-pickup-details",
+            kwargs=dict(pk=self.pickup.pk),
+        )
+
+        with patch("karrio.server.core.gateway.utils.identity") as mock:
+            mock.return_value = UPDATE_RETURNED_VALUE
+            response = self.client.post(url, {"metadata": {"note": "important"}})
+
+            # Metadata-only updates bypass the guard
+            self.assertEqual(response.status_code, status.HTTP_200_OK)
+
+class TestPickupScheduleNewAPI(TestFixture):
+    """Tests for the new POST /v1/pickups endpoint with carrier_code in body."""
+
+    def test_schedule_pickup_with_carrier_code(self):
+        url = reverse("karrio.server.manager:shipment-pickup-list")
+
+        with patch("karrio.server.core.gateway.utils.identity") as mock:
+            mock.return_value = SCHEDULE_RETURNED_VALUE
+            response = self.client.post(f"{url}", PICKUP_DATA_NEW_API)
+            response_data = json.loads(response.content)
+
+            self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+            self.assertDictEqual(response_data, PICKUP_RESPONSE)
+
+    def test_schedule_pickup_with_connection_id(self):
+        url = reverse("karrio.server.manager:shipment-pickup-list")
+
+        with patch("karrio.server.core.gateway.utils.identity") as mock:
+            mock.return_value = SCHEDULE_RETURNED_VALUE
+            response = self.client.post(f"{url}", PICKUP_DATA_WITH_CONNECTION_ID)
+            response_data = json.loads(response.content)
+
+            self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+            self.assertEqual(response_data["confirmation_number"], "27241")
+            self.assertEqual(response_data["carrier_name"], "canadapost")
+            self.assertEqual(response_data["carrier_id"], "canadapost")
+
+    def test_schedule_pickup_standalone_with_carrier_code(self):
+        url = reverse("karrio.server.manager:shipment-pickup-list")
+
+        with patch("karrio.server.core.gateway.utils.identity") as mock:
+            mock.return_value = SCHEDULE_RETURNED_VALUE
+            response = self.client.post(f"{url}", PICKUP_DATA_NEW_API_STANDALONE)
+            response_data = json.loads(response.content)
+
+            self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+            self.assertEqual(response_data["confirmation_number"], "27241")
+
+    def test_schedule_pickup_validation_no_source_new_api(self):
+        url = reverse("karrio.server.manager:shipment-pickup-list")
+        data = {
+            "carrier_code": "canadapost",
+            "pickup_date": "2020-10-25",
+            "ready_time": "13:00",
+            "closing_time": "17:00",
+            "address": {
+                "address_line1": "125 Church St",
+                "person_name": "John Doe",
+                "city": "Moncton",
+                "country_code": "CA",
+                "postal_code": "E1C4Z8",
+            },
+        }
+
+        response = self.client.post(f"{url}", data)
+
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        response_data = json.loads(response.content)
+        self.assertIn("errors", response_data)
+
+class TestLegacyEndpointDeprecation(TestFixture):
+    """Tests for the legacy endpoint deprecation headers."""
+
+    def test_legacy_endpoint_returns_deprecation_headers(self):
+        url = reverse(
+            "karrio.server.manager:shipment-pickup-request",
+            kwargs=dict(carrier_name="canadapost"),
+        )
+
+        with patch("karrio.server.core.gateway.utils.identity") as mock:
+            mock.return_value = SCHEDULE_RETURNED_VALUE
+            response = self.client.post(f"{url}", PICKUP_DATA)
+
+            self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+            self.assertEqual(response["Deprecation"], "true")
+            self.assertIn("successor-version", response["Link"])
+            self.assertIn("/v1/pickups", response["Link"])
+
+    def test_legacy_endpoint_still_creates_pickup(self):
+        url = reverse(
+            "karrio.server.manager:shipment-pickup-request",
+            kwargs=dict(carrier_name="canadapost"),
+        )
+
+        with patch("karrio.server.core.gateway.utils.identity") as mock:
+            mock.return_value = SCHEDULE_RETURNED_VALUE
+            response = self.client.post(f"{url}", PICKUP_DATA)
+            response_data = json.loads(response.content)
+
+            self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+            self.assertEqual(response_data["confirmation_number"], "27241")
+            self.assertEqual(response_data["carrier_name"], "canadapost")
 
 PICKUP_DATA = {
     "pickup_date": "2020-10-25",
@@ -357,7 +720,6 @@ PICKUP_UPDATE_DATA = {
     "address": {"person_name": "Janet Jackson"},
 }
 
-
 SCHEDULE_RETURNED_VALUE = [
     PickupDetails(
         carrier_id="canadapost",
@@ -393,13 +755,14 @@ CANCEL_RETURNED_VALUE = [
     [],
 ]
 
-
 PICKUP_RESPONSE = {
     "id": ANY,
     "object_type": "pickup",
     "carrier_name": "canadapost",
     "carrier_id": "canadapost",
+    "carrier_code": "canadapost",
     "confirmation_number": "27241",
+    "status": "scheduled",
     "pickup_date": "2020-10-25",
     "pickup_charge": {
         "name": "Pickup fees",
@@ -468,7 +831,9 @@ PICKUP_UPDATE_RESPONSE = {
     "object_type": "pickup",
     "carrier_name": "canadapost",
     "carrier_id": "canadapost",
+    "carrier_code": "canadapost",
     "confirmation_number": "00110215",
+    "status": "scheduled",
     "pickup_date": "2020-10-25",
     "pickup_charge": {
         "name": "Pickup fees",
@@ -533,22 +898,24 @@ PICKUP_UPDATE_RESPONSE = {
 }
 
 PICKUP_CANCEL_RESPONSE = {
-    "id": None,  # Deleted pickup has no id
+    "id": ANY,
     "object_type": "pickup",
     "carrier_name": "canadapost",
     "carrier_id": "canadapost",
+    "carrier_code": "canadapost",
     "confirmation_number": "00110215",
+    "status": "cancelled",
     "pickup_date": "2020-10-25",
     "pickup_charge": {
         "name": "Pickup fees",
         "amount": 0.0,
         "currency": "CAD",
-        "id": None,
+        "id": ANY,
     },
     "ready_time": "13:00",
     "closing_time": "17:00",
     "address": {
-        "id": "adr_001122334455",  # JSON address retains its id
+        "id": "adr_001122334455",
         "postal_code": "E1C4Z8",
         "city": "Moncton",
         "federal_tax_id": None,
@@ -568,7 +935,28 @@ PICKUP_CANCEL_RESPONSE = {
         "validation": None,
         "meta": {},
     },
-    "parcels": [],  # Deleted pickup has no parcels
+    "parcels": [
+        {
+            "id": ANY,
+            "object_type": "parcel",
+            "weight": 1.0,
+            "width": None,
+            "height": None,
+            "length": None,
+            "packaging_type": None,
+            "package_preset": "canadapost_corrugated_small_box",
+            "description": None,
+            "content": None,
+            "is_document": False,
+            "items": [],
+            "weight_unit": "KG",
+            "dimension_unit": None,
+            "freight_class": None,
+            "reference_number": ANY,
+            "options": {},
+            "meta": {},
+        }
+    ],
     "parcels_count": None,
     "instruction": "Should not be folded",
     "package_location": "At the main entrance hall",
@@ -579,3 +967,82 @@ PICKUP_CANCEL_RESPONSE = {
     "test_mode": True,
     "meta": ANY,
 }
+
+# ─────────────────────────────────────────────────────────────────
+# NEW API TEST DATA (POST /v1/pickups/schedule with carrier_code)
+# ─────────────────────────────────────────────────────────────────
+
+PICKUP_DATA_NEW_API = {
+    "carrier_code": "canadapost",
+    "pickup_date": "2020-10-25",
+    "ready_time": "13:00",
+    "closing_time": "17:00",
+    "instruction": "Should not be folded",
+    "package_location": "At the main entrance hall",
+    "address": {
+        "id": "adr_aabbccddeeff",
+        "address_line1": "125 Church St",
+        "person_name": "John Doe",
+        "company_name": "A corp.",
+        "phone_number": "514 000 0000",
+        "city": "Moncton",
+        "country_code": "CA",
+        "postal_code": "E1C4Z8",
+        "residential": False,
+        "state_code": "NB",
+        "email": "john@a.com",
+        "validate_location": False,
+        "validation": None,
+    },
+    "tracking_numbers": ["123456789012"],
+}
+
+PICKUP_DATA_WITH_CONNECTION_ID = {
+    "carrier_code": "canadapost",
+    "pickup_date": "2020-10-25",
+    "ready_time": "13:00",
+    "closing_time": "17:00",
+    "instruction": "Should not be folded",
+    "package_location": "At the main entrance hall",
+    "address": {
+        "id": "adr_aabbccddeeff",
+        "address_line1": "125 Church St",
+        "person_name": "John Doe",
+        "company_name": "A corp.",
+        "phone_number": "514 000 0000",
+        "city": "Moncton",
+        "country_code": "CA",
+        "postal_code": "E1C4Z8",
+        "residential": False,
+        "state_code": "NB",
+        "email": "john@a.com",
+        "validate_location": False,
+        "validation": None,
+    },
+    "tracking_numbers": ["123456789012"],
+    "options": {
+        "connection_id": "canadapost",
+    },
+}
+
+PICKUP_DATA_NEW_API_STANDALONE = {
+    "carrier_code": "canadapost",
+    "pickup_date": "2020-10-25",
+    "ready_time": "13:00",
+    "closing_time": "17:00",
+    "instruction": "Handle with care",
+    "package_location": "Front desk",
+    "address": {
+        "address_line1": "125 Church St",
+        "person_name": "John Doe",
+        "company_name": "A corp.",
+        "phone_number": "514 000 0000",
+        "city": "Moncton",
+        "country_code": "CA",
+        "postal_code": "E1C4Z8",
+        "residential": False,
+        "state_code": "NB",
+        "email": "john@a.com",
+    },
+    "parcels_count": 3,
+}

karrio/server/manager/views/pickups.py

@@ -9,6 +9,7 @@ from karrio.server.core.logging import logger
 from karrio.server.core.views.api import GenericAPIView, APIView
 from karrio.server.core.filters import PickupFilters
 from karrio.server.manager.router import router
+from karrio.server.core.serializers import PickupStatus
 from karrio.server.manager.serializers import (
     PaginatedResult,
     Pickup,
@@ -17,6 +18,7 @@ from karrio.server.manager.serializers import (
     PickupData,
     PickupUpdateData,
     PickupCancelData,
+    can_mutate_pickup,
 )
 import karrio.server.manager.models as models
 import karrio.server.openapi as openapi
@@ -33,6 +35,7 @@ class PickupList(GenericAPIView):
     filterset_class = PickupFilters
     serializer_class = Pickups
     model = models.Pickup
+    throttle_scope = "carrier_request"
 
     @openapi.extend_schema(
         tags=["Pickups"],
@@ -54,6 +57,34 @@ class PickupList(GenericAPIView):
         response = self.paginate_queryset(Pickup(pickups, many=True).data)
         return self.get_paginated_response(response)
 
+    @openapi.extend_schema(
+        tags=["Pickups"],
+        operation_id=f"{ENDPOINT_ID}create",
+        extensions={"x-operationId": "createPickup"},
+        summary="Schedule a pickup",
+        responses={
+            201: Pickup(),
+            400: ErrorResponse(),
+            424: ErrorMessages(),
+            500: ErrorResponse(),
+        },
+        request=PickupData(),
+    )
+    def post(self, request: Request):
+        """
+        Schedule a pickup for one or many shipments with labels already purchased.
+
+        The carrier is identified by `carrier_code` in the request body.
+        Use `options.connection_id` to target a specific carrier connection.
+        """
+        pickup = (
+            PickupData.map(data=request.data, context=request)
+            .save()
+            .instance
+        )
+
+        return Response(Pickup(pickup).data, status=status.HTTP_201_CREATED)
+
 
 class PickupRequest(APIView):
     throttle_scope = "carrier_request"
@@ -62,7 +93,8 @@ class PickupRequest(APIView):
         tags=["Pickups"],
         operation_id=f"{ENDPOINT_ID}schedule",
         extensions={"x-operationId": "schedulePickup"},
-        summary="Schedule a pickup",
+        summary="Schedule a pickup (deprecated)",
+        deprecated=True,
         responses={
             201: Pickup(),
             400: ErrorResponse(),
@@ -74,6 +106,8 @@ class PickupRequest(APIView):
     def post(self, request: Request, carrier_name: str):
         """
         Schedule a pickup for one or many shipments with labels already purchased.
+
+        **Deprecated**: Use `POST /v1/pickups` with `carrier_code` in the request body instead.
         """
         carrier_filter = {
             "carrier_name": carrier_name,
@@ -85,7 +119,10 @@ class PickupRequest(APIView):
             .instance
         )
 
-        return Response(Pickup(pickup).data, status=status.HTTP_201_CREATED)
+        response = Response(Pickup(pickup).data, status=status.HTTP_201_CREATED)
+        response["Deprecation"] = "true"
+        response["Link"] = '</v1/pickups>; rel="successor-version"'
+        return response
 
 
 class PickupDetails(APIView):
@@ -126,6 +163,15 @@ class PickupDetails(APIView):
         Modify a pickup for one or many shipments with labels already purchased.
         """
         pickup = models.Pickup.access_by(request).get(pk=pk)
+        can_mutate_pickup(pickup, update=True, payload=request.data)
+
+        # Metadata-only updates skip the carrier API call
+        if list((request.data or {}).keys()) == ["metadata"]:
+            existing = pickup.metadata or {}
+            pickup.metadata = {**existing, **(request.data["metadata"] or {})}
+            pickup.save(update_fields=["metadata", "updated_at"])
+            return Response(Pickup(pickup).data, status=status.HTTP_200_OK)
+
         instance = (
             PickupUpdateData.map(pickup, data=request.data, context=request)
             .save()
@@ -157,6 +203,11 @@ class PickupCancel(APIView):
         """
         pickup = models.Pickup.access_by(request).get(pk=pk)
 
+        # Idempotent re-cancel: return 409 if already cancelled
+        if pickup.status == PickupStatus.cancelled.value:
+            return Response(Pickup(pickup).data, status=status.HTTP_409_CONFLICT)
+
+        can_mutate_pickup(pickup, cancel=True)
         update = PickupCancelData.map(pickup, data=request.data).save().instance
 
         return Response(Pickup(update).data)
@@ -164,7 +215,11 @@ class PickupCancel(APIView):
 
 router.urls.append(path("pickups", PickupList.as_view(), name="shipment-pickup-list"))
 router.urls.append(
-    path("pickups/<str:pk>", PickupDetails.as_view(), name="shipment-pickup-details")
+    path(
+        "pickups/<str:carrier_name>/schedule",
+        PickupRequest.as_view(),
+        name="shipment-pickup-request",
+    )
 )
 router.urls.append(
     path(
@@ -172,9 +227,5 @@ router.urls.append(
     )
 )
 router.urls.append(
-    path(
-        "pickups/<str:carrier_name>/schedule",
-        PickupRequest.as_view(),
-        name="shipment-pickup-request",
-    )
+    path("pickups/<str:pk>", PickupDetails.as_view(), name="shipment-pickup-details")
 )

{karrio_server_manager-2026.1.3.dist-info → karrio_server_manager-2026.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karrio_server_manager
-Version: 2026.1.3
+Version: 2026.1.5
 Summary: Multi-carrier shipping API Shipments manager module
 Author-email: karrio <hello@karrio.io>
 License-Expression: LGPL-3.0

{karrio_server_manager-2026.1.3.dist-info → karrio_server_manager-2026.1.5.dist-info}/RECORD

@@ -1,7 +1,7 @@
 karrio/server/manager/__init__.py,sha256=lDTMs_O6mQl0DEI2_TniT24TDJbjnkla-5QpnwfYlxs,64
 karrio/server/manager/admin.py,sha256=QOl5e2m3ekU5aj0yj9Uq4nRQrNMB_FfqNae6RyIxkC0,35
 karrio/server/manager/apps.py,sha256=WHTQ1t79uDZTbinRzvNg1NjtFwnwEvg0tP_ChrtTRwI,364
-karrio/server/manager/models.py,sha256=M0VZOTMvy1r_mw5bl2zvnWUw9a0g0KsS3X9bWFLN-tc,42323
+karrio/server/manager/models.py,sha256=FIrbDtHKXPpYu-wO9T4xKC3cohe310vG-EorAyq_qWQ,42453
 karrio/server/manager/router.py,sha256=IBUR7rfBkdEHQzWxYOPcVSM8NBp3fte9G6Q5BVTUNNw,95
 karrio/server/manager/signals.py,sha256=3ZApZY4Ne8Gb0AT5rjC3Xneb7dnbSQyXp1OiBXt7eIA,1908
 karrio/server/manager/urls.py,sha256=oXJlvhHNKxFkc_CmpFoyTSAMJcLp4Wt9dHbViQDkqw4,220
@@ -88,14 +88,15 @@ karrio/server/manager/migrations/0079_remove_carrier_fk_fields.py,sha256=xDOEq4a
 karrio/server/manager/migrations/0080_add_carrier_json_indexes.py,sha256=P7FUoX5HdXfi8GkcUjFAyA-HbtXBbAM3EXiqdIElxn4,6019
 karrio/server/manager/migrations/0081_cleanup.py,sha256=cvON11RAgUskyXAMKrBwxIiPNHP0WbhIB31DnN3rp0w,1932
 karrio/server/manager/migrations/0082_shipment_fees.py,sha256=CWJc-ZGITLnN2ln6XZDBIgtbDHdQYYz9AyRQpq1VChc,719
+karrio/server/manager/migrations/0083_pickup_status.py,sha256=cxCVyJcTOisAxiXH5pff8-8Nfl8p-5v5Bov2-EvmLDQ,528
 karrio/server/manager/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-karrio/server/manager/serializers/__init__.py,sha256=AW1RpB3rNLKbMD85rCFFiVcpngj-kPUNdyb1hkaYDrk,1513
+karrio/server/manager/serializers/__init__.py,sha256=LZ9O7gDVtI3UWvTLTt8HJjEMaS5FOLIL6d9JPHPn37Q,1536
 karrio/server/manager/serializers/address.py,sha256=jc_D9gQb0m7ObO6RHk6SEfZipNRPCH4sPKkd_sa7T_Y,2950
 karrio/server/manager/serializers/commodity.py,sha256=tPbGXuDd6N2xqRDWCXTKnSnl4-e1MnHIKe0KdCfQYpA,1897
 karrio/server/manager/serializers/document.py,sha256=MFa8lqcy4Qa0RAUdn4D02AO5cY4_EgxC-aabbxqr-tI,4611
 karrio/server/manager/serializers/manifest.py,sha256=dyEG2A9rWj59Khs5d8ltgRrUWXpk32GU4a2gZNFFU_c,3114
 karrio/server/manager/serializers/parcel.py,sha256=Wfu2trm2pqiOWhsYG-GElhRHSS4HTW5dttkpVNdfXd4,2761
-karrio/server/manager/serializers/pickup.py,sha256=UOIG0trWxjE12jIDyayaoEKvzepmvcSAmER7dSf8WQo,15211
+karrio/server/manager/serializers/pickup.py,sha256=gY-r3cR9cX285A1e7NSaV-cvDey0src2THaznHQcrEs,17341
 karrio/server/manager/serializers/rate.py,sha256=7vYK_v8iWEDnswqYHG2Lir16_UhHTOxW5rdC6lw3lzA,652
 karrio/server/manager/serializers/shipment.py,sha256=uM775c5L0sfgW8kTbUwqCOrnVWoCQfsWy1awQ7dRt5M,41343
 karrio/server/manager/serializers/tracking.py,sha256=HCl-WeCF-AjFaTdEd4xSb068NIKcMH-Hbo0QRMSYrvY,14319
@@ -104,7 +105,7 @@ karrio/server/manager/tests/test_addresses.py,sha256=4eiFQ_6YhLLrfBuLUbYiIfqeRiP
 karrio/server/manager/tests/test_errors.py,sha256=x2-mSsXknHkE4V7TajEu8d3rpqV38T_xyAaYJU7xcGQ,3616
 karrio/server/manager/tests/test_manifests.py,sha256=X35ZTXTFEM4Gxdjz598yiNNkOOKZGpILjHWRC0oM5U4,2764
 karrio/server/manager/tests/test_parcels.py,sha256=nB5SaTjwj_ZF2962ZIGy-DXq6XHXc15uhnV3WtKjuUU,4355
-karrio/server/manager/tests/test_pickups.py,sha256=M8x4j12Zw3vp_L8Xw2Tw9oUzopLJK4QVEfvNn5fZyGk,19081
+karrio/server/manager/tests/test_pickups.py,sha256=nt8S-4SAe848eaQKhQeAIVPJMlL_UbWe7OBNhb-vSM0,37210
 karrio/server/manager/tests/test_products.py,sha256=mK0TxjO2SBllbl_rB0foZQqTjCPR1qky_yeCVCZvzOY,20984
 karrio/server/manager/tests/test_shipments.py,sha256=G2HdzzruZcs9M66fU6sWb763DAfbL8E7if8XVjcYS48,45545
 karrio/server/manager/tests/test_trackers.py,sha256=pDWxYYCFxjZJTLrYbTp1YReexpIeOBXEU8xifht4-D4,9959
@@ -113,11 +114,11 @@ karrio/server/manager/views/addresses.py,sha256=bwW0x75W0n1NxOfP0CdXYbnE25_YZi3x
 karrio/server/manager/views/documents.py,sha256=8Lh49y9LZEDiwBJ77pq4EQVtTv04U-68hc7zzY-gwk4,4049
 karrio/server/manager/views/manifests.py,sha256=KwDoV7GSdRv7YDAzl0SLaNoAx4R-gBguO_WiW_qwfBM,7083
 karrio/server/manager/views/parcels.py,sha256=mF0BzP92_FLdBohnWaXecQGWWaibudoe3KsHZ3yPkR8,5322
-karrio/server/manager/views/pickups.py,sha256=gmpxz9ot1OR-BP1qh-0MXU3kUJi1ht_74hfaLJzJ42w,5503
+karrio/server/manager/views/pickups.py,sha256=QAQ6oLvlwrZMNIbwHfAXKF_YiAMxWN3eEN2ZE2wIAn4,7497
 karrio/server/manager/views/products.py,sha256=1ZxODea-slOhrAZ9pazviLRuJv0I90f4NRTPhA_LxzM,7762
 karrio/server/manager/views/shipments.py,sha256=vdJFgIKnSHEb2FVGtqJbiMoHuMqzWtDpINMH4UaEtQQ,13154
 karrio/server/manager/views/trackers.py,sha256=9uRjNiyqTULmKFOminGgIXj-H0RW-e0JUAF6Z3vMNCY,14744
-karrio_server_manager-2026.1.3.dist-info/METADATA,sha256=C7RRJeRwFZdmmk4DArDcABxeHCzLp8qrLvoMvukR654,730
-karrio_server_manager-2026.1.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-karrio_server_manager-2026.1.3.dist-info/top_level.txt,sha256=D1D7x8R3cTfjF_15mfiO7wCQ5QMtuM4x8GaPr7z5i78,12
-karrio_server_manager-2026.1.3.dist-info/RECORD,,
+karrio_server_manager-2026.1.5.dist-info/METADATA,sha256=JNOsUPhETcMdvPewuUG8E74mBGZaVY9D1uLaf0-XoWU,730
+karrio_server_manager-2026.1.5.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+karrio_server_manager-2026.1.5.dist-info/top_level.txt,sha256=D1D7x8R3cTfjF_15mfiO7wCQ5QMtuM4x8GaPr7z5i78,12
+karrio_server_manager-2026.1.5.dist-info/RECORD,,