Karrio Carriers API

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. <br/>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. <br/>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. <br/>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:'