Register an Existing Carrier Account

HTTP Request

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

Summary

This operation registers a merchant’s existing commercial carrier account for use with the PB Shipping APIs. Note that the merchant can alternatively register the carrier account through the Merchant Portal, as described on the Carrier Account Registration page.

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 Register through the Carrier Registration APIs.

Things to Consider

  1. The merchant must have an existing account with the carrier.
  2. 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.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/developers/{developerId}/merchants/{postalReportingNumber}/carrier-accounts/register?carrier={carrier}
Production: https://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 and click your username and select Profile.
postalReportingNumber Required. The unique ID used to identify the merchant. To retrieve the merchant’s postalReportingNumber, issue the Get All Merchants 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.

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] 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 PB Shipping APIs. Do not use these to issue API operations. Instead, use the shipperCarrierAccountId, below.

        name String The carrier account attribute.
        value String The value of the carrier account attribute.
shipperCarrierAccountId String RESPONSE ONLY. A unique identifier for the carrier account. If the merchant registers multiple accounts with this carrier with the Shipping APIs, you must pass this identifier in the X-PB-Shipper-Carrier-AccountId header when the merchant performs an operation with the carrier.

Request / Response Elements: Address Object

The Address Object appears in the accountAddress and contactAddress fields. The object contains the following elements:

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.

Request / Response Elements: Input Parameters

For a list of parameters used in the inputParameters array, see Carrier Account Input Parameters.

Response Elements: Carrier Account Attributes

The following attributes and their values are returned in the carrierAccount array in the response of the Register an Existing Carrier Account API.

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:

FedEx 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>",
    "inputParameters" : [
      {
        "name" : "CLIENT_SOFTWARE_PRODUCT",
        "value" : "SAPI"
      }
    ]
}'
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"
      }
    ],
    "inputParameters": [
      {
        "name": "CLIENT_SOFTWARE_PRODUCT",
        "value": "SAPI"
      }
    ],
    "shipperCarrierAccountId": "12345678-abcd-1234-abcd-1234abcd1234"
}

UPS 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

For a list of all error codes, please see 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.