Skip to main content

Karrio API (2024.2.15)

Download OpenAPI specification:Download

API Reference

Karrio is an open source multi-carrier shipping API that simplifies the integration of logistics carrier services.

The Karrio API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The Karrio API differs for every account as we release new versions. These docs are customized to your version of the API.

Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. The current version is 2024.2.15.

Read our API changelog to learn more about backwards compatibility.

As a precaution, use API versioning to check a new API version before committing to an upgrade.

Environments

The Karrio API offer the possibility to create and retrieve certain objects in test_mode. In development, it is therefore possible to add carrier connections, get live rates, buy labels, create trackers and schedule pickups in test_mode.

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list addresses, list shipments, and list trackers. These list API methods share a common structure, taking at least these two parameters: limit, and offset.

Karrio utilizes offset-based pagination via the offset and limit parameters. Both parameters take a number as value (see below) and return objects in reverse chronological order. The offset parameter returns objects listed after an index. The limit parameter take a limit on the number of objects to be returned from 1 to 100.

{
    "count": 100,
    "next": "/v1/shipments?limit=25&offset=50",
    "previous": "/v1/shipments?limit=25&offset=25",
    "results": [
        { ... },
    ]
}

Metadata

Updateable Karrio objects—including Shipment and Order have a metadata parameter. You can use this parameter to attach key-value data to these Karrio objects.

Metadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system on a Karrio Order object.

Do not store any sensitive information as metadata.

Authentication

API keys are used to authenticate requests. You can view and manage your API keys in the Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API token as the basic auth username value. You do not need to provide a password.

$ curl https://instance.api.com/v1/shipments \
    -u key_xxxxxx:
# The colon prevents curl from asking for a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Token key_xxxxxx" instead of -u key_xxxxxx.

All API requests must be made over HTTPS. API requests without authentication will also fail.

API

API instance metadata resources.

Instance Metadata

Responses

Response samples

Content type
application/json
{
  • "VERSION": "",
  • "APP_NAME": "",
  • "APP_WEBSITE": "",
  • "HOST": "",
  • "ADMIN": "",
  • "OPENAPI": "",
  • "GRAPHQL": "",
  • "AUDIT_LOGGING": true,
  • "ALLOW_SIGNUP": true,
  • "ALLOW_ADMIN_APPROVED_SIGNUP": true,
  • "ALLOW_MULTI_ACCOUNT": true,
  • "ADMIN_DASHBOARD": true,
  • "MULTI_ORGANIZATIONS": true,
  • "ORDERS_MANAGEMENT": true,
  • "APPS_MANAGEMENT": true,
  • "DOCUMENTS_MANAGEMENT": true,
  • "DATA_IMPORT_EXPORT": true,
  • "CUSTOM_CARRIER_DEFINITION": true,
  • "PERSIST_SDK_TRACING": true,
  • "ORDER_DATA_RETENTION": true,
  • "TRACKER_DATA_RETENTION": true,
  • "SHIPMENT_DATA_RETENTION": true,
  • "API_LOGS_DATA_RETENTION": true,
  • "WORKFLOW_MANAGEMENT": true
}

Data References

Responses

Response samples

Content type
application/json
{
  • "VERSION": "",
  • "APP_NAME": "",
  • "APP_WEBSITE": "",
  • "HOST": "",
  • "ADMIN": "",
  • "OPENAPI": "",
  • "GRAPHQL": "",
  • "AUDIT_LOGGING": true,
  • "ALLOW_SIGNUP": true,
  • "ALLOW_ADMIN_APPROVED_SIGNUP": true,
  • "ALLOW_MULTI_ACCOUNT": true,
  • "ADMIN_DASHBOARD": true,
  • "MULTI_ORGANIZATIONS": true,
  • "ORDERS_MANAGEMENT": true,
  • "APPS_MANAGEMENT": true,
  • "DOCUMENTS_MANAGEMENT": true,
  • "DATA_IMPORT_EXPORT": true,
  • "CUSTOM_CARRIER_DEFINITION": true,
  • "PERSIST_SDK_TRACING": true,
  • "ORDER_DATA_RETENTION": true,
  • "TRACKER_DATA_RETENTION": true,
  • "SHIPMENT_DATA_RETENTION": true,
  • "API_LOGS_DATA_RETENTION": true,
  • "WORKFLOW_MANAGEMENT": true,
  • "ADDRESS_AUTO_COMPLETE": { },
  • "countries": { },
  • "currencies": { },
  • "carriers": { },
  • "customs_content_type": { },
  • "incoterms": { },
  • "states": { },
  • "services": { },
  • "connection_configs": { },
  • "service_names": { },
  • "options": { },
  • "option_names": { },
  • "package_presets": { },
  • "packaging_types": { },
  • "payment_types": { },
  • "carrier_capabilities": { },
  • "service_levels": { }
}

Auth

API authentication resources.

Obtain auth token pair

