Orders Management

Community Edition

Core Feature

Every Karrio project comes with comprehensive order management capabilities, providing a complete system to create, manage, and track order records with line items, customer information, and fulfillment workflows.

Features

Complete Order Lifecycle

You don’t have to build order management from scratch. Our orders system provides complete lifecycle management from creation to fulfillment and delivery tracking.

Orders Management Dashboard

Rate comparison interface with carrier options and pricing

Line Items Management

Manage detailed line items with SKU, quantity, weight, and pricing information for accurate fulfillment and shipping calculations.

Shipment Integration

Seamlessly link orders to shipments for complete fulfillment tracking and automated status updates.

Customer Information

Store comprehensive customer details including shipping addresses, contact information, and order preferences.

Status Tracking

Track orders through the entire fulfillment lifecycle with customizable status workflows and automated updates.

Additional features

Karrio extends orders with real-time fulfillment status synchronization.
Every order includes comprehensive metadata support for integration needs.
Karrio manages automatic order-to-shipment linking and status updates.
Support for bulk order operations and batch processing.

Data Flow

Order Management Flow

API Reference

REST API

Create Order

1curl -X POST "https://api.karrio.io/v1/orders" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "order_id": "ORDER-2024-001",
6    "order_date": "2024-01-15",
7    "source": "API",
8    "shipping_to": {
9      "person_name": "John Doe",
10      "company_name": "Acme Corp",
11      "email": "john@acme.com",
12      "phone_number": "+1234567890",
13      "address_line1": "123 Customer Street",
14      "city": "New York",
15      "state_code": "NY",
16      "postal_code": "10001",
17      "country_code": "US"
18    },
19    "shipping_from": {
20      "company_name": "Warehouse Inc",
21      "address_line1": "456 Warehouse Ave",
22      "city": "Chicago",
23      "state_code": "IL",
24      "postal_code": "60601",
25      "country_code": "US"
26    },
27    "line_items": [
28      {
29        "sku": "WIDGET-001",
30        "title": "Red Widget",
31        "quantity": 2,
32        "weight": 1.5,
33        "weight_unit": "LB",
34        "value_amount": 25.00,
35        "value_currency": "USD"
36      },
37      {
38        "sku": "GADGET-002",
39        "title": "Blue Gadget",
40        "quantity": 1,
41        "weight": 0.8,
42        "weight_unit": "LB",
43        "value_amount": 15.00,
44        "value_currency": "USD"
45      }
46    ],
47    "options": {
48      "currency": "USD",
49      "shipping_method": "ground"
50    },
51    "metadata": {
52      "customer_id": "CUST-12345",
53      "order_source": "website"
54    }
55  }'

Response:

1{
2  "id": "ord_1234567890",
3  "order_id": "ORDER-2024-001",
4  "order_date": "2024-01-15",
5  "source": "API",
6  "status": "unfulfilled",
7  "shipping_to": {
8    "person_name": "John Doe",
9    "company_name": "Acme Corp",
10    "email": "john@acme.com",
11    "phone_number": "+1234567890",
12    "address_line1": "123 Customer Street",
13    "city": "New York",
14    "state_code": "NY",
15    "postal_code": "10001",
16    "country_code": "US"
17  },
18  "shipping_from": {
19    "company_name": "Warehouse Inc",
20    "address_line1": "456 Warehouse Ave",
21    "city": "Chicago",
22    "state_code": "IL",
23    "postal_code": "60601",
24    "country_code": "US"
25  },
26  "line_items": [
27    {
28      "id": "cdt_549f66b743a147958f084f5b1928e08e",
29      "sku": "WIDGET-001",
30      "title": "Red Widget",
31      "quantity": 2,
32      "unfulfilled_quantity": 2,
33      "weight": 1.5,
34      "weight_unit": "LB",
35      "value_amount": 25.0,
36      "value_currency": "USD"
37    },
38    {
39      "id": "cdt_e44ecabf0d904aa9b45d1139d4ce045a",
40      "sku": "GADGET-002",
41      "title": "Blue Gadget",
42      "quantity": 1,
43      "unfulfilled_quantity": 1,
44      "weight": 0.8,
45      "weight_unit": "LB",
46      "value_amount": 15.0,
47      "value_currency": "USD"
48    }
49  ],
50  "test_mode": false,
51  "created_at": "2024-01-15T10:30:00Z",
52  "updated_at": "2024-01-15T10:30:00Z"
53}

