Looking for the old docs? View our old docs site.
API Docs

CarrierAccount

A CarrierAccount encapsulates your credentials with the carrier. The CarrierAccount object provides CRUD operations for all CarrierAccounts.

Each EasyPost account is automatically provided a USPS account managed by EasyPost.

Other operations, such as Shipment creation, can reference CarrierAccounts to reduce the scope of data returned. For instance, you may have multiple warehouses that need to use distinct FedEx SmartPost credentials to request the correct rates.

Rate objects will include a carrier_account_id field which can be used to determine the account used for rating.

Endpoints
POST
/carrier_accounts
GET
/carrier_accounts
GET
/carrier_accounts/:id
PATCH
/carrier_accounts/:id
DELETE
/carrier_accounts/:id

CarrierAccount object

id
string
Unique, begins with "ca_"
object
string
"CarrierAccount"
type
string
The name of the CarrierType
fields
Fields object
Contains credentials and/or test_credentials, or may be empty
clone
boolean
If true, only the reference and description are possible to update
description
string
An optional, user-readable field to help distinguish accounts
reference
string
An optional field that may be used in place of carrier_account_id in other API endpoints
readable
string
The name used when displaying a readable value for the type of the account
credentials
object
Unlike the credentials object contained in fields, this nullable object contains just raw credential pairs for client library consumption.
test_credentials
object
Unlike the test_credentials object contained in fields, this nullable object contains just raw test_credential pairs for client library consumption.
billing_type
string
Billing type of the carrier account
created_at
datetime
When the CarrierAccount was created
updated_at
datetime
When the CarrierAccount was last updated
CarrierAccount Object
{
  "id": "ca_f64a75cee8ed4c83a7625c1d00cf8f0b",
  "object": "CarrierAccount",
  "type": "DhlEcsAccount",
  "clone": false,
  "created_at": "2024-01-24T00:05:37Z",
  "updated_at": "2024-01-24T00:05:37Z",
  "description": "CA Location DHL eCommerce Solutions Account",
  "reference": null,
  "billing_type": "carrier",
  "readable": "DHL eCommerce Solutions",
  "logo": null,
  "fields": {
    "credentials": {
      "client_id": {
        "visibility": "visible",
        "label": "DHL eCommerce Solutions client ID",
        "value": "123456"
      },
      "client_secret": {
        "visibility": "password",
        "label": "DHL eCommerce Solutions client secret",
        "value": "********"
      },
      "pickup_id": {
        "visibility": "visible",
        "label": "DHL eCommerce Solutions pickup ID",
        "value": "123456"
      },
      "distribution_center": {
        "visibility": "visible",
        "label": "DHL eCommerce Solutions distribution center",
        "value": "USLAX1"
      }
    },
    "test_credentials": {
      "client_id": {
        "visibility": "visible",
        "label": "Test DHL eCommerce Solutions client ID",
        "value": "123456"
      },
      "client_secret": {
        "visibility": "password",
        "label": "Test DHL eCommerce Solutions client secret",
        "value": "********"
      },
      "pickup_id": {
        "visibility": "visible",
        "label": "Test DHL eCommerce Solutions pickup ID",
        "value": "123456"
      },
      "distribution_center": {
        "visibility": "visible",
        "label": "Test DHL eCommerce Solutions distribution center",
        "value": "USLAX1"
      }
    }
  },
  "credentials": {
    "client_id": "123456",
    "client_secret": "********",
    "pickup_id": "123456",
    "distribution_center": "USLAX1"
  },
  "test_credentials": {
    "client_id": "123456",
    "client_secret": "********",
    "pickup_id": "123456",
    "distribution_center": "USLAX1"
  }
}

Fields object

