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​