šŸ“– Looking for karrio's legacy docs? Visit docs.karrio.io

Karrio Apps - Getting Started

Insiders
Enterprise

Karrio Apps enable developers to extend Karrio’s shipping platform with custom integrations, embedded user interfaces, and powerful automation. Whether you’re building internal tools or creating apps for the marketplace, this guide will help you get started.

What are Karrio Apps?

Karrio Apps are custom integrations that can:

  • Embed UI components directly in the Karrio dashboard
  • Access Karrio’s API with proper authentication and permissions
  • Store configuration data securely with encrypted credentials
  • Handle webhooks for real-time data synchronization
  • Integrate with external services like e-commerce platforms, ERPs, and carriers

Quick Start

1. Create Your First App

Start by creating a simple ā€œHello Worldā€ app to understand the basics:

Create a new app directory
1mkdir my-karrio-app 2cd my-karrio-app 3 4# Create the app manifest 5touch manifest.ts 6touch component.tsx

Create your app manifest:

manifest.ts
1import { AppManifest } from "@karrio/app-store/types"; 2 3export const manifest: AppManifest = { 4 id: "hello-world", 5 name: "Hello World", 6 version: "1.0.0", 7 description: "A simple hello world app for Karrio", 8 author: { 9 name: "Your Name", 10 email: "you@example.com", 11 }, 12 permissions: ["manage_shipments"], 13 assets: { 14 icon: "./assets/icon.svg", 15 screenshots: ["./assets/screenshot1.png"], 16 readme: "./README.md", 17 }, 18 components: { 19 main: "./component.tsx", 20 }, 21};

Create your main component:

component.tsx
1import React from "react"; 2import { AppComponentProps } from "@karrio/app-store/types"; 3 4export default function HelloWorldApp({ app, context }: AppComponentProps) { 5 const { user, organization } = context; 6 7 return ( 8 <div className="p-6"> 9 <h1 className="text-2xl font-bold mb-4">Hello World!</h1> 10 <p className="text-gray-600 mb-4"> 11 Welcome to your first Karrio app, {user.full_name}! 12 </p> 13 <div className="bg-gray-50 p-4 rounded-lg"> 14 <h2 className="font-semibold mb-2">App Information</h2> 15 <ul className="text-sm space-y-1"> 16 <li> 17 <strong>App ID:</strong> {app.id} 18 </li> 19 <li> 20 <strong>Organization:</strong> {organization.name} 21 </li> 22 <li> 23 <strong>Installation ID:</strong> {app.installation.id} 24 </li> 25 </ul> 26 </div> 27 </div> 28 ); 29}

2. Install and Test Your App

Install your app through the Karrio dashboard or via API:

1mutation InstallApp { 2 install_app( 3 input: { 4 app_id: "hello-world" 5 app_type: "private" 6 access_scopes: ["manage_shipments"] 7 } 8 ) { 9 installation { 10 id 11 app_id 12 api_key 13 is_active 14 } 15 errors { 16 field 17 messages 18 } 19 } 20}

Your app will now be available in the Karrio dashboard with its own dedicated space.

App Types

Karrio supports three types of apps:

Built-in Apps

Pre-installed apps that come with Karrio. These are developed and maintained by the Karrio team.

Install a built-in app
1const installation = await installApp({ 2 app_id: "shipping-optimizer", 3 app_type: "builtin", 4});

Marketplace Apps

Public apps available in the Karrio App Store. These go through a review process before being published.

Install a marketplace app
1const installation = await installApp({ 2 app_id: "shopify-integration", 3 app_type: "marketplace", 4 access_scopes: ["manage_shipments", "manage_orders"], 5});

Private Apps

Custom apps built for specific organizations. These can be internal tools or custom integrations.

Install a private app with OAuth
1const installation = await installApp({ 2 app_id: "custom-erp-sync", 3 app_type: "private", 4 requires_oauth: true, 5 oauth_app_data: { 6 display_name: "Custom ERP Sync", 7 launch_url: "https://your-app.com/karrio/launch", 8 redirect_uris: "https://your-app.com/karrio/callback", 9 }, 10});

App Architecture

Karrio Apps follow a structured architecture that ensures security, scalability, and maintainability:

Key Features

šŸ” Secure Authentication

  • Automatic API key generation for each app installation
  • OAuth2 integration for external service authentication
  • JWT-based session management for embedded apps
  • Encrypted credential storage

šŸŽØ Embedded UI Components

  • React-based component system
  • Access to Karrio’s design system and UI components
  • Responsive layouts that work across devices
  • Real-time data updates

šŸ”Œ API Integration

  • Full access to Karrio’s GraphQL and REST APIs
  • Scoped permissions for fine-grained access control
  • Rate limiting and request validation
  • Webhook support for real-time events

āš™ļø Configuration Management

  • Secure storage of app settings and credentials
  • User-friendly configuration interfaces
  • Environment-specific configurations
  • Automatic encryption of sensitive data