credentials
dictionary of string-Field pairs
Credentials used in the production environment. Each key represents a carrier-specific credentials field name.
test_credentials
dictionary of string-Field pairs
Credentials used in the test environment. Each key represents a carrier-specific credentials field name.
auto_link
boolean
For USPS, this designates that no credentials are required.
custom_workflow
boolean
When present, a separate authentication process will be required through the UI to link this account type.
Fields Object
{
  "credentials": {
    "client_id": {
      "visibility": "visible",
      "label": "DHL eCommerce Solutions client ID",
      "value": "123456"
    },
    "client_secret": {
      "visibility": "password",
      "label": "DHL eCommerce Solutions client secret",
      "value": "********"
    },
    "pickup_id": {
      "visibility": "visible",
      "label": "DHL eCommerce Solutions pickup ID",
      "value": "123456"
    },
    "distribution_center": {
      "visibility": "visible",
      "label": "DHL eCommerce Solutions distribution center",
      "value": "USLAX1"
    }
  },
  "test_credentials": {
    "client_id": {
      "visibility": "visible",
      "label": "Test DHL eCommerce Solutions client ID",
      "value": "123456"
    },
    "client_secret": {
      "visibility": "password",
      "label": "Test DHL eCommerce Solutions client secret",
      "value": "********"
    },
    "pickup_id": {
      "visibility": "visible",
      "label": "Test DHL eCommerce Solutions pickup ID",
      "value": "123456"
    },
    "distribution_center": {
      "visibility": "visible",
      "label": "Test DHL eCommerce Solutions distribution center",
      "value": "USLAX1"
    }
  }
}

Field object

visibility
string
The visibility value is used to control form field types. Discussed in the CarrierType section
label
string
The label value is used in form rendering to display a more precise field name
value
string
Checkbox fields use "0" and "1" as false and true, respectively. All other field types present plaintext, partly-masked, or masked credential data for reference.
Field Object
{
  "visibility": "visible",
  "label": "DHL eCommerce Solutions client ID",
  "value": "123456"
}
Production OnlyThis call will only work with your Production API Key.

Create a CarrierAccount

CarrierAccount objects may be managed through the EasyPost API using the Production API Key only. Multiple accounts can be added for a single carrier.

The CarrierType of the preferred CarrierAccount should be consulted before attempting to create a new CarrierAccount, as it will inform you of the field names expected by a certain carrier. Some carriers may have a custom_workflow field set to true. These carriers cannot be created with the traditional flow listed below and instead have a special steps that must be followed. Please see Adding Carriers With Custom Workflows for more details on these carriers.

POST /carrier_accounts
1curl -X POST https://api.easypost.com/v2/carrier_accounts \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "carrier_account": {
6      "type": "DhlEcsAccount",
7      "description": "CA Location DHL eCommerce Solutions Account",
8      "reference": "my-reference",
9      "credentials": {
10        "client_id": "123456",
11        "client_secret": "123abc",
12        "distribution_center": "USLAX1",
13        "pickup_id": "123456"
14      },
15      "test_credentials": {
16        "client_id": "123456",
17        "client_secret": "123abc",
18        "distribution_center": "USLAX1",
19        "pickup_id": "123456"
20      }
21    }
22  }'
Response
1{
2  "id": "ca_f64a75cee8ed4c83a7625c1d00cf8f0b",
3  "object": "CarrierAccount",
4  "type": "DhlEcsAccount",
5  "clone": false,
6  "created_at": "2024-01-24T00:05:37Z",
7  "updated_at": "2024-01-24T00:05:37Z",
8  "description": "CA Location DHL eCommerce Solutions Account",
9  "reference": null,
10  "billing_type": "carrier",
11  "readable": "DHL eCommerce Solutions",
12  "logo": null,
13  "fields": {
14    "credentials": {
15      "client_id": {
16        "visibility": "visible",
17        "label": "DHL eCommerce Solutions client ID",
18        "value": "123456"
19      },
20      "client_secret": {
21        "visibility": "password",
22        "label": "DHL eCommerce Solutions client secret",
23        "value": "********"
24      },
25      "pickup_id": {
26        "visibility": "visible",
27        "label": "DHL eCommerce Solutions pickup ID",
28        "value": "123456"
29      },
30      "distribution_center": {
31        "visibility": "visible",
32        "label": "DHL eCommerce Solutions distribution center",
33        "value": "USLAX1"
34      }
35    },
36    "test_credentials": {
37      "client_id": {
38        "visibility": "visible",
39        "label": "Test DHL eCommerce Solutions client ID",
40        "value": "123456"
41      },
42      "client_secret": {
43        "visibility": "password",
44        "label": "Test DHL eCommerce Solutions client secret",
45        "value": "********"
46      },
47      "pickup_id": {
48        "visibility": "visible",
49        "label": "Test DHL eCommerce Solutions pickup ID",
50        "value": "123456"
51      },
52      "distribution_center": {
53        "visibility": "visible",
54        "label": "Test DHL eCommerce Solutions distribution center",
55        "value": "USLAX1"
56      }
57    }
58  },
59  "credentials": {
60    "client_id": "123456",
61    "client_secret": "********",
62    "pickup_id": "123456",
63    "distribution_center": "USLAX1"
64  },
65  "test_credentials": {
66    "client_id": "123456",
67    "client_secret": "********",
68    "pickup_id": "123456",
69    "distribution_center": "USLAX1"
70  }
71}
Production OnlyThis call will only work with your Production API Key.

