Skip to main content
API docs by Redocly

Karrio API (2023.4.6)

Download OpenAPI specification:Download

API Reference

Karrio is an open source multi-carrier shipping API that simplifies the integration of logistic 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 2023.4.6.

Read our API changelog and 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 and authentication resources.

Instance Metadata

Responses

Response samples

Content type
application/json
{
  • "VERSION": "",
  • "APP_NAME": "",
  • "HOST": "",
  • "ADMIN": "",
  • "OPENAPI": "",
  • "GRAPHQL": "",
  • "AUDIT_LOGGING": true,
  • "ALLOW_SIGNUP": true,
  • "ALLOW_ADMIN_APPROVED_SIGNUP": true,
  • "ALLOW_MULTI_ACCOUNT": 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,
  • "ORG_LEVEL_BILLING": true,
  • "TENANT_LEVEL_BILLING": true
}

Obtain auth token pair

Authenticate the user and return a token pair

Request Body schema: application/json
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
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
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
token
required
string

Responses

Request samples

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

Response samples

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

Data References

Responses

Response samples

Content type
application/json
{
  • "VERSION": "",
  • "APP_NAME": "",
  • "HOST": "",
  • "ADMIN": "",
  • "OPENAPI": "",
  • "GRAPHQL": "",
  • "AUDIT_LOGGING": true,
  • "ALLOW_SIGNUP": true,
  • "ALLOW_ADMIN_APPROVED_SIGNUP": true,
  • "ALLOW_MULTI_ACCOUNT": 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,
  • "ORG_LEVEL_BILLING": true,
  • "TENANT_LEVEL_BILLING": 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": { }
}

Carriers

This is an object representing your a 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: amazon_mws, aramex, australiapost, boxknight, canadapost, canpar, chronopost, dhl_express, dhl_poland, dhl_universal, dicom, dpd, dpdhl, easypost, eshipper, fedex, freightcom, generic, geodis, laposte, nationex, purolator, roadie, royalmail, sendle, sf_express, tnt, ups, ups_freight, usps, usps_international, yanwen, yunexpress

system_only
boolean

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "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: amazon_mws, aramex, australiapost, boxknight, canadapost, canpar, chronopost, dhl_express, dhl_poland, dhl_universal, dicom, dpd, dpdhl, easypost, eshipper, fedex, freightcom, generic, geodis, laposte, nationex, purolator, roadie, royalmail, sendle, sf_express, tnt, ups, ups_freight, usps, usps_international, yanwen, yunexpress

Responses

Response samples

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

Addresses

This is an object representing your a 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,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Create an address

Create a new address.

Authorizations:
TokenBasicTokenOAuth2JWT
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 <= 30 characters

Attention to (required for shipment purchase)

company_name
string or null <= 30 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

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

suburb
string or null <= 20 characters

The address suburb if known

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",
  • "suburb": "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",
  • "suburb": "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",
  • "suburb": "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 <= 30 characters

Attention to (required for shipment purchase)

company_name
string or null <= 30 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

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

suburb
string or null <= 20 characters

The address suburb if known

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",
  • "suburb": "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",
  • "suburb": "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",
  • "suburb": "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 a 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,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Create a parcel

Create a new parcel.

Authorizations:
TokenBasicTokenOAuth2JWT
Request Body schema: application/json
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"

The parcel's weight unit

  • KG - KG
  • LB - LB
dimension_unit
string or null
Enum: "CM" "IN" null

The parcel's dimension unit

  • CM - CM
  • IN - IN
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,
  • "width": 0,
  • "height": 0,
  • "length": 0,
  • "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,
  • "width": 0,
  • "height": 0,
  • "length": 0,
  • "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,
  • "width": 0,
  • "height": 0,
  • "length": 0,
  • "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"

The parcel's weight unit

  • KG - KG
  • LB - LB
dimension_unit
string or null
Enum: "CM" "IN" null

The parcel's dimension unit

  • CM - CM
  • IN - IN
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,
  • "width": 0,
  • "height": 0,
  • "length": 0,
  • "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,
  • "width": 0,
  • "height": 0,
  • "length": 0,
  • "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,
  • "width": 0,
  • "height": 0,
  • "length": 0,
  • "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"
}

