Register a Merchant as Part of a Bulk Postage Account

HTTP Request

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

Summary

Use this API if you use a Pitney Bowes Bulk Postage Account to manage funds on behalf of your merchants. Use this POST operation to register the merchant with Pitney Bowes and provide the merchant with a Shipper ID.

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

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 Data Type Description
developerId String Required. Your Pitney Bowes developer ID.

Request Headers

Name Data Type Description
Authorization String Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type String Required. The media type of the request entity. Set this to application/json.

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

The city or town name.

Conditional: This is required if postalCode is absent.

stateProvince String

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

Conditional: This is required if postalCode is absent. Note that 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.

postalCode String

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

Conditional: This is required if cityTown and stateProvince are absent.

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

The operation returns a merchant object. The table lists all possible fields in a merchant object. Some 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

The date the merchant’s account was deactivated, if applicable, shown as milliseconds since the Unix Epoch. A deactivated merchant can no longer print labels. For an active merchant, the field is set to null.

To convert the value to human-readable form, round from milliseconds to seconds and then 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 If you change a merchant’s status from ACTIVE to INACTIVE, you must give a reason for the change. The reason is recorded here. For an active merchant, the field is set to null.
parcelProtection String If true, the merchant can choose to insure a parcel with PB Parcel Protection when creating a shipment.
paymentMethod String

This is returned only for the Authorize Merchant API call. This field indicates the payment method for the merchant’s PB Postage Account. Possible values are:

Sample Request

curl -X POST .../v2/developers/<developer_id>/merchants/registration \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-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.