Authenticate the user and return a token pair

Request Body schema: application/json
required
email
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "access": "string",
  • "refresh": "string"
}

Refresh auth token

Authenticate the user and return a token pair

Request Body schema: application/json
required
refresh
required
string

Responses

Request samples

Content type
application/json
{
  • "refresh": "string"
}

Response samples

Content type
application/json
{
  • "access": "string",
  • "refresh": "string"
}

Get verified JWT token

Get a verified JWT token pair by submitting a Two-Factor authentication code.

Request Body schema: application/json
required
refresh
required
string
otp_token
required
string

The OTP (One Time Password) token received by the user from the configured Two Factor Authentication method.

Responses

Request samples

Content type
application/json
{
  • "refresh": "string",
  • "otp_token": "string"
}

Response samples

Content type
application/json
{
  • "access": "string",
  • "refresh": "string"
}

Verify token

Verify an existent authentication token

Request Body schema: application/json
required
token
required
string

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "property1": null,
  • "property2": null
}

Carriers

This is an object representing your Karrio carrier account connectsions. You can retrieve all configured connections available to your Karrio account. The carrier_id is a nickname you assign to your connection.

List all carriers

Returns the list of configured carriers

Authorizations:
TokenBasicTokenOAuth2JWT
query Parameters
active
boolean
carrier_name
string

The unique carrier slug.
Values: allied_express, allied_express_local, amazon_shipping, aramex, asendia_us, australiapost, boxknight, bpost, canadapost, canpar, chronopost, colissimo, dhl_express, dhl_parcel_de, dhl_poland, dhl_universal, dicom, dpd, dpdhl, easypost, eshipper, fedex, fedex_ws, freightcom, generic, geodis, laposte, locate2u, nationex, purolator, roadie, royalmail, sendle, tge, tnt, ups, usps, usps_international, zoom2u

metadata_key
string
metadata_value
string
system_only
boolean

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results": [
    ]
}

Get carrier services

Retrieve a carrier's services

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
carrier_name
required
string

The unique carrier slug.
Values: allied_express, allied_express_local, amazon_shipping, aramex, asendia_us, australiapost, boxknight, bpost, canadapost, canpar, chronopost, colissimo, dhl_express, dhl_parcel_de, dhl_poland, dhl_universal, dicom, dpd, dpdhl, easypost, eshipper, fedex, fedex_ws, freightcom, generic, geodis, laposte, locate2u, nationex, purolator, roadie, royalmail, sendle, tge, tnt, ups, usps, usps_international, zoom2u

Responses

Response samples

Content type
application/json
{
  • "property1": null,
  • "property2": null
}

Retrieve a carrier account

Retrieve a carrier account.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object_type": "carrier",
  • "carrier_id": "string",
  • "carrier_name": "allied_express",
  • "display_name": "string",
  • "test_mode": true,
  • "active": true,
  • "capabilities": [
    ],
  • "metadata": { },
  • "config": { }
}

Addresses

This is an object representing your Karrio shipping address. You can retrieve all addresses related to your Karrio account. Address objects are linked to your shipment history, and can be used for recurring shipping to / from the same locations.

List all addresses

Retrieve all addresses.

Authorizations:
TokenBasicTokenOAuth2JWT

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results": [
    ]
}

Create an address

Create a new address.

Authorizations:
TokenBasicTokenOAuth2JWT
Request Body schema: application/json
required
postal_code
string or null <= 10 characters

The address postal code (required for shipment purchase)

city
string or null <= 30 characters

The address city. (required for shipment purchase)

federal_tax_id
string or null <= 20 characters

The party frederal tax id

state_tax_id
string or null <= 20 characters

The party state id

person_name
string or null <= 50 characters

Attention to (required for shipment purchase)

company_name
string or null <= 50 characters

The company name if the party is a company

country_code
required
string
Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AN" "AO" "AR" "AS" "AT" "AU" "AW" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BM" "BN" "BO" "BR" "BS" "BT" "BW" "BY" "BZ" "CA" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "ER" "ES" "ET" "FI" "FJ" "FK" "FM" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GT" "GU" "GW" "GY" "HK" "HN" "HR" "HT" "HU" "IC" "ID" "IE" "IL" "IN" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KV" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PR" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SY" "SZ" "TC" "TD" "TG" "TH" "TJ" "TL" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WS" "XB" "XC" "XE" "XM" "XN" "XS" "XY" "YE" "YT" "ZA" "ZM" "ZW"

The address country code

email
string or null

The party email

phone_number
string or null <= 20 characters

The party phone number.

state_code
string or null <= 20 characters

The address state code

residential
boolean or null
Default: false

Indicate if the address is residential or commercial (enterprise)

street_number
string or null <= 20 characters

The address street number

address_line1
string or null <= 50 characters

The address line with street number
(required for shipment purchase)

address_line2
string or null <= 50 characters

The address line with suite number

validate_location
boolean or null
Default: false

