Karrio OSS 2025.5 (Yayra Edition)

[danh91]

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.

flowchart TB
    subgraph Client["Client Application"]
        API[Karrio API]
    end

    subgraph Core["Core Shipping Operations"]
        Rating[Rating]
        Shipping[Shipping]
        Tracking[Tracking]
        Pickup[Pickup]
    end

    subgraph NewInterfaces["New Interfaces (2025.5)"]
        Hooks[Hooks Interface]
        Duties[Duties Interface]
        Insurance[Insurance Interface]
        Webhook[Webhook Interface]
        AuthProxy[Auth Proxy Interface]
    end

    subgraph Existing["Existing Interfaces"]
        Address[Address Validation]
        Manifest[Manifest]
        Document[Document Upload]
    end

    subgraph Plugins["Carrier & LSP Plugins"]
        Carriers[UPS, FedEx, DHL...]
        LSPs[Avalara, InsureShield...]
    end

    API --> Core
    API --> NewInterfaces
    API --> Existing

    Core --> Plugins
    NewInterfaces --> Plugins
    Existing --> Plugins

Loading

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

---

This discussion was created from the release Karrio OSS 2025.5 (Yayra Edition).