Register an Existing Carrier Account

HTTP Request

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

Summary

This operation authorizes an additional carrier for a merchant to use with the PB Shipping APIs. The merchant must have an existing account with the carrier. Currently, the API supports integration with UPS®.

When you call this API, Pitney Bowes verifies the merchant’s carrier account and receives a unique set of credentials for access to the account. Pitney Bowes maps the credentials to a shipperCarrierAccountId, which is returned in the API response. You must store this ID. You pass the ID in the X-PB-Shipper-Carrier-AccountId request header whenever the merchant performs an operation that uses this carrier. .

Tutorial

To use this API, you must also invoke the Carrier License Agreement API. For a set of steps on how to use the two APIs, see Tutorial: Register a Merchant’s Existing Carrier Account.

Prerequisites

  • The merchant must have an existing account with the carrier.

  • You must retrieve text of the carrier’s license agreement through the Carrier License Agreement API.

  • You must gather the following information about the merchant’s carrier account:

    Required Information Description
    Account number The merchant’s account number with the carrier.
    Account address The Ship From address as it appears on the merchant’s account with the carrier.
    Contact title and address The title and address of the primary contact that the merchant provided to the carrier.
    Identity and IP address of the merchant’s machine

    You need the black-box identity and IP address of the merchant’s machine.

    For help in retrieving the black-box identity, consult your Pitney Bowes implementation engineer.

    Invoice information

    UPS Only: If the merchant has shipped in the last 90 days, you must have information from the most recent invoice. If the merchant has not shipped in the last 90 days, no invoice information is required.

    Merchants can retrieve invoices by logging into their accounts at https://www.ups.com.

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 to add to the merchant’s account.

Valid value: 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 for the transaction, up to 25 characters.

Important: You must ensure this is a unique id.

X-PB-UnifiedErrorStructure Recommended. Set this to true to use the standard error object if an error occurs.

Request / Response Elements

Name Data Type Description
accountNumber String Required. The merchant’s account number with the carrier.
accountAddress Carrier Registration 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 Carrier Registration Address Object Required. The contact address that the merchant provided to the carrier.
inputParameters Array[Object]

Required. Carrier Registration Parameters. The parameters include information the merchant received from the carrier and must provide to the developer. Each object in the array defines a parameter in the form of a name-value pair. For example:

{
    "name": "ACCOUNT_POSTAL_CODE",
    "value": "80301"
}
carrierAccount Array[Object] Response Only. When Pitney Bowes verifies the merchant’s account with the carrier, the carrier generates and sends back a set of credentials for use when the merchant accesses the carrier through the PB Shipping APIs. These are not required for future API operations. Instead, Pitney Bowes provides the shipperCarrierAccountId (below) to be passed with API calls.
shipperCarrierAccountId String Response Only. The identifier to use when the merchant performs an operation that uses this carrier account. The identifier is passed in the X-PB-Shipper-Carrier-AccountId request header of the API request.

Carrier Registration Address Object

The accountAddress and contactAddress elements each contain an object with the following fields.

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 address, use the 2-letter state code.
postalCode String Postal/ZIP code. For US addresses, either the 5-digit or 9-digit ZIP code.
countryCode String Two-character country code from the ISO country list.

Carrier Registration Parameters

The inputParameters array includes information about the merchant’s carrier account. Each object in the array defines a parameter in the form of a name-value pair.

Name Description Applies to the following carriers
ACCOUNT_COUNTRY_CODE

The two-character ISO country code for the merchant’s country.

Supported countries:

  • US
  • CA
UPS
ACCOUNT_POSTAL_CODE The merchant’s postal code. UPS
CONTACT_TITLE The title of the primary contact that the merchant provided to the carrier. UPS: Required
DEVICE_IDENTITY

The black-box identity of the merchant’s machine.

For help in retrieving this information, consult your Pitney Bowes implementation engineer.

UPS: Required
END_USER_IP The IP address of the merchant’s machine. UPS: Required
INVOICE_AMOUNT