Get Order

1curl -X GET "https://api.karrio.io/v1/orders/ord_1234567890" \
2  -H "Authorization: Token YOUR_API_KEY"

Response:

1{
2  "id": "ord_1234567890",
3  "order_id": "ORDER-2024-001",
4  "order_date": "2024-01-15",
5  "source": "API",
6  "status": "fulfilled",
7  "shipping_to": {
8    "person_name": "John Doe",
9    "company_name": "Acme Corp",
10    "email": "john@acme.com",
11    "address_line1": "123 Customer Street",
12    "city": "New York",
13    "state_code": "NY",
14    "postal_code": "10001",
15    "country_code": "US"
16  },
17  "line_items": [
18    {
19      "id": "cdt_549f66b743a147958f084f5b1928e08e",
20      "sku": "WIDGET-001",
21      "title": "Red Widget",
22      "quantity": 2,
23      "unfulfilled_quantity": 0,
24      "weight": 1.5,
25      "weight_unit": "LB",
26      "value_amount": 25.0,
27      "value_currency": "USD"
28    }
29  ],
30  "shipments": [
31    {
32      "id": "shp_0987654321",
33      "tracking_number": "1Z12345E0205271688",
34      "carrier_name": "ups",
35      "status": "purchased"
36    }
37  ],
38  "test_mode": false,
39  "created_at": "2024-01-15T10:30:00Z",
40  "updated_at": "2024-01-16T14:20:00Z"
41}

List Orders

1curl -X GET "https://api.karrio.io/v1/orders?status=unfulfilled&limit=10" \
2  -H "Authorization: Token YOUR_API_KEY"

Response:

1{
2  "count": 35,
3  "next": "/v1/orders?status=unfulfilled&limit=10&offset=10",
4  "previous": null,
5  "results": [
6    {
7      "id": "ord_1234567890",
8      "order_id": "ORDER-2024-001",
9      "order_date": "2024-01-15",
10      "status": "unfulfilled",
11      "shipping_to": {
12        "person_name": "John Doe",
13        "city": "New York",
14        "state_code": "NY"
15      },
16      "created_at": "2024-01-15T10:30:00Z"
17    },
18    {
19      "id": "ord_2345678901",
20      "order_id": "ORDER-2024-002",
21      "order_date": "2024-01-15",
22      "status": "unfulfilled",
23      "shipping_to": {
24        "person_name": "Jane Smith",
25        "city": "Los Angeles",
26        "state_code": "CA"
27      },
28      "created_at": "2024-01-15T11:45:00Z"
29    }
30  ]
31}

Update Order Status

1curl -X PATCH "https://api.karrio.io/v1/orders/ord_1234567890" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "options": {
6      "priority": "high",
7      "special_instructions": "Handle with care"
8    },
9    "metadata": {
10      "updated_by": "admin",
11      "notes": "Customer requested expedited shipping"
12    }
13  }'

Response:

1{
2  "id": "ord_1234567890",
3  "order_id": "ORDER-2024-001",
4  "status": "unfulfilled",
5  "options": {
6    "currency": "USD",
7    "shipping_method": "ground",
8    "priority": "high",
9    "special_instructions": "Handle with care"
10  },
11  "metadata": {
12    "customer_id": "CUST-12345",
13    "order_source": "website",
14    "updated_by": "admin",
15    "notes": "Customer requested expedited shipping"
16  },
17  "updated_at": "2024-01-15T15:30:00Z"
18}

Create Shipment from Order

When creating a shipment from an order, Karrio automatically links the order line items to the shipment parcels using the parent_id field. This mechanism enables accurate fulfillment tracking and order status computation.

