Karrio Trackers API
This is an object representing your 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
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/karrio-trackers-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
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 Specification
openapi: 3.2.0
info:
description: Karrio is a multi-carrier shipping API that simplifies the integration of logistics carrier services.
title: Karrio Trackers API
version: 2026.1.32
tags:
- name: Trackers
description: 'This is an object representing your 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'
paths:
/v1/trackers:
get:
operationId: $$$$$$list
description: Retrieve all shipment trackers.
summary: List all package trackers
parameters:
- in: query
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`'
- in: query
name: created_after
schema:
type: string
format: date-time
- in: query
name: created_before
schema:
type: string
format: date-time
- in: query
name: is_archived
schema:
type: boolean
- in: query
name: keyword
schema:
type: string
- in: query
name: request_id
schema:
type: string
- in: query
name: status
schema:
type: string
description: 'Valid tracker status. <br/>Values: `pending`, `picked_up`, `unknown`, `on_hold`, `cancelled`, `delivered`, `in_transit`, `delivery_delayed`, `out_for_delivery`, `ready_for_pickup`, `delivery_failed`, `return_to_sender`'
- in: query
name: tracking_number
schema:
type: string
tags:
- Trackers
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TrackerList'
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: listTrackers
post:
operationId: $$$$$$add
description: 'This API creates or retrieves (if existent) a tracking status object containing the
details and events of a shipping in progress.'
summary: Add a package tracker
parameters:
- in: query
name: hub
schema:
type: string
- in: query
name: pending_pickup
schema:
type: boolean
description: Add this flag to add the tracker whether the tracking info exist or not.When the package is eventually picked up, the tracker with capture real time updates.
tags:
- Trackers
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/TrackingStatus'
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: addTracker
/v1/trackers/{carrier_name}/{tracking_number}:
get:
operationId: $$$$$$create
description: 'This API creates or retrieves (if existent) a tracking status object containing the
details and events of a shipping in progress.'
summary: Create a package tracker
parameters:
- in: path
name: carrier_name
schema:
type: string
required: true
- in: query
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:
- Trackers
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
deprecated: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TrackingStatus'
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: createTracker
/v1/trackers/{identifier}:
get:
operationId: $$$$$$retrieve
description: Retrieve a package tracker by ID or tracking number.
summary: Retrieves a package tracker
parameters:
- in: path
name: identifier
schema:
type: string
description: Tracker ID (trk_...) or tracking number
required: true
tags:
- Trackers
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TrackingStatus'
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessages'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: retrieveTracker
put:
operationId: $$$$$$update
description: Update a package tracker by ID.
summary: Update tracker data
parameters:
- in: path
name: identifier
schema:
type: string
description: Tracker ID (trk_...)
required: true
tags:
- Trackers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TrackerUpdateData'
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TrackingStatus'
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'400':
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: updateTracker
delete:
operationId: $$$$$$remove
description: Remove a package tracker by ID, tracking number, or request_id. The lookup tries the karrio tracker ID first, then tracking number, then falls back to request_id (most recent match).
summary: Discard a package tracker
parameters:
- in: path
name: identifier
schema:
type: string
description: Tracker ID (trk_...), tracking number, or request_id
required: true
tags:
- Trackers
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TrackingStatus'
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: removeTracker
/v1/trackers/{tracker_id}/inject-events:
post:
operationId: $$$$$$inject
description: Inject tracking events into an existing tracker for testing purposes.
summary: Inject tracking events
parameters:
- in: path
name: tracker_id
schema:
type: string
required: true
tags:
- Trackers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TrackerEventInjectRequest'
required: true
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: injectTrackingEvents
components:
schemas:
ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/APIError'
description: The list of API errors
TrackerEventInjectRequest:
type: object
description: Request payload for injecting tracking events.
properties:
events:
type: array
items:
$ref: '#/components/schemas/TrackingEvent'
description: List of tracking events to inject into the tracker
status:
enum:
- pending
- picked_up
- unknown
- on_hold
- cancelled
- delivered
- in_transit
- delivery_delayed
- out_for_delivery
- ready_for_pickup
- delivery_failed
- return_to_sender
- null
type:
- string
- 'null'
x-spec-enum-id: 74b67d0ba94b1fa9
description: 'Optional: Override the tracker status'
delivered:
type: boolean
default: false
description: 'Optional: Mark the tracker as delivered'
estimated_delivery:
type:
- string
- 'null'
format: date
description: 'Optional: Set the estimated delivery date'
required:
- events
TrackingEvent:
type: object
properties:
date:
type: string
description: 'The tracking event''s date. Format: `YYYY-MM-DD`'
time:
type:
- string
- 'null'
description: 'The tracking event''s time. Format: `HH:MM AM/PM`'
timestamp:
type:
- string
- 'null'
description: 'The tracking event''s timestamp. Format: `YYYY-MM-DDTHH:MM:SS.sssZ` (ISO 8601)'
status:
enum:
- pending
- picked_up
- unknown
- on_hold
- cancelled
- delivered
- in_transit
- delivery_delayed
- out_for_delivery
- ready_for_pickup
- delivery_failed
- return_to_sender
- ''
- null
type:
- string
- 'null'
x-spec-enum-id: 74b67d0ba94b1fa9
description: The normalized status of this specific event
code:
type:
- string
- 'null'
description: The tracking event's code
reason:
enum:
- carrier_damaged_parcel
- carrier_sorting_error
- carrier_address_not_found
- carrier_parcel_lost
- carrier_not_enough_time
- carrier_vehicle_issue
- carrier_capacity_exceeded
- carrier_mechanical_delay
- retailer_cancelled
- retailer_incorrect_data
- retailer_not_ready
- retailer_incorrect_parcel
- retailer_incorrect_dimensions
- retailer_packaging_issue
- consignee_refused
- consignee_business_closed
- consignee_not_available
- consignee_not_home
- consignee_cancelled
- consignee_verification_failed
- consignee_incorrect_address
- consignee_access_restricted
- consignee_safe_place_unavailable
- customs_delay
- customs_documentation
- customs_duties_unpaid
- customs_prohibited
- customs_inspection
- weather_delay
- natural_disaster
- force_majeure
- parcel_being_researched
- security_issue
- regulatory_hold
- unknown
- ''
- null
type:
- string
- 'null'
x-spec-enum-id: 8b6be95e78b07e31
description: The normalized incident reason (for exception events only)
description:
type:
- string
- 'null'
description: The tracking event's description
location:
type: string
description: The tracking event's location
latitude:
type:
- number
- 'null'
format: double
description: The tracking event's latitude.
longitude:
type:
- number
- 'null'
format: double
description: The tracking event's longitude.
TrackerUpdateData:
type: object
properties:
info:
allOf:
- $ref: '#/components/schemas/TrackingInfo'
description: The package and shipment tracking details
metadata:
type: object
additionalProperties: {}
description: User metadata for the tracker
Message:
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
carrier_name:
type: string
description: The targeted carrier
carrier_id:
type: string
description: The targeted carrier name (unique identifier)
TrackerList:
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/TrackingStatus'
required:
- results
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
- tracking_number
Operation:
type: object
properties:
operation:
type: string
description: Operation performed
success:
type: boolean
description: Specify whether the operation was successful
required:
- operation
- success
TrackingInfo:
type: object
properties:
carrier_tracking_link:
type:
- string
- 'null'
description: The carrier tracking link
customer_name:
type:
- string
- 'null'
description: The customer name
expected_delivery:
type:
- string
- 'null'
description: The expected delivery date
note:
type:
- string
- 'null'
description: A tracking note
order_date:
type:
- string
- 'null'
description: The package order date
order_id:
type:
- string
- 'null'
description: The package order id or number
package_weight:
type:
- string
- 'null'
description: The package weight
package_weight_unit:
type:
- string
- 'null'
description: The package weight unit
shipment_package_count:
type:
- string
- 'null'
description: The package count
shipment_pickup_date:
type:
- string
- 'null'
description: The shipment pickup date
shipment_delivery_date:
type:
- string
- 'null'
description: The shipment delivery date
shipment_service:
type:
- string
- 'null'
description: The shipment service
shipment_origin_country:
type:
- string
- 'null'
description: The shipment origin country
shipment_origin_postal_code:
type:
- string
- 'null'
description: The shipment origin postal code
shipment_destination_country:
type:
- string
- 'null'
description: The shipment destination country
shipment_destination_postal_code:
type:
- string
- 'null'
description: The shipment destination postal code
shipping_date:
type:
- string
- 'null'
description: The shipping date
signed_by:
type:
- string
- 'null'
description: The person who signed for the package
source:
type:
- string
- 'null'
description: The tracker source
ErrorMessages:
type: object
properties:
messages:
type: array
items:
$ref: '#/components/schemas/Message'
description: The list of error messages
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
TrackingStatus:
type: object
properties:
id:
type: string
description: A unique identifier
carrier_name:
type: string
description: The tracking carrier
carrier_id:
type: string
description: The tracking carrier configured identifier
tracking_number:
type: string
description: The shipment tracking number
info:
allOf:
- $ref: '#/components/schemas/TrackingInfo'
default:
carrier_tracking_link: null
customer_name: null
expected_delivery: null
note: null
order_date: null
order_id: null
package_weight: null
package_weight_unit: null
shipment_package_count: null
shipment_pickup_date: null
shipment_delivery_date: null
shipment_service: null
shipment_origin_country: null
shipment_origin_postal_code: null
shipment_destination_country: null
shipment_destination_postal_code: null
shipping_date: null
signed_by: null
source: null
description: The package and shipment tracking details
events:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/TrackingEvent'
description: The tracking details events
delivered:
type: boolean
description: Specified whether the related shipment was delivered
test_mode:
type: boolean
description: Specified whether the object was created with a carrier in test mode
status:
enum:
- pending
- picked_up
- unknown
- on_hold
- cancelled
- delivered
- in_transit
- delivery_delayed
- out_for_delivery
- ready_for_pickup
- delivery_failed
- return_to_sender
type: string
x-spec-enum-id: 74b67d0ba94b1fa9
default: pending
description: The current tracking status
estimated_delivery:
type: string
description: The delivery estimated date
meta:
type:
- object
- 'null'
additionalProperties: {}
description: provider specific metadata
object_type:
type: string
default: tracker
description: Specifies the object type
is_archived:
type: boolean
default: false
description: Indicates whether this tracker is archived.
archived_at:
type:
- string
- 'null'
description: Timestamp when the tracker was archived.
metadata:
type: object
additionalProperties: {}
default: {}
description: User metadata for the tracker
messages:
type: array
items:
$ref: '#/components/schemas/Message'
default: []
description: The list of note or warning messages
delivery_image_url:
type:
- string
- 'null'
format: uri
description: The shipment invoice URL
signature_image_url:
type:
- string
- 'null'
format: uri
description: The shipment invoice URL
required:
- carrier_id
- carrier_name
- test_mode
- tracking_number
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:'