Skip to main content

Shipping

Create

Once you fetch shipping rates and select your preferred service, your can submit your shipment to the carrier using the create function.

import karrio
from karrio.core.models import ShipmentRequest

request = ShipmentRequest(...)

shipment, messages = karrio.Shipment.create(request).from_(gateway).parse()

Parameters

ShipmentRequest

NameTypeDescription
servicestrrequired
shipperAddressrequired
recipientAddressrequired
parcelsList[Parcel]required
paymentPayment
customsCustoms
optionsdict
referencestr
label_typestr

Address

NameTypeDescription
idstr
postal_codestr
citystr
person_namestr
company_namestr
country_codestr
emailstr
phone_numberstr
state_codestr
residentialbool
address_line1str
address_line2str
federal_tax_idstr
state_tax_idstr
extraAddressExtra

AddressExtra

NameTypeDescription
street_namestr
street_numberstr
street_typestr
suburbstr
suitestr

Parcel

NameTypeDescription
idstr
weightfloat
widthfloat
heightfloat
lengthfloat
packaging_typestr
package_presetstr
descriptionstr
contentstr
is_documentbool
weight_unitstr
dimension_unitstr

Payment

NameTypeDescription
paid_bystr
currencystr
account_numberstr
idstr

Customs

NameTypeDescription
aesstr
eel_pfcstr
certifybool
signerstr
content_typestr
content_descriptionstr
incotermstr
invoicestr
invoice_datestr
license_numberstr
certificate_numberstr
commoditiesList[Commodity]
dutyDuty
commercial_invoicebool
optionsdict
idstr

Duty

NameTypeDescription
paid_bystr
currencystr
account_numberstr
declared_valuefloat
bill_toAddress
idstr

Commodity

NameTypeDescription
idstr
weightfloat
weight_unitstr
descriptionstr
quantityint
skustr
value_amountfloat
value_currencystr
origin_countrystr

Response

ShipmentDetails

NameTypeDescription
carrier_namestrrequired
carrier_idstrrequired
labelstrrequired
tracking_numberstrrequired
shipment_identifierstrrequired
selected_rateRateDetails
metadict
idstr

RateDetails

NameTypeDescription
carrier_namestrrequired
carrier_idstrrequired
currencystrrequired
transit_daysint
servicestr
discountfloat
base_chargefloat
total_chargefloat
duties_and_taxesfloat
extra_chargesList[ChargeDetails]
metadict
idstr

ChargeDetails

NameTypeDescription
namestr
amountfloat
currencystr

Message

NameTypeDescription
carrier_namestrrequired
carrier_idstrrequired
messageUnion[str, Any]
codestr
detailsdict

Code sample

import karrio
from karrio.core.models import Address, Parcel, ShipmentRequest, Payment

shipper = Address(
postal_code="V6M2V9",
city="Vancouver",
country_code="CA",
state_code="BC",
address_line1="5840 Oak St"
)

recipient = Address(
postal_code="E1C4Z8",
city="Moncton",
country_code="CA",
state_code="NB",
residential=False,
address_line1="125 Church St"
)

parcel = Parcel(
height=3.0,
length=6.0,
width=3.0,
weight=0.5,
weight_unit='KG',
dimension_unit='CM'
)

payment = Payment(paid_by="sender")

request = karrio.Shipment.create(
ShipmentRequest(
service="canadapost_xpresspost",
shipper=shipper,
recipient=recipient,
parcels=[parcel],
payment=payment
)
)

shipment, messages = request.from_(carrier_gateway).parse()
On success
print(shipment)
# ShipmentDetails(
# carrier_name="canadapost",
# carrier_id="canadapost",
# label="JVBERi0xLjQKJfbk/N8KMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovVmVyc2lvbiAvMS40CijEzMTA4MwolJUVPRgo=\n",
# tracking_number="123456789012",
# shipment_identifier="123456789012",
# selected_rate=None,
# meta=None,
# id=None,
# )

Cancel

Shipment previously submitted to the carrier server can be cancelled to void the attached label and let the carrier know that you do not intend to ship using the method selected anymore.

caution

It is recommended to cancel shipment (void the label printed) when you decide not to ship because some carriers will still bill you after a certain days for shipment submitted unless they are voided.

import karrio
from karrio.core.models import ShipmentCancelRequest

request = ShipmentCancelRequest(...)

confirmation, messages = karrio.Shipment.cancel(request).from_(carrier_gateway).parse()

Parameters

ShipmentCancelRequest

NameTypeDescription
shipment_identifierstrrequired
servicestr
optionsdict

Response

ConfirmationDetails

NameTypeDescription
carrier_namestrrequired
carrier_idstrrequired
successboolrequired
operationstrrequired

Message

NameTypeDescription
carrier_namestrrequired
carrier_idstrrequired
messageUnion[str, Any]
codestr
detailsdict

Code sample

import karrio
from karrio.core.models import ShipmentCancelRequest

request = karrio.Shipment.cancel(
ShipmentCancelRequest(
shipment_identifier='123456789012'
)
)

confirmation, messages = request.from_(carrier_gateway).parse()
On success
print(confirmation)
# ConfirmationDetails(
# carrier_name="canadapost",
# carrier_id="canadapost",
# success=True,
# operation="Cancel Shipment",
# )