1curl -X POST "https://api.karrio.io/v1/shipments" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "carrier_ids": ["ups-account"],
6    "label_type": "PDF",
7    "metadata": {
8      "order_ids": "ORDER-2024-001"
9    },
10    "options": {
11      "currency": "USD",
12      "declared_value": 65.00,
13      "preferred_service": "ups_ground"
14    },
15    "parcels": [
16      {
17        "weight": 3.1,
18        "weight_unit": "LB",
19        "dimension_unit": "IN",
20        "height": 6,
21        "length": 12,
22        "width": 8,
23        "items": [
24          {
25            "description": "Red Widget",
26            "quantity": 2,
27            "weight": 1.5,
28            "weight_unit": "LB",
29            "value_amount": 25.00,
30            "value_currency": "USD",
31            "parent_id": "cdt_549f66b743a147958f084f5b1928e08e"
32          },
33          {
34            "description": "Blue Gadget",
35            "quantity": 1,
36            "weight": 0.8,
37            "weight_unit": "LB",
38            "value_amount": 15.00,
39            "value_currency": "USD",
40            "parent_id": "cdt_e44ecabf0d904aa9b45d1139d4ce045a"
41          }
42        ]
43      }
44    ],
45    "recipient": {
46      "person_name": "John Doe",
47      "company_name": "Acme Corp",
48      "address_line1": "123 Customer Street",
49      "city": "New York",
50      "state_code": "NY",
51      "postal_code": "10001",
52      "country_code": "US"
53    },
54    "shipper": {
55      "company_name": "Warehouse Inc",
56      "address_line1": "456 Warehouse Ave",
57      "city": "Chicago",
58      "state_code": "IL",
59      "postal_code": "60601",
60      "country_code": "US"
61    }
62  }'

Response:

1{
2  "id": "shp_0987654321",
3  "carrier_name": "ups",
4  "service": "ups_ground",
5  "tracking_number": "1Z12345E0205271688",
6  "status": "purchased",
7  "selected_rate": {
8    "total_charge": 15.99,
9    "currency": "USD",
10    "service": "ups_ground"
11  },
12  "parcels": [
13    {
14      "items": [
15        {
16          "description": "Red Widget",
17          "quantity": 2,
18          "parent_id": "cdt_549f66b743a147958f084f5b1928e08e"
19        },
20        {
21          "description": "Blue Gadget",
22          "quantity": 1,
23          "parent_id": "cdt_e44ecabf0d904aa9b45d1139d4ce045a"
24        }
25      ]
26    }
27  ],
28  "label_url": "https://api.karrio.io/v1/documents/label_123.pdf",
29  "created_at": "2024-01-15T16:00:00Z"
30}

Order Fulfillment

Critical: The parent_id field in shipment parcel items references the id of order line items. This enables Karrio to:

Track Fulfillment: Determine how much of each line item has been shipped
Compute Order Status: Automatically update order status based on fulfillment progress
Handle Partial Fulfillment: Support multiple shipments for a single order
Maintain Inventory Accuracy: Track unfulfilled quantities per line item

Example Flow:

1Order Line Item (id: cdt_549f66b743a147958f084f5b1928e08e)
2├── quantity: 2
3├── unfulfilled_quantity: 2 (initially)
4└── Shipment Parcel Item (parent_id: cdt_549f66b743a147958f084f5b1928e08e)
5    ├── quantity: 2 (fulfills entire line item)
6    └── unfulfilled_quantity: 0 (after shipment)

When Karrio processes the shipment, it:

Matches parcel items to order line items using parent_id
Reduces unfulfilled_quantity by the shipped quantity
Updates order status when all line items are fully shipped

GraphQL API

Query Orders

