feat: add support for DDP shipments and customs payment method handling

- Introduce logic for handling Delivered Duty Paid (DDP) shipments, including determining appropriate payment methods.
- Add support for selecting customs and duties payment method, with built-in caching for efficiency.
- Ensure accurate mapping of tax recipients and guarantee customs charges for DDP shipments.

Author: jacobshilitz

plugins/freightcom_rest/karrio/providers/freightcom_rest/rate.py

@@ -124,12 +124,18 @@ def rate_request(
     # Create the carrier-specific request object
     is_intl = shipper.country_code != recipient.country_code
     is_ca_to_us = shipper.country_code == "CA" and recipient.country_code == "US"
+    
     customs = lib.to_customs_info(
         payload.customs,
         shipper=payload.shipper,
         recipient=payload.recipient,
         weight_unit=packages.weight_unit,
     )
+    commodities = lib.identity(
+        (customs.commodities if any(customs.commodities) else packages.items)
+        if any(packages.items) or any(customs.commodities)
+        else []
+    )
 
     packaging_type = provider_units.PackagingType.map(packages.package_type or "small_box").value
     ship_datetime = lib.to_next_business_datetime(
@@ -262,19 +268,19 @@ def rate_request(
                     products=[
                         freightcom_rest_req.ProductType(
                             hs_code=item.hs_code,
-                            country_of_origin=item.origin_country,
-                            num_units=item.quantity,
+                            country_of_origin=item.origin_country or shipper.country_code,
+                            num_units=item.quantity or 1,
                             unit_price=freightcom_rest_req.TotalCostType(
-                                currency=item.value_currency,
-                                value=str(int(item.value_amount * 100))
+                                currency=item.value_currency or "CAD",
+                                value=str(int((item.value_amount or 0) * 100))
                             ),
-                            description=item.description,
+                            description=item.description or item.title,
                             fda_regulated="no"
-                        ) for item in customs.commodities
-                    ] if customs and customs.commodities else [],
-                    request_guaranteed_customs_charges=options.request_guaranteed_customs_charges.state if hasattr(options, 'request_guaranteed_customs_charges') else None
+                        ) for item in (list(commodities) if is_ca_to_us else [])
+                    ],
+                    request_guaranteed_customs_charges=settings.connection_config.request_guaranteed_customs_charges.state or True
                 )
-                if is_ca_to_us and customs and any(customs.commodities)
+                if is_ca_to_us and len(commodities) > 0
                 else None
             ),
         ),

plugins/freightcom_rest/karrio/providers/freightcom_rest/shipment/create.py

@@ -213,9 +213,23 @@ def shipment_request(
     if not payment_method_id:
         raise Exception("No payment method found need to be set in config")
 
+    # Check if it's DDP (Delivered Duty Paid)
+    is_ddp = (
+        customs and (
+            customs.incoterm == "DDP" or
+            (customs.duty and customs.duty.paid_by == "sender")
+        )
+    ) if customs else False
+
+    # For DDP shipments with Net Terms, need credit card for customs/duties payment
+    customs_and_duties_payment_method_id = None
+    if is_ddp and settings.connection_config.payment_method_type.state == provider_utils.PaymentMethodType.net_terms.value:
+        customs_and_duties_payment_method_id = settings.customs_and_duties_payment_method
+
     request = freightcom_rest_req.ShipmentRequestType(
         unique_id=str(uuid.uuid4()),
         payment_method_id=payment_method_id,
+        customs_and_duties_payment_method_id=customs_and_duties_payment_method_id,
         service_id=provider_units.ShippingService.map(payload.service).value_or_key,
         details=freightcom_rest_req.ShipmentRequestDetailsType(
             origin=freightcom_rest_req.DestinationType(
@@ -377,11 +391,14 @@ def shipment_request(
                         ) for item in customs.commodities
                     ],
                     tax_recipient=freightcom_rest_req.TaxRecipientType(
-                        # they require it to be receiver, has to be enabled in the api
-                        type=provider_units.PaymentType.map(
+                        # For DDP shipments, tax recipient must be 'shipper'
+                        type="shipper" if is_ddp else (
+                            provider_units.PaymentType.map(
                                 customs.duty.paid_by
                             ).value
-                        or "receiver",
+                            if customs.duty and customs.duty.paid_by
+                            else "receiver"
+                        ),
                         name=customs.duty_billing_address.company_name or customs.duty.person_name,
                         address=freightcom_rest_req.AddressType(
                             address_line_1=customs.duty_billing_address.address_line1,

plugins/freightcom_rest/karrio/providers/freightcom_rest/utils.py

@@ -58,6 +58,24 @@ def payment_method(self):
 
         return new_auth.get("id")
 
+    @property
+    def customs_and_duties_payment_method(self):
+
+        if not self.connection_config.customs_and_duties_payment_method.state:
+            raise Exception(f"Customs and duties payment method type not set")
+        cache_key = f"payment|{self.carrier_name}|{self.connection_config.customs_and_duties_payment_method.state}|{self.api_key}"
+
+        payment = self.connection_cache.get(cache_key) or {}
+        payment_id = payment.get("id")
+
+        if payment_id:
+            return payment_id
+
+        self.connection_cache.set(cache_key, lambda: get_customs_payment_id(self))
+        new_auth = self.connection_cache.get(cache_key)
+
+        return new_auth.get("id")
+
 
 def download_document_to_base64(file_url: str) -> str:
     return lib.request(
@@ -95,13 +113,44 @@ def get_payment_id(settings: Settings) -> dict:
     except Exception as e:
         raise
 
+def get_customs_payment_id(settings: Settings) -> dict:
+
+    try:
+        from karrio.mappers.freightcom_rest.proxy import Proxy
+
+        proxy = Proxy(settings)
+        response = proxy._get_payments_methods()
+        methods = response.deserialize()
+
+        selected_method = next((
+            method for method in methods
+            if settings.connection_config.customs_and_duties_payment_method.type.map(
+            method.get('type')).name == settings.connection_config.customs_and_duties_payment_method.state
+        ), None)
+
+
+        if not selected_method:
+            raise Exception(f"Customs payment method {settings.connection_config.customs_and_duties_payment_method.state} not found in API")
+
+        return selected_method
+
+    except Exception as e:
+        raise
+
 
 class PaymentMethodType(lib.StrEnum):
     net_terms = "net-terms"
     credit_card = "credit-card"
 
+class CustomsPaymentMethodType(lib.StrEnum):
+    """Payment method type for customs and duties (credit-card only)"""
+    credit_card = "credit-card"
+
 class ConnectionConfig(lib.Enum):
     """Carrier specific connection configs"""
     payment_method_type = lib.OptionEnum("payment_method_type", PaymentMethodType)
+    customs_and_duties_payment_method = lib.OptionEnum("customs_and_duties_payment_method", CustomsPaymentMethodType)
+    request_guaranteed_customs_charges = lib.OptionEnum("request_guaranteed_customs_charges", bool, default=True)
     shipping_options = lib.OptionEnum("shipping_options", list)
     shipping_services = lib.OptionEnum("shipping_services", list)
+