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 Accounts.
Request URIs¶
Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/developers/{developerId}/merchants
Production: https://api.pitneybowes.com/shippingservices/v1/developers/{developerId}/merchants
Path Parameter¶
| Name | Description |
|---|---|
| developerId
|
Required. Your Pitney Bowes developer ID. |
Query Parameters¶
Query parameters are optional.
| Name | Description |
|---|---|
| size | The number of merchants to return per page in the result set. The default
page size is 20. |
| page | The index number of the page to return. Page index numbering starts at
In the response body, the API displays the index number in the
|
| sort | Defines a property to sort on and the sort order. Sort order can be
ascending (
For example:
|
Request Header¶
| Name
|
Description |
|---|---|
| Authorization | Required. OAuth token generated using the Generate an OAuth Token API. |
| X-PB-UnifiedErrorStructure | Recommended. Set this to true to use the standard error
object if an error occurs. |
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 To specify the index number in the API call, use the |
| 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¶
The content array returns a separate merchant object for every merchant. The
merchant object can contain the following fields. Some fields might not apply to a
given merchant:
| Name
|
Data Type | Description |
|---|---|---|
| fullName | String | The merchant’s full name. |
| 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 To convert milliseconds since the Epoch to human-readable form:
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:
|
| 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 For the Authorize a Merchant API call, the possible values are:
|
| 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:
|
| 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 GET .../v1/developers/<developer_id>/merchants?sort=fullName,asc \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-UnifiedErrorStructure: true"
Sample Response¶
{
"content": [ {
"fullName": "Alan Smith",
"email": "alan@example.com",
"registeredDate": 1481153979899,
"deactivatedDate": null,
"paymentAccountNumber": "1234567",
"enterpriseAccount": "2345678",
"subscriptionAccount": "3456789",
"postalReportingNumber": "9024989955",
"merchantStatus": "ACTIVE",
"merchantStatusReason": null
}, {
"fullName": "Avery Jones",
"email": "avery@example.com",
"registeredDate": 1557792000000,
"deactivatedDate": null,
"paymentAccountNumber": "3456789",
"enterpriseAccount": "4567890",
"subscriptionAccount": "6789012",
"postalReportingNumber": "9024989978",
"merchantStatus": "ACTIVE",
"merchantStatusReason": null,
"merchantCarrierAccounts": [ {
"accountNumber": "123456",
"carrierName": "UPS",
"deactivationDate": 0,
"isActive": true,
"isAuthorized": true,
"merchantCarrierAccountAttributes": [ {
"attributeName": "ACCOUNT_NUMBER",
"attributeValue": "123456"
}, {
"attributeName": "USER_ID",
"attributeValue": "abcd1234"
} ],
"registrationDate": 1544209739845,
"shipperCarrierAccountId": "abcdef89-1234-5678-1234-abcf5678def0"
},
...
],
},
...
],
"totalPages": 4,
"totalElements": 64,
"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, please see Error Codes.