Register an Existing Carrier Account

Note

This feature is available in the Sandbox environment.

HTTP Request

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

Summary

This operation authorizes a merchant to use an additional carrier for use with a merchant’s Pitney Bowes Account. The merchant must have an existing account with the carrier. Currently, this API supports integration with UPS.

For step-by-step implementation of the API, please see the Carrier Registration Tutorial.

When you issue this API call, Pitney Bowes verifies the merchant’s account with the carrier using information you send in the API request. The carrier sends back to Pitney Bowes a unique set of credentials to use with the merchant’s Pitney Bowes account. Pitney Bowes returns the credentials in the response to this API call but also returns a unique shipperCarrierAccountId you use instead of the credentials. When the merchant performs an action that uses this carrier, you need only pass the shipperCarrierAccountId. Pitney Bowes uses the ID to locate and send the required credentials to the carrier. You pass the ID in the X-PB-Shipper-Carrier-AccountId request header of an API request.

Prerequisites

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 The merchant’s account number with the carrier.
accountAddress Carrier Registration Address Object

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 The merchant’s contact address.
inputParameters Array[Object]

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 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.  
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
INVOICE_CONTROL_ID The Control ID displayed on the invoice. UPS: Required
INVOICE_CURRENCY_CODE

The currency code used on the invoice.

Supported currencies:

  • USD
  • CAD
UPS
INVOICE_DATE

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

Use the following format:

yyyyMMdd

UPS
INVOICE_NUMBER The invoice number. UPS
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.