karrio-server-pricing 2026.1.1__py3-none-any.whl → 2026.1.4__py3-none-any.whl

karrio/server/pricing/admin.py

@@ -1,55 +1,151 @@
+"""
+Django admin configuration for Pricing module.
+"""
+
 import importlib
 
 from django import forms
 from django.contrib import admin
-from karrio.server.pricing.models import Surcharge
+from karrio.server.pricing.models import Markup, Fee
 
 if importlib.util.find_spec("karrio.server.orgs") is not None:
     import karrio.server.orgs.models as orgs
 
 
-class SurchargeAdmin(admin.ModelAdmin):
+# ─────────────────────────────────────────────────────────────────────────────
+# MARKUP ADMIN
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class MarkupAdmin(admin.ModelAdmin):
+    """Admin interface for Markup model."""
+
+    list_display = ("name", "amount", "markup_type", "active", "is_visible")
+    list_filter = ("active", "is_visible", "markup_type")
+    search_fields = ("name", "carrier_codes", "service_codes")
+    readonly_fields = ("id",)
+
     fieldsets = (
-        (None, {"fields": (("name", "active"), ("amount", "surcharge_type"))}),
-        (
-            "Advanced options",
-            {
-                "classes": ("collapse",),
-                "fields": (
-                    "carriers",
-                    "carrier_accounts",
-                    "services",
-                ),
-            },
-        ),
+        (None, {
+            "fields": (
+                "id",
+                ("name", "active"),
+                ("amount", "markup_type"),
+                "is_visible",
+            )
+        }),
+        ("Filters", {
+            "classes": ("collapse",),
+            "description": "Leave empty to apply to all carriers/services/connections",
+            "fields": (
+                "carrier_codes",
+                "service_codes",
+                "connection_ids",
+            ),
+        }),
+        ("Metadata", {
+            "classes": ("collapse",),
+            "fields": ("metadata",),
+        }),
     )
 
     if importlib.util.find_spec("karrio.server.orgs") is not None:
 
-        class SurchargeForm(forms.ModelForm):
+        class MarkupForm(forms.ModelForm):
             class Meta:
-                model = Surcharge
+                model = Markup
                 fields = "__all__"
 
             def __init__(self, *args, **kwargs):
                 super().__init__(*args, **kwargs)
 
                 if kwargs.get("instance") is not None:
-                    self.fields["organizations"].initial = kwargs["instance"].org.all()
+                    org_ids = kwargs["instance"].organization_ids or []
+                    self.fields["organizations"].initial = (
+                        orgs.Organization.objects.filter(id__in=org_ids)
+                    )
 
             organizations = forms.ModelMultipleChoiceField(
-                queryset=orgs.Organization.objects.all(), required=False
+                queryset=orgs.Organization.objects.all(),
+                required=False,
+                help_text="Organizations this markup applies to. Leave empty for global.",
             )
 
             def save(self, commit=True):
-                instance = super().save(commit=commit)
-                instance.save()
+                instance = super().save(commit=False)
                 organizations = self.cleaned_data.get("organizations", [])
-                instance.org.set(organizations)
+                instance.organization_ids = [str(org.id) for org in organizations]
+                instance.save()
                 return instance
 
-        form = SurchargeForm
+        form = MarkupForm
         fieldsets += ((None, {"fields": ("organizations",)}),)
 
 
-admin.site.register(Surcharge, SurchargeAdmin)
+admin.site.register(Markup, MarkupAdmin)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# FEE ADMIN (Read-only)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class FeeAdmin(admin.ModelAdmin):
+    """Admin interface for Fee model (read-only)."""
+
+    list_display = ("name", "amount", "currency", "carrier_code", "service_code", "created_at")
+    list_filter = ("fee_type", "carrier_code", "currency", "test_mode")
+    search_fields = ("name", "shipment_id", "markup_id", "account_id")
+    readonly_fields = (
+        "id", "shipment_id", "markup_id", "account_id", "name", "amount", "currency",
+        "fee_type", "percentage", "carrier_code", "service_code",
+        "connection_id", "test_mode", "created_at",
+    )
+    date_hierarchy = "created_at"
+
+    fieldsets = (
+        (None, {
+            "fields": ("id", "shipment_id", "markup_id", "account_id")
+        }),
+        ("Fee Details", {
+            "fields": (
+                "name",
+                ("amount", "currency"),
+                ("fee_type", "percentage"),
+            )
+        }),
+        ("Context", {
+            "fields": (
+                "carrier_code",
+                "service_code",
+                "connection_id",
+                "test_mode",
+            )
+        }),
+        ("Timestamps", {
+            "fields": ("created_at",)
+        }),
+    )
+
+    def has_add_permission(self, request):
+        """Fees are created automatically, not manually."""
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        """Fees should not be edited."""
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        """Allow deletion for cleanup purposes."""
+        return True
+
+
+admin.site.register(Fee, FeeAdmin)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# LEGACY ALIAS
+# ─────────────────────────────────────────────────────────────────────────────
+
+# For backward compatibility
+SurchargeAdmin = MarkupAdmin

