Skip to content

Shippo external API. (2018-02-08)

Use this API to integrate with the Shippo service

Download OpenAPI description
carrier_acc.json
carrier_acc.yaml
Overview
URL
https://goshippo.com/contact/
Languages
Servers
https://api.goshippo.com

Carrier Accounts

Operations

List all carrier accounts

Request

Returns a list of all carrier accounts connected to your Shippo account. These carrier accounts include both Shippo carrier accounts and your own carrier accounts that you have connected to your Shippo account.

Additionally, you can get information about the service levels associated with each carrier account by passing in the ?service_levels=true query parameter.
Using it appends the property service_levels to each carrier account.
By default, if the query parameter is omitted, the service_levels property will not be included in the response.

Security
APIKeyHeader
Query
service_levelsboolean

Appends the property service_levels to each returned carrier account

carrierstring(CarriersEnum)

Filter the response by the specified carrier

Enum"airterra""apc_postal""apg""aramex""asendia_us""australia_post""axlehire""better_trucks""borderguru""boxberry"
account_idstring

Filter the response by the specified carrier account Id

pageinteger(int64)

The page number you want to select

Default 1
resultsinteger(int64)<= 100

The number of results to return per page (max 100, default 5)

Default 5
Headers
SHIPPO-API-VERSIONstring

String used to pick a non-default API version to use

Example: 2018-02-08
curl -i -X GET \
  'https://api.goshippo.com/carrier_accounts?service_levels=true&carrier=airterra&account_id=string&page=1&results=5' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'SHIPPO-API-VERSION: 2018-02-08'

Responses

Bodyapplication/json
nextstring
Example: "baseurl?page=3&results=10"
previousstring
Example: "baseurl?page=1&results=10"
resultsArray of objects(CarrierAccountWithExtraInfo)
Response
application/json
{
  "next": "baseurl?page=3&results=10",
  "previous": "baseurl?page=1&results=10",
  "results": [
    { … }
  ]
}

Create a new carrier account

Request

Creates a new carrier account or connects an existing carrier account to the Shippo account.

Security
APIKeyHeader
Headers
SHIPPO-API-VERSIONstring

String used to pick a non-default API version to use

Example: 2018-02-08
Bodyapplication/json

Examples.

account_idstringrequired
Example: "321123"
activeboolean
carrierstringrequired
Example: "fedex"
metadatastring
Example: "FEDEX Account"
parametersAccount parameters (any) or UPS account parameters (object) or FedEx account parameters (object)required
One of:

An array of additional parameters for the account, such as e.g. password or token. Please check our carrier accounts guide for the parameters per carrier. To protect account information, this field will be masked in any API response.

any(Account parameters)
testboolean
Example: false
curl -i -X POST \
  https://api.goshippo.com/carrier_accounts \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -H 'SHIPPO-API-VERSION: 2018-02-08' \
  -d '{
    "account_id": 293235673,
    "carrier": "fedex",
    "metadata": "FedEx Account",
    "parameters": {
      "use_multi_factor_registration": true,
      "first_name": "Tom",
      "last_name": "Monk",
      "phone_number": 1234567890,
      "from_address_st": "20 FED EX PKWY",
      "from_address_city": "Beverly Hills",
      "from_address_state": "CA",
      "from_address_zip": 90210,
      "from_address_country_iso2": "US",
      "verification_option": "SMS"
    },
    "test": false
  }'

Responses

Bodyapplication/json
account_idstringrequired

Unique identifier of the account. Please check the carrier accounts tutorial page for the account_id per carrier.
To protect account information, this field will be masked in any API response.

Example: "****"
activeboolean

Determines whether the account is active. When creating a shipment, if no carrier_accounts are explicitly passed Shippo will query all carrier accounts that have this field set. By default, this is set to True.

carrierstringrequired

Carrier token, see Carriers
Please check the carrier accounts tutorial page for all supported carriers.

Example: "usps"
parametersAccount parameters (any) or FedEx account parameters (object) or UPS account parameters (object)
One of:

