Generate Return Shipments #951

MarcoWel · 2026-01-30T20:27:18Z

MarcoWel
Jan 30, 2026

Dear karrio Team,
Can we generate import shipments (UPS calls them return shipments)?

Example 1:

Recipient: Ourselves (DE)
Shipper: Ourselves (DE)
Return Address: Supplier (US)

Result in karrio:

UPS/Fedex: Wrong services displayed (domestic within DE), trying to generate label: "ups The ShipFrom country must be the same as the Shipper country" / "fedex We could not authorize your credentials. Please check your permissions and try again."

Example 2:

Recipient: Ourselves (DE)
Shipper: Supplier (US)

Result in karrio:

UPS: No rates displayed
Fedex: Correct services but displayed rates too high, trying to generate label: "fedex We could not authorize your credentials. Please check your permissions and try again."

Dan (danh91) · 2026-02-07T04:47:11Z

Dan (danh91)
Feb 7, 2026
Maintainer

Hi MarcoWel ,
We are also beginning to look into return shipment.
The above would be great.

Can you share some anonymized requests of the scenarios you described above?
Thanks

0 replies

MarcoWel · 2026-02-08T23:45:30Z

MarcoWel
Feb 8, 2026
Author

Hi Dan (@danh91),
Focusing on UPS for now, where we have a German account (DE).
Trying to create an import shipment (US -> DE).

On the UPS website, this can be created as a return shipment without problems:
https://www.ups.com/ship/single-page?createAReturn=true
Within karrio it does not work. As of now, karrio 2026.1.5 seems to ignore the specified Return Address.

With "Add A Return Address"

Karrio is getting the wrong services - return shipments needs to be UPS Express Saver Worldwide, not Standard or Express EU.
Reson: Even when a return address is specified in karrio, ShipFrom is not supplied correctly to UPS API (still equals shipper).

karrio Request:

{
  "label_type": "PDF",
  "options": {
    "shipping_date": "2026-02-09T00:17"
  },
  "parcels": [
    {
      "dimension_unit": "CM",
      "height": 18.2,
      "is_document": false,
      "length": 10,
      "packaging_type": "your_packaging",
      "weight": 1,
      "weight_unit": "KG",
      "width": 33.7
    }
  ],
  "payment": {
    "paid_by": "sender"
  },
  "recipient": {
    "address_line1": "Teststr. 1",
    "city": "Karlsruhe",
    "company_name": "Test Company",
    "country_code": "DE",
    "id": "adr_052cabccc9164ca8aa404c40fa683eb7",
    "meta": {
      "is_default": false,
      "label": "Germany Test"
    },
    "object_type": "address",
    "person_name": "Person Name",
    "postal_code": "76131",
    "residential": false
  },
  "return_address": {
    "address_line1": "001 Test Blvd",
    "city": "San Francisco",
    "company_name": "US Company",
    "country_code": "US",
    "id": "adr_261ac794dc5744aea175f807c03b72fd",
    "meta": {
      "is_default": false,
      "label": "US Test"
    },
    "object_type": "address",
    "person_name": "Test Person",
    "postal_code": "94102",
    "residential": false,
    "state_code": "CA"
  },
  "shipper": {
    "address_line1": "Teststr. 1",
    "city": "Karlsruhe",
    "company_name": "Test Company",
    "country_code": "DE",
    "id": "adr_052cabccc9164ca8aa404c40fa683eb7",
    "meta": {
      "is_default": false,
      "label": "Germany Test"
    },
    "object_type": "address",
    "person_name": "Person Name",
    "postal_code": "76131",
    "residential": false
  }
}

UPS Request:

{
  "RateRequest": {
    "Request": {
      "RequestOption": "Shoptimeintransit",
      "SubVersion": "2409",
      "TransactionReference": {
        "CustomerContext": "fetch rates"
      }
    },
    "Shipment": {
      "DeliveryTimeInformation": {
        "PackageBillType": "03",
        "Pickup": {
          "Date": "20260209"
        }
      },
      "InvoiceLineTotal": {
        "CurrencyCode": "USD",
        "MonetaryValue": "1.0"
      },
      "Package": [
        {
          "Dimensions": {
            "Height": "18.2",
            "Length": "10.0",
            "UnitOfMeasurement": {
              "Code": "CM",
              "Description": "Dimension"
            },
            "Width": "33.7"
          },
          "PackageWeight": {
            "UnitOfMeasurement": {
              "Code": "KGS",
              "Description": "Weight"
            },
            "Weight": "1.0"
          },
          "PackagingType": {
            "Code": "02",
            "Description": "Packaging Type"
          }
        }
      ],
      "PaymentDetails": {
        "ShipmentCharge": [
          {
            "BillShipper": {
              "AccountNumber": "xxx"
            },
            "Type": "01"
          }
        ]
      },
      "RatingMethodRequestedIndicator": "Y",
      "Service": {
        "Code": "11",
        "Description": "Weight"
      },
      "ShipFrom": {
        "Address": {
          "AddressLine": [
            "1 Teststr."
          ],
          "City": "Karlsruhe",
          "CountryCode": "DE",
          "PostalCode": "76131"
        },
        "AttentionName": "Person Name"
      },
      "ShipTo": {
        "Address": {
          "AddressLine": [
            "1 Teststr."
          ],
          "City": "Karlsruhe",
          "CountryCode": "DE",
          "PostalCode": "76131"
        },
        "AttentionName": "Person Name"
      },
      "ShipmentDate": "20260209",
      "ShipmentRatingOptions": {
        "NegotiatedRatesIndicator": "Y"
      },
      "ShipmentTotalWeight": {
        "UnitOfMeasurement": {
          "Code": "KGS",
          "Description": "Dimension"
        },
        "Weight": "1.0"
      },
      "Shipper": {
        "Address": {
          "AddressLine": [
            "1 Teststr."
          ],
          "City": "Karlsruhe",
          "CountryCode": "DE",
          "PostalCode": "76131"
        },
        "AttentionName": "Person Name",
        "ShipperNumber": "xxx"
      },
      "TaxInformationIndicator": "Y"
    }
  }
}

karrio Response:

{
  "rates": [
    {
      "id": "rat_abb51918a434405d85310afac9ef24b8",
      "object_type": "rate",
      "carrier_name": "ups",
      "carrier_id": "UPS",
      "currency": "EUR",
      "service": "ups_standard_eu",
      "total_charge": x.xx,
      "transit_days": 1,
      "extra_charges": [
        {
          "name": "BASE CHARGE",
          "amount": x.xx,
          "currency": "EUR"
        },
        {
          "name": "FUEL SURCHARGE",
          "amount": x.xx,
          "currency": "EUR"
        },
        {
          "name": "MWST",
          "amount": x.xx,
          "currency": "EUR"
        }
      ],
      "meta": {
        "service_name": "UPS STANDARD EU",
        "rate_zone": "1",
        "ext": "ups",
        "carrier": "ups",
        "rate_provider": "ups",
        "carrier_connection_id": "car_662a8310b3c740f1909725b60ad7b630"
      },
      "test_mode": false
    },
    ...
  ]
}

UPS response:

