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 Parcels API version: 2026.1.32 tags: - name: Parcels description: "This is an object representing your Karrio shipping parcel.\n Parcel objects are linked to your shipment history, and can be used for recurring shipping\n using the same packaging.\n " paths: /v1/parcels: get: operationId: $$$list description: "\n Retrieve all stored parcels.\n\n Query Parameters:\n - label: Filter by meta.label (case-insensitive contains)\n - keyword: Search by label\n - usage: Filter by meta.usage (exact match in array)\n " summary: List all parcels tags: - Parcels security: - TokenBasic: [] - Token: [] - OAuth2: [] - JWT: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ParcelList' description: '' '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' x-operationId: listParcels post: operationId: $$$create description: Create a new parcel. summary: Create a parcel tags: - Parcels requestBody: content: application/json: schema: $ref: '#/components/schemas/ParcelData' required: true security: - TokenBasic: [] - Token: [] - OAuth2: [] - JWT: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/Parcel' description: '' '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' x-operationId: createParcel /v1/parcels/{id}: get: operationId: $$$retrieve description: Retrieve a parcel. summary: Retrieve a parcel parameters: - in: path name: id schema: type: string required: true tags: - Parcels security: - TokenBasic: [] - Token: [] - OAuth2: [] - JWT: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/Parcel' description: '' '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' x-operationId: retrieveParcel patch: operationId: $$$update description: modify an existing parcel's details. summary: Update a parcel parameters: - in: path name: id schema: type: string required: true tags: - Parcels requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedParcelData' security: - TokenBasic: [] - Token: [] - OAuth2: [] - JWT: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/Parcel' description: '' '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' x-operationId: updateParcel delete: operationId: $$$discard description: Remove a parcel. summary: Remove a parcel parameters: - in: path name: id schema: type: string required: true tags: - Parcels security: - TokenBasic: [] - Token: [] - OAuth2: [] - JWT: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/Parcel' description: '' '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' x-operationId: discardParcel components: schemas: CommodityData: type: object properties: weight: type: number format: double description: The commodity's weight weight_unit: enum: - KG - LB - OZ - G type: string x-spec-enum-id: 3a766910e8401666 description: The commodity's weight unit title: type: - string - 'null' description: A description of the commodity maxLength: 200 description: type: - string - 'null' description: A description of the commodity maxLength: 200 quantity: type: integer default: 1 description: The commodity's quantity (number or item) sku: type: - string - 'null' description: The commodity's sku number maxLength: 100 hs_code: type: - string - 'null' description: The commodity's hs_code number maxLength: 100 value_amount: type: - number - 'null' format: double description: The monetary value of the commodity value_currency: enum: - EUR - AED - USD - XCD - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - XOF - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - XAF - CHF - NZD - CLP - CNY - COP - CRC - CUC - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - FJD - GBP - GEL - GHS - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - XPF - NGN - NIO - NOK - NPR - OMR - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - SYP - SZL - THB - TJS - TND - TOP - TRY - TTD - TWD - TZS - UAH - UYU - UZS - VEF - VND - VUV - WST - YER - ZAR - null type: - string - 'null' x-spec-enum-id: fd73376ae25ab80b description: The currency of the commodity value amount origin_country: enum: - AC - 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 - EH - IM - BL - MF - SX - null type: - string - 'null' x-spec-enum-id: b4b44aee15c8daa0 description: The origin or manufacture country product_url: type: - string - 'null' description: The product url image_url: type: - string - 'null' description: The image url product_id: type: - string - 'null' description: The product id variant_id: type: - string - 'null' description: The variant id parent_id: type: - string - 'null' description: The id of the related order line item. metadata: type: - object - 'null' additionalProperties: {} description: "
\n Commodity user references metadata.\n\n {\n \"part_number\": \"5218487281\",\n \"reference1\": \"# ref 1\",\n \"reference2\": \"# ref 2\",\n \"reference3\": \"# ref 3\",\n ...\n }\n
\n " meta: type: - object - 'null' additionalProperties: {} description: "Template metadata for template identification.\n Structure: {\"label\": \"Widget Pro\", \"is_default\": false}\n " required: - weight - weight_unit Parcel: type: object properties: id: type: string description: A unique identifier weight: type: number format: double description: The parcel's weight width: type: - number - 'null' format: double description: The parcel's width height: type: - number - 'null' format: double description: The parcel's height length: type: - number - 'null' format: double description: The parcel's length packaging_type: type: - string - 'null' description: "The parcel's packaging type.
\n **Note that the packaging is optional when using a package preset.**
\n values:
\n `envelope` `pak` `tube` `pallet` `small_box` `medium_box` `your_packaging`
\n For carrier specific packaging types, please consult the reference.\n " maxLength: 100 package_preset: type: - string - 'null' description: "The parcel's package preset.
\n For carrier specific package presets, please consult the reference.\n " maxLength: 100 description: type: - string - 'null' description: The parcel's description maxLength: 250 content: type: - string - 'null' description: The parcel's content description maxLength: 100 is_document: type: - boolean - 'null' default: false description: Indicates if the parcel is composed of documents only weight_unit: enum: - KG - LB - OZ - G type: string x-spec-enum-id: 3a766910e8401666 description: The parcel's weight unit dimension_unit: enum: - CM - IN - null type: - string - 'null' x-spec-enum-id: 41993cb8117c279c description: The parcel's dimension unit items: type: array items: $ref: '#/components/schemas/Commodity' description: The parcel items. reference_number: type: - string - 'null' description: "The parcel reference number.
\n (can be used as tracking number for custom carriers)\n " maxLength: 100 freight_class: type: - string - 'null' description: The parcel's freight class for pallet and freight shipments. maxLength: 6 options: type: object additionalProperties: {} default: {} description: "
\n Parcel specific options.\n\n {\n \"insurance\": \"100.00\",\n \"insured_by\": \"carrier\",\n }\n
\n " meta: type: - object - 'null' additionalProperties: {} description: "Template metadata for template identification.\n Structure: {\"label\": \"Standard Box\", \"is_default\": true}\n " object_type: type: string default: parcel description: Specifies the object type required: - weight - weight_unit Commodity: type: object properties: id: type: string description: A unique identifier weight: type: number format: double description: The commodity's weight weight_unit: enum: - KG - LB - OZ - G type: string x-spec-enum-id: 3a766910e8401666 description: The commodity's weight unit title: type: - string - 'null' description: A description of the commodity maxLength: 200 description: type: - string - 'null' description: A description of the commodity maxLength: 200 quantity: type: integer default: 1 description: The commodity's quantity (number or item) sku: type: - string - 'null' description: The commodity's sku number maxLength: 100 hs_code: type: - string - 'null' description: The commodity's hs_code number maxLength: 100 value_amount: type: - number - 'null' format: double description: The monetary value of the commodity value_currency: enum: - EUR - AED - USD - XCD - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - XOF - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - XAF - CHF - NZD - CLP - CNY - COP - CRC - CUC - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - FJD - GBP - GEL - GHS - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - XPF - NGN - NIO - NOK - NPR - OMR - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - SYP - SZL - THB - TJS - TND - TOP - TRY - TTD - TWD - TZS - UAH - UYU - UZS - VEF - VND - VUV - WST - YER - ZAR - null type: - string - 'null' x-spec-enum-id: fd73376ae25ab80b description: The currency of the commodity value amount origin_country: enum: - AC - 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 - EH - IM - BL - MF - SX - null type: - string - 'null' x-spec-enum-id: b4b44aee15c8daa0 description: The origin or manufacture country product_url: type: - string - 'null' description: The product url image_url: type: - string - 'null' description: The image url product_id: type: - string - 'null' description: The product id variant_id: type: - string - 'null' description: The variant id parent_id: type: - string - 'null' description: The id of the related order line item. metadata: type: - object - 'null' additionalProperties: {} description: "
\n Commodity user references metadata.\n\n {\n \"part_number\": \"5218487281\",\n \"reference1\": \"# ref 1\",\n \"reference2\": \"# ref 2\",\n \"reference3\": \"# ref 3\",\n ...\n }\n
\n " meta: type: - object - 'null' additionalProperties: {} description: "Template metadata for template identification.\n Structure: {\"label\": \"Widget Pro\", \"is_default\": false}\n " object_type: type: string default: commodity description: Specifies the object type required: - weight - weight_unit 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 ErrorResponse: type: object properties: errors: type: array items: $ref: '#/components/schemas/APIError' description: The list of API errors PatchedParcelData: type: object properties: weight: type: number format: double description: The parcel's weight width: type: - number - 'null' format: double description: The parcel's width height: type: - number - 'null' format: double description: The parcel's height length: type: - number - 'null' format: double description: The parcel's length packaging_type: type: - string - 'null' description: "The parcel's packaging type.
\n **Note that the packaging is optional when using a package preset.**
\n values:
\n `envelope` `pak` `tube` `pallet` `small_box` `medium_box` `your_packaging`
\n For carrier specific packaging types, please consult the reference.\n " maxLength: 100 package_preset: type: - string - 'null' description: "The parcel's package preset.
\n For carrier specific package presets, please consult the reference.\n " maxLength: 100 description: type: - string - 'null' description: The parcel's description maxLength: 250 content: type: - string - 'null' description: The parcel's content description maxLength: 100 is_document: type: - boolean - 'null' default: false description: Indicates if the parcel is composed of documents only weight_unit: enum: - KG - LB - OZ - G type: string x-spec-enum-id: 3a766910e8401666 description: The parcel's weight unit dimension_unit: enum: - CM - IN - null type: - string - 'null' x-spec-enum-id: 41993cb8117c279c description: The parcel's dimension unit items: type: array items: $ref: '#/components/schemas/CommodityData' description: The parcel items. reference_number: type: - string - 'null' description: "The parcel reference number.
\n (can be used as tracking number for custom carriers)\n " maxLength: 100 freight_class: type: - string - 'null' description: The parcel's freight class for pallet and freight shipments. maxLength: 6 options: type: object additionalProperties: {} default: {} description: "
\n Parcel specific options.\n\n {\n \"insurance\": \"100.00\",\n \"insured_by\": \"carrier\",\n }\n
\n " meta: type: - object - 'null' additionalProperties: {} description: "Template metadata for template identification.\n Structure: {\"label\": \"Standard Box\", \"is_default\": true}\n " ParcelData: type: object properties: weight: type: number format: double description: The parcel's weight width: type: - number - 'null' format: double description: The parcel's width height: type: - number - 'null' format: double description: The parcel's height length: type: - number - 'null' format: double description: The parcel's length packaging_type: type: - string - 'null' description: "The parcel's packaging type.
\n **Note that the packaging is optional when using a package preset.**
\n values:
\n `envelope` `pak` `tube` `pallet` `small_box` `medium_box` `your_packaging`
\n For carrier specific packaging types, please consult the reference.\n " maxLength: 100 package_preset: type: - string - 'null' description: "The parcel's package preset.
\n For carrier specific package presets, please consult the reference.\n " maxLength: 100 description: type: - string - 'null' description: The parcel's description maxLength: 250 content: type: - string - 'null' description: The parcel's content description maxLength: 100 is_document: type: - boolean - 'null' default: false description: Indicates if the parcel is composed of documents only weight_unit: enum: - KG - LB - OZ - G type: string x-spec-enum-id: 3a766910e8401666 description: The parcel's weight unit dimension_unit: enum: - CM - IN - null type: - string - 'null' x-spec-enum-id: 41993cb8117c279c description: The parcel's dimension unit items: type: array items: $ref: '#/components/schemas/CommodityData' description: The parcel items. reference_number: type: - string - 'null' description: "The parcel reference number.
\n (can be used as tracking number for custom carriers)\n " maxLength: 100 freight_class: type: - string - 'null' description: The parcel's freight class for pallet and freight shipments. maxLength: 6 options: type: object additionalProperties: {} default: {} description: "
\n Parcel specific options.\n\n {\n \"insurance\": \"100.00\",\n \"insured_by\": \"carrier\",\n }\n
\n " meta: type: - object - 'null' additionalProperties: {} description: "Template metadata for template identification.\n Structure: {\"label\": \"Standard Box\", \"is_default\": true}\n " required: - weight - weight_unit ParcelList: type: object properties: count: type: - integer - 'null' next: type: - string - 'null' format: uri previous: type: - string - 'null' format: uri results: type: array items: $ref: '#/components/schemas/Parcel' required: - results 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:'