Indicate if the address should be validated

Responses

Request samples

Content type
application/json
{
  • "postal_code": "string",
  • "city": "string",
  • "federal_tax_id": "string",
  • "state_tax_id": "string",
  • "person_name": "string",
  • "company_name": "string",
  • "country_code": "AD",
  • "email": "string",
  • "phone_number": "string",
  • "state_code": "string",
  • "residential": false,
  • "street_number": "string",
  • "address_line1": "string",
  • "address_line2": "string",
  • "validate_location": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "postal_code": "string",
  • "city": "string",
  • "federal_tax_id": "string",
  • "state_tax_id": "string",
  • "person_name": "string",
  • "company_name": "string",
  • "country_code": "AD",
  • "email": "string",
  • "phone_number": "string",
  • "state_code": "string",
  • "residential": false,
  • "street_number": "string",
  • "address_line1": "string",
  • "address_line2": "string",
  • "validate_location": false,
  • "object_type": "address",
  • "validation": {
    }
}

Retrieve an address

Retrieve an address.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "postal_code": "string",
  • "city": "string",
  • "federal_tax_id": "string",
  • "state_tax_id": "string",
  • "person_name": "string",
  • "company_name": "string",
  • "country_code": "AD",
  • "email": "string",
  • "phone_number": "string",
  • "state_code": "string",
  • "residential": false,
  • "street_number": "string",
  • "address_line1": "string",
  • "address_line2": "string",
  • "validate_location": false,
  • "object_type": "address",
  • "validation": {
    }
}

Update an address

update an address.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string
Request Body schema: application/json
postal_code
string or null <= 10 characters

The address postal code (required for shipment purchase)

city
string or null <= 30 characters

The address city. (required for shipment purchase)

federal_tax_id
string or null <= 20 characters

The party frederal tax id

state_tax_id
string or null <= 20 characters

The party state id

person_name
string or null <= 50 characters

Attention to (required for shipment purchase)

company_name
string or null <= 50 characters

The company name if the party is a company

country_code
string
Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AN" "AO" "AR" "AS" "AT" "AU" "AW" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BM" "BN" "BO" "BR" "BS" "BT" "BW" "BY" "BZ" "CA" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "ER" "ES" "ET" "FI" "FJ" "FK" "FM" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GT" "GU" "GW" "GY" "HK" "HN" "HR" "HT" "HU" "IC" "ID" "IE" "IL" "IN" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KV" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PR" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SY" "SZ" "TC" "TD" "TG" "TH" "TJ" "TL" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WS" "XB" "XC" "XE" "XM" "XN" "XS" "XY" "YE" "YT" "ZA" "ZM" "ZW"

The address country code

email
string or null

The party email

phone_number
string or null <= 20 characters

The party phone number.

state_code
string or null <= 20 characters

The address state code

residential
boolean or null
Default: false

Indicate if the address is residential or commercial (enterprise)

street_number
string or null <= 20 characters

The address street number

address_line1
string or null <= 50 characters

The address line with street number
(required for shipment purchase)

address_line2
string or null <= 50 characters

The address line with suite number

validate_location
boolean or null
Default: false

Indicate if the address should be validated

Responses

Request samples

Content type
application/json
{
  • "postal_code": "string",
  • "city": "string",
  • "federal_tax_id": "string",
  • "state_tax_id": "string",
  • "person_name": "string",
  • "company_name": "string",
  • "country_code": "AD",
  • "email": "string",
  • "phone_number": "string",
  • "state_code": "string",
  • "residential": false,
  • "street_number": "string",
  • "address_line1": "string",
  • "address_line2": "string",
  • "validate_location": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "postal_code": "string",
  • "city": "string",
  • "federal_tax_id": "string",
  • "state_tax_id": "string",
  • "person_name": "string",
  • "company_name": "string",
  • "country_code": "AD",
  • "email": "string",
  • "phone_number": "string",
  • "state_code": "string",
  • "residential": false,
  • "street_number": "string",
  • "address_line1": "string",
  • "address_line2": "string",
  • "validate_location": false,
  • "object_type": "address",
  • "validation": {
    }
}

Discard an address

Discard an address.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "postal_code": "string",
  • "city": "string",
  • "federal_tax_id": "string",
  • "state_tax_id": "string",
  • "person_name": "string",
  • "company_name": "string",
  • "country_code": "AD",
  • "email": "string",
  • "phone_number": "string",
  • "state_code": "string",
  • "residential": false,
  • "street_number": "string",
  • "address_line1": "string",
  • "address_line2": "string",
  • "validate_location": false,
  • "object_type": "address",
  • "validation": {
    }
}

Parcels

This is an object representing your Karrio shipping parcel. Parcel objects are linked to your shipment history, and can be used for recurring shipping using the same packaging.

List all parcels

Retrieve all stored parcels.

Authorizations:
TokenBasicTokenOAuth2JWT

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results": [
    ]
}

