Add a Carrier Account¶

HTTP Request¶

POST /v1/developers/{developerId}/merchants/{postalReportingNumber}/carrier-accounts/register?carrier={carrier}

Summary¶

This operation adds a commercial carrier account for use with the APIs. Merchants can alternatively add carrier accounts through the Merchant Portal.

When you issue this API, Pitney Bowes verifies the merchant’s carrier account and receives a unique set of credentials for access to the account. Pitney Bowes then creates a unique shipper-carrier account ID (shipperCarrierAccountId) to identify the carrier account and returns the ID in the response. The ID identifies the carrier account when the merchant performs an operation that uses the account.

The API supports integration with FedEx^® and UPS^®.

Tutorial¶

For steps to implement the API, see Add a Carrier through the Merchant Account APIs.

Considerations¶

The merchant must have an existing account with the carrier.
During this API call, the merchant must provide:
- The account number for the carrier account.
- The Ship From address as it appears on the carrier account.
- The address for the primary contact on the carrier account.
- Additional account information, dependent on the carrier. See Carrier Account Input Parameters.
If for some reason you must later remove the carrier account, contact Client Support at ClientSupportTechServices@pb.com.

Request URLs¶

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/developers/{developerId}/merchants/{postalReportingNumber}/carrier-accounts/register?carrier={carrier}
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/developers/{developerId}/merchants/{postalReportingNumber}/carrier-accounts/register?carrier={carrier}

Path Parameters¶

Name

Description

developerId

Required. Your Pitney Bowes developer ID. To retrieve your developer ID, log into Developer Hub.

postalReportingNumber

Required. The unique ID used to identify the merchant. To retrieve the merchant’s postalReportingNumber, issue the Get Merchant Accounts API call.

Query Parameter¶

Name

Description

carrier

Required. The carrier with which the merchant has an existing account.

Valid values:

FEDEX
UPS

Request Headers¶

Name

Description

Authorization

Required. OAuth token generated using the Generate an OAuth Token API.

Content-Type

Required. The media type of the request entity. Set this to application/json.

X-PB-TransactionId

Required. A unique identifier, up to 25 characters. The following characters are allowed: letters, numbers, hyphens (-), and underscores (_).

Request / Response Elements¶

Name	Data Type	Description
accountNumber	String	Required. The merchant’s account number with the carrier.
accountAddress	Address Object	Required. The merchant’s Ship From address as it appears on the carrier account. For UPS, this address must exactly match the Ship From address on the merchant’s UPS invoice.
contactAddress	Address Object	Required. The contact address that the merchant provided to the carrier.
inputParameters	Array[Object]	UPS Only. Required. Information about the merchant’s existing carrier account. Each object in the array defines a parameter and value. For the parameters, see Carrier Account Input Parameters.
carrierAccount	Array[Object]	RESPONSE ONLY. Attributes that correspond to settings in the merchant’s carrier account. Each object in the array defines an attribute and its value. The attributes include the unique credentials assigned to Pitney Bowes for use when the merchant accesses the carrier through the Global Ecommerce Shipping APIs. Do not use these to issue API operations. Instead, use the `shipperCarrierAccountId`, below.
carrierAccount.name	String	The carrier account attribute.
carrierAccount.value	String	The value of the carrier account attribute.
shipperCarrierAccountId	String	RESPONSE ONLY. A unique identifier for the carrier account. If the merchant has added multiple accounts with this carrier, you must pass this identifier in the `X-PB-Shipper-Carrier-AccountId` header when the merchant performs an operation with the carrier.

Address Object for Carrier Accounts¶

The accountAddress and contactAddress fields take the address object described here:

Name	Data Type	Description
company	String	Company name.
addressLines	Array[String]	Street address or P.O. Box. For a street address, include the apartment number if applicable.
name	String	The merchant’s first and last name.
phone	String	Phone number.
email	String	Email address.
residential	Boolean	Set this to `true` if this a residential address; `false` if it is not a residential address.
cityTown	String	The city or town.
stateProvince	String	The state or province. For US addresses, use the 2-letter state code.
postalCode	String	Postal/ZIP code. For US addresses, use either the 5-digit or 9-digit ZIP code.
countryCode	String	Two-character country code from the ISO country list.

Carrier Account Attributes¶