{
  "RateResponse": {
    "Response": {
      "ResponseStatus": {
        "Code": "1",
        "Description": "Success"
      },
      "Alert": [
        {
          "Code": "110971",
          "Description": "Your invoice may vary from the displayed reference rates"
        }
      ],
      "TransactionReference": {
        "CustomerContext": "fetch rates"
      }
    },
    "RatedShipment": [
      ...,
      {
        "Disclaimer": [
          {
            "Code": "01",
            "Description": "Taxes are included in the shipping cost and apply to the transportation charges but additional duties/taxes may apply and are not reflected in the total amount due."
          }
        ],
        "Service": {
          "Code": "11",
          "Description": ""
        },
        "Zone": "1",
        "RatedShipmentAlert": [
          {
            "Code": "110971",
            "Description": "Your invoice may vary from the displayed reference rates"
          }
        ],
        "RatingMethod": "01",
        "BillableWeightCalculationMethod": "02",
        "BillingWeight": {
          "UnitOfMeasurement": {
            "Code": "KGS",
            "Description": "Kilograms"
          },
          "Weight": "1.5"
        },
        "TransportationCharges": {
          "CurrencyCode": "EUR",
          "MonetaryValue": "17.75"
        },
        "BaseServiceCharge": {
          "CurrencyCode": "EUR",
          "MonetaryValue": "14.55"
        },
        "ItemizedCharges": [
          {
            "Code": "375",
            "CurrencyCode": "EUR",
            "MonetaryValue": "x.xx"
          }
        ],
        "ServiceOptionsCharges": {
          "CurrencyCode": "EUR",
          "MonetaryValue": "0.00"
        },
        "TotalCharges": {
          "CurrencyCode": "EUR",
          "MonetaryValue": "17.75"
        },
        "NegotiatedRateCharges": {
          "BaseServiceCharge": {
            "CurrencyCode": "EUR",
            "MonetaryValue": "x.xx"
          },
          "ItemizedCharges": [
            {
              "Code": "375",
              "CurrencyCode": "EUR",
              "MonetaryValue": "x.xx"
            }
          ],
          "TaxCharges": [
            {
              "Type": "MWST",
              "MonetaryValue": "x.xx"
            }
          ],
          "TotalCharge": {
            "CurrencyCode": "EUR",
            "MonetaryValue": "x.xx"
          },
          "TotalChargesWithTaxes": {
            "CurrencyCode": "EUR",
            "MonetaryValue": "x.xx"
          }
        },
        "RatedPackage": [
          {
            "NegotiatedCharges": {
              "BaseServiceCharge": {
                "CurrencyCode": "EUR",
                "MonetaryValue": "0.00"
              },
              "TransportationCharges": {
                "CurrencyCode": "EUR",
                "MonetaryValue": "0.00"
              },
              "ServiceOptionsCharges": {
                "CurrencyCode": "EUR",
                "MonetaryValue": "0.00"
              },
              "TotalCharge": {
                "CurrencyCode": "EUR",
                "MonetaryValue": "0.00"
              }
            },
            "Weight": "1.0"
          }
        ],
        "TimeInTransit": {
          "PickupDate": "20260209",
          "PackageBillType": "03",
          "AutoDutyCode": "02",
          "Disclaimer": "Services listed as guaranteed are backed by a money-back guarantee for transportation charges only. See Terms and Conditions in the Service Guide for details. Certain commodities and high value shipments may require additional transit time for customs clearance.",
          "ServiceSummary": {
            "Service": {
              "Description": "UPS Standard"
            },
            "EstimatedArrival": {
              "Arrival": {
                "Date": "20260210",
                "Time": "233000"
              },
              "BusinessDaysInTransit": "1",
              "Pickup": {
                "Date": "20260209",
                "Time": "190000"
              },
              "DayOfWeek": "TUE",
              "CustomerCenterCutoff": "170000",
              "TotalTransitDays": "1"
            },
            "Disclaimer": "UPS Standard is available to UPS Account holders only.",
            "SaturdayDelivery": "0"
          }
        }
      }
    ]
  }
}

Without "Add A Return Address"

karrio Request:

{
  "label_type": "PDF",
  "options": {
    "shipping_date": "2026-02-09T00:17"
  },
  "parcels": [
    {
      "dimension_unit": "CM",
      "height": 18.2,
      "is_document": false,
      "length": 10,
      "packaging_type": "your_packaging",
      "weight": 1,
      "weight_unit": "KG",
      "width": 33.7
    }
  ],
  "payment": {
    "paid_by": "sender"
  },
  "recipient": {
    "address_line1": "Teststr. 1",
    "city": "Karlsruhe",
    "company_name": "Test Company",
    "country_code": "DE",
    "id": "adr_052cabccc9164ca8aa404c40fa683eb7",
    "meta": {
      "is_default": false,
      "label": "Germany Test"
    },
    "object_type": "address",
    "person_name": "Person Name",
    "postal_code": "76131",
    "residential": false
  },
  "shipper": {
    "address_line1": "001 Test Blvd",
    "city": "San Francisco",
    "company_name": "US Company",
    "country_code": "US",
    "id": "adr_261ac794dc5744aea175f807c03b72fd",
    "meta": {
      "is_default": false,
      "label": "US Test"
    },
    "object_type": "address",
    "person_name": "Test Person",
    "postal_code": "94102",
    "residential": false,
    "state_code": "CA"
  }
}