Create a parcel

Create a new parcel.

Authorizations:
TokenBasicTokenOAuth2JWT
Request Body schema: application/json
required
weight
required
number <double>

The parcel's weight

width
number or null <double>

The parcel's width

height
number or null <double>

The parcel's height

length
number or null <double>

The parcel's length

packaging_type
string or null <= 50 characters

The parcel's packaging type.
Note that the packaging is optional when using a package preset.
values:
envelope pak tube pallet small_box medium_box your_packaging
For carrier specific packaging types, please consult the reference.

package_preset
string or null <= 50 characters

The parcel's package preset.
For carrier specific package presets, please consult the reference.

description
string or null <= 250 characters

The parcel's description

content
string or null <= 100 characters

The parcel's content description

is_document
boolean or null
Default: false

Indicates if the parcel is composed of documents only

weight_unit
required
string
Enum: "KG" "LB" "OZ" "G"

The parcel's weight unit

dimension_unit
string or null
Enum: "CM" "IN" null

The parcel's dimension unit

Array of objects (CommodityData)

The parcel items.

reference_number
string or null <= 100 characters

The parcel reference number.
(can be used as tracking number for custom carriers)

freight_class
string or null <= 6 characters

The parcel's freight class for pallet and freight shipments.

object
Default: {}
Parcel specific options.
    {
        "insurance": "100.00",
        "insured_by": "carrier",
    }
    

Responses

Request samples

Content type
application/json
{
  • "weight": 0.1,
  • "width": 0.1,
  • "height": 0.1,
  • "length": 0.1,
  • "packaging_type": "string",
  • "package_preset": "string",
  • "description": "string",
  • "content": "string",
  • "is_document": false,
  • "weight_unit": "KG",
  • "dimension_unit": "CM",
  • "items": [
    ],
  • "reference_number": "string",
  • "freight_class": "string",
  • "options": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "weight": 0.1,
  • "width": 0.1,
  • "height": 0.1,
  • "length": 0.1,
  • "packaging_type": "string",
  • "package_preset": "string",
  • "description": "string",
  • "content": "string",
  • "is_document": false,
  • "weight_unit": "KG",
  • "dimension_unit": "CM",
  • "items": [
    ],
  • "reference_number": "string",
  • "freight_class": "string",
  • "options": { },
  • "object_type": "parcel"
}

Retrieve a parcel

Retrieve a parcel.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "weight": 0.1,
  • "width": 0.1,
  • "height": 0.1,
  • "length": 0.1,
  • "packaging_type": "string",
  • "package_preset": "string",
  • "description": "string",
  • "content": "string",
  • "is_document": false,
  • "weight_unit": "KG",
  • "dimension_unit": "CM",
  • "items": [
    ],
  • "reference_number": "string",
  • "freight_class": "string",
  • "options": { },
  • "object_type": "parcel"
}

Update a parcel

modify an existing parcel's details.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string
Request Body schema: application/json
weight
number <double>

The parcel's weight

width
number or null <double>

The parcel's width

height
number or null <double>

The parcel's height

length
number or null <double>

The parcel's length

packaging_type
string or null <= 50 characters

The parcel's packaging type.
Note that the packaging is optional when using a package preset.
values:
envelope pak tube pallet small_box medium_box your_packaging
For carrier specific packaging types, please consult the reference.

package_preset
string or null <= 50 characters

The parcel's package preset.
For carrier specific package presets, please consult the reference.

description
string or null <= 250 characters

The parcel's description

content
string or null <= 100 characters

The parcel's content description

is_document
boolean or null
Default: false

Indicates if the parcel is composed of documents only

weight_unit
string
Enum: "KG" "LB" "OZ" "G"

The parcel's weight unit

dimension_unit
string or null
Enum: "CM" "IN" null

The parcel's dimension unit

Array of objects (CommodityData)

The parcel items.

reference_number
string or null <= 100 characters

The parcel reference number.
(can be used as tracking number for custom carriers)

freight_class
string or null <= 6 characters

The parcel's freight class for pallet and freight shipments.

object
Default: {}
Parcel specific options.
    {
        "insurance": "100.00",
        "insured_by": "carrier",
    }
    

Responses

Request samples

Content type
application/json
{
  • "weight": 0.1,
  • "width": 0.1,
  • "height": 0.1,
  • "length": 0.1,
  • "packaging_type": "string",
  • "package_preset": "string",
  • "description": "string",
  • "content": "string",
  • "is_document": false,
  • "weight_unit": "KG",
  • "dimension_unit": "CM",
  • "items": [
    ],
  • "reference_number": "string",
  • "freight_class": "string",
  • "options": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "weight": 0.1,
  • "width": 0.1,
  • "height": 0.1,
  • "length": 0.1,
  • "packaging_type": "string",
  • "package_preset": "string",
  • "description": "string",
  • "content": "string",
  • "is_document": false,
  • "weight_unit": "KG",
  • "dimension_unit": "CM",
  • "items": [
    ],
  • "reference_number": "string",
  • "freight_class": "string",
  • "options": { },
  • "object_type": "parcel"
}