Customs

This is an object representing your a Karrio shipping customs declaration. You can retrieve all customs declarations used historically with your Karrio account shipments.

List all customs info

Retrieve all stored customs declarations.

Authorizations:
TokenBasicTokenOAuth2JWT

Responses

Response samples

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

Create a customs info

Create a new customs declaration.

Authorizations:
TokenBasicTokenOAuth2JWT
Request Body schema: application/json
required
Array of objects (CommodityData)

The parcel content items

object or null

The payment details.
Note that this is required for a Dutiable parcel shipped internationally.

object or null

The duty payor address.

content_type
string or null
Enum: "documents" "gift" "sample" "merchandise" "return_merchandise" "other" "" null
  • documents - documents
  • gift - gift
  • sample - sample
  • merchandise - merchandise
  • return_merchandise - return_merchandise
  • other - other
content_description
string or null
incoterm
string or null
Enum: "CFR" "CIF" "CIP" "CPT" "DAF" "DDP" "DDU" "DEQ" "DES" "EXW" "FAS" "FCA" "FOB" null

The customs 'term of trade' also known as 'incoterm'

  • CFR - CFR
  • CIF - CIF
  • CIP - CIP
  • CPT - CPT
  • DAF - DAF
  • DDP - DDP
  • DDU - DDU
  • DEQ - DEQ
  • DES - DES
  • EXW - EXW
  • FAS - FAS
  • FCA - FCA
  • FOB - FOB
invoice
string or null <= 50 characters

The invoice reference number

invoice_date
string or null

The invoice date

commercial_invoice
boolean or null

Indicates if the shipment is commercial

certify
boolean or null

Indicate that signer certified confirmed all

signer
string or null <= 50 characters
object
Default: {}
Customs identification options. 
    {
        "aes": "5218487281",
        "eel_pfc": "5218487281",
        "license_number": "5218487281",
        "certificate_number": "5218487281",
        "nip_number": "5218487281",
        "eori_number": "5218487281",
        "vat_registration_number": "5218487281",
    }

Responses

Request samples

Content type
application/json
{
  • "commodities": [
    ],
  • "duty": {
    },
  • "duty_billing_address": {
    },
  • "content_type": "documents",
  • "content_description": "string",
  • "incoterm": "CFR",
  • "invoice": "string",
  • "invoice_date": "string",
  • "commercial_invoice": true,
  • "certify": true,
  • "signer": "string",
  • "options": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "commodities": [
    ],
  • "duty": {
    },
  • "duty_billing_address": {
    },
  • "content_type": "documents",
  • "content_description": "string",
  • "incoterm": "CFR",
  • "invoice": "string",
  • "invoice_date": "string",
  • "commercial_invoice": true,
  • "certify": true,
  • "signer": "string",
  • "options": { },
  • "object_type": "customs_info"
}

Retrieve a customs info

Retrieve customs declaration.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "commodities": [
    ],
  • "duty": {
    },
  • "duty_billing_address": {
    },
  • "content_type": "documents",
  • "content_description": "string",
  • "incoterm": "CFR",
  • "invoice": "string",
  • "invoice_date": "string",
  • "commercial_invoice": true,
  • "certify": true,
  • "signer": "string",
  • "options": { },
  • "object_type": "customs_info"
}

Update a customs info

modify an existing customs declaration.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string
Request Body schema: application/json
Array of objects (CommodityData)

The parcel content items

object or null

The payment details.
Note that this is required for a Dutiable parcel shipped internationally.

object or null

The duty payor address.

content_type
string or null
Enum: "documents" "gift" "sample" "merchandise" "return_merchandise" "other" "" null
  • documents - documents
  • gift - gift
  • sample - sample
  • merchandise - merchandise
  • return_merchandise - return_merchandise
  • other - other
content_description
string or null
incoterm
string or null
Enum: "CFR" "CIF" "CIP" "CPT" "DAF" "DDP" "DDU" "DEQ" "DES" "EXW" "FAS" "FCA" "FOB" null