UPS Request:

{
  "RateRequest": {
    "Request": {
      "RequestOption": "Shoptimeintransit",
      "SubVersion": "2409",
      "TransactionReference": {
        "CustomerContext": "fetch rates"
      }
    },
    "Shipment": {
      "DeliveryTimeInformation": {
        "PackageBillType": "03",
        "Pickup": {
          "Date": "20260209"
        }
      },
      "InvoiceLineTotal": {
        "CurrencyCode": "USD",
        "MonetaryValue": "1.0"
      },
      "Package": [
        {
          "Dimensions": {
            "Height": "7.17",
            "Length": "3.94",
            "UnitOfMeasurement": {
              "Code": "IN",
              "Description": "Dimension"
            },
            "Width": "13.27"
          },
          "PackageWeight": {
            "UnitOfMeasurement": {
              "Code": "LBS",
              "Description": "Weight"
            },
            "Weight": "2.21"
          },
          "PackagingType": {
            "Code": "02",
            "Description": "Packaging Type"
          }
        }
      ],
      "PaymentDetails": {
        "ShipmentCharge": [
          {
            "BillShipper": {
              "AccountNumber": "xxxxx"
            },
            "Type": "01"
          }
        ]
      },
      "RatingMethodRequestedIndicator": "Y",
      "Service": {
        "Code": "11",
        "Description": "Weight"
      },
      "ShipFrom": {
        "Address": {
          "AddressLine": [
            "001 Test Blvd"
          ],
          "City": "San Francisco",
          "CountryCode": "US",
          "PostalCode": "94102",
          "StateProvinceCode": "CA"
        },
        "AttentionName": "Test Person"
      },
      "ShipTo": {
        "Address": {
          "AddressLine": [
            "1 Teststr."
          ],
          "City": "Karlsruhe",
          "CountryCode": "DE",
          "PostalCode": "76131"
        },
        "AttentionName": "Person Name"
      },
      "ShipmentDate": "20260209",
      "ShipmentRatingOptions": {
        "NegotiatedRatesIndicator": "Y"
      },
      "ShipmentTotalWeight": {
        "UnitOfMeasurement": {
          "Code": "KGS",
          "Description": "Dimension"
        },
        "Weight": "1.0"
      },
      "Shipper": {
        "Address": {
          "AddressLine": [
            "001 Test Blvd"
          ],
          "City": "San Francisco",
          "CountryCode": "US",
          "PostalCode": "94102",
          "StateProvinceCode": "CA"
        },
        "AttentionName": "Test Person",
        "ShipperNumber": "xxx"
      },
      "TaxInformationIndicator": "Y"
    }
  }
}

karrio Response:

{
  "messages": [
    {
      "carrier_id": "UPS",
      "carrier_name": "ups",
      "code": "111617",
      "level": "error",
      "message": "The country associated with Shippers ShipperNumber must be the same as the shipments Shippers country."
    }
  ]
}

UPS response:

{
  "response": {
    "errors": [
      {
        "code": "111617",
        "message": "The country associated with Shippers ShipperNumber must be the same as the shipments Shippers country."
      }
    ]
  }
}

0 replies

MarcoWel · 2026-02-21T17:08:45Z

MarcoWel
Feb 21, 2026
Author

Hi Dan (@danh91),
I saw you made progress on return shipments and just tested 2026.1.14.
Just wanted to reprot that there are no visible changes for how return shipment rates are fetched, means the issue still persists.

0 replies

MarcoWel · 2026-03-04T11:46:07Z

MarcoWel
Mar 4, 2026
Author

Update 2026.1.17: Rate fetching for international return shipments now seems to work for ~~Fedex and~~ UPS! 💯

There is still an issue for UPS though. Return shipment US->DE is giving the error ups Invalid Unit of Measurement for the given country when using kg for parcel weight in karrio. Changing the unit to anything else (g or lb) makes the error disappear and fetches the rates sucessfully. Analyzing the request log it seems karrio converts anything else than kg to lbs already.

Requesting in kg - Error "Invalid Unit of Measurement"

karrio request:

{
  "label_type": "PDF",
  "options": {
    "shipping_date": "2026-03-04T12:27"
  },
  "parcels": [
    {
      "dimension_unit": "CM",
      "height": 18.2,
      "is_document": false,
      "length": 10,
      "packaging_type": "your_packaging",
      "weight": 1,
      "weight_unit": "KG",
      "width": 33.7
    }
  ],
  "payment": {
    "paid_by": "sender"
  },
  "recipient": {
    "address_line1": "Teststr. 1",
    "city": "Karlsruhe",
    "company_name": "Test Company",
    "country_code": "DE",
    "id": "adr_052cabccc9164ca8aa404c40fa683eb7",
    "meta": {
      "is_default": false,
      "label": "Germany Test"
    },
    "object_type": "address",
    "person_name": "Person Name",
    "postal_code": "76131",
    "residential": false
  },
  "return_address": {
    "address_line1": "001 Test Blvd",
    "city": "San Francisco",
    "company_name": "US Company",
    "country_code": "US",
    "id": "adr_261ac794dc5744aea175f807c03b72fd",
    "meta": {
      "is_default": false,
      "label": "US Test"
    },
    "object_type": "address",
    "person_name": "Test Person",
    "postal_code": "94102",
    "residential": false,
    "state_code": "CA"
  },
  "shipper": {
    "address_line1": "Teststr. 1",
    "city": "Karlsruhe",
    "company_name": "Test Company",
    "country_code": "DE",
    "id": "adr_052cabccc9164ca8aa404c40fa683eb7",
    "meta": {
      "is_default": false,
      "label": "Germany Test"
    },
    "object_type": "address",
    "person_name": "Person Name",
    "postal_code": "76131",
    "residential": false
  }
}

UPS request:

{
  "RateRequest": {
    "Request": {
      "RequestOption": "Shoptimeintransit",
      "SubVersion": "2409",
      "TransactionReference": {
        "CustomerContext": "fetch rates"
      }
    },
    "Shipment": {
      "DeliveryTimeInformation": {
        "PackageBillType": "03",
        "Pickup": {
          "Date": "20260304"
        }
      },
      "InvoiceLineTotal": {
        "CurrencyCode": "USD",
        "MonetaryValue": "1.0"
      },
      "Package": [
        {
          "Dimensions": {
            "Height": "18.2",
            "Length": "10.0",
            "UnitOfMeasurement": {
              "Code": "CM",
              "Description": "Dimension"
            },
            "Width": "33.7"
          },
          "PackageWeight": {
            "UnitOfMeasurement": {
              "Code": "KGS",
              "Description": "Weight"
            },
            "Weight": "1.0"
          },
          "PackagingType": {
            "Code": "02",
            "Description": "Packaging Type"
          }
        }
      ],
      "PaymentDetails": {
        "ShipmentCharge": [
          {
            "BillShipper": {
              "AccountNumber": "xxx"
            },
            "Type": "01"
          }
        ]
      },
      "RatingMethodRequestedIndicator": "Y",
      "Service": {
        "Code": "11",
        "Description": "Weight"
      },
      "ShipFrom": {
        "Address": {
          "AddressLine": [
            "001 Test Blvd"
          ],
          "City": "San Francisco",
          "CountryCode": "US",
          "PostalCode": "94102",
          "StateProvinceCode": "CA"
        },
        "AttentionName": "Test Person"
      },
      "ShipTo": {
        "Address": {
          "AddressLine": [
            "1 Teststr."
          ],
          "City": "Karlsruhe",
          "CountryCode": "DE",
          "PostalCode": "76131"
        },
        "AttentionName": "Person Name"
      },
      "ShipmentDate": "20260304",
      "ShipmentRatingOptions": {
        "NegotiatedRatesIndicator": "Y"
      },
      "ShipmentTotalWeight": {
        "UnitOfMeasurement": {
          "Code": "KGS",
          "Description": "Dimension"
        },
        "Weight": "1.0"
      },
      "Shipper": {
        "Address": {
          "AddressLine": [
            "1 Teststr."
          ],
          "City": "Karlsruhe",
          "CountryCode": "DE",
          "PostalCode": "76131"
        },
        "AttentionName": "Person Name",
        "ShipperNumber": "xxx"
      },
      "TaxInformationIndicator": "Y"
    }
  }
}