Remove a parcel

Remove a parcel.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "weight": 0.1,
  • "width": 0.1,
  • "height": 0.1,
  • "length": 0.1,
  • "packaging_type": "string",
  • "package_preset": "string",
  • "description": "string",
  • "content": "string",
  • "is_document": false,
  • "weight_unit": "KG",
  • "dimension_unit": "CM",
  • "items": [
    ],
  • "reference_number": "string",
  • "freight_class": "string",
  • "options": { },
  • "object_type": "parcel"
}

Shipments

This is an object representing your Karrio shipment. A Shipment guides you through process of preparing and purchasing a label for an order. A Shipment transitions through multiple statuses throughout its lifetime as the package shipped makes its journey to it's destination.

List all shipments

Retrieve all shipments.

Authorizations:
TokenBasicTokenOAuth2JWT
query Parameters
address
string
carrier_name
string

The unique carrier slug.
Values: allied_express, allied_express_local, amazon_shipping, aramex, asendia_us, australiapost, boxknight, bpost, canadapost, canpar, chronopost, colissimo, dhl_express, dhl_parcel_de, dhl_poland, dhl_universal, dicom, dpd, dpdhl, easypost, eshipper, fedex, fedex_ws, freightcom, generic, geodis, laposte, locate2u, nationex, purolator, roadie, royalmail, sendle, tge, tnt, ups, usps, usps_international, zoom2u

created_after
string <date-time>
created_before
string <date-time>
has_manifest
boolean
has_tracker
boolean
id
string
keyword
string
meta_key
string
meta_value
string
metadata_key
string
metadata_value
string
option_key
string
option_value
string
reference
string
service
string
status
string

Valid shipment status.
Values: draft, purchased, cancelled, shipped, in_transit, delivered, needs_attention, out_for_delivery, delivery_failed

tracking_number
string

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results": [
    ]
}

Create a shipment

Create a new shipment instance.

Authorizations:
TokenBasicTokenOAuth2JWT
Request Body schema: application/json
required
required
object

The address of the party.
Origin address (ship from) for the shipper
Destination address (ship to) for the recipient

required
object

The address of the party.
Origin address (ship from) for the shipper
Destination address (ship to) for the recipient

required
Array of objects (ParcelData)

The shipment's parcels

object
Default: {}
The options available for the shipment.
    {
        "currency": "USD",
        "insurance": 100.00,
        "cash_on_delivery": 30.00,
        "dangerous_good": true,
        "declared_value": 150.00,
        "sms_notification": true,
        "email_notification": true,
        "email_notification_to": "shipper@mail.com",
        "hold_at_location": true,
        "paperless_trade": true,
        "preferred_service": "fedex_express_saver",
        "shipment_date": "2020-01-01",
        "shipment_note": "This is a shipment note",
        "signature_confirmation": true,
        "doc_files": [
            {
                "doc_type": "commercial_invoice",
                "doc_file": "base64 encoded file",
                "doc_name": "commercial_invoice.pdf",
                "doc_format": "pdf",
            }
        ],
        "doc_references": [
            {
                "doc_id": "123456789",
                "doc_type": "commercial_invoice",
            }
        ],
    }
    
object
Default: {"paid_by":"sender","currency":null,"account_number":null}

The payment details

object or null

The payor address.

object or null

The customs details.
Note that this is required for the shipment of an international Dutiable parcel.

reference
string or null <= 35 characters

The shipment reference

label_type
string
Default: "PDF"
Enum: "PDF" "ZPL" "PNG"

The shipment label file type.

service
string

Specify a service to Buy a label in one call without rating.

services
Array of strings or null
Default: []

The requested carrier service for the shipment.
Please consult the reference for specific carriers services.
Note that this is a list because on a Multi-carrier rate request you could specify a service per carrier.

carrier_ids
Array of strings or null
Default: []

The list of configured carriers you wish to get rates from.
Note that the request will be sent to all carriers in nothing is specified

object
Default: {}

User metadata for the shipment

Responses

Request samples

Content type
application/json
{
  • "shipper": {
    },
  • "recipient": {
    },
  • "parcels": [
    ],
  • "options": { },
  • "payment": {
    },
  • "billing_address": {
    },
  • "customs": {
    },
  • "reference": "string",
  • "label_type": "PDF",
  • "service": "string",
  • "services": [ ],
  • "carrier_ids": [ ],
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "object_type": "shipment",
  • "tracking_url": "http://example.com",
  • "shipper": {
    },
  • "recipient": {
    },
  • "parcels": [
    ],
  • "services": [ ],
  • "options": { },
  • "payment": {
    },
  • "billing_address": {
    },
  • "customs": {
    },
  • "rates": [ ],
  • "reference": "string",
  • "label_type": "PDF",
  • "carrier_ids": [ ],
  • "tracker_id": "string",
  • "created_at": "string",
  • "metadata": { },
  • "messages": [ ],
  • "status": "draft",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "tracking_number": "string",
  • "shipment_identifier": "string",
  • "selected_rate": {
    },
  • "meta": {
    },
  • "service": "string",
  • "selected_rate_id": "string",
  • "test_mode": true,
  • "label_url": "http://example.com",
  • "invoice_url": "http://example.com"
}

