Karrio Documents 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 Documents API
  version: 2026.1.32
tags:
- name: Documents
  description: "This is an object representing your Karrio document upload record.\n                A Document upload record keep traces of shipping trade documents uploaded to carriers\n                to fast track customs and border processing.\n                "
paths:
  /v1/documents/generate:
    post:
      operationId: '&&&&$$generateDocument'
      description: 'Generate any document.

        This API is designed to be used to generate GS1 labels,

        invoices and any document that requires external data.'
      summary: Generate a document
      tags:
      - Documents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentData'
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratedDocument'
          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: ''
  /v1/documents/templates:
    get:
      operationId: '&&&&$$list'
      description: Retrieve all templates.
      summary: List all templates
      tags:
      - Documents
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTemplateList'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
      x-operationId: listDocumentTemplates
    post:
      operationId: '&&&&$$create'
      description: Create a new template.
      summary: Create a template
      tags:
      - Documents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentTemplateData'
        required: true
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTemplate'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
      x-operationId: createDocumentTemplate
  /v1/documents/templates/{id}:
    get:
      operationId: '&&&&$$retrieve'
      description: Retrieve a template.
      summary: Retrieve a template
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - Documents
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTemplate'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
      x-operationId: retrieveDocumentTemplate
    patch:
      operationId: '&&&&$$update'
      description: update a template.
      summary: Update a template
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - Documents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedDocumentTemplateData'
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTemplate'
          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: updateDocumentTemplate
    delete:
      operationId: '&&&&$$discard'
      description: Delete a template.
      summary: Delete a template
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - Documents
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTemplate'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
      x-operationId: discardDocumentTemplate
  /v1/documents/uploads:
    get:
      operationId: $$$$$&uploads
      description: Retrieve all shipping document upload records.
      summary: List all upload records
      parameters:
      - 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: shipment_id
        schema:
          type: string
      tags:
      - Documents
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadRecords'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
    post:
      operationId: $$$$$&upload
      description: Upload a shipping document.
      summary: Upload documents
      tags:
      - Documents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentUploadData'
        required: true
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadRecord'
          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: ''
  /v1/documents/uploads/{id}:
    get:
      operationId: $$$$$&retrieve_upload
      description: Retrieve a shipping document upload record.
      summary: Retrieve upload record
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - Documents
      security:
      - TokenBasic: []
      - Token: []
      - OAuth2: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadRecord'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: ''
components:
  schemas:
    GeneratedDocument:
      type: object
      properties:
        template_id:
          type: string
          description: The template name
        doc_format:
          type: string
          description: The format of the document
        doc_name:
          type: string
          description: The file name
        doc_file:
          type: string
          description: A base64 file content
      required:
      - doc_file
    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)
    DocumentTemplateData:
      type: object
      properties:
        name:
          type: string
          description: The template name
          maxLength: 255
        slug:
          type: string
          description: The template slug
          maxLength: 255
        template:
          type: string
          description: The template content
        active:
          type: boolean
          default: true
          description: disable template flag.
        description:
          type: string
          description: The template description
          maxLength: 255
        metadata:
          type: object
          additionalProperties: {}
          description: The template metadata
        options:
          type: object
          additionalProperties: {}
          description: The template rendering options
        related_object:
          enum:
          - shipment
          - order
          - other
          type: string
          x-spec-enum-id: b3691dad14d14121
          default: other
          description: The template related object
      required:
      - name
      - slug
      - template
    DocumentDetails:
      type: object
      properties:
        doc_id:
          type: string
          description: The uploaded document id.
        file_name:
          type: string
          description: The uploaded document file name.
    DocumentTemplate:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier
        name:
          type: string
          description: The template name
          maxLength: 255
        slug:
          type: string
          description: The template slug
          maxLength: 255
        template:
          type: string
          description: The template content
        active:
          type: boolean
          default: true
          description: disable template flag.
        description:
          type: string
          description: The template description
          maxLength: 255
        metadata:
          type: object
          additionalProperties: {}
          description: The template metadata
        options:
          type: object
          additionalProperties: {}
          description: The template rendering options
        related_object:
          enum:
          - shipment
          - order
          - other
          type: string
          x-spec-enum-id: b3691dad14d14121
          default: other
          description: The template related object
        object_type:
          type: string
          default: document-template
          description: Specifies the object type
        preview_url:
          type: string
          format: uri
          description: The template preview URL
      required:
      - name
      - slug
      - template
    DocumentData:
      type: object
      properties:
        template_id:
          type: string
          description: The template name. **Required if template is not provided.**
        template:
          type: string
          description: The template content. **Required if template_id is not provided.**
        doc_format:
          type: string
          description: The format of the document
        doc_name:
          type: string
          description: The file name
        data:
          type: object
          additionalProperties: {}
          default: {}
          description: The template data
        options:
          type: object
          additionalProperties: {}
          description: The template rendering options
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/APIError'
          description: The list of API errors
    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
    DocumentTemplateList:
      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/DocumentTemplate'
      required:
      - results
    DocumentUploadRecords:
      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/DocumentUploadRecord'
      required:
      - results
    ErrorMessages:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: The list of error messages
    DocumentFileData:
      type: object
      properties:
        doc_file:
          type: string
          description: A base64 file to upload
        doc_name:
          type: string
          description: The file name
        doc_format:
          type:
          - string
          - 'null'
          description: The file format
        doc_type:
          type:
          - string
          - 'null'
          default: other
          description: "\n        Shipment document type\n\n        values: <br/>\n        `certificate_of_origin` `commercial_invoice` `pro_forma_invoice` `packing_list` `other`\n\n        For carrier specific packaging types, please consult the reference.\n        "
          maxLength: 50
      required:
      - doc_file
      - doc_name
    PatchedDocumentTemplateData:
      type: object
      properties:
        name:
          type: string
          description: The template name
          maxLength: 255
        slug:
          type: string
          description: The template slug
          maxLength: 255
        template:
          type: string
          description: The template content
        active:
          type: boolean
          default: true
          description: disable template flag.
        description:
          type: string
          description: The template description
          maxLength: 255
        metadata:
          type: object
          additionalProperties: {}
          description: The template metadata
        options:
          type: object
          additionalProperties: {}
          description: The template rendering options
        related_object:
          enum:
          - shipment
          - order
          - other
          type: string
          x-spec-enum-id: b3691dad14d14121
          default: other
          description: The template related object
    DocumentUploadRecord:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier
        carrier_name:
          type:
          - string
          - 'null'
          description: The shipment carrier
        carrier_id:
          type:
          - string
          - 'null'
          description: The shipment carrier configured identifier
        documents:
          type: array
          items:
            $ref: '#/components/schemas/DocumentDetails'
          default: []
          description: the carrier shipping document ids
        meta:
          type:
          - object
          - 'null'
          additionalProperties: {}
          description: provider specific metadata
        reference:
          type:
          - string
          - 'null'
          description: Shipping document file reference
          maxLength: 50
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          default: []
          description: The list of note or warning messages
    DocumentUploadData:
      type: object
      properties:
        shipment_id:
          type: string
          description: The documents related shipment.
        document_files:
          type: array
          items:
            $ref: '#/components/schemas/DocumentFileData'
          description: Shipping document files
        reference:
          type:
          - string
          - 'null'
          description: Shipping document file reference
          maxLength: 50
      required:
      - document_files
      - shipment_id
  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:'