1query GetOrders($filter: OrderFilter) {
2  orders(filter: $filter) {
3    edges {
4      node {
5        id
6        order_id
7        status
8        source
9        shipping_to {
10          person_name
11          company_name
12          email
13          phone_number
14          address_line1
15          address_line2
16          city
17          state_code
18          postal_code
19          country_code
20        }
21        shipping_from {
22          person_name
23          company_name
24          address_line1
25          city
26          state_code
27          postal_code
28          country_code
29        }
30        billing_address {
31          person_name
32          company_name
33          email
34          address_line1
35          city
36          state_code
37          postal_code
38          country_code
39        }
40        line_items {
41          id
42          sku
43          title
44          description
45          quantity
46          unfulfilled_quantity
47          weight
48          weight_unit
49          value_amount
50          value_currency
51          origin_country
52          hs_code
53          metadata
54          parent_id
55        }
56        created_at
57        updated_at
58        created_by {
59          email
60          full_name
61        }
62        test_mode
63        options
64        metadata
65        shipments {
66          id
67          status
68          tracking_number
69        }
70      }
71    }
72    page_info {
73      count
74      has_next_page
75      has_previous_page
76      start_cursor
77      end_cursor
78    }
79  }
80}

Variables:

1{
2  "filter": {
3    "status": ["unfulfilled"],
4    "source": ["API"]
5  }
6}

Response:

1{
2  "data": {
3    "orders": {
4      "edges": [
5        {
6          "node": {
7            "id": "ord_1234567890",
8            "order_id": "ORDER-2024-001",
9            "status": "unfulfilled",
10            "source": "API",
11            "shipping_to": {
12              "person_name": "John Doe",
13              "company_name": "Acme Corp",
14              "email": "john@acme.com",
15              "phone_number": "+1234567890",
16              "address_line1": "123 Main St",
17              "address_line2": "Suite 100",
18              "city": "New York",
19              "state_code": "NY",
20              "postal_code": "10001",
21              "country_code": "US"
22            },
23            "shipping_from": {
24              "company_name": "Warehouse Inc",
25              "address_line1": "456 Warehouse Ave",
26              "city": "Chicago",
27              "state_code": "IL",
28              "postal_code": "60601",
29              "country_code": "US"
30            },
31            "billing_address": null,
32            "line_items": [
33              {
34                "id": "cdt_549f66b743a147958f084f5b1928e08e",
35                "sku": "WIDGET-001",
36                "title": "Red Widget",
37                "description": "Premium red widget",
38                "quantity": 2,
39                "unfulfilled_quantity": 2,
40                "weight": 1.5,
41                "weight_unit": "LB",
42                "value_amount": 25.0,
43                "value_currency": "USD",
44                "origin_country": "US",
45                "hs_code": "1234567890",
46                "metadata": {},
47                "parent_id": null
48              }
49            ],
50            "created_at": "2024-01-15T10:30:00Z",
51            "updated_at": "2024-01-15T10:30:00Z",
52            "created_by": {
53              "email": "admin@acme.com",
54              "full_name": "Admin User"
55            },
56            "test_mode": false,
57            "options": {},
58            "metadata": {},
59            "shipments": []
60          }
61        }
62      ],
63      "page_info": {
64        "count": 1,
65        "has_next_page": false,
66        "has_previous_page": false,
67        "start_cursor": "YXJyYXljb25uZWN0aW9uOjA=",
68        "end_cursor": "YXJyYXljb25uZWN0aW9uOjA="
69      }
70    }
71  }
72}

Create Order Mutation

1mutation CreateOrder($data: CreateOrderMutationInput!) {
2  create_order(data: $data) {
3    order {
4      id
5      order_id
6      status
7      source
8      shipping_to {
9        person_name
10        email
11        city
12        state_code
13      }
14      line_items {
15        id
16        sku
17        title
18        quantity
19        weight
20        value_amount
21      }
22    }
23    errors {
24      field
25      messages
26    }
27  }
28}

Variables:

1{
2  "data": {
3    "order_id": "ORDER-2024-002",
4    "shipping_to": {
5      "person_name": "Jane Smith",
6      "company_name": "Tech Solutions",
7      "email": "jane@techsolutions.com",
8      "phone_number": "+1987654321",
9      "address_line1": "789 Oak Avenue",
10      "city": "Los Angeles",
11      "state_code": "CA",
12      "postal_code": "90210",
13      "country_code": "US"
14    },
15    "shipping_from": {
16      "company_name": "Fulfillment Center",
17      "address_line1": "100 Industrial Blvd",
18      "city": "Phoenix",
19      "state_code": "AZ",
20      "postal_code": "85001",
21      "country_code": "US"
22    },
23    "line_items": [
24      {
25        "sku": "PRODUCT-003",
26        "title": "Premium Item",
27        "description": "High-quality premium product",
28        "quantity": 1,
29        "weight": 2.0,
30        "weight_unit": "LB",
31        "value_amount": 50.0,
32        "value_currency": "USD",
33        "origin_country": "US"
34      }
35    ],
36    "metadata": {
37      "channel": "website",
38      "campaign": "summer_sale"
39    },
40    "options": {
41      "signature_required": true
42    }
43  }
44}