Retrieve a shipment

Retrieve a shipment.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object_type": "shipment",
  • "tracking_url": "http://example.com",
  • "shipper": {
    },
  • "recipient": {
    },
  • "parcels": [
    ],
  • "services": [ ],
  • "options": { },
  • "payment": {
    },
  • "billing_address": {
    },
  • "customs": {
    },
  • "rates": [ ],
  • "reference": "string",
  • "label_type": "PDF",
  • "carrier_ids": [ ],
  • "tracker_id": "string",
  • "created_at": "string",
  • "metadata": { },
  • "messages": [ ],
  • "status": "draft",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "tracking_number": "string",
  • "shipment_identifier": "string",
  • "selected_rate": {
    },
  • "meta": {
    },
  • "service": "string",
  • "selected_rate_id": "string",
  • "test_mode": true,
  • "label_url": "http://example.com",
  • "invoice_url": "http://example.com"
}

Update a shipment

This operation allows for updating properties of a shipment including label_type, reference, payment, options and metadata. It is not for editing the parcels of a shipment.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string
Request Body schema: application/json
label_type
string
Default: "PDF"
Enum: "PDF" "ZPL" "PNG"

The shipment label file type.

object

The payment details

object
The options available for the shipment.
    {
        "currency": "USD",
        "insurance": 100.00,
        "cash_on_delivery": 30.00,
        "shipment_date": "2020-01-01",
        "dangerous_good": true,
        "declared_value": 150.00,
        "email_notification": true,
        "email_notification_to": "shipper@mail.com",
        "signature_confirmation": true,
    }
    
reference
string or null

The shipment reference

object

User metadata for the shipment

Responses

Request samples

Content type
application/json
{
  • "label_type": "PDF",
  • "payment": {
    },
  • "options": {
    },
  • "reference": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "object_type": "shipment",
  • "tracking_url": "http://example.com",
  • "shipper": {
    },
  • "recipient": {
    },
  • "parcels": [
    ],
  • "services": [ ],
  • "options": { },
  • "payment": {
    },
  • "billing_address": {
    },
  • "customs": {
    },
  • "rates": [ ],
  • "reference": "string",
  • "label_type": "PDF",
  • "carrier_ids": [ ],
  • "tracker_id": "string",
  • "created_at": "string",
  • "metadata": { },
  • "messages": [ ],
  • "status": "draft",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "tracking_number": "string",
  • "shipment_identifier": "string",
  • "selected_rate": {
    },
  • "meta": {
    },
  • "service": "string",
  • "selected_rate_id": "string",
  • "test_mode": true,
  • "label_url": "http://example.com",
  • "invoice_url": "http://example.com"
}

Cancel a shipment

Void a shipment with the associated label.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object_type": "shipment",
  • "tracking_url": "http://example.com",
  • "shipper": {
    },
  • "recipient": {
    },
  • "parcels": [
    ],
  • "services": [ ],
  • "options": { },
  • "payment": {
    },
  • "billing_address": {
    },
  • "customs": {
    },
  • "rates": [ ],
  • "reference": "string",
  • "label_type": "PDF",
  • "carrier_ids": [ ],
  • "tracker_id": "string",
  • "created_at": "string",
  • "metadata": { },
  • "messages": [ ],
  • "status": "draft",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "tracking_number": "string",
  • "shipment_identifier": "string",
  • "selected_rate": {
    },
  • "meta": {
    },
  • "service": "string",
  • "selected_rate_id": "string",
  • "test_mode": true,
  • "label_url": "http://example.com",
  • "invoice_url": "http://example.com"
}

Buy a shipment label

Select your preferred rates to buy a shipment label.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string
Request Body schema: application/json
required
selected_rate_id
required
string

The shipment selected rate.

label_type
string
Default: "PDF"
Enum: "PDF" "ZPL" "PNG"

The shipment label file type.

object

The payment details

reference
string or null

The shipment reference

object

User metadata for the shipment

Responses

Request samples