Requesting in g - works fine

karrio request:

{
  "label_type": "PDF",
  "options": {
    "shipping_date": "2026-03-04T12:27"
  },
  "parcels": [
    {
      "dimension_unit": "CM",
      "height": 18.2,
      "is_document": false,
      "length": 10,
      "packaging_type": "your_packaging",
      "weight": 1000,
      "weight_unit": "G",
      "width": 33.7
    }
  ],
  "payment": {
    "paid_by": "sender"
  },
  "recipient": {
    "address_line1": "Teststr. 1",
    "city": "Karlsruhe",
    "company_name": "Test Company",
    "country_code": "DE",
    "id": "adr_052cabccc9164ca8aa404c40fa683eb7",
    "meta": {
      "is_default": false,
      "label": "Germany Test"
    },
    "object_type": "address",
    "person_name": "Person Name",
    "postal_code": "76131",
    "residential": false
  },
  "return_address": {
    "address_line1": "001 Test Blvd",
    "city": "San Francisco",
    "company_name": "US Company",
    "country_code": "US",
    "id": "adr_261ac794dc5744aea175f807c03b72fd",
    "meta": {
      "is_default": false,
      "label": "US Test"
    },
    "object_type": "address",
    "person_name": "Test Person",
    "postal_code": "94102",
    "residential": false,
    "state_code": "CA"
  },
  "shipper": {
    "address_line1": "Teststr. 1",
    "city": "Karlsruhe",
    "company_name": "Test Company",
    "country_code": "DE",
    "id": "adr_052cabccc9164ca8aa404c40fa683eb7",
    "meta": {
      "is_default": false,
      "label": "Germany Test"
    },
    "object_type": "address",
    "person_name": "Person Name",
    "postal_code": "76131",
    "residential": false
  }
}

UPS request:

{
  "RateRequest": {
    "Request": {
      "RequestOption": "Shoptimeintransit",
      "SubVersion": "2409",
      "TransactionReference": {
        "CustomerContext": "fetch rates"
      }
    },
    "Shipment": {
      "DeliveryTimeInformation": {
        "PackageBillType": "03",
        "Pickup": {
          "Date": "20260304"
        }
      },
      "InvoiceLineTotal": {
        "CurrencyCode": "USD",
        "MonetaryValue": "1.0"
      },
      "Package": [
        {
          "Dimensions": {
            "Height": "7.17",
            "Length": "3.94",
            "UnitOfMeasurement": {
              "Code": "IN",
              "Description": "Dimension"
            },
            "Width": "13.27"
          },
          "PackageWeight": {
            "UnitOfMeasurement": {
              "Code": "LBS",
              "Description": "Weight"
            },
            "Weight": "2.2"
          },
          "PackagingType": {
            "Code": "02",
            "Description": "Packaging Type"
          }
        }
      ],
      "PaymentDetails": {
        "ShipmentCharge": [
          {
            "BillShipper": {
              "AccountNumber": "xxx"
            },
            "Type": "01"
          }
        ]
      },
      "RatingMethodRequestedIndicator": "Y",
      "Service": {
        "Code": "11",
        "Description": "Weight"
      },
      "ShipFrom": {
        "Address": {
          "AddressLine": [
            "001 Test Blvd"
          ],
          "City": "San Francisco",
          "CountryCode": "US",
          "PostalCode": "94102",
          "StateProvinceCode": "CA"
        },
        "AttentionName": "Test Person"
      },
      "ShipTo": {
        "Address": {
          "AddressLine": [
            "1 Teststr."
          ],
          "City": "Karlsruhe",
          "CountryCode": "DE",
          "PostalCode": "76131"
        },
        "AttentionName": "Person Name"
      },
      "ShipmentDate": "20260304",
      "ShipmentRatingOptions": {
        "NegotiatedRatesIndicator": "Y"
      },
      "ShipmentTotalWeight": {
        "UnitOfMeasurement": {
          "Code": "LBS",
          "Description": "Dimension"
        },
        "Weight": "2.2"
      },
      "Shipper": {
        "Address": {
          "AddressLine": [
            "1 Teststr."
          ],
          "City": "Karlsruhe",
          "CountryCode": "DE",
          "PostalCode": "76131"
        },
        "AttentionName": "Person Name",
        "ShipperNumber": "xxx"
      },
      "TaxInformationIndicator": "Y"
    }
  }
}