Retrieve all CarrierAccounts

Retrieve an unpaginated list of all CarrierAccounts available to the authenticated account. Only Production API Keysmay be used to retrieve this list.

GET /carrier_accounts
1curl -X GET https://api.easypost.com/v2/carrier_accounts \
2  -u "EASYPOST_API_KEY":
Response
1[
2  {
3    "id": "ca_9685a1198a75477885a3cdca37559bac",
4    "object": "CarrierAccount",
5    "type": "UspsAccount",
6    "clone": false,
7    "created_at": "2022-10-14T17:23:58Z",
8    "updated_at": "2022-10-14T17:34:05Z",
9    "description": "USPS Account",
10    "reference": null,
11    "billing_type": "easypost",
12    "readable": "USPS",
13    "logo": null,
14    "fields": {
15      "credentials": {
16        "company_name": {
17          "visibility": "visible",
18          "label": "Account Holder Name",
19          "value": ""
20        },
21        "address_street": {
22          "visibility": "visible",
23          "label": "Street Address",
24          "value": ""
25        },
26        "address_city": {
27          "visibility": "visible",
28          "label": "City",
29          "value": ""
30        },
31        "address_state": {
32          "visibility": "visible",
33          "label": "State",
34          "value": ""
35        },
36        "address_zip": {
37          "visibility": "visible",
38          "label": "ZIP Code",
39          "value": ""
40        },
41        "phone": {
42          "visibility": "visible",
43          "label": "Phone Number",
44          "value": ""
45        },
46        "email": {
47          "visibility": "visible",
48          "label": "Email Address",
49          "value": null
50        },
51        "shipper_id": {
52          "visibility": "visible",
53          "label": "Shipper Identifier (Optional)",
54          "value": ""
55        }
56      }
57    },
58    "credentials": {
59      "company_name": "",
60      "address_street": "",
61      "address_city": "",
62      "address_state": "",
63      "address_zip": "",
64      "phone": "",
65      "email": null,
66      "shipper_id": ""
67    },
68    "test_credentials": null
69  }
70]
Production OnlyThis call will only work with your Production API Key.

Retrieve a CarrierAccount

Retrieve a CarrierAccount by its id or reference. It is recommended to use EasyPost's provided identifiers because we do not enforce a unique reference.

GET /carrier_accounts/:id
1curl -X GET https://api.easypost.com/v2/carrier_accounts/ca_... \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "id": "ca_13e1617aec534a8bb7b5daee3d0e471c",
3  "object": "CarrierAccount",
4  "type": "DhlEcsAccount",
5  "clone": false,
6  "created_at": "2024-01-24T00:05:38Z",
7  "updated_at": "2024-01-24T00:05:38Z",
8  "description": "CA Location DHL eCommerce Solutions Account",
9  "reference": null,
10  "billing_type": "carrier",
11  "readable": "DHL eCommerce Solutions",
12  "logo": null,
13  "fields": {
14    "credentials": {
15      "client_id": {
16        "visibility": "visible",
17        "label": "DHL eCommerce Solutions client ID",
18        "value": "123456"
19      },
20      "client_secret": {
21        "visibility": "password",
22        "label": "DHL eCommerce Solutions client secret",
23        "value": "********"
24      },
25      "pickup_id": {
26        "visibility": "visible",
27        "label": "DHL eCommerce Solutions pickup ID",
28        "value": "123456"
29      },
30      "distribution_center": {
31        "visibility": "visible",
32        "label": "DHL eCommerce Solutions distribution center",
33        "value": "USLAX1"
34      }
35    },
36    "test_credentials": {
37      "client_id": {
38        "visibility": "visible",
39        "label": "Test DHL eCommerce Solutions client ID",
40        "value": "123456"
41      },
42      "client_secret": {
43        "visibility": "password",
44        "label": "Test DHL eCommerce Solutions client secret",
45        "value": "********"
46      },
47      "pickup_id": {
48        "visibility": "visible",
49        "label": "Test DHL eCommerce Solutions pickup ID",
50        "value": "123456"
51      },
52      "distribution_center": {
53        "visibility": "visible",
54        "label": "Test DHL eCommerce Solutions distribution center",
55        "value": "USLAX1"
56      }
57    }
58  },
59  "credentials": {
60    "client_id": "123456",
61    "client_secret": "********",
62    "pickup_id": "123456",
63    "distribution_center": "USLAX1"
64  },
65  "test_credentials": {
66    "client_id": "123456",
67    "client_secret": "********",
68    "pickup_id": "123456",
69    "distribution_center": "USLAX1"
70  }
71}
Production OnlyThis call will only work with your Production API Key.

