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:

Authentication - Learn about secure authentication methods
Building Apps - Deep dive into app development
App Manifest - Understand app configuration
UI Components - Build beautiful interfaces
API Integration - Connect with Karrio’s APIs
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!

Product Guides

Control Plane

Developer Tools