Karrio patch 2025.5.2

Changes

Feat

• feat: consolidate apply_shipping_rules with support for single call label generation

Fix

• fix: server perf affected by Sentry + fix permission issues caused by carriers permission update

Karrio OSS 2025.5 (Yayra Edition)

Release Date: Dec 1st, 2025

Full Changelog: https://github.com/karrioapi/karrio/releases/tag/v2025.5

Blog Post: https://karrio.io/blog/karrio-2025-5-sustainability

Highlights

Karrio 2025.5 is a milestone release introducing a dual-license model to ensure long-term sustainability while preserving the open-source core. This release also includes significant technical improvements, new carrier integrations, and enhanced developer experience.

License Transition

Karrio now uses a dual-license structure:

• LGPL-3.0 for the open-source core (server, SDK, community plugins)
• Karrio Enterprise License for enterprise features (/ee directory)

This follows the proven models of Odoo and n8n—enabling a thriving open-source community alongside a sustainable business.

Discontinuation of Karrio Insiders

The Karrio Insiders program is discontinued in favor of a focused Karrio Enterprise License for embedding and white-labeling needs.
Existing Insiders donations and subscriptions will end December 31st.

What's New

New Interfaces & APIs

Karrio 2025.5 introduces a comprehensive set of interfaces that extend the platform's capabilities beyond core shipping operations. These interfaces allow carriers and LSP (Logistics Service Provider) plugins to provide specialized services.

Interface	Purpose	Example Use Cases
Hooks	Custom shipping logic integration points	Pre/post shipment processing, custom validations
Duties	International duties and taxes calculation	Landed cost estimation, DDP shipments
Insurance	Shipment protection capabilities	Third-party insurance providers, declared value
Webhook	Carrier webhook management	Real-time tracking updates, event subscriptions
Auth Proxy	Standardized OAuth/authentication	Carrier OAuth flows, token management

New Carrier Integrations

• Teleship - Full integration with OAuth, webhooks, and duties engine support
• Landmark Global - Cross-border e-commerce shipping (enhanced)
• DTDC - Indian courier and logistics integration

Dashboard & UI

• Migrated to shadcn/ui with Tailwind CSS
• Dark mode theme for developer tools
• New Karrio Dev Tools drawer
• Improved carrier connection management
• Enhanced settings and organization management
• Document template editor improvements
• Bulk print and shipment CSV export
• App Store for managing shipping apps (beta)
• Swagger API playground (replaced Redoc)
• Shippers addons management page

Performance & Reliability

• Resolved N+1 query issues across models and GraphQL
• Database lock fixes for SQLite-based workers
• Improved Redis configuration (REDIS_URL, REDIS_SSL support)
• HUEY worker initialization race condition fix
• Optimized archiving queries with batch processing
• Database indexes for date-based filters

Automation & Workflows

• Shipping Rules API and dashboard panels
• Workflows management for automated shipping logic
• has_alternative_services flag for carrier connections

Developer Experience

• Plugin development guide documentation
• Telemetry abstraction (Sentry, DataDog, OpenTelemetry)
• Loguru logging improvements
• AGENTS.md for AI-assisted development
• Improved error parsing and notifications
• Karrio CLI (kcli) with plugin management and carrier details
• SDK plugins loader with entrypoint support
• Docker-Compose plugins mount point (./plugins dir)
• x-tenant-id and x-request-id headers support

Security & Enterprise

• Limited scope API tokens for secure document downloads
• SSO metadata fields for organizations
• Secure Redis connection handling
• Admin session cookie customization
• Tenant isolation improvements

Breaking Changes

• Python SDK import: Changed from import karrio to import karrio.sdk as karrio
• Dashboard port: Default changed from 3000 to 3002
• Python version: Now requires >=3.11
• Deprecated carrier connections and custom models removed
• GraphQL query/mutation changes (see integration tests)
• Dashboard component refactor (shadcn migration)
• Headless UI removed in favor of shadcn/ui components

Bug Fixes

• OAuth token expiry calculation
• Package preset override regression
• Custom rate resolution with missing dimensions
• Order duplication and race conditions
• Shipment cancellation webhook format
• Email change token validation
• Organization dropdown errors
• Dashboard state management issues

Documentation

• Updated plugin development guide
• Redis setup instructions
• Dashboard navigation guide
• Missing environment variables documented

Upgrade Notes

