In some scenarios, all we need is to send request to a carrier using the Karrio unified API. The Proxy API comes handy for that as it turn Karrio into a simple middleware that converts and validate your request and simply forward it to the shipping carrier server. **Note:** When using the proxy API, no objects are created in the Karrio system. excpet API logs and tracing records for debugging purposes.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/karrio-proxy-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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 Proxy API
version: 2026.1.32
tags:
- name: Proxy
description: "In some scenarios, all we need is to send request to a carrier using the Karrio unified API.\n The Proxy API comes handy for that as it turn Karrio into a simple middleware that converts and\n validate your request and simply forward it to the shipping carrier server.<br/>\n **Note:**<br/>\n When using the proxy API, no objects are created in the Karrio system.\n excpet API logs and tracing records for debugging purposes.\n "
paths:
/v1/proxy/manifest:
post:
operationId: '@@@$generate_manifest'
description: '
Some carriers require shipment manifests to be created for pickups and dropoff.
Creating a manifest for a shipment also kicks off billing as a commitment or confirmation of the shipment.
'
summary: Create a manifest
tags:
- Proxy
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ManifestRequest'
required: true
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ManifestResponse'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'424':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessages'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: generateManifest
/v1/proxy/pickups/{carrier_name}:
post:
operationId: '@schedule_pickup'
description: Schedule one or many parcels pickup
summary: Schedule a pickup
parameters:
- in: path
name: carrier_name
schema:
type: string
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
required: true
tags:
- Proxy
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PickupRequest'
required: true
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/PickupResponse'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'424':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessages'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: pickupSchedule
/v1/proxy/pickups/{carrier_name}/cancel:
post:
operationId: '@cancel_pickup'
description: Cancel a pickup previously scheduled
summary: Cancel a pickup
parameters:
- in: path
name: carrier_name
schema:
type: string
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
required: true
tags:
- Proxy
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PickupCancelRequest'
required: true
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/OperationResponse'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'424':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessages'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: pickupCancel
/v1/proxy/pickups/{carrier_name}/update:
post:
operationId: '@update_pickup'
description: Modify a scheduled pickup
summary: Update a pickup
parameters:
- in: path
name: carrier_name
schema:
type: string
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
required: true
tags:
- Proxy
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PickupUpdateRequest'
required: true
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PickupResponse'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'424':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessages'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: pickupUpdate
/v1/proxy/rates:
post:
operationId: '@@fetch_rates'
description: '
The Shipping process begins by fetching rates for your shipment.
Use this service to fetch a shipping rates available.
'
summary: Fetch shipment rates
tags:
- Proxy
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RateRequest'
required: true
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RateResponse'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'424':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessages'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: fetchRates
/v1/proxy/shipping:
post:
operationId: '@@@buy_label'
description: 'Once the shipping rates are retrieved, provide the required info to
submit the shipment by specifying your preferred rate.'
summary: Buy a shipment label
tags:
- Proxy
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ShippingRequest'
required: true
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ShippingResponse'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'424':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessages'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: buyLabel
/v1/proxy/shipping/{carrier_name}/cancel:
post:
operationId: '@@@void_label'
description: Cancel a shipment and the label previously created
summary: Void a shipment label
parameters:
- in: path
name: carrier_name
schema:
type: string
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
required: true
tags:
- Proxy
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentCancelRequest'
required: true
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/OperationResponse'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'424':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessages'
description: ''
x-operationId: voidLabel
/v1/proxy/tracking:
post:
operationId: '@@@@get_tracking'
description: You can track a shipment by specifying the carrier and the shipment tracking number.
summary: Get tracking details
parameters:
- in: query
name: hub
schema:
type: string
tags:
- Proxy
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TrackingData'
required: true
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TrackingResponse'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'424':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessages'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: getTracking
/v1/proxy/tracking/{carrier_name}/{tracking_number}:
get:
operationId: '@@@@track_shipment'
description: You can track a shipment by specifying the carrier and the shipment tracking number.
summary: Track a shipment
parameters:
- in: path
name: carrier_name
schema:
type: string
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
- fedex
- generic
- geodis
- gls
- hay_post
- hermes
- landmark
- laposte
- locate2u
- mydhl
- nationex
- postat
- purolator
- roadie
- royalmail
- seko
- sendle
- smartkargo
- spring
- teleship
- tge
- tnt
- ups
- usps
- usps_international
- veho
- zoom2u
required: true
- in: query
name: hub
schema:
type: string
- in: path
name: tracking_number
schema:
type: string
required: true
tags:
- Proxy
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
deprecated: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TrackingResponse'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'424':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessages'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: trackShipment
components:
schemas:
Documents:
type: object
properties:
label:
type:
- string
- 'null'
description: A shipping label in base64 string
invoice:
type:
- string
- 'null'
description: A shipping invoice in base64 string
extra_documents:
type: array
items:
$ref: '#/components/schemas/ShippingDocument'
default: []
description: Additional shipping documents (return labels, COD documents, etc.)
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.<br/>\n **Note that the packaging is optional when using a package preset.**<br/>\n values: <br/>\n `envelope` `pak` `tube` `pallet` `small_box` `medium_box` `your_packaging`<br/>\n For carrier specific packaging types, please consult the reference.\n "
maxLength: 100
package_preset:
type:
- string
- 'null'
description: "The parcel's package preset.<br/>\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.<br/>\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: "<details>\n <summary>Parcel specific options.</summary>\n\n {\n \"insurance\": \"100.00\",\n \"insured_by\": \"carrier\",\n }\n </details>\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
Rate:
type: object
properties:
id:
type: string
description: A unique identifier
object_type:
type: string
default: rate
description: Specifies the object type
carrier_name:
type: string
description: The rate's carrier
carrier_id:
type: string
description: The targeted carrier's name (unique identifier)
currency:
type: string
description: The rate monetary values currency code
service:
type:
- string
- 'null'
description: The carrier's rate (quote) service
total_charge:
type: number
format: double
default: 0.0
description: "The rate's monetary amount of the total charge.<br/>\n This is the gross amount of the rate after adding the additional charges\n "
transit_days:
type:
- integer
- 'null'
description: The estimated delivery transit days
extra_charges:
type: array
items:
$ref: '#/components/schemas/Charge'
default: []
description: list of the rate's additional charges
estimated_delivery:
type:
- string
- 'null'
description: The delivery estimated date
meta:
type:
- object
- 'null'
additionalProperties: {}
description: provider specific metadata
test_mode:
type: boolean
description: Specified whether it was created with a carrier in test mode
required:
- carrier_id
- carrier_name
- test_mode
RateRequest:
type: object
properties:
shipper:
allOf:
- $ref: '#/components/schemas/AddressData'
description: "The address of the party<br/>\n Origin address (ship from) for the **shipper**<br/>\n Destination address (ship to) for the **recipient**\n "
recipient:
allOf:
- $ref: '#/components/schemas/AddressData'
description: "The address of the party<br/>\n Origin address (ship from) for the **shipper**<br/>\n Destination address (ship to) for the **recipient**\n "
parcels:
type: array
items:
$ref: '#/components/schemas/ParcelData'
description: The shipment's parcels
services:
type:
- array
- 'null'
items:
type: string
default: []
description: "The requested carrier service for the shipment.<br/>\n Please consult the reference for specific carriers services.<br/>\n Note that this is a list because on a Multi-carrier rate request you could specify a service per carrier.\n "
options:
type: object
additionalProperties: {}
default: {}
description: "<details>\n <summary>The options available for the shipment.</summary>\n\n {\n \"currency\": \"USD\",\n \"insurance\": 100.00,\n \"insured_by\": \"carrier\",\n \"cash_on_delivery\": 30.00,\n \"dangerous_good\": true,\n \"declared_value\": 150.00,\n \"sms_notification\": true,\n \"email_notification\": true,\n \"email_notification_to\": \"shipper@mail.com\",\n \"hold_at_location\": true,\n \"paperless_trade\": true,\n \"preferred_service\": \"fedex_express_saver\",\n \"shipment_date\": \"2020-01-01\", # TODO: deprecate\n \"shipping_date\": \"2020-01-01T00:00\",\n \"shipment_note\": \"This is a shipment note\",\n \"signature_confirmation\": true,\n \"saturday_delivery\": true,\n \"shipper_instructions\": \"This is a shipper instruction\",\n \"recipient_instructions\": \"This is a recipient instruction\",\n \"doc_files\": [\n {\n \"doc_type\": \"commercial_invoice\",\n \"doc_file\": \"base64 encoded file\",\n \"doc_name\": \"commercial_invoice.pdf\",\n \"doc_format\": \"pdf\",\n }\n ],\n \"doc_references\": [\n {\n \"doc_id\": \"123456789\",\n \"doc_type\": \"commercial_invoice\",\n }\n ],\n }\n </details>\n "
reference:
type:
- string
- 'null'
description: The shipment reference
payment:
allOf:
- $ref: '#/components/schemas/Payment'
description: The payment details
customs:
allOf:
- $ref: '#/components/schemas/CustomsData'
description: "The customs details.<br/>\n **Note that this is required for international shipments.**\n "
return_address:
allOf:
- $ref: '#/components/schemas/AddressData'
description: The return address for this shipment. Defaults to the shipper address.
billing_address:
allOf:
- $ref: '#/components/schemas/AddressData'
description: The billing address for this shipment.
is_return:
type: boolean
default: false
description: Indicates whether this is a return shipment rate request.
carrier_ids:
type:
- array
- 'null'
items:
type: string
default: []
description: The list of configured carriers you wish to get rates from.
required:
- parcels
- recipient
- shipper
TrackingData:
type: object
properties:
tracking_number:
type: string
description: The package tracking number
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
- fedex
- generic
- geodis
- gls
- hay_post
- hermes
- landmark
- laposte
- locate2u
- mydhl
- nationex
- postat
- purolator
- roadie
- royalmail
- seko
- sendle
- smartkargo
- spring
- teleship
- tge
- tnt
- ups
- usps
- usps_international
- veho
- zoom2u
type: string
x-spec-enum-id: b6c8e3114206d815
description: The tracking carrier
account_number:
type:
- string
- 'null'
description: The shipper account number
reference:
type:
- string
- 'null'
description: The shipment reference
info:
allOf:
- $ref: '#/components/schemas/TrackingInfo'
description: The package and shipment tracking details
metadata:
type: object
additionalProperties: {}
default: {}
description: The carrier user metadata.
required:
- carrier_name
- tracki
# --- truncated at 32 KB (114 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/karrio/refs/heads/main/openapi/karrio-proxy-api-openapi.yml