Release/2026.1.19 (#1002)

* docs: add carrier testing report for MyDHL

* fix(shipment): rename status 'purchased' to 'created' across codebase

* fix(migration): data migration purchased→created + remove choices constraint from Shipment.status

* fix(mydhl): fix date parsing in rate and shipment requests and dimension null check

* fix(mydhl): add additionalDetails to error response schema and parser

* fix(mydhl): replace invalid PackagingType codes with DHL API spec values and make typeCode optional

* fix(mydhl): correct ShippingService product codes and services.csv to match DHL API spec

* fix(mydhl): resolve service name in shipment response using request context

* fix: mydhl pickup creation fails with extraneous countryName key

* fix: mydhl bundle multi-piece shipment labels from per-package documents

* fix: mydhl add missing product codes O and C to ShippingService enum

* docs(readme): add MCP server section with quick install and usage examples

* docs: update mydhl carrier testing report

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(usps): resolve KeyError 'PRIORITY_MAIL' in OptionEnum value lookup (#1003)

* fix(usps): resolve KeyError 'PRIORITY_MAIL' in OptionEnum value lookup

OptionEnum.__call__ was using name-based enum lookup (self.type[value].name)
which fails when the USPS API returns the mail class as its string value
(e.g. 'PRIORITY_MAIL') rather than the enum member name ('usps_priority_mail').

Fix: replace with self.type.map(value).name_or_key — the existing karrio SDK
helper that resolves by both name and value.

Flow that triggered the bug:
  rate.py:93 stores usps_mail_class=rate.mailClass ('PRIORITY_MAIL')
  ShipmentPurchaseSerializer passes option through shipping_options_initializer
  ShippingOptions.__init__ calls OptionEnum.__call__('PRIORITY_MAIL')
  ShippingService['PRIORITY_MAIL'] raises KeyError (member name is usps_priority_mail)

Also adds USPS OpenAPI specs to vendor/:
  - usps-domestic-labels.yaml (Labels API 3.9.8)
  - usps-domestic-prices.yaml (Domestic Prices v3)
  - usps-tracking.yaml (Tracking v3)
  - usps-international-labels.yaml (International Labels v3)
  - usps-addresses.yaml (Addresses v3)
  - usps-carrier-pickup.yaml (Carrier Pickup v3)

Reported by: Noel Ferreria <nferreria@ameripharma.us>

* fix(usps): normalize mailClass to karrio name in rate meta

The real failure point was gateway.py:296 merging selected_rate.meta
directly into payload options before calling the USPS connector:

  options = {**(selected_rate.meta or {}), **(payload.get('options') or {})}

rate.py stored the raw USPS API value (e.g. 'PRIORITY_MAIL') in meta,
which then reached OptionEnum.__call__ expecting a member name ('usps_priority_mail').

Fix: normalize at the source — map the raw API value to the karrio
member name when building rate meta:

  usps_mail_class=ShippingService.map(rate.mailClass).name_or_key

Also reverts the incorrect enum.py change — enum.py was correct all along.

* fix(core): handle enum API values in OptionEnum name resolution

When selected_rate.meta is merged into options (gateway.py:296), USPS
stores raw API values like 'PRIORITY_MAIL' in usps_mail_class. These
reach OptionEnum.__call__ where the original else-branch did a pure
name-based lookup (self.type[value]) that fails for API values.

Fix: three-way resolution —
  1. value has .map (enum object)  → type.map(value).name_or_key
  2. value is a member name        → type[value].name  (unchanged)
  3. value is an API value         → type.map(value).name_or_key (fallback)

rate.py meta is left as-is (raw API values) so existing tests pass.

* release: 2026.1.19

---------

Co-authored-by: Ansh Dev Nagar <anshdevnagar@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -1,3 +1,29 @@
+# Karrio 2026.1.19
+
+## Changes
+
+### Fix
+
+- fix(usps): resolve KeyError 'PRIORITY_MAIL' in OptionEnum value lookup (#1003)
+- fix(carriers/mydhl): carrier fixes and improvements
+- fix(shipment): rename status purchased→created, remove choices constraint, enrich tracker event
+- fix(mydhl): add missing product codes O and C to ShippingService enum
+- fix(mydhl): bundle multi-piece shipment labels from per-package documents
+- fix(mydhl): pickup creation fails with extraneous countryName key
+- fix(mydhl): resolve service name in shipment response using request context
+- fix(mydhl): correct ShippingService product codes and services.csv to match DHL API spec
+- fix(mydhl): replace invalid PackagingType codes with DHL API spec values and make typeCode optional
+- fix(mydhl): add additionalDetails to error response schema and parser
+- fix(mydhl): fix date parsing in rate and shipment requests and dimension null check
+- fix(migration): data migration purchased→created + remove choices constraint from Shipment.status
+
+### Docs
+
+- docs(mydhl): update carrier testing report
+- docs(readme): add MCP server section with quick install and usage examples
+
+---
+
 # Karrio 2026.1.18
 
 ## Changes

README.md

@@ -62,6 +62,59 @@ Default Login: `admin@example.com` | `demo`
   <img alt="Developer Tools" src="screenshots/developer-tools.png" width="800" style="max-width: 100%;" />
 </p>
 
+## MCP Server
+
+Karrio ships with a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server, letting AI assistants like Claude, Cursor, and Windsurf query rates, purchase labels, track shipments, and manage carriers directly from your IDE or chat interface.
+
+### Quick install
+
+**Claude Desktop / Cursor / Windsurf** — add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "karrio": {
+      "command": "uvx",
+      "args": ["karrio-mcp"],
+      "env": {
+        "KARRIO_API_KEY": "your_api_key",
+        "KARRIO_API_URL": "https://api.karrio.io"
+      }
+    }
+  }
+}
+```
+
+**Self-hosted instance:**
+
+```json
+{
+  "mcpServers": {
+    "karrio": {
+      "command": "uvx",
+      "args": ["karrio-mcp"],
+      "env": {
+        "KARRIO_API_KEY": "your_api_key",
+        "KARRIO_API_URL": "http://localhost:5002"
+      }
+    }
+  }
+}
+```
+
+### What you can do
+
+Once connected, ask your AI assistant things like:
+
+- _"Get me shipping rates from DHL and FedEx for a 2kg package to Germany"_
+- _"Purchase a UPS label for order #1234"_
+- _"Track shipment 1Z999AA10123456784"_
+- _"List my connected carrier accounts"_
+
+→ **[Full MCP server docs and tool reference](https://www.karrio.io/docs/developing/mcp-server)**
+
+---
+
 ## Get started
 
 ### Quick start demo

apps/api/karrio/server/VERSION

@@ -1 +1 @@
-2026.1.18
+2026.1.19

apps/web/public/carrier-integrations.json

@@ -14,7 +14,7 @@ info:
     ## Versioning
 
     When backwards-incompatible changes are made to the API, a new, dated version is released.
-    The current version is `2026.1.18`.
+    The current version is `2026.1.19`.
 
     Read our API changelog to learn more about backwards compatibility.
 
@@ -84,7 +84,7 @@ info:
     All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure).
     API requests without authentication will also fail.
   title: Karrio API
-  version: 2026.1.18
+  version: 2026.1.19
 paths:
   /:
     get:

apps/www/openapi.yml

@@ -2,7 +2,7 @@
 
 set -e
 
-export KARRIO_TAG="${KARRIO_TAG:-2026.1.18}"
+export KARRIO_TAG="${KARRIO_TAG:-2026.1.19}"
 export SENTRY_DSN="${SENTRY_DSN:-'https://public@sentry.example.com/1'}"
 
 SECRET_KEY=$(head -c 28 /dev/urandom | sha224sum -b | head -c 56)
@@ -22,7 +22,7 @@ echo ""
 if ! [ -z "$1" ]; then
     export KARRIO_TAG=$1
 else
-    echo "What version of Karrio would you like to install? (We default to '2026.1.18')"
+    echo "What version of Karrio would you like to install? (We default to '2026.1.19')"
     echo "You can check out available versions here: https://hub.docker.com/r/karrio/server/tags"
     read -r KARRIO_TAG_READ
     if [ -z "$KARRIO_TAG_READ" ]; then

bin/deploy-hobby

@@ -2,7 +2,7 @@
 
 set -e
 
-export KARRIO_TAG="${KARRIO_TAG:-2026.1.18}"
+export KARRIO_TAG="${KARRIO_TAG:-2026.1.19}"
 export SENTRY_DSN="${SENTRY_DSN:-'https://public@sentry.example.com/1'}"
 
 SECRET_KEY=$(head -c 28 /dev/urandom | sha224sum -b | head -c 56)

bin/deploy-insiders

@@ -41,7 +41,7 @@ else
 fi
 
 [[ -f ".env" ]] && export $(cat .env | xargs) || (echo "No .env file found. Please create it with SECRET_KEY and DOMAIN set." && exit 1)
-export KARRIO_TAG="${KARRIO_TAG:-2026.1.18}"
+export KARRIO_TAG="${KARRIO_TAG:-2026.1.19}"
 
 # get karrio scripts
 mkdir -p ./karrio

bin/upgrade-hobby

@@ -0,0 +1,220 @@
+# MyDHL Express — Carrier Testing
+
+## Metadata
+
+| Field                      | Value                                |
+|----------------------------|--------------------------------------|
+| **Carrier Name**           | `mydhl`                              |
+| **Carrier Display Name**   | MyDHL Express                        |
+| **Environment**            | Production (`express.api.dhl.com/mydhlapi`) |
+| **Connection Credentials** | DE production account configured in Dashboard |
+| **Last Tested**            | 2026-03-05                           |
+
+---
+
+## 1. Connection Setup
+
+> Verify the carrier can be connected and authenticated. MyDHL uses Basic Authentication with `username`, `password`, and `account_number`.
+
+- [x] Carrier connection created successfully in Dashboard
+- [x] Authentication succeeds (no credential errors)
+- [x] Connection appears in carrier list
+
+**Notes:** `account_number` (DHL billing number) is required — without it, rate/shipment requests fail with `"required key [number] not found"`.
+
+---
+
+## 2. Rating / Rate Fetching
+
+> Test rate retrieval for shipments. MyDHL provides a **live rate endpoint** via `/rates`.
+
+**Rate Type:** `Live API Endpoint`
+
+### Live API Endpoint:
+- [x] Fetch domestic rates successfully
+- [x] Fetch international rates successfully
+- [x] Rates returned for all expected services
+
+**DE Domestic (Bonn→Stuttgart):** 6 services returned in EUR — EXPRESS EASY/`mydhl_express_worldwide_b2c` (19.29), EXPRESS DOMESTIC/`mydhl_express_domestic` (27.26), EXPRESS DOMESTIC 12:00/`mydhl_express_domestic_12_00` (33.18), EXPRESS DOMESTIC 10:30/`mydhl_express_domestic_10_30` (45.00), EXPRESS DOMESTIC 9:00/`mydhl_express_domestic_9_00` (68.65), MEDICAL EXPRESS DOMESTIC/`mydhl_medical_express_domestic` (74.98).
+
+**DE→US International (Bonn→New York):** 5 services returned in EUR — EXPRESS EASY/`mydhl_express_easy` (112.01), EXPRESS WORLDWIDE/`mydhl_express_worldwide` (170.12), EXPRESS 12:00/`mydhl_express_9_00` (176.64), EXPRESS 10:30/`mydhl_globalmail_business` (189.69), MEDICAL EXPRESS/`mydhl_medical_express` (206.53).
+
+---
+
+## 3. Shipping / Shipment Creation
+
+> Test creating shipments and generating labels via `/shipments`.
+
+**Supported:** `Yes`
+
+### Basic Shipment
+- [x] Create domestic shipment with default service
+- [x] Label generated and downloadable as PDF
+- [x] Tracking number returned in response
+- [x] Shipment appears in shipment list
+
+### Service Coverage
+- [x] Create shipment with available services (list services tested below)
+
+| Service Code | Service Name | Product Code | Result |
+|---|---|---|---|
+| mydhl_express_worldwide_b2c | EXPRESS EASY | 7 | Pass (domestic) — tracking 4785851114, label PDF, 19.29 EUR |
+| mydhl_express_easy | EXPRESS EASY | 8 | Pass (international DE→US) — tracking 4960664505, label PDF, 112.01 EUR |
+| mydhl_express_worldwide | EXPRESS WORLDWIDE | P | Fail — `"Requested product(s) not available at origin"` (account limitation) |
+| mydhl_express_domestic | EXPRESS DOMESTIC | N | Fail — `"Requested product(s) not available at origin"` (account limitation) |
+
+### Multi-Piece Shipment
+- [ ] Create shipment with 2+ parcels — Not available (EXPRESS EASY 7/8 are single-piece only; domestic services N/1/O/I support multi-piece but are not available for this account)
+
+### International Shipment (if applicable)
+- [x] Create international shipment with customs info
+
+**Notes:** International shipment DE→US with customs (merchandise, DDU, commodity declaration) succeeded with `mydhl_express_easy`. Express Worldwide (P) and Express Domestic (N) are not available for this DE production account.
+
+---
+
+## 4. Label
+
+> Test label output options. MyDHL supports PDF, ZPL, LP2, and EPL label formats.
+
+**Supported:** `Yes`
+
+- [x] Label downloads as PDF (HTTP 200, 5414–9275 bytes)
+- [x] Label format matches requested format
+- [x] Label available via `label_url` and in `shipping_documents` base64
+
+**Available label formats:** `PDF`, `ZPL`, `LP2`, `EPL`
+
+---
+
+## 5. Shipment Cancellation
+
+> Test cancelling/voiding shipments.
+
+**Supported:** `No` — connector does not implement shipment cancellation with DHL API. Karrio allows soft cancel (status update only) but the shipment is not voided with DHL.
+
+---
+
+## 6. Tracking
+
+> Test tracking shipment status via `/tracking`.
+
+**Supported:** `Yes`
+
+- [x] Track a shipment by tracking number
+- [x] Tracking events returned with timestamps
+- [x] Tracking status reflects current state
+
+**Notes:** Newly created shipments return `pending` status. Events include timestamps and descriptions from DHL.
+
+---
+
+## 7. Pickup Scheduling
+
+> Test scheduling and managing pickups via `/pickups`.
+
+**Supported:** `Yes`
+
+### Schedule Pickup
+- [x] Schedule pickup with valid address and date
+- [x] Confirmation number returned
+- [x] Pickup appears in pickup list
+
+### Pickup with Shipment
+- [x] Schedule pickup associated with a shipment
+- [ ] Schedule pickup without an associated shipment (standalone)
+
+### Cancel Pickup
+- [x] Cancel a scheduled pickup
+- [x] Pickup status updates to cancelled
+
+**Notes:** Standalone pickup fails — parcel data not forwarded to connector when no tracking numbers provided (framework-level issue, not connector bug).
+
+---
+
+## 8. Return Shipment
+
+> Test return shipment creation.
+
+**Supported:** `Yes`
+
+- [x] Create return shipment
+- [x] Return label generated
+- [x] Return tracking number provided
+
+**Notes:** Return shipment created with `is_return: true`. Tracking number, label PDF, and rate returned successfully.
+
+---
+
+## Shipping Options Reference
+
+> Key shipping options available for testing.
+
+| Option | Type | Description |
+|---|---|---|
+| `mydhl_saturday_delivery` | bool | Saturday delivery (AA) |
+| `mydhl_hold_for_collection` | bool | Hold at service point (LX) |
+| `mydhl_duty_tax_paid` | bool | DTP — Duty/Tax Paid (DD) |
+| `mydhl_shipment_insurance` | float | Insurance value (II) |
+| `mydhl_dangerous_goods` | bool | Dangerous goods (HE) |
+| `mydhl_direct_signature` | bool | Direct signature required (SF) |
+| `mydhl_paperless_trade` | bool | Paperless trade (WY) |
+| `mydhl_gogreen_climate_neutral` | bool | GoGreen Carbon Neutral (EE) |
+
+---
+
+## Edge Cases & Error Handling
+
+> General robustness checks.
+
+- [x] Invalid credentials show clear error message
+- [x] Missing required fields return descriptive validation errors
+- [x] Error responses include `additionalDetails` with specific DHL error codes
+
+**Notes:** DHL returns `additionalDetails` array with granular error codes (e.g., `"1001: The requested product(s) (N) not available"`) — important to surface these to the user.
+
+---
+
+## Bugs Found
+
+> Bugs discovered during testing.
+
+### Bug 1: Date parsing error in rate and shipment requests — FIXED
+`lib.fdatetime` called without `current_format`. **Files:** `rate.py`, `shipment/create.py`
+
+### Bug 2: Invalid package typeCode — FIXED
+`typeCode` defaulted to "YP" even when unspecified. Made optional. **Files:** `units.py`, `shipment/create.py`, `pickup/create.py`
+
+### Bug 3: Label content not extracted — NOT A BUG
+Side effect of Bug 1+2 blocking shipment creation. Labels work correctly once those are fixed.
+
+### Bug 4: Service code mapping mismatches — FIXED
+Vendor OpenAPI spec had wrong product codes. Reverted to codes verified against live API. **Files:** `units.py`
+
+### Bug 5: Service name shows carrier name instead of actual service — FIXED
+Hardcoded `service=settings.carrier_name`. Fixed by forwarding service from request context. **Files:** `shipment/create.py`, `proxy.py`
+
+### Bug 6: Error responses missing additionalDetails — FIXED
+`ErrorResponseType` schema missing `additionalDetails` field. **Files:** `error_response.py`, `error.py`
+
+### Bug 7: Pickup fails with extraneous countryName key — FIXED
+DHL pickup API rejects `countryName` (shipment API accepts it). Removed from pickup create/update. **Files:** `pickup/create.py`, `pickup/update.py`
+
+---
+
+## Summary
+
+| Feature          | Status  |
+|------------------|---------|
+| Connection Setup | Pass    |
+| Rating           | Pass    |
+| Shipping         | Pass    |
+| Label            | Pass    |
+| Cancellation     | Not supported |
+| Tracking         | Pass    |
+| Pickup           | Pass    |
+| Return Shipment  | Pass    |
+
+**Overall Result:** Pass — all 7 bugs fixed
+
+**Additional Notes:** Tested against `express.api.dhl.com/mydhlapi` with DE production credentials. All core flows work end-to-end. Multi-piece not testable — Express Easy is single-piece only, other services unavailable for this account. Express Worldwide (P) and Express Domestic (N) unavailable — account limitation, not a connector bug.