Development Workflow

1. Planning Your App

Before you start coding, consider:

  • What problem does your app solve?
  • What Karrio data do you need access to?
  • Do you need to integrate with external services?
  • Will your app have a user interface?

2. Setting Up Development

Clone the Karrio repository (for access to types and utilities)
1git clone https://github.com/karrioapi/karrio.git 2 3# Install dependencies 4npm install @karrio/app-store @karrio/types 5 6# Set up your development environment 7export KARRIO_API_URL="http://localhost:8000" 8export KARRIO_API_KEY="your-dev-api-key"

3. Building Your App

Follow the modular architecture:

1my-app/ 2ā”œā”€ā”€ manifest.ts # App configuration 3ā”œā”€ā”€ component.tsx # Main React component 4ā”œā”€ā”€ configuration.tsx # Settings interface (optional) 5ā”œā”€ā”€ api/ # Server-side logic 6│ ā”œā”€ā”€ webhooks.ts # Webhook handlers 7│ └── sync.ts # Background jobs 8ā”œā”€ā”€ assets/ # Static assets 9│ ā”œā”€ā”€ icon.svg 10│ └── screenshots/ 11└── types.ts # TypeScript definitions

4. Testing and Deployment

  • Test your app in a development environment
  • Use the Karrio test suite for integration testing
  • Deploy to staging for user acceptance testing
  • Submit to the marketplace or install privately

Example Apps

Shipping Task Manager

A simple task management app for shipping operations:

1import React, { useState } from "react"; 2import { Button, Card, Badge } from "@karrio/ui"; 3 4export default function ShippingTasksApp({ app, karrio }) { 5 const [tasks, setTasks] = useState([]); 6 7 const addTask = async (title: string, priority: string) => { 8 const task = { 9 id: Date.now().toString(), 10 title, 11 priority, 12 completed: false, 13 created_at: new Date().toISOString(), 14 }; 15 16 setTasks([...tasks, task]); 17 18 // Optionally sync with external system 19 await karrio.post("/api/tasks", task); 20 }; 21 22 return ( 23 <div className="space-y-4"> 24 <div className="flex justify-between items-center"> 25 <h2 className="text-xl font-semibold">Shipping Tasks</h2> 26 <Button onClick={() => addTask("New Task", "medium")}>Add Task</Button> 27 </div> 28 29 <div className="grid gap-4"> 30 {tasks.map((task) => ( 31 <Card key={task.id} className="p-4"> 32 <div className="flex justify-between items-center"> 33 <h3 className="font-medium">{task.title}</h3> 34 <Badge variant={task.priority}>{task.priority}</Badge> 35 </div> 36 </Card> 37 ))} 38 </div> 39 </div> 40 ); 41}

E-commerce Integration

Connect Karrio with your e-commerce platform:

1export default function ShopifyIntegrationApp({ app, karrio, context }) { 2 const [connected, setConnected] = useState(false); 3 const [orders, setOrders] = useState([]); 4 5 const connectShopify = async () => { 6 // OAuth flow to connect with Shopify 7 const authUrl = await app.oauth.getAuthorizationUrl("shopify"); 8 window.location.href = authUrl; 9 }; 10 11 const syncOrders = async () => { 12 const shopifyOrders = await app.api.get("/shopify/orders"); 13 const shipments = await Promise.all( 14 shopifyOrders.map((order) => 15 karrio.createShipment({ 16 recipient: order.shipping_address, 17 parcels: order.line_items.map((item) => ({ 18 weight: item.weight, 19 description: item.title, 20 })), 21 }), 22 ), 23 ); 24 25 setOrders(shipments); 26 }; 27 28 return ( 29 <div className="space-y-6"> 30 {!connected ? ( 31 <div className="text-center py-8"> 32 <h2 className="text-xl mb-4">Connect your Shopify Store</h2> 33 <Button onClick={connectShopify}>Connect with Shopify</Button> 34 </div> 35 ) : ( 36 <div> 37 <div className="flex justify-between items-center mb-4"> 38 <h2 className="text-xl">Recent Orders</h2> 39 <Button onClick={syncOrders}>Sync Orders</Button> 40 </div> 41 42 {/* Order list and management */} 43 <OrdersList orders={orders} karrio={karrio} /> 44 </div> 45 )} 46 </div> 47 ); 48}

Next Steps

Ready to build your first Karrio app? Here’s what to explore next:

  1. Authentication - Learn about secure authentication methods
  2. Building Apps - Deep dive into app development
  3. App Manifest - Understand app configuration
  4. UI Components - Build beautiful interfaces
  5. API Integration - Connect with Karrio’s APIs
  6. Examples - See more real-world examples

Support

Need help building your app? Here are some resources:

  • Documentation: Comprehensive guides and API references
  • Community: Join our Discord server for discussions
  • GitHub: Report issues and contribute to the platform
  • Support: Contact our team for enterprise support

Ready to transform shipping with custom apps? Let’s build something amazing together!