An array of additional parameters for the account, such as e.g. password or token. Please check our carrier accounts guide for the parameters per carrier. To protect account information, this field will be masked in any API response.

any(Account parameters)
carrier_nameany

Carrier name, see Carriers

Example: "USPS"
is_shippo_accountboolean
Example: false
metadatastring
object_idstring

Unique identifier of the carrier account object.

Example: "6aa34d5f6865448fbb1ee93636e98999"
object_ownerstring

Username of the user who created the carrier account object.

Example: "bob+22@gmail.com"
service_levelsArray of objects(CarrierAccountServiceLevel)
testboolean

Indicates whether the object has been created in test mode.

Example: false
Response
application/json
{
  "account_id": "****",
  "active": true,
  "carrier": "usps",
  "parameters": {},
  "carrier_name": "USPS",
  "is_shippo_account": false,
  "metadata": "string",
  "object_id": "6aa34d5f6865448fbb1ee93636e98999",
  "object_owner": "bob+22@gmail.com",
  "service_levels": [
    { … }
  ],
  "test": false
}

Retrieve a carrier account

Request

Returns an existing carrier account using an object ID.

Security
APIKeyHeader
Path
CarrierAccountIdstringrequired

Object ID of the carrier account

Headers
SHIPPO-API-VERSIONstring

String used to pick a non-default API version to use

Example: 2018-02-08
curl -i -X GET \
  'https://api.goshippo.com/carrier_accounts/{CarrierAccountId}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'SHIPPO-API-VERSION: 2018-02-08'

Responses

Bodyapplication/json
account_idstringrequired

Unique identifier of the account. Please check the carrier accounts tutorial page for the account_id per carrier.
To protect account information, this field will be masked in any API response.

Example: "****"
activeboolean

Determines whether the account is active. When creating a shipment, if no carrier_accounts are explicitly passed Shippo will query all carrier accounts that have this field set. By default, this is set to True.

carrierstringrequired

Carrier token, see Carriers
Please check the carrier accounts tutorial page for all supported carriers.

Example: "usps"
parametersAccount parameters (any) or FedEx account parameters (object) or UPS account parameters (object)
One of:

An array of additional parameters for the account, such as e.g. password or token. Please check our carrier accounts guide for the parameters per carrier. To protect account information, this field will be masked in any API response.

any(Account parameters)
carrier_nameany

Carrier name, see Carriers

Example: "USPS"
is_shippo_accountboolean
Example: false
metadatastring
object_idstring

Unique identifier of the carrier account object.

Example: "6aa34d5f6865448fbb1ee93636e98999"
object_ownerstring

Username of the user who created the carrier account object.

Example: "bob+22@gmail.com"
service_levelsArray of objects(CarrierAccountServiceLevel)
testboolean

Indicates whether the object has been created in test mode.

Example: false
Response
application/json
{
  "account_id": "****",
  "active": true,
  "carrier": "usps",
  "parameters": {},
  "carrier_name": "USPS",
  "is_shippo_account": false,
  "metadata": "string",
  "object_id": "6aa34d5f6865448fbb1ee93636e98999",
  "object_owner": "bob+22@gmail.com",
  "service_levels": [
    { … }
  ],
  "test": false
}

Update a carrier account

Request

Updates an existing carrier account object. The account_id and carrier can't be updated. This is because they form the unique identifier together.

Security
APIKeyHeader
Path
CarrierAccountIdstringrequired

Object ID of the carrier account

Headers
SHIPPO-API-VERSIONstring

String used to pick a non-default API version to use

Example: 2018-02-08
Bodyapplication/json

Examples.

account_idstringrequired

Unique identifier of the account. Please check the carrier accounts tutorial page for the account_id per carrier.
To protect account information, this field will be masked in any API response.

Example: "****"
activeboolean

Determines whether the account is active. When creating a shipment, if no carrier_accounts are explicitly passed Shippo will query all carrier accounts that have this field set. By default, this is set to True.

carrierstringrequired

