Get All Merchants

HTTP Request

GET /v1/developers/{developerId}/merchants

Summary

This operation retrieves all the merchants enrolled under your Developer ID. For more information on merchant enrollment, see Merchant Enrollment.

Request URIs

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

Path Parameters

Name Data Type Description
developerId String Required. Your Pitney Bowes developer ID.

Query Parameters

Query parameters are optional.

Name Data Type Description
size Number The page size of the result set. Specifically, the number of merchants to return per page in the result set. The default page size is 20 merchants.
page Number

The index number of the page to return. Page index numbering starts at 0. Specify page=0 to return the 1st page; specify page=1 to return the 2nd page, and so on.

In the response object, the API displays the index number in the number field.

sort String

Defines a property to sort on and the sort order. Sort order can be ascending (asc) or descending (desc). Use the following form:

<property name>,<sort direction>

For example:

sort=fullName,desc

Request Header

Name Data Type Description
Authorization String Required. OAuth token generated using the Generate an OAuth Token API.

Response Elements

Name Data Type Description
content Array[merchant object] The merchants enrolled under your Developer ID. The merchant object’s elements are described in the next table below.
totalPages Number The number of pages in the result set.
totalElements Number The number of merchants in the result set.
last Boolean If true, this is the last page of the result set.
size Number The number of merchants per page in the result set. The default is 20.
number Number

The page’s index number. Index numbers start at 0. If the value of number is 0, the API has returned the 1st page of the result set; if the value is 1, the API has returned the 2nd page, and so on.

To specify the index number in the API call, use the page query parameter.

sort Array[Object] Lists the property used to sort the merchants and the sort order.
numberOfElements Number The number of merchants on the current page.
first Boolean If true, this is the first page of the result set.

Response Elements: Merchant Object

IMPORTANT: Some fields might not apply to your operation. This table describes all the possible fields in a merchant object.

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 GET .../v1/developers/<developer_id>/merchants?sort=fullName,asc \
–H "Authorization: Bearer <oauth_token>"

Sample Response

{
    "content": [ {
        "fullName": "Avery Smith",
        "email": "avery@example.com",
        "registeredDate": 1481153979899,
        "deactivatedDate": null,
        "paymentAccountNumber": "1234567",
        "enterpriseAccount": "2345678",
        "subscriptionAccount": "3456789",
        "postalReportingNumber": "55555555",
        "merchantStatus": "ACTIVE",
        "merchantStatusReason": null
    }, ... ],
    "totalPages": 2,
    "totalElements": 24,
    "last": false,
    "size": 20,
    "number": 0,
    "sort": [ {
        "direction": "ASC",
        "property": "fullName",
        "ignoreCase": false,
        "nullHandling": "NATIVE",
        "ascending": true,
        "descending": false
    } ],
    "numberOfElements": 20,
    "first": true
}

Error Codes

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