Update a CarrierAccount

Updates can be made to description, reference, and any fields in credentials or test_credentials.

The CarrierType of the CarrierAccount should be consulted before attempting to updating an existing CarrierAccount, as it will inform you of the field names expected by a certain carrier. An update request for a CarrierAccount is a partial update; only attributes specifically passed in will be altered.

PATCH /carrier_accounts/:id
1curl -X PATCH https://api.easypost.com/v2/carrier_accounts/ca_... \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "carrier_account": {
6      "description": "FL Location DHL eCommerce Solutions Account",
7      "credentials": {
8        "pickup_id": "abc123",
9      }
10    }
11  }'
Response
1{
2  "id": "ca_1f69b4afc44a480a8728e19381cb9b0f",
3  "object": "CarrierAccount",
4  "type": "DhlEcsAccount",
5  "clone": false,
6  "created_at": "2024-01-24T00:05:40Z",
7  "updated_at": "2024-01-24T00:05:40Z",
8  "description": "My custom description",
9  "reference": null,
10  "billing_type": "carrier",
11  "readable": "DHL eCommerce Solutions",
12  "logo": null,
13  "fields": {
14    "credentials": {
15      "client_id": {
16        "visibility": "visible",
17        "label": "DHL eCommerce Solutions client ID",
18        "value": "123456"
19      },
20      "client_secret": {
21        "visibility": "password",
22        "label": "DHL eCommerce Solutions client secret",
23        "value": "********"
24      },
25      "pickup_id": {
26        "visibility": "visible",
27        "label": "DHL eCommerce Solutions pickup ID",
28        "value": "123456"
29      },
30      "distribution_center": {
31        "visibility": "visible",
32        "label": "DHL eCommerce Solutions distribution center",
33        "value": "USLAX1"
34      }
35    },
36    "test_credentials": {
37      "client_id": {
38        "visibility": "visible",
39        "label": "Test DHL eCommerce Solutions client ID",
40        "value": "123456"
41      },
42      "client_secret": {
43        "visibility": "password",
44        "label": "Test DHL eCommerce Solutions client secret",
45        "value": "********"
46      },
47      "pickup_id": {
48        "visibility": "visible",
49        "label": "Test DHL eCommerce Solutions pickup ID",
50        "value": "123456"
51      },
52      "distribution_center": {
53        "visibility": "visible",
54        "label": "Test DHL eCommerce Solutions distribution center",
55        "value": "USLAX1"
56      }
57    }
58  },
59  "credentials": {
60    "client_id": "123456",
61    "client_secret": "********",
62    "pickup_id": "123456",
63    "distribution_center": "USLAX1"
64  },
65  "test_credentials": {
66    "client_id": "123456",
67    "client_secret": "********",
68    "pickup_id": "123456",
69    "distribution_center": "USLAX1"
70  }
71}
Production OnlyThis call will only work with your Production API Key.

Delete a CarrierAccount

CarrierAccount objects may be removed from your account when they become out of date or no longer useful.

DELETE /carrier_accounts/:id
1curl -X DELETE https://api.easypost.com/v2/carrier_accounts/ca_... \
2  -u "EASYPOST_API_KEY":
Response
1{}