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

/carrier_accounts/:id

PATCH

/carrier_accounts/:id

DELETE

/carrier_accounts/:id

CarrierAccount object

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_a2cb50e6c5c3451586b3a507db5f163a",
  "object": "CarrierAccount",
  "type": "DhlEcsAccount",
  "clone": false,
  "created_at": "2025-05-09T20:39:13Z",
  "updated_at": "2025-05-09T20:39:13Z",
  "description": "CA Location DHL eCommerce Solutions Account",
  "reference": null,
  "billing_type": "carrier",
  "readable": "DHL eCommerce",
  "logo": null,
  "fields": {
    "credentials": {
      "client_id": {
        "visibility": "visible",
        "label": "DHL eCommerce client ID",
        "value": "123456"
      },
      "client_secret": {
        "visibility": "password",
        "label": "DHL eCommerce client secret",
        "value": "********"
      },
      "pickup_id": {
        "visibility": "visible",
        "label": "DHL eCommerce pickup ID",
        "value": "123456"
      },
      "distribution_center": {
        "visibility": "visible",
        "label": "DHL eCommerce distribution center",
        "value": "USLAX1"
      }
    },
    "test_credentials": {
      "client_id": {
        "visibility": "visible",
        "label": "Test DHL eCommerce client ID",
        "value": "123456"
      },
      "client_secret": {
        "visibility": "password",
        "label": "Test DHL eCommerce client secret",
        "value": "********"
      },
      "pickup_id": {
        "visibility": "visible",
        "label": "Test DHL eCommerce pickup ID",
        "value": "123456"
      },
      "distribution_center": {
        "visibility": "visible",
        "label": "Test DHL eCommerce 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 client ID",
      "value": "123456"
    },
    "client_secret": {
      "visibility": "password",
      "label": "DHL eCommerce client secret",
      "value": "********"
    },
    "pickup_id": {
      "visibility": "visible",
      "label": "DHL eCommerce pickup ID",
      "value": "123456"
    },
    "distribution_center": {
      "visibility": "visible",
      "label": "DHL eCommerce distribution center",
      "value": "USLAX1"
    }
  },
  "test_credentials": {
    "client_id": {
      "visibility": "visible",
      "label": "Test DHL eCommerce client ID",
      "value": "123456"
    },
    "client_secret": {
      "visibility": "password",
      "label": "Test DHL eCommerce client secret",
      "value": "********"
    },
    "pickup_id": {
      "visibility": "visible",
      "label": "Test DHL eCommerce pickup ID",
      "value": "123456"
    },
    "distribution_center": {
      "visibility": "visible",
      "label": "Test DHL eCommerce 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 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_a2cb50e6c5c3451586b3a507db5f163a",
3  "object": "CarrierAccount",
4  "type": "DhlEcsAccount",
5  "clone": false,
6  "created_at": "2025-05-09T20:39:13Z",
7  "updated_at": "2025-05-09T20:39:13Z",
8  "description": "CA Location DHL eCommerce Solutions Account",
9  "reference": null,
10  "billing_type": "carrier",
11  "readable": "DHL eCommerce",
12  "logo": null,
13  "fields": {
14    "credentials": {
15      "client_id": {
16        "visibility": "visible",
17        "label": "DHL eCommerce client ID",
18        "value": "123456"
19      },
20      "client_secret": {
21        "visibility": "password",
22        "label": "DHL eCommerce client secret",
23        "value": "********"
24      },
25      "pickup_id": {
26        "visibility": "visible",
27        "label": "DHL eCommerce pickup ID",
28        "value": "123456"
29      },
30      "distribution_center": {
31        "visibility": "visible",
32        "label": "DHL eCommerce distribution center",
33        "value": "USLAX1"
34      }
35    },
36    "test_credentials": {
37      "client_id": {
38        "visibility": "visible",
39        "label": "Test DHL eCommerce client ID",
40        "value": "123456"
41      },
42      "client_secret": {
43        "visibility": "password",
44        "label": "Test DHL eCommerce client secret",
45        "value": "********"
46      },
47      "pickup_id": {
48        "visibility": "visible",
49        "label": "Test DHL eCommerce pickup ID",
50        "value": "123456"
51      },
52      "distribution_center": {
53        "visibility": "visible",
54        "label": "Test DHL eCommerce 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_14a7abb395a54d98b2c92e0d36af54fa",
3  "object": "CarrierAccount",
4  "type": "DhlEcsAccount",
5  "clone": false,
6  "created_at": "2025-05-09T20:39:13Z",
7  "updated_at": "2025-05-09T20:39:13Z",
8  "description": "CA Location DHL eCommerce Solutions Account",
9  "reference": null,
10  "billing_type": "carrier",
11  "readable": "DHL eCommerce",
12  "logo": null,
13  "fields": {
14    "credentials": {
15      "client_id": {
16        "visibility": "visible",
17        "label": "DHL eCommerce client ID",
18        "value": "123456"
19      },
20      "client_secret": {
21        "visibility": "password",
22        "label": "DHL eCommerce client secret",
23        "value": "********"
24      },
25      "pickup_id": {
26        "visibility": "visible",
27        "label": "DHL eCommerce pickup ID",
28        "value": "123456"
29      },
30      "distribution_center": {
31        "visibility": "visible",
32        "label": "DHL eCommerce distribution center",
33        "value": "USLAX1"
34      }
35    },
36    "test_credentials": {
37      "client_id": {
38        "visibility": "visible",
39        "label": "Test DHL eCommerce client ID",
40        "value": "123456"
41      },
42      "client_secret": {
43        "visibility": "password",
44        "label": "Test DHL eCommerce client secret",
45        "value": "********"
46      },
47      "pickup_id": {
48        "visibility": "visible",
49        "label": "Test DHL eCommerce pickup ID",
50        "value": "123456"
51      },
52      "distribution_center": {
53        "visibility": "visible",
54        "label": "Test DHL eCommerce 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_07bc1b4652bd46bdabe27a04bf982716",
3  "object": "CarrierAccount",
4  "type": "DhlEcsAccount",
5  "clone": false,
6  "created_at": "2025-05-09T20:39:14Z",
7  "updated_at": "2025-05-09T20:39:14Z",
8  "description": "CA Location DHL eCommerce Solutions Account",
9  "reference": null,
10  "billing_type": "carrier",
11  "readable": "DHL eCommerce",
12  "logo": null,
13  "fields": {
14    "credentials": {
15      "client_id": {
16        "visibility": "visible",
17        "label": "DHL eCommerce client ID",
18        "value": "123456"
19      },
20      "client_secret": {
21        "visibility": "password",
22        "label": "DHL eCommerce client secret",
23        "value": "********"
24      },
25      "pickup_id": {
26        "visibility": "visible",
27        "label": "DHL eCommerce pickup ID",
28        "value": "123456"
29      },
30      "distribution_center": {
31        "visibility": "visible",
32        "label": "DHL eCommerce distribution center",
33        "value": "USLAX1"
34      }
35    },
36    "test_credentials": {
37      "client_id": {
38        "visibility": "visible",
39        "label": "Test DHL eCommerce client ID",
40        "value": "123456"
41      },
42      "client_secret": {
43        "visibility": "password",
44        "label": "Test DHL eCommerce client secret",
45        "value": "********"
46      },
47      "pickup_id": {
48        "visibility": "visible",
49        "label": "Test DHL eCommerce pickup ID",
50        "value": "123456"
51      },
52      "distribution_center": {
53        "visibility": "visible",
54        "label": "Test DHL eCommerce 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{}