Skip to main content

Shipments

Karrio exposes API endpoints that forwards shipping requests to the carrier's API.

Shipping Flow

From a technical perspective, the shipping process can visualized as follow

Prepare a package
Prepare a package
Yes
Yes
Require shipping details
- shipper address
- receiver address
- package weight & dimension
Require shipping details...
Receive a list of rates
Receive a list of rates

GET SHIPPING RATES

GET SHIPPING RATES
Buy a shipping label
Buy a shipping label
Yes
Yes
Require preferred shipping rate
Require preferred shipp...
Receive a shipping label
Receive a shipping label

GENERATE SHIPPING LABEL

GENERATE SHIPPING LABEL
Viewer does not support full SVG 1.1

Proxy Request APIs

The proxy APIs allow you to send shipping requests to carriers without creating any objects in karrio.

info

In that schenario, karrio is just a proxy that forward requests.

Get shipping rates

POST /v1/proxy/rates

You can use the this endpoint to get shipping rates from a carrier. based off the provided shipping details.

curl --request POST \
--url https://api.karrio.io/v1/proxy/rates \
--header 'Authorization: Token [API_KEY]' \
--header 'Content-Type: application/json' \
--data '{
"shipper": {
"postal_code": "V6M2V9",
"city": "Vancouver",
"country_code": "CA",
"state_code": "BC",
"residential": true,
"address_line1": "5840 Oak St"
},
"recipient": {
"postal_code": "E1C4Z8",
"city": "Moncton",
"country_code": "CA",
"state_code": "NB",
"residential": false,
"address_line1": "125 Church St"
},
"parcels": [{
"weight": 1,
"weight_unit": "KG",
"package_preset": "canadapost_corrugated_small_box"
}],
"carrier_ids": ["canadapost"]
}'

Buy shipping label

POST /v1/proxy/shipping

You can use this endpoint to buy a shipping service from a carrier and get a label in return.

To buy a shipping label, you need to provide the shipping details, the rates retrieved previously and the preferred rate' selected_rate_id.

curl --request POST \
--url https://api.karrio.io/v1/proxy/shipping \
--header 'Authorization: Token [API_KEY]' \
--header 'Content-Type: application/json' \
--data '{
"selected_rate_id": "rat_c84e2953599d4757b1d9265a5e36a54b",
"label_type": "PDF",
"options": {},
"recipient": {
"address_line1": "125 Church St",
"person_name": "John Doe",
"company_name": "A corp.",
"phone_number": "514 000 0000",
"city": "Moncton",
"country_code": "CA",
"postal_code": "E1C4Z8",
"residential": false,
"state_code": "NB"
},
"shipper": {
"address_line1": "5840 Oak St",
"person_name": "Jane Doe",
"company_name": "B corp.",
"phone_number": "514-000-0000",
"city": "Vancouver",
"country_code": "CA",
"postal_code": "V6M2V9",
"residential": false,
"state_code": "BC"
},
"parcels": [
{
"weight": 1,
"weight_unit": "LB",
"package_preset": "canadapost_corrugated_small_box"
}
],
"rates": [
{
"id": "rat_c84e2953599d4757b1d9265a5e36a54b",
"carrier_name": "canadapost",
"carrier_id": "canadapost",
"currency": "CAD",
"service": "canadapost_regular_parcel",
"discount": 3.52,
"base_charge": 27.06,
"total_charge": 35.17,
"duties_and_taxes": 4.59,
"transit_days": 10,
"extra_charges": [
{
"name": "Fuel surcharge",
"amount": 3.52,
"currency": "CAD"
}
],
"meta": {
"service_name": "CANADAPOST REGULAR PARCEL",
"rate_provider": "canadapost"
},
"carrier_ref": "car_773f4a5577e4471e8918a9a1d47b208b",
"test_mode": true
},
{
"id": "rat_c557e31a85ee46e6914545f0c4eb60fb",
"carrier_name": "canadapost",
"carrier_id": "canadapost",
"currency": "CAD",
"service": "canadapost_xpresspost",
"discount": 9.74,
"base_charge": 74.96,
"total_charge": 97.41,
"duties_and_taxes": 12.71,
"transit_days": 3,
"extra_charges": [
{
"name": "Fuel surcharge",
"amount": 9.74,
"currency": "CAD"
}
],
"meta": {
"service_name": "CANADAPOST XPRESSPOST",
"rate_provider": "canadapost"
},
"carrier_ref": "car_773f4a5577e4471e8918a9a1d47b208b",
"test_mode": true
}
],
"payment": {
"currency": "CAD",
"paid_by": "sender"
},
"reference": "Order Id: #1222"
}'

Shipments Management APIs

The shipments management APIs offer a set of endpoints around the karrio unified shipment object.

Create a shipment

POST /v1/shipments

You can use this endpoint to create a shipment object in the karrio system and retrieve shipping rates for it.

curl --request POST \
--url 'https://api.karrio.io/v1/shipments' \
--header 'Authorization: Token [API_KEY]' \
--header 'Content-Type: application/json' \
--data '{
"shipper": {
"postal_code": "E1C4Z8",
"city": "Moncton",
"federal_tax_id": null,
"state_tax_id": null,
"person_name": "John Doe",
"company_name": "A corp.",
"country_code": "CA",
"email": null,
"phone_number": "+1 514-000-0000",
"state_code": "NB",
"suburb": null,
"residential": false,
"address_line1": "125 Church St",
"address_line2": null,
"validate_location": null
},
"recipient": {
"postal_code": "V6M2V9",
"city": "Vancouver",
"person_name": "Jane Doe",
"company_name": "B corp.",
"country_code": "CA",
"email": null,
"phone_number": "+1 514-000-0000",
"state_code": "BC",
"residential": true,
"address_line1": "5840 Oak St",
"address_line2": null,
"validate_location": null
},
"parcels": [
{
"weight": 1,
"width": 46,
"height": 38,
"length": 32,
"packaging_type": null,
"package_preset": "canadapost_corrugated_medium_box",
"description": null,
"content": null,
"is_document": false,
"weight_unit": "KG",
"dimension_unit": "CM"
}
],
"options": {},
"carrier_ids": ["canadapost"]
}'

Buy the shipment label

POST /v1/shipments/{shipment_id}/purchase`

Since the shipment object is stored on the karrio server, all you need is to provide the preferred shipping rate id to buy the label.

curl --request POST \
--url https://api.karrio.io/v1/shipments/shp_e53f4d88846a48079e71c2fff81dfddc/purchase \
--header 'Authorization: Token [API_KEY]' \
--header 'Content-Type: application/json' \
--data '{
"selected_rate_id": "rat_314a24e3a2b3444a9c4f688daced0cb8"
}'

Next steps