Karrio Trackers 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 Trackers API
  version: 2026.1.32
tags:
- name: Trackers
  description: "This is an object representing your Karrio shipment tracker.\n                A shipment tracker is an object attached to a shipment by it's tracking number.\n                The tracker provide the latest tracking status and events associated with a shipment\n                "
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:
    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
    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
    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)
    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
    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.
    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
    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
    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
    ErrorMessages:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: The list of error messages
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/APIError'
          description: The list of API errors
    Operation:
      type: object
      properties:
        operation:
          type: string
          description: Operation performed
        success:
          type: boolean
          description: Specify whether the operation was successful
      required:
      - operation
      - success
    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
  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:'