0 replies

Ansh dev nagar (Ansh-Dev-Nagar) · 2026-03-04T13:46:09Z

Ansh dev nagar (Ansh-Dev-Nagar)
Mar 4, 2026

Hi MarcoWel,

Thanks for the update. We've noted the UPS kg unit conversion issue and will look into it.

The return shipment API is still a work in progress; we have yet to finish the full implementation and documentation. We'll let you know once that's done.

1 reply

MarcoWel Mar 4, 2026
Author

Hi Ansh dev nagar (@Ansh-Dev-Nagar),
I have to re-add another issue - return shipment rating works for UPS (except the noted kg issue), but still not for Fedex.
It seems to work but displays wrong rates, as karrio is still requesting a DE->DE shipment from Fedex when asking for a US->DE shipment.

For return shipments, the return origin address needs to be set as shipper:
https://developer.fedex.com/api/en-us/catalog/rate/docs.html#operation/Rate%20and%20Transit%20times

karrio Request: same as for UPS issue above
Fedex request sent from Karrio (shipper and recipient are identical):

{
  "accountNumber": {
    "value": "xxx"
  },
  "rateRequestControlParameters": {
    "rateSortOrder": "COMMITASCENDING",
    "returnTransitTimes": true,
    "servicesNeededOnRateFailure": true
  },
  "requestedShipment": {
    "documentShipment": false,
    "packagingType": "YOUR_PACKAGING",
    "pickupType": "DROPOFF_AT_FEDEX_LOCATION",
    "preferredCurrency": "EUR",
    "rateRequestType": [
      "LIST",
      "ACCOUNT",
      "PREFERRED"
    ],
    "recipient": {
      "address": {
        "city": "Karlsruhe",
        "countryCode": "DE",
        "postalCode": "76131",
        "residential": false,
        "streetLines": [
          "1 Teststr."
        ]
      }
    },
    "requestedPackageLineItems": [
      {
        "declaredValue": {
          "amount": 0,
          "currency": "EUR"
        },
        "dimensions": {
          "height": 7.17,
          "length": 3.94,
          "units": "IN",
          "width": 13.27
        },
        "groupPackageCount": 1,
        "subPackagingType": "OTHER",
        "weight": {
          "units": "LB",
          "value": 2.2
        }
      }
    ],
    "shipDateStamp": "2026-03-04",
    "shipper": {
      "address": {
        "city": "Karlsruhe",
        "countryCode": "DE",
        "postalCode": "76131",
        "residential": false,
        "streetLines": [
          "1 Teststr."
        ]
      }
    },
    "totalWeight": 2.2
  }
}

Ansh dev nagar (Ansh-Dev-Nagar) · 2026-03-14T14:48:11Z

Ansh dev nagar (Ansh-Dev-Nagar)
Mar 14, 2026

Hi MarcoWel,

Thanks for the detailed reports - they helped us identify and fix real bugs in both UPS and FedEx return handling.

I wanted to clarify how return shipments work in Karrio, since there are two distinct flows that behave differently.

Flow 1: `return_address` - Alternate pickup location

return_address sets an alternate physical pickup location (ShipFrom for UPS / origin for FedEx).
It does NOT make the shipment a return - the direction stays shipper → recipient.

{
 "shipper": { "country_code": "DE", "city": "Berlin" },
 "recipient": { "country_code": "US" },
 "return_address": { "country_code": "DE", "city": "Munich" }
}

Field	Value
Direction	DE → US (unchanged)
Pickup from	`return_address` (Munich, DE)
Rates/services	DE → US

Use case: Your company address (shipper) is in Berlin, but the parcel ships from your warehouse in Munich. The direction and rates stay the same - only the physical pickup location changes.

Flow 2: `is_return: true` - Actual return shipment

is_return triggers the return shipment flow. Karrio auto-swaps shipper and recipient internally, so you provide addresses in the same orientation as the original outbound order - Karrio handles the reversal.

