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:
\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:'