The amount charged on a recent invoice. The invoice must be from within the last 90 days. Use the same invoice for all the INVOICE_* parameters in this table.

The value for this parameter can have a maximum of 16 digits before the decimal and 2 digits after the decimal.

Example: 1235.84

For UPS, this is the amount in the invoice’s Charges This Period field.

UPS: Required if the merchant has shipped in the last 90 days.
INVOICE_CONTROL_ID The Control ID displayed on the invoice. UPS: Required if the merchant has shipped in the last 90 days.
INVOICE_CURRENCY_CODE

The currency code used on the invoice.

Supported currencies:

  • USD
  • CAD
UPS: Required if the merchant has shipped in the last 90 days.
INVOICE_DATE

The date of the invoice. The invoice date should be within the last 90 days.

Use the following format:

yyyyMMdd

UPS: Required if the merchant has shipped in the last 90 days.
INVOICE_NUMBER The invoice number. UPS: Required if the merchant has shipped in the last 90 days.
LICENSE_TEXT The text of the merchant’s license agreement with the carrier, as retrieved through the Get Carrier License Agreement API. UPS: Required

Sample Request

curl -X POST .../v1/developers/{developerId}/merchants/{postalReportingNumber}/carrier-accounts/register?carrier={carrier} \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: reg453abc" \
-H "cache-control: no-cache" \
-d '
{
    "accountNumber": "56V7A6",
    "accountAddress": {
        "company": "Widgets",
        "name": "James Smith",
        "phone": "303-555-1213",
        "email": "js@example.com",
        "residential": false,
        "addressLines": [ "4750 Walnut Street" ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "contactAddress": {
        "company": "Widgets",
        "name": "James Smith",
        "phone": "303-555-1213",
        "email": "js@example.com",
        "residential": false,
        "addressLines": [ "4750 Walnut Street" ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "inputParameters": [ {
        "name": "ACCOUNT_POSTAL_CODE",
        "value": "80301"
    }, {
        "name": "ACCOUNT_COUNTRY_CODE",
        "value": "US"
    }, {
        "name": "CONTACT_TITLE",
        "value": "Manager"
    }, {
        "name": "END_USER_IP",
        "value": "10.100.20.20"
    }, {
        "name": "DEVICE_IDENTITY",
        "value": "84315tr3M5e4n"
    }, {
        "name": "LICENSE_TEXT",
        "value": "<license text>"
    } ]
}'

Sample Response

{
    "accountNumber": "56V7A6",
    "accountAddress": {
        "company": "Widgets",
        "name": "James Smith",
        "phone": "303-555-1213",
        "email": "js@example.com",
        "residential": false,
        "addressLines": [ "4750 Walnut Street" ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "contactAddress": {
        "company": "Widgets",
        "name": "James Smith",
        "phone": "303-555-1213",
        "email": "js@example.com",
        "residential": false,
        "addressLines": [ "4750 Walnut Street" ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "inputParameters": [
      {
        "name": "ACCOUNT_POSTAL_CODE",
        "value": "80301"
      },
      {
        "name": "ACCOUNT_COUNTRY_CODE",
        "value": "US"
      },
      {
        "name": "CONTACT_TITLE",
        "value": "Manager"
      },
      {
        "name": "END_USER_IP",
        "value": "10.100.20.20"
      },
      {
        "name": "DEVICE_IDENTITY",
        "value": "84315tr3M5e4n"
      }
    ],
    "carrierAccount": [ {
        "name": "ACCOUNT_NUMBER",
        "value": "1b34e6"
      },
      {
        "name": "USER_ID",
        "value": "cf5890157121ca"
      },
      {
        "name": "PASSWORD",
        "value": "Password"
      },
      {
        "name": "KEY",
        "value": "ABCD123456789DEF"
      }
    ],
    "shipperCarrierAccountId": "24313c83-1956-f43a-0805943453ed718a9"
}

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.