Carrier token, see Carriers
Please check the carrier accounts tutorial page for all supported carriers.

Example: "usps"
parametersAccount parameters (any) or FedEx account parameters (object) or UPS account parameters (object)
One of:

An array of additional parameters for the account, such as e.g. password or token. Please check our carrier accounts guide for the parameters per carrier. To protect account information, this field will be masked in any API response.

any(Account parameters)
curl -i -X PUT \
  'https://api.goshippo.com/carrier_accounts/{CarrierAccountId}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -H 'SHIPPO-API-VERSION: 2018-02-08' \
  -d '{
    "account_id": 123356,
    "active": true,
    "carrier": "ups",
    "parameters": {}
  }'

Responses

Bodyapplication/json
account_idstringrequired

Unique identifier of the account. Please check the carrier accounts tutorial page for the account_id per carrier.
To protect account information, this field will be masked in any API response.

Example: "****"
activeboolean

Determines whether the account is active. When creating a shipment, if no carrier_accounts are explicitly passed Shippo will query all carrier accounts that have this field set. By default, this is set to True.

carrierstringrequired

Carrier token, see Carriers
Please check the carrier accounts tutorial page for all supported carriers.

Example: "usps"
parametersAccount parameters (any) or FedEx account parameters (object) or UPS account parameters (object)
One of:

An array of additional parameters for the account, such as e.g. password or token. Please check our carrier accounts guide for the parameters per carrier. To protect account information, this field will be masked in any API response.

any(Account parameters)
carrier_nameany

Carrier name, see Carriers

Example: "USPS"
is_shippo_accountboolean
Example: false
metadatastring
object_idstring

Unique identifier of the carrier account object.

Example: "6aa34d5f6865448fbb1ee93636e98999"
object_ownerstring

Username of the user who created the carrier account object.

Example: "bob+22@gmail.com"
service_levelsArray of objects(CarrierAccountServiceLevel)
testboolean

Indicates whether the object has been created in test mode.

Example: false
Response
application/json
{
  "account_id": "****",
  "active": true,
  "carrier": "usps",
  "parameters": {},
  "carrier_name": "USPS",
  "is_shippo_account": false,
  "metadata": "string",
  "object_id": "6aa34d5f6865448fbb1ee93636e98999",
  "object_owner": "bob+22@gmail.com",
  "service_levels": [
    { … }
  ],
  "test": false
}

Connect an existing carrier account using OAuth 2.0

Request

Used by client applications to setup or reconnect an existing carrier account with carriers that support OAuth 2.0

Security
APIKeyHeader
Path
CarrierAccountObjectIdstringrequired

The carrier account ID (UUID) to start a signin process.

Query
redirect_uristring(uri)required

Callback URL. The URL that tells the authorization server where to send the user back to after they approve the request.

statestring

A random string generated by the consuming application and included in the request to prevent CSRF attacks. The consuming application checks that the same value is returned after the user authorizes Shippo.

Headers
SHIPPO-API-VERSIONstring

String used to pick a non-default API version to use

Example: 2018-02-08
curl "https://api.goshippo.com/carrier_accounts/2ccf5af209bb484cb20190d9cadbb61c/signin/initiate?redirect_uri=https://client.example.com/cb&state=SplxlOBeZQQYbYS6WxSbIA" \
-H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"

Responses

Redirects the browser to the carrier login page, with the needed parameters

Headers
Locationstring(uri)

Carrier login page URI, with the needed parameters set as query string

Example: "https://www.ups.com/lasso/signin?client_id=testClientID&redirect_uri=https://client.example.com/cb&response_type=code&scope=read&type=ups_com_api"
Response
No content

Add a Shippo carrier account

Request

Adds a Shippo carrier account

Security
APIKeyHeader
Headers
SHIPPO-API-VERSIONstring

String used to pick a non-default API version to use

Example: 2018-02-08
Bodyapplication/json

Examples.

