Shipping Carriers API Overview

You can manage carriers and carrier credentials via the Shipping Admin APIs. The Shipping Admin APIs have replaced the former Carrier Service API (also known as CARS), so all management of credentials via API should be done through the endpoints detailed below.

For information about configuring carriers in the Admin UI instead of via API, see the Shipping Carriers user guide. Additionally, see the Location Group documentation for details on how to enable carriers for locations.

Carrier Configuration API

The Carrier Configuration API can initialize and update a basic carrier configuration. This must exist first before setting any credentials on the carrier account. If a carrier configuration does not already exist for the carrier, you will have to create one (as well as a carrier credential set). But in most cases, these will automatically be created for you and you can skip ahead to the Carrier Credentials API.

POST .../api/commerce/shipping/admin/carriers/{carrierID}

The request body should follow the below template as defined in the API schema. Note that the settings array was used with previous carrier implementations and is no longer necessary as of August 2024 (as the same data is now provided via credential sets), so it can be left null.

{
    "id": "carrierId",
    "enabled": true,
    "enabledForReturns": false,
    "settings": [],
    "customTableRates": [],
    "areCredentialsSet": false
}

Carrier Credential Set API

A credential set is used to store a list of key-value pairs for a carrier, such as an account ID and password. A single credential set can be assigned to multiple sites, location groups, or locations. Call Create Carrier Credential Set to create the initial credential set.

POST .../api/commerce/shipping/admin/carriers/credential-sets/{carrierID}

The request body should follow the below template. 

{
    "carrierId": "string",
    "code": "string",
    "name": "string",
    "values": [
        {
            "key": "string",
            "value": "string"
        }

    ]
}

Credential Values

The required keys vary depending on the carrier, but all accept string values that should correspond to valid information about your account.

• USPS: easypostapikey
• UPS: accountnumber
• UPS SurePost: accountnumber
• Canada Post: accountnumber, canadapostapikey, contractid, payeenumber
• Purolator: accountnumber, apikeypassword, purolatorapikey
• FedEx: accountnumber, corporatefirstname, corporatelastname, corporatejobtitle, corporatecompanyname, corporatephonenumber, corporateemailaddress, corporateaddressstreet, corporateaddresscity, corporateaddressstate, corporateaddresspostalcode, corporateaddresscountrycode, shippingaddressstreet, shippingaddresscity, shippingaddressstate, shippingaddresspostalcode, shippingaddresscountycode
• FedEx SmartPost: Same as FedEx with the addition of hubid
• FedEx Cross Border: apiclientid, apiclientsecret, login, partnerkey, password

For example, the credential set for USPS may look like:

{
    "carrierId": "UPS",
    "code": "upscredentials1",
    "name": "UPS Account",
    "values": [
        {
            "key": "accountnumber",
            "value": "123456"
        }

    ]
}

Carrier Credentials API

Finally, you can add carrier credentials with the Create Carrier Credentials call.

POST .../api/commerce/shipping/admin/carriers/credentials/{carrierId}

The request body should follow the below template. The locationCode and locationGroupCode are optional— by default, credentials are created at the site level. If location or location group credentials are not configured for a particular fulfillment location, then it will fall back to using those site-level credentials. Providing a location or location group will set these credentials as an override at that lower level.

{
   "carrierId": "string",
   "siteId": "string",
   "locationCode": "string", 
   "locationGroupCode": "string", 
   "credentialSet": {
      "carrierId": "string",
      "code": "string"
   }
}