Shipping Rules

Automation

Insiders

PREVIEW

Every Karrio Insiders project comes with comprehensive shipping rules and automation capabilities, providing intelligent carrier selection, cost optimization, delivery time preferences, and business rule enforcement across all shipping operations.

Features

Multi-Carrier Rate Shopping

You don’t have to manually compare carrier rates. Our rate shopping engine automatically fetches rates from all configured carriers and presents the best options based on your criteria.

Shipping Rules Dashboard

Rate comparison interface with carrier options and pricing

Intelligent Carrier Selection

Automatically select the best carrier based on cost, delivery time, service level, or custom business rules.

Service-Level Filtering

Filter carriers and services based on delivery requirements, package restrictions, and destination capabilities.

Real-Time Rate Comparison

Get live rates from multiple carriers simultaneously with support for different package configurations and shipping options.

Custom Business Logic

Implement sophisticated carrier selection rules based on your business requirements and shipping strategies.

Additional features

Karrio extends rate shopping with carrier performance analytics and delivery time estimates.
Every rate request includes automatic fallback options for carrier failures.
Karrio manages rate caching and optimization for faster response times.
Support for zone skipping, dimensional weight pricing, and surcharge calculations.

Data Flow

Rate Shopping & Carrier Selection Flow

API Reference

REST API

Get Shipping Rates

1curl -X POST "https://api.karrio.io/v1/proxy/rates" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "shipper": {
6      "company_name": "Your Warehouse",
7      "address_line1": "123 Warehouse St",
8      "city": "Chicago",
9      "state_code": "IL",
10      "postal_code": "60601",
11      "country_code": "US"
12    },
13    "recipient": {
14      "person_name": "John Doe",
15      "address_line1": "456 Customer Ave",
16      "city": "New York",
17      "state_code": "NY",
18      "postal_code": "10001",
19      "country_code": "US"
20    },
21    "parcels": [
22      {
23        "weight": 2.5,
24        "weight_unit": "LB",
25        "length": 12,
26        "width": 8,
27        "height": 6,
28        "dimension_unit": "IN"
29      }
30    ]
31  }'

Response:

1{
2  "rates": [
3    {
4      "id": "rate_1234567890",
5      "carrier_name": "fedex",
6      "carrier_id": "fedex_connection",
7      "service": "fedex_ground",
8      "service_type": "ground",
9      "total_charge": 12.45,
10      "currency": "USD",
11      "transit_days": 3,
12      "delivery_date": "2024-01-18",
13      "meta": {
14        "service_name": "FedEx Ground"
15      }
16    },
17    {
18      "id": "rate_1234567891",
19      "carrier_name": "ups",
20      "carrier_id": "ups_connection",
21      "service": "ups_ground",
22      "service_type": "ground",
23      "total_charge": 11.89,
24      "currency": "USD",
25      "transit_days": 3,
26      "delivery_date": "2024-01-18",
27      "meta": {
28        "service_name": "UPS Ground"
29      }
30    },
31    {
32      "id": "rate_1234567892",
33      "carrier_name": "usps",
34      "carrier_id": "usps_connection",
35      "service": "usps_priority",
36      "service_type": "priority",
37      "total_charge": 9.95,
38      "currency": "USD",
39      "transit_days": 2,
40      "delivery_date": "2024-01-17",
41      "meta": {
42        "service_name": "USPS Priority Mail"
43      }
44    }
45  ],
46  "messages": []
47}

Carrier-Specific Rate Shopping

1curl -X POST "https://api.karrio.io/v1/proxy/rates" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "shipper": {
6      "address_line1": "123 Warehouse St",
7      "city": "Chicago",
8      "state_code": "IL",
9      "postal_code": "60601",
10      "country_code": "US"
11    },
12    "recipient": {
13      "person_name": "John Doe",
14      "address_line1": "456 Customer Ave",
15      "city": "New York",
16      "state_code": "NY",
17      "postal_code": "10001",
18      "country_code": "US"
19    },
20    "parcels": [
21      {
22        "weight": 2.5,
23        "weight_unit": "LB"
24      }
25    ],
26    "carrier_ids": ["fedex_connection", "ups_connection"]
27  }'

Response:

1{
2  "rates": [
3    {
4      "id": "rate_1234567890",
5      "carrier_name": "fedex",
6      "carrier_id": "fedex_connection",
7      "service": "fedex_ground",
8      "total_charge": 12.45,
9      "currency": "USD",
10      "transit_days": 3
11    },
12    {
13      "id": "rate_1234567891",
14      "carrier_name": "ups",
15      "carrier_id": "ups_connection",
16      "service": "ups_ground",
17      "total_charge": 11.89,
18      "currency": "USD",
19      "transit_days": 3
20    }
21  ],
22  "messages": []
23}