For shipment creation:

{
  "shipper": { "country_code": "DE" },
  "recipient": { "country_code": "US" },
  "is_return": true,
  "service": "ups_standard"
}

For rate fetching:

{
  "shipper": { "country_code": "DE" },
  "recipient": { "country_code": "US" },
  "options": { "is_return": true }
}

Field	Value
Direction	US → DE (auto-swapped)
Pickup from	Customer (US)
Rates/services	US → DE
Weight unit	Based on origin country (US → LBS)

What was happening in your case

From your reports, you were using return_address (Flow 1) to signal a return. Since is_return wasn't set, Karrio treated it as a normal shipment with an alternate pickup - leading to:

Country mismatches (ShipFrom country must match Shipper country)
Wrong services (domestic instead of international)
Wrong weight units (KG rejected for US-origin)
FedEx auth errors (wrong origin country)

The fix: Use Flow 2 with is_return: true instead.

What we fixed (PR #1016)

We also found and fixed bugs in both flows:

Shipment creation: ShipFrom/origin was pointing to the merchant instead of the customer in return shipments — fixed for both UPS and FedEx
Rate fetching: rate.py had no is_return awareness — rates were fetched in the wrong direction with wrong weight units — fixed for both UPS and FedEx

Note: Currently is_return is only available via the API (POST /v1/shipments, POST /v1/proxy/rates). The dashboard UI doesn't have an is_return toggle yet, that's on our roadmap. In the meantime, you can test return shipments by calling the API directly with is_return: true.

2 replies

MarcoWel Mar 14, 2026
Author

Hi Ansh dev nagar (@Ansh-Dev-Nagar) and Dan (@danh91),
Thank you for the fixes and clear documentation! 💯

While we plan to integrate karrio into our ERP by API, we currently test all the basic flows via the dashboard and also plan to use the dashboard to centralize many steps that are currently scattered over different carrier websites (e.g. rate comparison for different shipments).

The is_return checkbox should be a very easy addition to the dashboard and at the same time of great importance for many users, hopefully it can be implemented soon!

MarcoWel Mar 29, 2026
Author

It still seems unchanged in 2026.1.26.
Any update to adding is_return checkbox to the dashboard?

Karrio Shipping

Generate Return Shipments #951

Uh oh!

MarcoWel Jan 30, 2026

Replies: 6 comments · 3 replies

Uh oh!

Dan (danh91) Feb 7, 2026 Maintainer

Uh oh!

Uh oh!

MarcoWel Feb 8, 2026 Author

With "Add A Return Address"

Without "Add A Return Address"

Uh oh!

MarcoWel Feb 21, 2026 Author

Uh oh!

Uh oh!

MarcoWel Mar 4, 2026 Author

Requesting in kg - Error "Invalid Unit of Measurement"

Requesting in g - works fine

Uh oh!

Ansh dev nagar (Ansh-Dev-Nagar) Mar 4, 2026

Uh oh!

MarcoWel Mar 4, 2026 Author

Uh oh!

Uh oh!

Ansh dev nagar (Ansh-Dev-Nagar) Mar 14, 2026

Flow 1: return_address - Alternate pickup location

Flow 2: is_return: true - Actual return shipment

What was happening in your case

What we fixed (PR #1016)

Uh oh!

MarcoWel Mar 14, 2026 Author

Uh oh!

MarcoWel Mar 29, 2026 Author

MarcoWel
Jan 30, 2026

Replies: 6 comments 3 replies

Dan (danh91)
Feb 7, 2026
Maintainer

MarcoWel
Feb 8, 2026
Author

MarcoWel
Feb 21, 2026
Author

MarcoWel
Mar 4, 2026
Author

Ansh dev nagar (Ansh-Dev-Nagar)
Mar 4, 2026

MarcoWel Mar 4, 2026
Author

Ansh dev nagar (Ansh-Dev-Nagar)
Mar 14, 2026

Flow 1: `return_address` - Alternate pickup location

Flow 2: `is_return: true` - Actual return shipment

MarcoWel Mar 14, 2026
Author

MarcoWel Mar 29, 2026
Author