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 Manifests API
  version: 2026.1.32
tags:
- name: Manifests
  description: "This is an object representing your Karrio manifest details.\n                Some carriers require manifests to be created after labels are generated.\n                A manifest is a summary of all the shipments that are being sent out.\n                "
paths:
  /v1/manifests:
    get:
      operationId: $$$$&&list
      description: Retrieve all manifests.
      summary: List manifests
      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
      tags:
      - Manifests
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManifestList'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
      x-operationId: listManifests
    post:
      operationId: $$$$&&create
      description: Create a manifest for one or many shipments with labels already purchased.
      summary: Create a manifest
      tags:
      - Manifests
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManifestData'
        required: true
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Manifest'
          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: createManifest
  /v1/manifests/{id}:
    get:
      operationId: $$$$&&retrieve
      description: Retrieve a shipping manifest.
      summary: Retrieve a manifest
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - Manifests
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Manifest'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
      x-operationId: retrieveManifest
  /v1/manifests/{id}/document:
    post:
      operationId: $$$$&&document
      description: Retrieve a manifest document as base64 encoded content.
      summary: Retrieve a manifest document
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - Manifests
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingDocument'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
      x-operationId: retrieveManifestDocument
components:
  schemas:
    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)
    AddressData:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: A unique identifier for the address (used in JSON embedded data)
        postal_code:
          type:
          - string
          - 'null'
          description: "The address postal code\n        **(required for shipment purchase)**\n        "
          maxLength: 20
        city:
          type:
          - string
          - 'null'
          description: "The address city.\n        **(required for shipment purchase)**\n        "
          maxLength: 50
        federal_tax_id:
          type:
          - string
          - 'null'
          description: The party frederal tax id
          maxLength: 50
        state_tax_id:
          type:
          - string
          - 'null'
          description: The party state id
          maxLength: 50
        person_name:
          type:
          - string
          - 'null'
          description: "Attention to\n        **(required for shipment purchase)**\n        "
          maxLength: 100
        company_name:
          type:
          - string
          - 'null'
          description: The company name if the party is a company
          maxLength: 100
        country_code:
          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
          type: string
          x-spec-enum-id: b4b44aee15c8daa0
          description: The address country code
        email:
          type:
          - string
          - 'null'
          description: The party email
        phone_number:
          type:
          - string
          - 'null'
          description: The party phone number.
          maxLength: 50
        state_code:
          type:
          - string
          - 'null'
          description: The address state code
          maxLength: 50
        residential:
          type:
          - boolean
          - 'null'
          default: false
          description: Indicate if the address is residential or commercial (enterprise)
        street_number:
          type:
          - string
          - 'null'
          description: The address street number
          maxLength: 100
        address_line1:
          type:
          - string
          - 'null'
          description: "The address line with street number <br/>\n        **(required for shipment purchase)**\n        "
          maxLength: 100
        address_line2:
          type:
          - string
          - 'null'
          description: The address line with suite number
          maxLength: 100
        validate_location:
          type:
          - boolean
          - 'null'
          default: false
          description: Indicate if the address should be validated
        meta:
          type:
          - object
          - 'null'
          additionalProperties: {}
          description: "Template metadata for template identification.\n        Structure: {\"label\": \"Warehouse A\", \"is_default\": true, \"usage\": [\"sender\", \"return\"]}\n        "
      required:
      - country_code
    Manifest:
      type: object
      properties:
        id:
          type: string
          description: A unique manifest identifier
        object_type:
          type: string
          default: manifest
          description: Specifies the object type
        carrier_name:
          type: string
          description: The manifest carrier
        carrier_id:
          type: string
          description: The manifest carrier configured name
        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
        address:
          allOf:
          - $ref: '#/components/schemas/AddressData'
          description: The address of the warehouse or location where the shipments originate.
        options:
          type: object
          additionalProperties: {}
          default: {}
          description: "<details>\n        <summary>The options available for the manifest.</summary>\n\n        {\n            \"shipments\": [\n                {\n                    \"tracking_number\": \"123456789\",\n                    ...\n                    \"meta\": {...}\n                }\n            ]\n        }\n        </details>\n        "
        reference:
          type:
          - string
          - 'null'
          description: The manifest reference
        shipment_identifiers:
          type: array
          items:
            type: string
          description: "The list of shipment identifiers you want to add to your manifest.<br/>\n        shipment_identifier is often a tracking_number or shipment_id returned when you purchase a label.\n        "
        metadata:
          type: object
          additionalProperties: {}
          default: {}
          description: User metadata for the pickup
        manifest_url:
          type:
          - string
          - 'null'
          format: uri
          description: The Manifest file URL
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          default: []
          description: The list of note or warning messages
      required:
      - address
      - carrier_id
      - carrier_name
      - shipment_identifiers
      - test_mode
    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
    ManifestData:
      type: object
      properties:
        carrier_name:
          type: string
          description: The manifest's carrier
        address:
          allOf:
          - $ref: '#/components/schemas/AddressData'
          description: The address of the warehouse or location where the shipments originate.
        options:
          type: object
          additionalProperties: {}
          default: {}
          description: "<details>\n        <summary>The options available for the manifest.</summary>\n\n        {\n            \"shipments\": [\n                {\n                    \"tracking_number\": \"123456789\",\n                    ...\n                    \"meta\": {...}\n                }\n            ]\n        }\n        </details>\n        "
        reference:
          type:
          - string
          - 'null'
          description: The manifest reference
        shipment_ids:
          type: array
          items:
            type: string
          description: The list of existing shipment object ids with label purchased.
      required:
      - address
      - carrier_name
      - shipment_ids
    ShippingDocument:
      type: object
      description: Serializer for shipping document download response.
      properties:
        category:
          type: string
          description: The document category (e.g., 'label', 'invoice', 'manifest')
        format:
          type: string
          description: The document format (e.g., 'PDF', 'ZPL')
        print_format:
          type:
          - string
          - 'null'
          description: The document print format (e.g., 'A4', '6x4', '8.5x11')
        url:
          type:
          - string
          - 'null'
          description: The document URL
        base64:
          type:
          - string
          - 'null'
          description: The document content encoded in base64
      required:
      - category
      - format
    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
    ManifestList:
      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/Manifest'
      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:'