Service-Specific Requests

1curl -X POST "https://api.karrio.io/v1/proxy/rates" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "shipper": {
6      "address_line1": "123 Warehouse St",
7      "city": "Chicago",
8      "state_code": "IL",
9      "postal_code": "60601",
10      "country_code": "US"
11    },
12    "recipient": {
13      "person_name": "John Doe",
14      "address_line1": "456 Customer Ave",
15      "city": "New York",
16      "state_code": "NY",
17      "postal_code": "10001",
18      "country_code": "US"
19    },
20    "parcels": [
21      {
22        "weight": 2.5,
23        "weight_unit": "LB"
24      }
25    ],
26    "services": ["fedex_ground", "ups_ground", "usps_priority"]
27  }'

Response:

1{
2  "rates": [
3    {
4      "id": "rate_1234567890",
5      "carrier_name": "fedex",
6      "service": "fedex_ground",
7      "total_charge": 12.45,
8      "currency": "USD",
9      "transit_days": 3,
10      "meta": {
11        "service_name": "FedEx Ground"
12      }
13    },
14    {
15      "id": "rate_1234567891",
16      "carrier_name": "ups",
17      "service": "ups_ground",
18      "total_charge": 11.89,
19      "currency": "USD",
20      "transit_days": 3,
21      "meta": {
22        "service_name": "UPS Ground"
23      }
24    },
25    {
26      "id": "rate_1234567892",
27      "carrier_name": "usps",
28      "service": "usps_priority",
29      "total_charge": 9.95,
30      "currency": "USD",
31      "transit_days": 2,
32      "meta": {
33        "service_name": "USPS Priority Mail"
34      }
35    }
36  ],
37  "messages": []
38}

Create Shipment with Selected Rate

1curl -X POST "https://api.karrio.io/v1/proxy/shipments" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "selected_rate_id": "rate_1234567892",
6    "label_type": "PDF",
7    "references": ["ORDER-12345"]
8  }'

Response:

1{
2  "id": "shp_1234567890",
3  "carrier_name": "usps",
4  "carrier_id": "usps_connection",
5  "service": "usps_priority",
6  "tracking_number": "9400109999999999999999",
7  "shipment_identifier": "shp_1234567890",
8  "label_url": "https://api.karrio.io/v1/shipments/shp_1234567890/label.pdf",
9  "selected_rate": {
10    "id": "rate_1234567892",
11    "total_charge": 9.95,
12    "currency": "USD"
13  },
14  "status": "purchased",
15  "created_at": "2024-01-15T10:30:00Z"
16}

GraphQL API

Query Rates

1query GetRates($data: RateRequestInput!) {
2  rates(data: $data) {
3    rates {
4      id
5      carrier_name
6      carrier_id
7      service
8      service_type
9      total_charge
10      currency
11      transit_days
12      delivery_date
13      meta
14    }
15    messages {
16      code
17      message
18    }
19  }
20}

Variables:

1{
2  "data": {
3    "shipper": {
4      "company_name": "Your Warehouse",
5      "address_line1": "123 Warehouse St",
6      "city": "Chicago",
7      "state_code": "IL",
8      "postal_code": "60601",
9      "country_code": "US"
10    },
11    "recipient": {
12      "person_name": "John Doe",
13      "address_line1": "456 Customer Ave",
14      "city": "New York",
15      "state_code": "NY",
16      "postal_code": "10001",
17      "country_code": "US"
18    },
19    "parcels": [
20      {
21        "weight": 2.5,
22        "weight_unit": "LB"
23      }
24    ]
25  }
26}

Carrier Selection Strategies

Cost-Based Selection

Choose carriers based on shipping cost optimization:

Cheapest Option

1async function selectCheapestCarrier(shipmentData) {
2  const response = await karrio.proxy.fetchRates({
3    rateRequest: shipmentData,
4  });
5
6  if (!response.rates || response.rates.length === 0) {
7    throw new Error("No rates available");
8  }
9
10  // Sort by total charge (ascending)
11  const sortedRates = response.rates.sort(
12    (a, b) => a.total_charge - b.total_charge,
13  );
14
15  return sortedRates[0]; // Return cheapest rate
16}

Value-Based Selection

