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 PB Shipping APIs. Note that 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 APIs.

Considerations

  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.

  3. 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 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 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.

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 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.

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.

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

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"
}

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

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.