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 Addresses API
version: 2026.1.32
tags:
- name: Addresses
description: "This is an object representing your Karrio shipping address.\n You can retrieve all addresses related to your Karrio account.\n Address objects are linked to your shipment history, and can be used for recurring shipping\n to / from the same locations.\n "
paths:
/v1/addresses:
get:
operationId: $list
description: "\n Retrieve all addresses.\n\n Query Parameters:\n - label: Filter by meta.label (case-insensitive contains)\n - keyword: Search across label, address fields, contact info\n - usage: Filter by meta.usage (exact match in array)\n "
summary: List all addresses
tags:
- Addresses
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AddressList'
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: listAddresses
post:
operationId: $create
description: Create a new address.
summary: Create an address
tags:
- Addresses
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddressData'
required: true
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Address'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: createAddress
/v1/addresses/{id}:
get:
operationId: $retrieve
description: Retrieve an address.
summary: Retrieve an address
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Addresses
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Address'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: ''
x-operationId: retrieveAddress
patch:
operationId: $update
description: update an address.
summary: Update an address
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Addresses
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedAddressData'
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Address'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
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: updateAddress
delete:
operationId: $discard
description: Discard an address.
summary: Discard an address
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Addresses
security:
- TokenBasic: []
- Token: []
- OAuth2: []
- JWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Address'
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: discardAddress
components:
schemas:
AddressList:
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/Address'
required:
- results
AddressValidation:
type: object
properties:
success:
type: boolean
description: True if the address is valid
meta:
type:
- object
- 'null'
additionalProperties: {}
description: validation service details
required:
- success
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
\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
PatchedAddressData:
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
\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 "
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
Address:
type: object
properties:
id:
type: string
description: A unique identifier
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
\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 "
object_type:
type: string
default: address
description: Specifies the object type
validation:
allOf:
- $ref: '#/components/schemas/AddressValidation'
description: Specify address validation result
required:
- country_code
ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/APIError'
description: The list of API errors
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:'