The customs 'term of trade' also known as 'incoterm'

  • CFR - CFR
  • CIF - CIF
  • CIP - CIP
  • CPT - CPT
  • DAF - DAF
  • DDP - DDP
  • DDU - DDU
  • DEQ - DEQ
  • DES - DES
  • EXW - EXW
  • FAS - FAS
  • FCA - FCA
  • FOB - FOB
invoice
string or null <= 50 characters

The invoice reference number

invoice_date
string or null

The invoice date

commercial_invoice
boolean or null

Indicates if the shipment is commercial

certify
boolean or null

Indicate that signer certified confirmed all

signer
string or null <= 50 characters
object
Default: {}
Customs identification options. 
    {
        "aes": "5218487281",
        "eel_pfc": "5218487281",
        "license_number": "5218487281",
        "certificate_number": "5218487281",
        "nip_number": "5218487281",
        "eori_number": "5218487281",
        "vat_registration_number": "5218487281",
    }

Responses

Request samples

Content type
application/json
{
  • "commodities": [
    ],
  • "duty": {
    },
  • "duty_billing_address": {
    },
  • "content_type": "documents",
  • "content_description": "string",
  • "incoterm": "CFR",
  • "invoice": "string",
  • "invoice_date": "string",
  • "commercial_invoice": true,
  • "certify": true,
  • "signer": "string",
  • "options": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "commodities": [
    ],
  • "duty": {
    },
  • "duty_billing_address": {
    },
  • "content_type": "documents",
  • "content_description": "string",
  • "incoterm": "CFR",
  • "invoice": "string",
  • "invoice_date": "string",
  • "commercial_invoice": true,
  • "certify": true,
  • "signer": "string",
  • "options": { },
  • "object_type": "customs_info"
}

Discard a customs info

Discard a customs declaration.

Authorizations:
TokenBasicTokenOAuth2JWT
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "commodities": [
    ],
  • "duty": {
    },
  • "duty_billing_address": {
    },
  • "content_type": "documents",
  • "content_description": "string",
  • "incoterm": "CFR",
  • "invoice": "string",
  • "invoice_date": "string",
  • "commercial_invoice": true,
  • "certify": true,
  • "signer": "string",
  • "options": { },
  • "object_type": "customs_info"
}

Shipments

This is an object representing your a 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: amazon_mws, aramex, australiapost, boxknight, canadapost, canpar, chronopost, dhl_express, dhl_poland, dhl_universal, dicom, dpd, dpdhl, easypost, eshipper, fedex, freightcom, generic, geodis, laposte, nationex, purolator, roadie, royalmail, sendle, sf_express, tnt, ups, ups_freight, usps, usps_international, yanwen, yunexpress

created_after
string <date-time>
created_before
string <date-time>
keyword
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,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Create a shipment

Create a new shipment instance.

Authorizations:
TokenBasicTokenOAuth2JWT
Request Body schema: application/json
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.

  • PDF - PDF
  • ZPL - ZPL
  • PNG - PNG
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.

  • PDF - PDF
  • ZPL - ZPL
  • PNG - PNG
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
selected_rate_id
required
string

The shipment selected rate.

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

The shipment label file type.

  • PDF - PDF
  • ZPL - ZPL
  • PNG - PNG
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 a Karrio document upload record. A Document upload record keep traces of shipping trade documents uploaded to carriers to fast track customs 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,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Upload documents

Upload a shipping document.

Authorizations:
TokenBasicTokenOAuth2JWT
Request Body schema: application/json
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": [ ]
}

Trackers

This is an object representing your a 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: amazon_mws, aramex, australiapost, boxknight, canadapost, canpar, chronopost, dhl_express, dhl_poland, dhl_universal, dicom, dpd, dpdhl, easypost, eshipper, fedex, freightcom, generic, geodis, laposte, nationex, purolator, roadie, royalmail, sendle, sf_express, tnt, ups, ups_freight, usps, usps_international, yanwen, yunexpress

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

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

tracking_number
string

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "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