Register a Merchant as a Known Shipper

HTTP Request

POST /v2/developers/{developerId}/merchants/registration

Summary

This operation registers a merchant as a known shipper with Pitney Bowes and provides the merchant with a unique Shipper ID. Use this operation if you use a Pitney Bowes Bulk Postage Account to manage funds on behalf of your merchants.

To learn more about Bulk Postage Accounts, please contact the Pitney Bowes support team at ShippingAPISupport@pb.com.

See also: Merchant Enrollment Models

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v2/developers/{developerId}/merchants/registration
Production: https://api.pitneybowes.com/shippingservices/v2/developers/{developerId}/merchants/registration

Path Parameter

Name Description
developerId
Required. Your Pitney Bowes developer ID.

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-UnifiedErrorStructure Recommended. Set this to true to use the standard error object if an error occurs.

Request Elements

Name Data Type Description
addressLines Array[String]

Required. Street address, including apartment number if applicable. You can specify up to 3 address lines.

Note: For USPS, the address cannot be a P.O. Box.

cityTown String

Conditional. Required if postalCode is absent; otherwise optional.

The city or town name.

stateProvince String

Conditional. Required if postalCode is absent; otherwise optional. In some cases where cityTown is a unique name within the country, this can be left out even if postalCode is absent, but the best practice is to include this field when postalCode absent.

State or province name. For US address, use the 2-letter state code.

postalCode String

Conditional. Required if cityTown and stateProvince are absent.

Postal/ZIP code. For US addresses, either the 5-digit or 9-digit ZIP code.

countryCode String Required. Two-character country code from the ISO country list.
name String Required. The merchant’s first and last name.
company String Required. The name of the company.
phone String Required. A valid phone number for the merchant. For USPS, this must be a valid 10-digit number. The string should contain 10 numeric characters and no additional characters. For example: "8442566444"
email String Required. The email address.

Response Elements

Important

The operation returns a Merchant Object. The table below lists all possible fields in a Merchant Object. Some fields might not apply to your operation.

Name
Data Type Description
fullName String The merchant’s full name.
email String The merchant’s email address.
registeredDate Number The date the merchant’s account was created, shown as milliseconds since the Unix Epoch. You can convert the date to human-readable form by rounding from milliseconds to seconds and then using the Unix timestamp conversion algorithm, or by using a web site that converts milliseconds since the Epoch, such as https://currentmillis.com.
deactivatedDate Number

For an inactive merchant, the date the merchant’s account was deactivated, shown as milliseconds since the Unix Epoch. For an active merchant, this field is set to null.

To convert milliseconds since the Epoch to human-readable form:

  1. Round from milliseconds to seconds.
  2. Apply the Unix timestamp conversion algorithm.

Alternatively, use a web site that converts milliseconds since the Epoch, such as https://currentmillis.com.

paymentAccountNumber String The Pitney Bowes customer account number assigned to the merchant.
enterpriseAccount String An enterprise account number that is associated with the merchant.
subscriptionAccount String Any subscription account that the merchant might have.
postalReportingNumber String

The unique ID used to identify the merchant.

Note: This value is also the merchant’s Shipper ID. You must specify Shipper ID when creating a shipment.

merchantStatus String

The merchant’s status. Possible values are:

  • ACTIVE
  • INACTIVE
merchantStatusReason String For an inactive merchant, the reason the merchant was deactivated. For an active merchant, this field is set to null.
parcelProtection String If true, the merchant can choose to request PB Parcel Protection coverage when creating a shipment.
paymentKey String If the merchant uses ACH as the payment method, this returns the ACH payment key. Otherwise this returns the null value.
paymentMethod String

When returned by the Authorize a Merchant API call, this field indicates the payment method for the merchant’s PB Postage Account. For other API calls, this field returns the null value.

For the Authorize a Merchant API call, the possible values are:

  • LineOfCredit: PB Line of Credit
  • CreditCard: U.S. credit card
  • ACH: (Automated Clearing House)
merchantCarrierAccounts Array[Object] Merchants with Multiple Carriers Only. This array appears in the response of the merchant object only if the merchant has registered additional commercial carrier accounts, other than Newgistics or PB Presort. Each object in this array contains information on a specific carrier account.
    accountNumber String The merchant’s account number with the carrier.
    carrierName String

The carrier. Possible values:

  • UPS
  • FEDEX (Coming soon to Sandbox)
    deactivationDate Number If the merchant has removed the carrier account, this is the date the account was removed.
    isActive Boolean If true, the carrier account is active. If false, the merchant has removed the carrier account.
    isAuthorized Boolean If true, the PB Shipping APIs can generate labels with this carrier on behalf of the merchant. If false, the APIs cannot generate labels with the carrier for this merchant.
    merchantCarrierAccountAttributes Array[Object] Attributes that correspond to settings in the merchant’s carrier account. Each object in the array defines an attribute and its value.
        attributeName String The carrier account attribute.
        attributeValue String The value of the carrier account attribute.
    registrationDate Number The date the carrier account was registered to be used with Pitney Bowes.
    shipperCarrierAccountId String The unique 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.

Sample Request

curl -X POST .../v2/developers/<developer_id>/merchants/registration \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "addressLines": [
        "1 Atwell rd",
        "bldg 2",
        "unit 302"
    ],
    "cityTown": "Cooperstown",
    "stateProvince": "NY",
    "postalCode": "13326",
    "countryCode": "US",
    "name": "James Brother",
    "company": "Supplies",
    "phone": "203-924-2428",
    "email": "jb@example.com"
}'

Sample Response

{
    "fullName": "James Brother",
    "email": "jb@example.com",
    "registeredDate": 1481153979899,
    "deactivatedDate": null,
    "paymentAccountNumber": "1234567",
    "enterpriseAccount": "2345678",
    "subscriptionAccount": "3456789"
    "postalReportingNumber": "55555555",
    "merchantStatus": "ACTIVE",
    "merchantStatusReason": null,
    "parcelProtection": false
}

Error Codes

For a list of all PB Shipping APIs error codes, see Error Codes.