1async function selectBestValue(shipmentData) {
2  const response = await karrio.proxy.fetchRates({
3    rateRequest: shipmentData,
4  });
5
6  // Calculate value score (lower cost + faster delivery = higher score)
7  const ratesWithScore = response.rates.map((rate) => ({
8    ...rate,
9    valueScore: (1 / rate.total_charge) * (1 / rate.transit_days),
10  }));
11
12  // Sort by value score (descending)
13  const sortedRates = ratesWithScore.sort(
14    (a, b) => b.valueScore - a.valueScore,
15  );
16
17  return sortedRates[0];
18}

Service-Level Selection

Choose carriers based on delivery requirements:

Speed Priority

1async function selectFastestCarrier(shipmentData) {
2  const response = await karrio.proxy.fetchRates({
3    rateRequest: shipmentData,
4  });
5
6  // Filter rates with transit days information
7  const ratesWithTransit = response.rates.filter(
8    (rate) => rate.transit_days !== null,
9  );
10
11  // Sort by transit days (ascending)
12  const sortedRates = ratesWithTransit.sort(
13    (a, b) => a.transit_days - b.transit_days,
14  );
15
16  return sortedRates[0]; // Return fastest option
17}

Service Type Priority

1async function selectByServiceType(shipmentData, preferredType = "priority") {
2  const response = await karrio.proxy.fetchRates({
3    rateRequest: shipmentData,
4  });
5
6  // Filter by preferred service type
7  const preferredRates = response.rates.filter(
8    (rate) => rate.service_type === preferredType,
9  );
10
11  if (preferredRates.length > 0) {
12    // Return cheapest among preferred service type
13    return preferredRates.sort((a, b) => a.total_charge - b.total_charge)[0];
14  }
15
16  // Fallback to cheapest overall
17  return response.rates.sort((a, b) => a.total_charge - b.total_charge)[0];
18}

Advanced Selection Rules

Business Rules Engine

1class ShippingRulesEngine {
2  constructor(rules) {
3    this.rules = rules;
4  }
5
6  async selectCarrier(shipmentData, rates) {
7    // Apply rules in priority order
8    for (const rule of this.rules) {
9      const selectedRate = await rule.apply(rates, shipmentData);
10      if (selectedRate) {
11        return selectedRate;
12      }
13    }
14
15    // Default fallback
16    return rates.sort((a, b) => a.total_charge - b.total_charge)[0];
17  }
18}
19
20// Example rules
21const shippingRules = new ShippingRulesEngine([
22  {
23    name: "High-value items use FedEx",
24    apply: (rates, shipmentData) => {
25      const declaredValue = shipmentData.parcels.reduce(
26        (sum, parcel) => sum + (parcel.value || 0),
27        0,
28      );
29
30      if (declaredValue > 1000) {
31        return rates.find((rate) => rate.carrier_name === "fedex");
32      }
33      return null;
34    },
35  },
36  {
37    name: "International shipments prefer DHL",
38    apply: (rates, shipmentData) => {
39      const isInternational =
40        shipmentData.shipper.country_code !==
41        shipmentData.recipient.country_code;
42
43      if (isInternational) {
44        return rates.find((rate) => rate.carrier_name === "dhl");
45      }
46      return null;
47    },
48  },
49  {
50    name: "Rush orders use fastest service",
51    apply: (rates, shipmentData) => {
52      if (shipmentData.rush_delivery) {
53        return rates.sort((a, b) => a.transit_days - b.transit_days)[0];
54      }
55      return null;
56    },
57  },
58]);
59
60// Usage
61const rateResponse = await karrio.proxy.fetchRates({
62  rateRequest: shipmentData,
63});
64const selectedRate = await shippingRules.selectCarrier(
65  shipmentData,
66  rateResponse.rates,
67);

Rate Filtering & Constraints

Geographic Constraints

Filter rates based on destination capabilities:

1async function filterByDestination(shipmentData) {
2  const response = await karrio.proxy.fetchRates({
3    rateRequest: shipmentData,
4  });
5
6  // Filter out carriers that don't serve the destination
7  const validRates = response.rates.filter((rate) => {
8    // Custom logic to check if carrier serves destination
9    return isDestinationSupported(rate.carrier_name, shipmentData.recipient);
10  });
11
12  return validRates;
13}
14
15function isDestinationSupported(carrierName, recipient) {
16  // Example: USPS only serves US addresses
17  if (carrierName === "usps" && recipient.country_code !== "US") {
18    return false;
19  }
20
21  // Add more carrier-specific logic
22  return true;
23}

