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 LABELViewer 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​