Skip to main content

Introduction

This section is dedicated to the karrio core shipping SDK. This SDK has been created based on a core set of abtractions required for common shipping services. The constructs and helpers functions provided constitute a framework for shipping integration.

The general architecture is an application of the translation pattern that maps various carrier APIs under a unified set of standardized data models.

The key features are:

  • Unified API: A standardized set of models representing the common shipping data (Address, Parcel, Shipment...)
  • Intuitive API: A library that abstracts and unifies the typical shipping API services (Rating, Pickup, Tracking...)
  • Multi-carrier: Integrate Karrio once and connect to multiple shipping carrier APIs
  • Custom carrier: A framework to integrate a shipping carrier services within minutes

Usage​

The Karrio SDK offer a modular set of packages. The karrio core package and all supported supported carrier as extensions.

It is therefore use the karrio SDK without any of the server API aspect of the project.

caution

The SDK is written in Python. Therefore, you can only use it within a Python project.

Using the karrio server APIs gives you a better interoperability with other languages and ecosystems.

Installation​

Requirements:

  • Python 3.10+
# Install karrio SDK core package
pip install karrio

# Install a carrier extension
pip install karrio.canadapost
Available carrier extensions
Carrier Pypi Packages
  • karrio.aramex
  • karrio.australiapost
  • karrio.canadapost
  • karrio.canpar
  • karrio.dhl-express
  • karrio.dhl-universal
  • karrio.dicom
  • karrio.fedex
  • karrio.purolator
  • karrio.royalmail
  • karrio.sendle
  • karrio.sf-express
  • karrio.tnt
  • karrio.ups
  • karrio.usps
  • karrio.usps-international
  • karrio.yanwen
  • karrio.yunexpress

Installation​

  • Fetch shipping rates
import karrio
from karrio.core.models import Address, Parcel, RateRequest
from karrio.mappers.canadapost.settings import Settings


# Initialize a carrier gateway
canadapost = karrio.gateway["canadapost"].create(
    Settings(
        username="username",
        password="password",
        customer_number="123456789",
        test=True
    )
)

# Fetching shipment rates

# Provide the shipper's address
shipper = Address(
    postal_code="V6M2V9",
    city="Vancouver",
    country_code="CA",
    state_code="BC",
    address_line1="5840 Oak St"
)

# Provide the recipient's address
recipient = Address(
    postal_code="E1C4Z8",
    city="Moncton",
    country_code="CA",
    state_code="NB",
    residential=False,
    address_line1="125 Church St"
)

# Specify your package dimensions and weight
parcel = Parcel(
    height=3.0,
    length=6.0,
    width=3.0,
    weight=0.5,
    weight_unit='KG',
    dimension_unit='CM'
)

# Prepare a rate request
rate_request = RateRequest(
    shipper=shipper,
    recipient=recipient,
    parcels=[parcel],
)

# Send a rate request using a carrier gateway
response = karrio.Rating.fetch(rate_request).from_(canadapost)

# Parse the returned response
rates, messages = response.parse()

print(rates)
# [
#     RateDetails(
#         carrier_name="canadapost",
#         carrier_id="canadapost",
#         currency="CAD",
#         transit_days=2,
#         service="canadapost_xpresspost",
#         discount=1.38,
#         base_charge=12.26,
#         total_charge=13.64,
#         duties_and_taxes=0.0,
#         extra_charges=[
#             ChargeDetails(name="Automation discount", amount=-0.37, currency="CAD"),
#             ChargeDetails(name="Fuel surcharge", amount=1.75, currency="CAD"),
#         ],
#         meta=None,
#         id=None,
#     )
# ]

Next steps​