openapi: 3.2.0
info:
description: "\nKarrio is a multi-carrier shipping API that simplifies the integration of logistics carrier services.\n\nThe Karrio API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded\nrequest bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\nThe Karrio API differs for every account as we release new versions.\nThese docs are customized to your version of the API.\n\n\n## Versioning\n\nWhen backwards-incompatible changes are made to the API, a new, dated version is released.\nThe current version is `2026.1.32`.\n\nRead our API changelog to learn more about backwards compatibility.\n\nAs a precaution, use API versioning to check a new API version before committing to an upgrade.\n\n\n## Environments\n\nThe Karrio API offer the possibility to create and retrieve certain objects in `test_mode`.\nIn development, it is therefore possible to add carrier connections, get live rates,\nbuy labels, create trackers and schedule pickups in `test_mode`.\n\n\n## Pagination\n\nAll top-level API resources have support for bulk fetches via \"list\" API methods. For instance, you can list addresses,\nlist shipments, and list trackers. These list API methods share a common structure, taking at least these\ntwo parameters: limit, and offset.\n\nKarrio utilizes offset-based pagination via the offset and limit parameters.\nBoth parameters take a number as value (see below) and return objects in reverse chronological order.\nThe offset parameter returns objects listed after an index.\nThe limit parameter take a limit on the number of objects to be returned from 1 to 100.\n\n\n```json\n{\n \"count\": 100,\n \"next\": \"/v1/shipments?limit=25&offset=50\",\n \"previous\": \"/v1/shipments?limit=25&offset=25\",\n \"results\": [\n { ... },\n ]\n}\n```\n\n## Metadata\n\nUpdateable Karrio objects—including Shipment and Order have a metadata parameter.\nYou can use this parameter to attach key-value data to these Karrio objects.\n\nMetadata is useful for storing additional, structured information on an object.\nAs an example, you could store your user's full name and corresponding unique identifier\nfrom your system on a Karrio Order object.\n\nDo not store any sensitive information as metadata.\n\n## Authentication\n\nAPI keys are used to authenticate requests. You can view and manage your API keys in the Dashboard.\n\nYour API keys carry many privileges, so be sure to keep them secure! Do not share your secret\nAPI keys in publicly accessible areas such as GitHub, client-side code, and so forth.\n\nAuthentication to the API is performed via HTTP Basic Auth. Provide your API token as\nthe basic auth username value. You do not need to provide a password.\n\n```shell\n$ curl https://instance.api.com/v1/shipments \\\n -u key_xxxxxx:\n# The colon prevents curl from asking for a password.\n```\n\nIf you need to authenticate via bearer auth (e.g., for a cross-origin request),\nuse `-H \"Authorization: Token key_xxxxxx\"` instead of `-u key_xxxxxx`.\n\nAll API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure).\nAPI requests without authentication will also fail.\n"
title: Karrio Carriers API
version: 2026.1.32
tags:
- name: Carriers
description: "This is an object representing your Karrio carrier extension.\n You can retrieve all supported carrier extensions available.\n "
paths:
/v1/carriers:
get:
operationId: '&&list'
description: Returns the list of configured carriers
summary: List all carriers
parameters:
- in: query
name: lang
schema:
type: string
description: Language code for translated labels (e.g., 'de', 'en').
tags:
- Carriers
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CarrierDetails'
examples:
CarrierList:
value:
- carrier_name: dhl_parcel_de
display_name: DHL Parcel DE
integration_status: in-development
capabilities:
- rating
- shipping
- tracking
connection_fields:
username:
name: username
required: true
type: string
password:
name: password
required: true
type: string
dhl_api_key:
name: dhl_api_key
required: true
type: string
customer_number:
name: customer_number
required: false
type: string
tracking_consumer_key:
name: tracking_consumer_key
required: false
type: string
tracking_consumer_secret:
name: tracking_consumer_secret
required: false
type: string
services:
default:
- active: true
currency: EUR
dimension_unit: CM
domicile: true
max_height: 60
max_length: 120
max_weight: 31.5
max_width: 60
metadata: {}
min_weight: 0.01
service_code: dhl_parcel_de_paket
service_name: DHL Paket
weight_unit: KG
zones:
- rate: 0.0
- active: true
currency: EUR
dimension_unit: CM
domicile: false
international: true
max_height: 60
max_length: 120
max_weight: 31.5
max_width: 60
metadata: {}
min_weight: 0.01
service_code: dhl_parcel_de_paket_international
service_name: DHL Paket International
weight_unit: KG
zones:
- rate: 0.0
- active: true
currency: EUR
dimension_unit: CM
domicile: false
international: true
max_height: 60
max_length: 120
max_weight: 31.5
max_width: 60
metadata: {}
min_weight: 0.01
service_code: dhl_parcel_de_europaket
service_name: DHL EuroPaket
weight_unit: KG
zones:
- rate: 0.0
- active: true
currency: EUR
dimension_unit: CM
domicile: true
international: false
max_height: 5
max_length: 35
max_weight: 1
max_width: 7
metadata: {}
min_weight: 0.01
service_code: dhl_parcel_de_warenpost
service_name: DHL Warenpost
weight_unit: KG
zones:
- rate: 0.0
- active: true
currency: EUR
dimension_unit: CM
domicile: false
international: true
max_height: 10
max_length: 35.3
max_weight: 1
max_width: 9
metadata: {}
min_weight: 0.01
service_code: dhl_parcel_de_warenpost_international
service_name: DHL Warenpost International
weight_unit: KG
zones:
- rate: 0.0
name: services
required: false
type: list
config_fields:
profile:
code: profile
name: profile
required: false
type: string
cost_center:
code: cost_center
name: cost_center
required: false
type: string
creation_software:
code: creation_software
name: creation_software
required: false
type: string
shipping_options:
code: shipping_options
name: shipping_options
required: false
type: list
shipping_services:
code: shipping_services
name: shipping_services
required: false
type: list
language:
code: language
enum:
- de
- en
name: language
required: false
type: string
label_type:
code: label_type
enum:
- PDF_A4
- ZPL2_A4
- PDF_910_300_700
- ZPL2_910_300_700
- PDF_910_300_700_oz
- ZPL2_910_300_700_oz
- PDF_910_300_710
- ZPL2_910_300_710
- PDF_910_300_600
- ZPL2_910_300_600
- PDF_910_300_610
- ZPL2_910_300_610
- PDF_910_300_400
- ZPL2_910_300_400
- PDF_910_300_410
- ZPL2_910_300_410
- PDF_910_300_300
- ZPL2_910_300_300
- PDF_910_300_300_oz
- ZPL2_910_300_300_oz
name: label_type
required: false
type: string
shipping_services:
dhl_parcel_de_paket: V01PAK
dhl_parcel_de_warenpost: V62WP
dhl_parcel_de_europaket: V54EPAK
dhl_parcel_de_paket_international: V53WPAK
dhl_parcel_de_warenpost_international: V66WPI
shipping_options:
dhl_parcel_de_preferred_neighbour:
code: preferredNeighbour
type: string
dhl_parcel_de_preferred_location:
code: preferredLocation
type: string
dhl_parcel_de_visual_check_of_age:
code: visualCheckOfAge
type: string
dhl_parcel_de_named_person_only:
code: namedPersonOnly
type: boolean
dhl_parcel_de_signed_for_by_recipient:
code: signedForByRecipient
type: boolean
dhl_parcel_de_endorsement:
code: endorsement
type: string
dhl_parcel_de_preferred_day:
code: preferredDay
type: string
dhl_parcel_de_no_neighbour_delivery:
code: noNeighbourDelivery
type: boolean
dhl_parcel_de_additional_insurance:
code: additionalInsurance
type: float
dhl_parcel_de_bulky_goods:
code: bulkyGoods
type: boolean
dhl_parcel_de_cash_on_delivery:
code: cashOnDelivery
type: float
dhl_parcel_de_individual_sender_requirement:
code: individualSenderRequirement
type: string
dhl_parcel_de_premium:
code: premium
type: boolean
dhl_parcel_de_closest_drop_point:
code: closestDropPoint
type: boolean
dhl_parcel_de_parcel_outlet_routing:
code: parcelOutletRouting
type: string
dhl_parcel_de_postal_delivery_duty_paid:
code: postalDeliveryDutyPaid
type: boolean
summary: Carrier List
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: listCarriers
/v1/carriers/{carrier_name}:
get:
operationId: '&&get_details'
description: Retrieve a carrier's details
summary: Get carrier details
parameters:
- in: path
name: carrier_name
schema:
type: string
description: 'The unique carrier slug.
Values: `aramex`, `asendia`, `asendia_us`, `australiapost`, `boxknight`, `bpost`, `canadapost`, `canpar`, `chronopost`, `colissimo`, `dhl_express`, `dhl_parcel_de`, `dhl_poland`, `dhl_universal`, `dicom`, `dpd`, `dpd_meta`, `dtdc`, `easypost`, `easyship`, `eshipper`, `fedex`, `freightcom`, `generic`, `geodis`, `gls`, `hay_post`, `hermes`, `landmark`, `laposte`, `locate2u`, `mydhl`, `nationex`, `parcelone`, `postat`, `purolator`, `roadie`, `royalmail`, `sapient`, `seko`, `sendle`, `shipengine`, `smartkargo`, `spring`, `teleship`, `tge`, `tnt`, `ups`, `usps`, `usps_international`, `veho`, `zoom2u`'
required: true
tags:
- Carriers
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CarrierDetails'
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: getDetails
/v1/carriers/{carrier_name}/options:
get:
operationId: '&&get_options'
description: Retrieve a carrier's options
summary: Get carrier options
parameters:
- in: path
name: carrier_name
schema:
type: string
description: 'The unique carrier slug.
Values: `aramex`, `asendia`, `asendia_us`, `australiapost`, `boxknight`, `bpost`, `canadapost`, `canpar`, `chronopost`, `colissimo`, `dhl_express`, `dhl_parcel_de`, `dhl_poland`, `dhl_universal`, `dicom`, `dpd`, `dpd_meta`, `dtdc`, `easypost`, `easyship`, `eshipper`, `fedex`, `freightcom`, `generic`, `geodis`, `gls`, `hay_post`, `hermes`, `landmark`, `laposte`, `locate2u`, `mydhl`, `nationex`, `parcelone`, `postat`, `purolator`, `roadie`, `royalmail`, `sapient`, `seko`, `sendle`, `shipengine`, `smartkargo`, `spring`, `teleship`, `tge`, `tnt`, `ups`, `usps`, `usps_international`, `veho`, `zoom2u`'
required: true
tags:
- Carriers
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: {}
examples:
CarrierOptions:
value:
sendle_hide_pickup_address:
code: hide_pickup_address
type: boolean
sendle_first_mile_option:
code: first_mile_option
type: boolean
summary: Carrier Options
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: getOptions
/v1/carriers/{carrier_name}/services:
get:
operationId: '&&get_services'
description: Retrieve a carrier's services
summary: Get carrier services
parameters:
- in: path
name: carrier_name
schema:
type: string
description: 'The unique carrier slug.
Values: `aramex`, `asendia`, `asendia_us`, `australiapost`, `boxknight`, `bpost`, `canadapost`, `canpar`, `chronopost`, `colissimo`, `dhl_express`, `dhl_parcel_de`, `dhl_poland`, `dhl_universal`, `dicom`, `dpd`, `dpd_meta`, `dtdc`, `easypost`, `easyship`, `eshipper`, `fedex`, `freightcom`, `generic`, `geodis`, `gls`, `hay_post`, `hermes`, `landmark`, `laposte`, `locate2u`, `mydhl`, `nationex`, `parcelone`, `postat`, `purolator`, `roadie`, `royalmail`, `sapient`, `seko`, `sendle`, `shipengine`, `smartkargo`, `spring`, `teleship`, `tge`, `tnt`, `ups`, `usps`, `usps_international`, `veho`, `zoom2u`'
required: true
tags:
- Carriers
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: {}
examples:
CarrierList:
value:
canadapost_regular_parcel: DOM.RP
canadapost_expedited_parcel: DOM.EP
canadapost_xpresspost: DOM.XP
canadapost_xpresspost_certified: DOM.XP.CERT
canadapost_priority: DOM.PC
canadapost_library_books: DOM.LIB
canadapost_expedited_parcel_usa: USA.EP
canadapost_priority_worldwide_envelope_usa: USA.PW.ENV
canadapost_priority_worldwide_pak_usa: USA.PW.PAK
canadapost_priority_worldwide_parcel_usa: USA.PW.PARCEL
canadapost_small_packet_usa_air: USA.SP.AIR
canadapost_tracked_packet_usa: USA.TP
canadapost_tracked_packet_usa_lvm: USA.TP.LVM
canadapost_xpresspost_usa: USA.XP
canadapost_xpresspost_international: INT.XP
canadapost_international_parcel_air: INT.IP.AIR
canadapost_international_parcel_surface: INT.IP.SURF
canadapost_priority_worldwide_envelope_intl: INT.PW.ENV
canadapost_priority_worldwide_pak_intl: INT.PW.PAK
canadapost_priority_worldwide_parcel_intl: INT.PW.PARCEL
canadapost_small_packet_international_air: INT.SP.AIR
canadapost_small_packet_international_surface: INT.SP.SURF
canadapost_tracked_packet_international: INT.TP
summary: Carrier List
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: getServices
components:
schemas:
ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/APIError'
description: The list of API errors
CarrierDetails:
type: object
properties:
carrier_name:
enum:
- aramex
- asendia
- asendia_us
- australiapost
- boxknight
- bpost
- canadapost
- canpar
- chronopost
- colissimo
- dhl_express
- dhl_parcel_de
- dhl_poland
- dhl_universal
- dicom
- dpd
- dpd_meta
- dtdc
- easypost
- easyship
- eshipper
- fedex
- freightcom
- generic
- geodis
- gls
- hay_post
- hermes
- landmark
- laposte
- locate2u
- mydhl
- nationex
- parcelone
- postat
- purolator
- roadie
- royalmail
- sapient
- seko
- sendle
- shipengine
- smartkargo
- spring
- teleship
- tge
- tnt
- ups
- usps
- usps_international
- veho
- zoom2u
type: string
x-spec-enum-id: ae0f7f0940fb5243
description: Indicates a carrier (type)
display_name:
type: string
description: The carrier verbose name.
integration_status:
enum:
- in-development
- beta
- production-ready
type: string
x-spec-enum-id: d58225b23f9a1710
description: The carrier integration status.
capabilities:
type: array
items:
type: string
default: []
description: The carrier supported and enabled capabilities.
connection_fields:
type: object
additionalProperties: {}
default: {}
description: The carrier connection fields.
config_fields:
type: object
additionalProperties: {}
default: {}
description: The carrier connection config.
shipping_services:
type: object
additionalProperties: {}
default: {}
description: The carrier shipping services.
shipping_options:
type: object
additionalProperties: {}
default: {}
description: The carrier shipping options.
required:
- carrier_name
- display_name
- integration_status
APIError:
type: object
properties:
message:
type: string
description: The error or warning message
code:
type: string
description: The message code
level:
type: string
description: The message level
details:
type: object
additionalProperties: {}
description: any additional details
securitySchemes:
JWT:
in: header
type: apiKey
scheme: bearer
bearerFormat: JWT
name: Authorization
description: 'Authorization: Bearer xxx.xxx.xxx'
OAuth2:
type: oauth2
in: header
name: Authorization
flows:
authorizationCode:
authorizationUrl: /oauth/authorize/
tokenUrl: /oauth/token/
scopes:
read: Read access to Karrio data
write: Write access to Karrio data
openid: OpenID connect
description: 'Authorization: Bearer xxxxxxxx'
Token:
type: apiKey
in: header
name: Authorization
description: 'Authorization: Token key_xxxxxxxx'
TokenBasic:
type: http
scheme: basic
name: Authorization
description: '-u key_xxxxxxxx:'