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 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
name	String	Required. The merchant’s first and last name.
email	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: `"8442566444"`
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 `postalCode` is absent; otherwise optional.
stateProvince	String	Conditional. The state or province name. For US addresses, use the 2-letter state code. 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.
postalCode	String	Conditional. The Postal or ZIP code. For US addresses, either the 5-digit or 9-digit ZIP code. Required if `cityTown` and `stateProvince` are absent.
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 `null`.
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 `null`.
developerId	String	Your Pitney Bowes developer ID.
email	String	The merchant’s email address.
enterpriseAccount	String	An enterprise account number associated with the merchant.
fullName	String	The merchant’s full name.
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 PB Standard or PB Presort. Each object in this array contains information on a specific carrier account.
merchantCarrierAccounts .accountNumber	String	The merchant’s account number with the carrier.
merchantCarrierAccounts .carrierName	String	The carrier. Possible values: `FEDEX` `UPS`
merchantCarrierAccounts .deactivationDate	Number	If the merchant has removed the carrier account, this field is set to the date that the carrier account was removed. If the carrier account is still active, this field is set to `0`.
merchantCarrierAccounts .isActive	Boolean	If `true`, the carrier account is active. If `false`, the merchant has removed the carrier account.
merchantCarrierAccounts .isAuthorized	Boolean	If `true`, the 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.
merchantCarrierAccounts .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.
merchantCarrierAccounts .merchantCarrierAccountAttributes .attributeName	String	The carrier account attribute.
merchantCarrierAccounts .merchantCarrierAccountAttributes .attributeValue	String	The value of the carrier account attribute.
merchantCarrierAccounts .registrationDate	Number	The date the merchant’s carrier account was registered with Pitney Bowes, shown as milliseconds since the Unix Epoch.
merchantCarrierAccounts .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.
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 `null`.
merchantType	String	Indicates the type of merchant: `DEFAULT`: The default merchant that comes with the developer account. `INDIVIDUAL`: A merchant with an individual postage account. `KNOWN_SHIPPER`: A merchant who uses a bulk postage account.
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 `true`, the merchant’s payment services account is active and can be used to fund postage.
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: `LineOfCredit/Prepaid`: PB Line of Credit `CreditCard`: U.S. credit card `ACH`: Automated Clearing House
paymentKey	String	Note This field will be removed in 2022. If the merchant uses ACH as the payment method, this returns the ACH payment key. Otherwise this field is `null`.

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.