karrio/server/pricing/apps.py

@@ -7,6 +7,10 @@ class PricingConfig(AppConfig):
     verbose_name = _("Shipping Markup")
 
     def ready(self):
-        from karrio.server.pricing.signals import register_rate_post_processing
+        from karrio.server.pricing.signals import (
+            register_rate_post_processing,
+            register_fee_capture,
+        )
 
         register_rate_post_processing()
+        register_fee_capture()

karrio/server/pricing/migrations/0076_create_markup_and_fee_models.py

@@ -0,0 +1,258 @@
+# Generated migration for Markup and Fee models
+
+import functools
+from django.db import migrations, models
+import django.db.models.deletion
+import karrio.server.core.models
+
+
+class Migration(migrations.Migration):
+    """
+    Create new Markup and Fee models.
+
+    This is part of the Surcharge -> Markup refactoring:
+    - Markup model replaces Surcharge with JSONField-based filters
+    - Fee model tracks applied markups for usage statistics
+    """
+
+    dependencies = [
+        ("pricing", "0075_alter_surcharge_carriers_alter_surcharge_services"),
+        ("manager", "0079_remove_carrier_fk_fields"),
+    ]
+
+    operations = [
+        # Create Markup model
+        migrations.CreateModel(
+            name="Markup",
+            fields=[
+                (
+                    "created_at",
+                    models.DateTimeField(auto_now_add=True),
+                ),
+                (
+                    "updated_at",
+                    models.DateTimeField(auto_now=True),
+                ),
+                (
+                    "id",
+                    models.CharField(
+                        default=functools.partial(
+                            karrio.server.core.models.uuid, prefix="mkp_"
+                        ),
+                        editable=False,
+                        max_length=50,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                (
+                    "name",
+                    models.CharField(
+                        help_text="The markup name (label) that will appear in the rate breakdown",
+                        max_length=100,
+                        unique=True,
+                    ),
+                ),
+                (
+                    "active",
+                    models.BooleanField(
+                        default=True,
+                        help_text="Whether the markup is active and will be applied to rates",
+                    ),
+                ),
+                (
+                    "amount",
+                    models.FloatField(
+                        default=0.0,
+                        help_text="The markup amount or percentage to add to the quote.",
+                    ),
+                ),
+                (
+                    "markup_type",
+                    models.CharField(
+                        choices=[("AMOUNT", "AMOUNT"), ("PERCENTAGE", "PERCENTAGE")],
+                        default="AMOUNT",
+                        help_text="Determine whether the markup is in percentage or net amount.",
+                        max_length=25,
+                    ),
+                ),
+                (
+                    "is_visible",
+                    models.BooleanField(
+                        default=True,
+                        help_text="Whether to show this markup in the rate breakdown to users",
+                    ),
+                ),
+                (
+                    "carrier_codes",
+                    models.JSONField(
+                        blank=True,
+                        default=list,
+                        help_text="List of carrier codes to apply the markup to.",
+                    ),
+                ),
+                (
+                    "service_codes",
+                    models.JSONField(
+                        blank=True,
+                        default=list,
+                        help_text="List of service codes to apply the markup to.",
+                    ),
+                ),
+                (
+                    "connection_ids",
+                    models.JSONField(
+                        blank=True,
+                        default=list,
+                        help_text="List of connection IDs to apply the markup to.",
+                    ),
+                ),
+                (
+                    "organization_ids",
+                    models.JSONField(
+                        blank=True,
+                        default=list,
+                        help_text="List of organization IDs to apply the markup to.",
+                    ),
+                ),
+                (
+                    "metadata",
+                    models.JSONField(
+                        blank=True,
+                        default=dict,
+                        help_text="Additional metadata for the markup",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Markup",
+                "verbose_name_plural": "Markups",
+                "db_table": "markup",
+                "ordering": ["-created_at"],
+            },
+        ),
+        # Create Fee model
+        migrations.CreateModel(
+            name="Fee",
+            fields=[
+                (
+                    "id",
+                    models.CharField(
+                        default=functools.partial(
+                            karrio.server.core.models.uuid, prefix="fee_"
+                        ),
+                        editable=False,
+                        max_length=50,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                (
+                    "name",
+                    models.CharField(
+                        help_text="The fee name at time of application",
+                        max_length=100,
+                    ),
+                ),
+                (
+                    "amount",
+                    models.FloatField(
+                        help_text="The fee amount in the shipment's currency",
+                    ),
+                ),
+                (
+                    "currency",
+                    models.CharField(
+                        help_text="Currency code (e.g., USD, EUR)",
+                        max_length=3,
+                    ),
+                ),
+                (
+                    "markup_type",
+                    models.CharField(
+                        choices=[("AMOUNT", "AMOUNT"), ("PERCENTAGE", "PERCENTAGE")],
+                        help_text="Whether this was a fixed amount or percentage markup",
+                        max_length=25,
+                    ),
+                ),
+                (
+                    "markup_percentage",
+                    models.FloatField(
+                        blank=True,
+                        help_text="Original percentage if this was a percentage-based markup",
+                        null=True,
+                    ),
+                ),
+                (
+                    "carrier_code",
+                    models.CharField(
+                        help_text="Carrier code at time of shipment creation",
+                        max_length=50,
+                    ),
+                ),
+                (
+                    "service_code",
+                    models.CharField(
+                        blank=True,
+                        help_text="Service code at time of shipment creation",
+                        max_length=100,
+                        null=True,
+                    ),
+                ),
+                (
+                    "connection_id",
+                    models.CharField(
+                        help_text="Connection ID used for this shipment",
+                        max_length=50,
+                    ),
+                ),
+                (
+                    "created_at",
+                    models.DateTimeField(auto_now_add=True),
+                ),
+                (
+                    "markup",
+                    models.ForeignKey(
+                        blank=True,
+                        help_text="The markup that generated this fee",
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="fees",
+                        to="pricing.markup",
+                    ),
+                ),
+                (
+                    "shipment",
+                    models.ForeignKey(
+                        help_text="The shipment this fee was applied to",
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="fees",
+                        to="manager.shipment",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Fee",
+                "verbose_name_plural": "Fees",
+                "db_table": "fee",
+                "ordering": ["-created_at"],
+            },
+        ),
+        # Add indexes for Fee model
+        migrations.AddIndex(
+            model_name="fee",
+            index=models.Index(fields=["shipment_id"], name="fee_shipmen_d4e9f2_idx"),
+        ),
+        migrations.AddIndex(
+            model_name="fee",
+            index=models.Index(fields=["markup_id"], name="fee_markup__29f8a1_idx"),
+        ),
+        migrations.AddIndex(
+            model_name="fee",
+            index=models.Index(fields=["carrier_code"], name="fee_carrier_3c7b8e_idx"),
+        ),
+        migrations.AddIndex(
+            model_name="fee",
+            index=models.Index(fields=["created_at"], name="fee_created_a1b2c3_idx"),
+        ),
+    ]

karrio/server/pricing/migrations/0077_migrate_surcharge_to_markup_data.py

@@ -0,0 +1,70 @@
+# Data migration: Surcharge -> Markup
+
+from django.db import migrations
+
+
+def migrate_surcharges_to_markups(apps, schema_editor):
+    """
+    Migrate existing Surcharge records to new Markup model.
+
+    Mappings:
+    - id: chrg_xxx -> mkp_xxx (preserve original ID for fee tracking)
+    - surcharge_type -> markup_type
+    - carriers -> carrier_codes
+    - services -> service_codes
+    - carrier_accounts (M2M) -> connection_ids (JSONField)
+    """
+    Surcharge = apps.get_model("pricing", "Surcharge")
+    Markup = apps.get_model("pricing", "Markup")
+
+    for surcharge in Surcharge.objects.all():
+        # Get carrier account IDs from M2M relation
+        connection_ids = list(
+            surcharge.carrier_accounts.values_list("id", flat=True)
+        )
+
+        # Create Markup record with mapped data
+        # Preserve original ID to maintain fee tracking
+        Markup.objects.create(
+            id=surcharge.id,  # Keep original ID (chrg_xxx)
+            name=surcharge.name,
+            active=surcharge.active,
+            amount=surcharge.amount,
+            markup_type=surcharge.surcharge_type,  # Same values (AMOUNT/PERCENTAGE)
+            is_visible=True,  # New field, default visible
+            carrier_codes=surcharge.carriers or [],
+            service_codes=surcharge.services or [],
+            connection_ids=connection_ids,
+            metadata={},
+            created_at=surcharge.created_at,
+            updated_at=surcharge.updated_at,
+        )
+
+        print(f"Migrated surcharge {surcharge.id} -> markup")
+
+
+def reverse_migration(apps, schema_editor):
+    """
+    Reverse the migration by clearing Markup table.
+    Note: This doesn't restore Surcharge data - use with caution.
+    """
+    Markup = apps.get_model("pricing", "Markup")
+    Markup.objects.all().delete()
+    print("Cleared Markup table")
+
+
+class Migration(migrations.Migration):
+    """
+    Data migration to convert Surcharge records to Markup records.
+    """
+
+    dependencies = [
+        ("pricing", "0076_create_markup_and_fee_models"),
+    ]
+
+    operations = [
+        migrations.RunPython(
+            migrate_surcharges_to_markups,
+            reverse_migration,
+        ),
+    ]

karrio/server/pricing/migrations/0078_cleanup.py

@@ -0,0 +1,109 @@
+# Generated by Django 5.2.10 on 2026-01-22 14:29
+
+import django.core.validators
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("pricing", "0077_migrate_surcharge_to_markup_data"),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name="surcharge",
+            name="carrier_accounts",
+        ),
+        migrations.RenameIndex(
+            model_name="fee",
+            new_name="fee_shipmen_cf6644_idx",
+            old_name="fee_shipmen_d4e9f2_idx",
+        ),
+        migrations.RenameIndex(
+            model_name="fee",
+            new_name="fee_markup__6438ea_idx",
+            old_name="fee_markup__29f8a1_idx",
+        ),
+        migrations.RenameIndex(
+            model_name="fee",
+            new_name="fee_carrier_86bb46_idx",
+            old_name="fee_carrier_3c7b8e_idx",
+        ),
+        migrations.RenameIndex(
+            model_name="fee",
+            new_name="fee_created_050ccc_idx",
+            old_name="fee_created_a1b2c3_idx",
+        ),
+        migrations.AlterField(
+            model_name="fee",
+            name="markup",
+            field=models.ForeignKey(
+                blank=True,
+                help_text="The markup that generated this fee (null if markup was deleted)",
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="fees",
+                to="pricing.markup",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="markup",
+            name="amount",
+            field=models.FloatField(
+                default=0.0,
+                help_text="\n        The markup amount or percentage to add to the quote.\n        For AMOUNT type: the exact dollar amount to add.\n        For PERCENTAGE type: the percentage (e.g., 5 means 5%).\n        ",
+                validators=[django.core.validators.MinValueValidator(0.0)],
+            ),
+        ),
+        migrations.AlterField(
+            model_name="markup",
+            name="carrier_codes",
+            field=models.JSONField(
+                blank=True,
+                default=list,
+                help_text='\n        List of carrier codes to apply the markup to (e.g., ["fedex", "ups"]).\n        Empty list means apply to all carriers.\n        ',
+            ),
+        ),
+        migrations.AlterField(
+            model_name="markup",
+            name="connection_ids",
+            field=models.JSONField(
+                blank=True,
+                default=list,
+                help_text='\n        List of connection IDs to apply the markup to (e.g., ["car_xxx", "car_yyy"]).\n        Supports all connection types: CarrierConnection, SystemConnection, BrokeredConnection.\n        Empty list means apply to all connections.\n        ',
+            ),
+        ),
+        migrations.AlterField(
+            model_name="markup",
+            name="markup_type",
+            field=models.CharField(
+                choices=[("AMOUNT", "AMOUNT"), ("PERCENTAGE", "PERCENTAGE")],
+                default="AMOUNT",
+                help_text="\n        Determine whether the markup is in percentage or net amount.\n        AMOUNT: rate ($22) + amount (1) = $23\n        PERCENTAGE: rate ($22) * 5% = $23.10\n        ",
+                max_length=25,
+            ),
+        ),
+        migrations.AlterField(
+            model_name="markup",
+            name="organization_ids",
+            field=models.JSONField(
+                blank=True,
+                default=list,
+                help_text="\n        List of organization IDs to apply the markup to.\n        Empty list means apply to all organizations (system-wide).\n        ",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="markup",
+            name="service_codes",
+            field=models.JSONField(
+                blank=True,
+                default=list,
+                help_text='\n        List of service codes to apply the markup to (e.g., ["fedex_ground", "ups_next_day"]).\n        Empty list means apply to all services.\n        ',
+            ),
+        ),
+        migrations.DeleteModel(
+            name="Surcharge",
+        ),
+    ]