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. A merchant must have a physical U.S. address to obtain a Shipping ID. Merchants cannot use P.O. Boxes as addresses.
To learn more about Bulk Postage Accounts, please contact Client Support at ClientSupportTechServices@pb.com. See also Merchant Enrollment Models.
Request URLs¶
Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v2/developers/{developerId}/merchants/registration
Production: https://shipping-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 |
X-PB-UnifiedErrorStructure |
Recommended. Set this to |
Request Elements¶
Name |
Data Type |
Description |
---|---|---|
name |
String |
Required. The merchant’s first and last name. |
String |
Required. The email address. |
|
company |
String |
Conditional. The name of the company. The company field is required if the merchant is incorporated. It should be left out if the merchant is not incorporated. Include this field only if the merchant is incorporated. |
phone |
String |
Required. A valid 10-digit number. The string should contain 10 numeric characters and no additional characters. For example: |
addressLines |
Array[String] |
Required. Street address, including apartment number if applicable. You can specify up to 3 address lines. The address cannot be a P.O. Box. |
cityTown |
String |
Conditional. The city or town name. Required if |
stateProvince |
String |
Conditional. The state or province name. For US addresses, use the 2-letter state code. Required if |
postalCode |
String |
Conditional. The Postal or ZIP code. For US addresses, either the 5-digit or 9-digit ZIP code. Required if |
countryCode |
String |
Required. Two-character country code from the ISO country list. |
Response Elements¶
The operation returns a Merchant Object. The following table lists all possible fields in a Merchant Object.
Important
Some fields in the Merchant Object might not apply to your operation and are marked accordingly.
Name |
Data Type |
Description |
---|---|---|
address |
Internal use only. If this field is returned, it is set to |
|
company |
String |
The merchant’s company. |
deactivatedDate |
String |
For an inactive merchant, the date the merchant’s account was deactivated, returned in the ISO 8601 format. For an active merchant, this field is |
developerId |
String |
Your Pitney Bowes developer ID. |
String |
The merchant’s email address. |
|
enterpriseAccount |
String |
An enterprise account number associated with the merchant. |
fullName |
String |
The merchant’s full name. |
merchantCarrierAccounts |
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 PB Standard or PB Presort. Each object in this array contains information on a specific carrier account. |
|
merchantStatus |
String |
The merchant’s status. Possible values are:
|
merchantStatusReason |
String |
For an inactive merchant, the reason the merchant was deactivated. For an active merchant, this field is |
merchantType |
String |
Indicates the type of merchant:
|
paymentAccountNumber |
String |
The identifier for the PB Postage Account. |
paymentServicesAccountId |
String |
A UUID that identifies the payment services account used to fund the merchant’s PB Postage Account. The payment services account has the merchant’s payment methods. A merchant can have one or more payment methods. |
paymentServicesAccountIdActive |
Boolean |
If set to |
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. |
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. |
subscriptionAccount |
String |
Any subscription account that the merchant might have. |
paymentMethod |
String |
When returned by the Authorize a Merchant API, this indicates the payment method for the merchant’s PB Postage Account. Possible values are:
|
Sample Request¶
curl -X POST .../v2/developers/12345678/merchants/registration \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
"name": "James Wright",
"email": "james@example.com",
"company": "Supplies Inc",
"phone": "6070000000",
"addressLines": [
"1 Atwell Rd",
"Unit 302"
],
"cityTown": "Cooperstown",
"stateProvince": "NY",
"postalCode": "13326",
"countryCode": "US"
}'
Sample Response¶
{
"postalReportingNumber": "902455555",
"developerId": "12345678",
"fullName": "James Wright",
"company": "Supplies Inc",
"email": "james@example.com",
"registeredDate": 1600705393223,
"deactivatedDate": null,
"paymentAccountNumber": "1234567",
"enterpriseAccount": "2345678",
"subscriptionAccount": "3456789",
"merchantStatus": "ACTIVE",
"merchantStatusReason": null,
"merchantType": "KNOWN_SHIPPER",
"paymentServicesAccountId": null,
"paymentServicesAccountIdActive": false
}
Error Codes¶
For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.