Content type
application/json
{
  • "selected_rate_id": "string",
  • "label_type": "PDF",
  • "payment": {
    },
  • "reference": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "object_type": "shipment",
  • "tracking_url": "http://example.com",
  • "shipper": {
    },
  • "recipient": {
    },
  • "parcels": [
    ],
  • "services": [ ],
  • "options": { },
  • "payment": {
    },
  • "billing_address": {
    },
  • "customs": {
    },
  • "rates": [ ],
  • "reference": "string",
  • "label_type": "PDF",
  • "carrier_ids": [ ],
  • "tracker_id": "string",
  • "created_at": "string",
  • "metadata": { },
  • "messages": [ ],
  • "status": "draft",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "tracking_number": "string",
  • "shipment_identifier": "string",
  • "selected_rate": {
    },
  • "meta": {
    },
  • "service": "string",
  • "selected_rate_id": "string",
  • "test_mode": true,
  • "label_url": "http://example.com",
  • "invoice_url": "http://example.com"
}

Fetch new shipment rates

Refresh the list of the shipment rates

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string
Request Body schema: application/json
services
Array of strings or null

The requested carrier service for the shipment.
Please consult the reference for specific carriers services.
Note that this is a list because on a Multi-carrier rate request you could specify a service per carrier.

carrier_ids
Array of strings or null

The list of configured carriers you wish to get rates from.
Note that the request will be sent to all carriers in nothing is specified

reference
string or null

The shipment reference

object

User metadata for the shipment

Responses

Request samples

Content type
application/json
{
  • "services": [
    ],
  • "carrier_ids": [
    ],
  • "reference": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "object_type": "shipment",
  • "tracking_url": "http://example.com",
  • "shipper": {
    },
  • "recipient": {
    },
  • "parcels": [
    ],
  • "services": [ ],
  • "options": { },
  • "payment": {
    },
  • "billing_address": {
    },
  • "customs": {
    },
  • "rates": [ ],
  • "reference": "string",
  • "label_type": "PDF",
  • "carrier_ids": [ ],
  • "tracker_id": "string",
  • "created_at": "string",
  • "metadata": { },
  • "messages": [ ],
  • "status": "draft",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "tracking_number": "string",
  • "shipment_identifier": "string",
  • "selected_rate": {
    },
  • "meta": {
    },
  • "service": "string",
  • "selected_rate_id": "string",
  • "test_mode": true,
  • "label_url": "http://example.com",
  • "invoice_url": "http://example.com"
}

Documents

This is an object representing your Karrio document upload record. A Document upload record keep traces of shipping trade documents uploaded to carriers to fast track customs and border processing.

List all upload records

Retrieve all shipping document upload records.

Authorizations:
TokenBasicTokenOAuth2JWT
query Parameters
created_after
string <date-time>
created_before
string <date-time>
shipment_id
string

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results": [
    ]
}

Upload documents

Upload a shipping document.

Authorizations:
TokenBasicTokenOAuth2JWT
Request Body schema: application/json
required
shipment_id
required
string

The documents related shipment.

required
Array of objects (DocumentFileData)

Shipping document files

reference
string or null <= 50 characters

Shipping document file reference

Responses

Request samples

Content type
application/json
{
  • "shipment_id": "string",
  • "document_files": [
    ],
  • "reference": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "documents": [ ],
  • "meta": {
    },
  • "reference": "string",
  • "messages": [ ]
}

Retrieve an upload record

Retrieve a shipping document upload record.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "documents": [ ],
  • "meta": {
    },
  • "reference": "string",
  • "messages": [ ]
}

Manifests

This is an object representing your Karrio manifest details. Some carriers require manifests to be created after labels are generated. A manifest is a summary of all the shipments that are being sent out.

List manifests

Retrieve all manifests.

Authorizations:
TokenBasicTokenOAuth2JWT
query Parameters
carrier_name
string

The unique carrier slug.
Values: allied_express, allied_express_local, amazon_shipping, aramex, asendia_us, australiapost, boxknight, bpost, canadapost, canpar, chronopost, colissimo, dhl_express, dhl_parcel_de, dhl_poland, dhl_universal, dicom, dpd, dpdhl, easypost, eshipper, fedex, fedex_ws, freightcom, generic, geodis, laposte, locate2u, nationex, purolator, roadie, royalmail, sendle, tge, tnt, ups, usps, usps_international, zoom2u

created_after
string <date-time>
created_before
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results": [
    ]
}

Create a manifest

Create a manifest for one or many shipments with labels already purchased.

Authorizations:
TokenBasicTokenOAuth2JWT
Request Body schema: application/json
required
carrier_name
required
string

The manifest's carrier

required
object

The address of the warehouse or location where the shipments originate.

object
Default: {}
The options available for the manifest.
    {
        "shipments": [
            {
                "tracking_number": "123456789",
                ...
                "meta": {...}
            }
        ]
    }
    
reference
string or null

The manifest reference

shipment_ids
required
Array of strings

The list of existing shipment object ids with label purchased.

Responses

Request samples

Content type
application/json
{
  • "carrier_name": "string",
  • "address": {
    },
  • "options": { },
  • "reference": "string",
  • "shipment_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "object_type": "manifest",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "meta": {
    },
  • "test_mode": true,
  • "address": {
    },
  • "options": { },
  • "reference": "string",
  • "shipment_identifiers": [
    ],
  • "metadata": { },
  • "manifest_url": "http://example.com",
  • "messages": [ ]
}