Order Status Workflow

Standard Statuses

Orders support these standard status values:

unfulfilled - Order received, awaiting fulfillment
partial - Order partially fulfilled (some line items shipped)
fulfilled - Order fully fulfilled (all line items shipped)
delivered - Order has been delivered (automatically updated from tracking)
cancelled - Order has been cancelled

Status Transitions

Use Cases

E-commerce Integration

Perfect for online stores managing order fulfillment:

Order Processing: Create orders from shopping cart checkouts
Inventory Management: Track line items and quantities
Fulfillment Automation: Automatically create shipments from orders
Status Synchronization: Update order status based on shipment progress

Warehouse Management

Designed for warehouse and fulfillment operations:

Pick Lists: Generate pick lists from order line items
Batch Fulfillment: Process multiple orders simultaneously
Shipping Integration: Create optimized shipments from order data
Performance Tracking: Monitor fulfillment times and accuracy

Multi-Channel Commerce

Handle orders from multiple sales channels:

Channel Attribution: Track order source (website, marketplace, POS)
Unified Processing: Process orders from all channels consistently
Customer Data: Maintain comprehensive customer information
Cross-Channel Analytics: Analyze performance across channels

Integration Examples

Order-to-Shipment Workflow

1. Create order
1const order = await karrio.orders.create({
2  orderData: {
3    order_id: "ORDER-12345",
4    shipping_to: {
5      /* customer details */
6    },
7    line_items: [
8      /* line items */
9    ],
10  },
11});
12
13// 2. Create shipment from order
14const shipment = await karrio.shipments.create({
15  shipmentData: {
16    reference: order.order_id,
17    service: "fedex_ground",
18    recipient: order.shipping_to,
19    shipper: order.shipping_from,
20    parcels: order.line_items.map((item) => ({
21      weight: item.weight,
22      weight_unit: item.weight_unit || "LB",
23    })),
24    options: { insurance: 100.0 },
25  },
26});
27
28// 3. Order status automatically updates to "fulfilled"

Webhook Integration

1{
2  "type": "order.status_updated",
3  "data": {
4    "id": "ord_1234567890",
5    "order_id": "ORDER-2024-001",
6    "status": "delivered",
7    "previous_status": "fulfilled",
8    "shipments": [
9      {
10        "tracking_number": "1Z12345E0205271688",
11        "status": "delivered"
12      }
13    ]
14  }
15}

Getting Started

Ready to start managing orders with Karrio? Follow these steps:

Create your first order with customer details and line items
Set up fulfillment workflow to create shipments from orders
Configure status tracking to monitor order progress
Integrate with your systems using webhooks and APIs

Next Steps

Learn about shipments to fulfill your orders
Set up webhooks for order status notifications
Explore tracking to monitor order deliveries
Configure batch processing for bulk operations

Need help with order management? Join our community Discord or contact our support team.

Product Guides

Control Plane

Developer Tools

Orders Management

Features

Complete Order Lifecycle

Line Items Management

Shipment Integration

Customer Information

Status Tracking

Additional features

Data Flow

Order Management Flow

API Reference

REST API

Create Order

Get Order

List Orders

Update Order Status

Create Shipment from Order

Order Fulfillment

GraphQL API

Query Orders

Create Order Mutation

Order Status Workflow

Standard Statuses

Status Transitions

Use Cases

E-commerce Integration

Warehouse Management

Multi-Channel Commerce

Integration Examples

Order-to-Shipment Workflow

Webhook Integration

Getting Started

Next Steps