Package Restrictions

Filter rates based on package limitations:

1async function filterByPackageRestrictions(shipmentData) {
2  const response = await karrio.proxy.fetchRates({
3    rateRequest: shipmentData,
4  });
5
6  const validRates = response.rates.filter((rate) => {
7    return shipmentData.parcels.every((parcel) =>
8      isPackageAllowed(rate.carrier_name, parcel),
9    );
10  });
11
12  return validRates;
13}
14
15function isPackageAllowed(carrierName, parcel) {
16  const restrictions = {
17    usps: { maxWeight: 70, maxLength: 108 },
18    fedex: { maxWeight: 150, maxLength: 119 },
19    ups: { maxWeight: 150, maxLength: 108 },
20  };
21
22  const carrierLimits = restrictions[carrierName];
23  if (!carrierLimits) return true;
24
25  return (
26    parcel.weight <= carrierLimits.maxWeight &&
27    (parcel.length || 0) <= carrierLimits.maxLength
28  );
29}

Use Cases

E-commerce Optimization

Perfect for online stores optimizing shipping costs:

Dynamic Pricing: Show customers the best available rates in real-time
Cost Optimization: Automatically select cheapest options to maximize margins
Service Options: Offer multiple delivery speeds with transparent pricing
Zone Optimization: Route shipments through optimal carrier networks

Enterprise Shipping

Designed for large-scale shipping operations:

Volume Discounts: Apply negotiated rates automatically
SLA Compliance: Ensure delivery commitments are met
Carrier Diversification: Distribute volume across multiple carriers
Performance Monitoring: Track carrier performance metrics

Marketplace Platforms

Enable sellers to optimize their shipping strategies:

Seller Tools: Provide rate comparison tools for marketplace sellers
Platform Fees: Apply platform-specific shipping fees and markups
Buyer Experience: Show competitive shipping options to buyers
Logistics Optimization: Optimize fulfillment across multiple warehouses

Best Practices

Rate Shopping Optimization

Request Optimization

Batch rate requests when possible
Use carrier-specific requests for known preferences
Include all necessary package details for accurate rates

Error Handling

1async function getRatesWithFallback(rateRequest) {
2  try {
3    const rateResponse = await karrio.proxy.fetchRates({
4      rateRequest: rateRequest,
5    });
6    const rates = rateResponse;
7
8    if (!rates.rates || rates.rates.length === 0) {
9      // Try with fewer restrictions
10      return await karrio.proxy.fetchRates({
11        rateRequest: {
12          ...rateRequest,
13          carrier_ids: undefined, // Remove carrier restrictions
14          services: undefined, // Remove service restrictions
15        },
16      });
17    }
18
19    return rates;
20  } catch (error) {
21    console.error("Rate request failed:", error);
22
23    // Implement fallback logic
24    return await getFallbackRates(rateRequest);
25  }
26}

Performance Monitoring

Track rate request response times
Monitor carrier availability and success rates
Log rate selection decisions for analysis
Measure cost savings from optimization

Getting Started

Ready to implement intelligent shipping rules with Karrio? Follow these steps:

Set up rate shopping to compare carrier options
Define business rules for carrier selection
Implement selection logic based on your requirements
Monitor and optimize carrier performance

Next Steps

Learn about shipments to create shipments with selected rates
Explore carrier connections to configure available carriers
Set up webhooks for rate and shipment notifications
Configure batch processing for high-volume rate requests

Product Guides

Control Plane

Developer Tools

Shipping Rules

Features

Multi-Carrier Rate Shopping

Intelligent Carrier Selection

Service-Level Filtering

Real-Time Rate Comparison

Custom Business Logic

Additional features

Data Flow

Rate Shopping & Carrier Selection Flow

API Reference

REST API

Get Shipping Rates

Carrier-Specific Rate Shopping

Service-Specific Requests

Create Shipment with Selected Rate

GraphQL API

Query Rates

Carrier Selection Strategies

Cost-Based Selection

Cheapest Option

Value-Based Selection

Service-Level Selection

Speed Priority

Service Type Priority

Advanced Selection Rules

Business Rules Engine

Rate Filtering & Constraints

Geographic Constraints

Package Restrictions

Use Cases

E-commerce Optimization

Enterprise Shipping

Marketplace Platforms

Best Practices

Rate Shopping Optimization

Request Optimization

Error Handling

Performance Monitoring

Getting Started

Next Steps