The following attributes and their values are returned in the carrierAccount array.

Attribute Name	Description
ACCOUNT_NUMBER	The merchant’s account number with the carrier. Note that this value also appears in the `accountNumber` field.
KEY	UPS Only. The API access key for the UPS account.
METER_NUMBER	FedEx Only. The identifier FedEx has assigned for this instance of the account’s registration.
PASSWORD	The password Pitney Bowes uses to access to the carrier account on behalf of the merchant. Do not use this password. Instead, use the value returned in the `shipperCarrierAccountId` field.
USER_ID	The username Pitney Bowes uses to access the carrier account on behalf of the merchant. Do not use this username. Instead, use the value returned in the `shipperCarrierAccountId` field.

Sample Requests¶

See the following examples:

Add a FedEx Account Sample Request
Add a UPS Account Sample Request

Add a FedEx Account Sample Request¶

Register FedEx Sample Request¶

curl -X POST ".../v1/developers/<developerId>/merchants/<postalReportingNumber>/carrier-accounts/register?carrier=FEDEX" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: regabc123" \
-d '
{
    "accountAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "303-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [ "4750 Walnut Street" ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "contactAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "303-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [ "4750 Walnut Street" ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "accountNumber": "<account-number>"
}'

Register FedEx Sample Response¶

{
    "accountAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "303-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [
            "4750 Walnut Street"
        ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "contactAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "303-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [
            "4750 Walnut Street"
        ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "accountNumber": "<account-number>",
    "carrierAccount": [
      {
        "name": "ACCOUNT_NUMBER",
        "value": "<account-number>"
      },
      {
        "name": "USER_ID",
        "value": "ABCdefABCdefABCD"
      },
      {
        "name": "PASSWORD",
        "value": "Password"
      },
      {
        "name": "METER_NUMBER",
        "value": "123456789"
      }
    ],
    "shipperCarrierAccountId": "12345678-abcd-1234-abcd-1234abcd1234"
}

Add a UPS Account Sample Request¶

Register UPS Sample Request¶

curl -X POST ".../v1/developers/<developerId>/merchants/<postalReportingNumber>/carrier-accounts/register?carrier=UPS" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: reg453abc" \
-d '
{
    "accountAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "303-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [ "4750 Walnut Street" ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "contactAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "303-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [ "4750 Walnut Street" ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "accountNumber": "<account-number>",
    "inputParameters": [
      {
        "name": "ACCOUNT_POSTAL_CODE",
        "value": "80301"
      },
      {
        "name": "ACCOUNT_COUNTRY_CODE",
        "value": "US"
      },
      {
        "name": "CONTACT_TITLE",
        "value": "Manager"
      },
      {
        "name": "END_USER_IP",
        "value": "192.0.2.0"
      },
      {
        "name": "DEVICE_IDENTITY",
        "value": "12345678abcde"
      },
      {
        "name": "LICENSE_TEXT",
        "value": "<license text>"
    } ]
}'

Register UPS Sample Response¶

{
    "accountAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "303-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [
            "4750 Walnut Street"
        ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "contactAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "303-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [
            "4750 Walnut Street"
        ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "accountNumber": "<account-number>",
    "carrierAccount": [
      {
        "name": "ACCOUNT_NUMBER",
        "value": "<account-number>"
      },
      {
        "name": "KEY",
        "value": "ABCD123456789DEF"
      },
      {
        "name": "USER_ID",
        "value": "ab12345678abcd"
      },
      {
        "name": "PASSWORD",
        "value": "Password"
      }
    ],
    "inputParameters": [
      {
        "name": "ACCOUNT_POSTAL_CODE",
        "value": "80301"
      },
      {
        "name": "ACCOUNT_COUNTRY_CODE",
        "value": "US"
      },
      {
        "name": "CONTACT_TITLE",
        "value": "Manager"
      },
      {
        "name": "END_USER_IP",
        "value": "192.0.2.0"
      },
      {
        "name": "DEVICE_IDENTITY",
        "value": "12345678abcde"
      }
    ],
    "shipperCarrierAccountId": "12345678-1234-abcd-1234-1234abcd1234"
}

Error Codes¶

The following code is specific to this operation:

Error Code

Error Description

Solution

1000500

System error from ups

Contact UPS using the information provided.

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.

Input Parameters