One of:
carrierstringrequired
Example: "canada_post"
parametersobject(CarrierAccountCanadaPostCreateParameters)required
curl --location --request POST '/carrier_accounts/register/new' \
--header 'Authorization: ShippoToken {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "carrier": "canada_post",
    "parameters": {
        "company": "Shippo",
        "full_name": "Shippo Meister",
        "email": "hippo@shippo.com",
        "phone": "1112221122",
        "canada_post_terms": true
    }
}'

Responses

Bodyapplication/json
account_idstringrequired

Unique identifier of the account. Please check the carrier accounts tutorial page for the account_id per carrier.
To protect account information, this field will be masked in any API response.

Example: "****"
activeboolean

Determines whether the account is active. When creating a shipment, if no carrier_accounts are explicitly passed Shippo will query all carrier accounts that have this field set. By default, this is set to True.

carrierstringrequired

Carrier token, see Carriers
Please check the carrier accounts tutorial page for all supported carriers.

Example: "usps"
parametersAccount parameters (any) or FedEx account parameters (object) or UPS account parameters (object)
One of:

An array of additional parameters for the account, such as e.g. password or token. Please check our carrier accounts guide for the parameters per carrier. To protect account information, this field will be masked in any API response.

any(Account parameters)
carrier_nameany

Carrier name, see Carriers

Example: "USPS"
is_shippo_accountboolean
Example: false
metadatastring
object_idstring

Unique identifier of the carrier account object.

Example: "6aa34d5f6865448fbb1ee93636e98999"
object_ownerstring

Username of the user who created the carrier account object.

Example: "bob+22@gmail.com"
service_levelsArray of objects(CarrierAccountServiceLevel)
testboolean

Indicates whether the object has been created in test mode.

Example: false
Response
application/json
{
  "account_id": "****",
  "active": true,
  "carrier": "usps",
  "parameters": {},
  "carrier_name": "USPS",
  "is_shippo_account": false,
  "metadata": "string",
  "object_id": "6aa34d5f6865448fbb1ee93636e98999",
  "object_owner": "bob+22@gmail.com",
  "service_levels": [
    { … }
  ],
  "test": false
}

Get Carrier Registration status

Request

Returns the registration status for the given account for the given carrier

Security
APIKeyHeader
Query
carrierstringrequired

filter by specific carrier

Enum"ups""usps""canada_post"
Headers
SHIPPO-API-VERSIONstring

String used to pick a non-default API version to use

Example: 2018-02-08
curl -i -X GET \
  'https://api.goshippo.com/carrier_accounts/reg-status?carrier=ups' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'SHIPPO-API-VERSION: 2018-02-08'

Responses

Bodyapplication/json
carrier_accountstring
Example: "99dc410d295b4a168993cc38809cb123"
object_createdstring(date-time)
object_ownerstring
Example: "tom@gmail.com"
object_updatedstring(date-time)
statusstring
Example: "PENDING_TERMS"
Response
application/json
{
  "carrier_account": "99dc410d295b4a168993cc38809cb123",
  "object_created": "2019-08-24T14:15:22Z",
  "object_owner": "tom@gmail.com",
  "object_updated": "2019-08-24T14:15:22Z",
  "status": "PENDING_TERMS"
}

Upload letterhead and signature documents

Request

Uploads a letterhead or signature image file that can be added to commercial invoices by supporting carriers.

Security
APIKeyHeader
Path
object_idstring(uuid)required

The object id of the account

Bodymultipart/form-datarequired

Document data required to upload a letterhead or signature document for a FedEx account.

document_typestringrequired

Type of document to upload.

Enum"LETTERHEAD""SIGNATURE"
filestring(binary)required

The document to upload. Only GIF and PNG image formats are supported.
LETTERHEAD files must be no larger than 700 pixels wide by 50 pixels high.
SIGNATURE files must be no larger than 240 pixels wide by 25 pixels high.

curl -i -X POST \
  'https://api.goshippo.com/carrier_accounts/{object_id}/documents' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: multipart/form-data' \
  -F document_type=LETTERHEAD \
  -F file=string

Responses

Document uploaded successfully

Response
No content