Retrieve a manifest

Retrieve a shipping manifest.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object_type": "manifest",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "meta": {
    },
  • "test_mode": true,
  • "address": {
    },
  • "options": { },
  • "reference": "string",
  • "shipment_identifiers": [
    ],
  • "metadata": { },
  • "manifest_url": "http://example.com",
  • "messages": [ ]
}

Trackers

This is an object representing your Karrio shipment tracker. A shipment tracker is an object attached to a shipment by it's tracking number. The tracker provide the latest tracking status and events associated with a shipment

List all package trackers

Retrieve all shipment trackers.

Authorizations:
TokenBasicTokenOAuth2JWT
query Parameters
carrier_name
string

The unique carrier slug.
Values: allied_express, allied_express_local, amazon_shipping, aramex, asendia_us, australiapost, boxknight, bpost, canadapost, canpar, chronopost, colissimo, dhl_express, dhl_parcel_de, dhl_poland, dhl_universal, dicom, dpd, dpdhl, easypost, eshipper, fedex, fedex_ws, freightcom, generic, geodis, laposte, locate2u, nationex, purolator, roadie, royalmail, sendle, tge, tnt, ups, usps, usps_international, zoom2u

created_after
string <date-time>
created_before
string <date-time>
status
string

Valid tracker status.
Values: pending, unknown, on_hold, delivered, in_transit, delivery_delayed, out_for_delivery, ready_for_pickup, delivery_failed

tracking_number
string

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results": [
    ]
}

Add a package tracker

This API creates or retrieves (if existent) a tracking status object containing the details and events of a shipping in progress.

Authorizations:
TokenBasicTokenOAuth2JWT
query Parameters
hub
string
pending_pickup
boolean

Add this flag to add the tracker whether the tracking info exist or not.When the package is eventually picked up, the tracker with capture real time updates.

Request Body schema: application/json
required
tracking_number
required
string

The package tracking number

carrier_name
required
string
Enum: "allied_express" "allied_express_local" "amazon_shipping" "aramex" "asendia_us" "australiapost" "boxknight" "bpost" "canadapost" "canpar" "chronopost" "colissimo" "dhl_express" "dhl_parcel_de" "dhl_poland" "dhl_universal" "dicom" "dpd" "dpdhl" "fedex" "fedex_ws" "generic" "geodis" "laposte" "locate2u" "nationex" "purolator" "roadie" "royalmail" "sendle" "tge" "tnt" "ups" "usps" "usps_international" "zoom2u"

The tracking carrier

account_number
string or null

The shipper account number

reference
string or null

The shipment reference

object or null

The package and shipment tracking details

object
Default: {}

The carrier user metadata.

Responses

Request samples

Content type
application/json
{
  • "tracking_number": "string",
  • "carrier_name": "allied_express",
  • "account_number": "string",
  • "reference": "string",
  • "info": {
    },
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "tracking_number": "string",
  • "info": {
    },
  • "events": [
    ],
  • "delivered": true,
  • "test_mode": true,
  • "status": "pending",
  • "estimated_delivery": "string",
  • "meta": {
    },
  • "object_type": "tracker",
  • "metadata": { },
  • "messages": [ ],
  • "delivery_image_url": "http://example.com",
  • "signature_image_url": "http://example.com"
}

Create a package tracker Deprecated

This API creates or retrieves (if existent) a tracking status object containing the details and events of a shipping in progress.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
carrier_name
required
string
tracking_number
required
string
query Parameters
carrier_name
required
string
Enum: "allied_express" "allied_express_local" "amazon_shipping" "aramex" "asendia_us" "australiapost" "boxknight" "bpost" "canadapost" "canpar" "chronopost" "colissimo" "dhl_express" "dhl_parcel_de" "dhl_poland" "dhl_universal" "dicom" "dpd" "dpdhl" "fedex" "fedex_ws" "generic" "geodis" "laposte" "locate2u" "nationex" "purolator" "roadie" "royalmail" "sendle" "tge" "tnt" "ups" "usps" "usps_international" "zoom2u"
hub
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "tracking_number": "string",
  • "info": {
    },
  • "events": [
    ],
  • "delivered": true,
  • "test_mode": true,
  • "status": "pending",
  • "estimated_delivery": "string",
  • "meta": {
    },
  • "object_type": "tracker",
  • "metadata": { },
  • "messages": [ ],
  • "delivery_image_url": "http://example.com",
  • "signature_image_url": "http://example.com"
}

Retrieves a package tracker

Retrieve a package tracker

Authorizations:
TokenBasicTokenOAuth2JWTNone
path Parameters
id_or_tracking_number
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "carrier_name": "string",
  • "carrier_id": "string",
  • "tracking_number": "string",
  • "info": {
    },
  • "events": [