1. Review the new LICENSE file
2. Insiders users: contact hello@karrio.io for questions
3. Update Python SDK imports: import karrio → import karrio.sdk as karrio
4. Update dashboard port references from 3000 to 3002
5. Ensure Python >=3.11 is installed
6. Check GraphQL queries and Shipping REST APIs for breaking changes

Contributors

Thanks to all contributors who made this release possible, including @mazzarito, @Ansh-Dev-Nagar @akaylia123 and @ashishdevnagar

Karrio preview 2025.5rc23

Changes

Feat

• feat: adds a button to copy docs pages for LLMs

Fix

• fix: redirection issue when the sign-in page is accessed directly
• fix: the readability of certain features on the documentation when in dark mode

Chore

• chore: set up Posthog for docs analytics

DevX

• devx: prevent node constant override to the latest version and set a minimum version for karrio development
• devx: debugging and improving dev and HTTPS support, both for development and production deployment
• devx: introduce AGENTS.md using cursor

Karrio preview 2025.5rc22

Changes

Feat

• feat: update sapient API options and fix max SKU length issue.
• feat: migrate shipment preview to Shadcn with enriched details.

Karrio preview 2025.5rc21

Changes

Feat

• feat: add support for thread lock caching and oauth access_token retrieval
• feat: remove selected_rate extraction on buy label for FedEx
• feat: improve live rate components and remove label type selection in label creation forms
• feat: set up ./plugins dir at the root of the Docker-Compose templates files to provide a default mounting point
• feat: added warning for mixed currencies in multiple items

Fix

• fix: FedEx default invoice generation behaviour and accountNumber data mapping
• fix: FedEx regression due to signature options handling behaviour change
• fix: for package level reference numbers (by @mazzarito)
• fix: generated type mismatch post schema regeneration for UPS
• fix: replaced create order with draft order
• fix: sync scrolling of left and right sections of draft-order page
• fix: removed unnecessary line-item unlinking mechanisms
• fix: dashboard-guide docs missing screenshots
• fix: removed sticky property of warning box

Docs

• docs: add open new terminal instructions
• docs: add missing screenshots for dashboard-guide docs
• docs: update docs to improve dashboard navigation guide and plugins mounting setup

Chore

• chore: ensure proper CSP setup for dashboard and website
• devX: update local development commands for starting the server

Karrio preview 2025.5rc20

Karrio 2025.5rc20

Changes

Feat

• feat: improve the new shadcn-based notifier error parsing
• feat: add tracing to connectors with OAuth support
• feat: improve UPS proxy auth error parsing
• feat: migrate draft order form to Shadcn and improve state management
• feat: migrate shipments list and page to Shadcn
• feat: migrate orders list and page to Shadcn
• feat: migrate trackers list and page to shadcn

Fix

• fix: FedEx rates parsing condition to use explicit None check

Karrio preview 2025.5rc19

Changes

Feat

• feat: combine title and description for a more exhaustive seko commodity descriptions for customs declaration

Fix

• fix: rendering loop issue in create_label form (by @Ansh-Dev-Nagar)
• fix: inconsistent max text length between models and serializers

Karrio preview 2025.5rc18

Karrio 2025.5rc18

Changes

Feat

• feat: add support for OpenTelemetry to Karrio server

Fix

• fix: missing workflow-trigger table migrations

Karrio preview 2025.5rc17

Changes

Fix

• fix: resolved module import error for karrio.server.admin.schemas.orgs in tenant GraphQL schema
• fix: enhanced UPS tracking status codes with comprehensive API documentation mapping
• fix: optimize N+1 query issues in tracking/shipment GraphQL resolvers with proper relationship prefetching
• fix: optimize N+1 query issues in constance configuration loading with bulk database operations
• fix: optimize N+1 query issues in data archiving tasks with bulk deletion for organization links
• fix: optimize N+1 query issues in carrier/organization access filtering for proxy endpoints
• fix: optimize N+1 query issues in tenant domain/client lookups with relationship prefetching
• fix: enhance all manager model querysets with organization relationship prefetching for multi-tenant mode
• fix: improve archiving query performance with optimized existence checks and batch processing
• fix: add database indexes for archiving date-based filters to reduce query execution time
• fix: refactor workflow scheduler error handling with cleaner diagnostic functions
• fix: add workflow-trigger table diagnostic migration for production database issues
• fix: resolve APILog proxy model index conflicts in Django migrations

Karrio preview 2025.5rc16

Karrio 2025.5rc16

Changes

Fix

• hotfix: document generation backward compatibility and improve document template editor