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 0. Specify page=0 to return the 1st page; specify page=1 to return the 2nd page, and so on. In the response body, the API displays the index number in the number field.
sort	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	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 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

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	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 null. To convert milliseconds since the Epoch to human-readable form: Round from milliseconds to seconds. 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	For an inactive merchant, the reason the merchant was deactivated as entered in the Deactivate a Merchant API. 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 null value. For the Authorize a Merchant API call, the possible values are: LineOfCredit: PB Line of Credit CreditCard: Credit card ACH: (Automated Clearing House)
merchantCarrierAccounts	Array[Object]	This applies if the merchant 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: UPS FEDEX (Coming soon to Sandbox)
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]	The merchant’s account settings with the carrier. Each object in the array defines a setting and its value.
attributeName	String	The name of 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": "1234AB",
            "carrierName": "UPS",
            "deactivationDate": 0,
            "isActive": true,
            "isAuthorized": true,
            "merchantCarrierAccountAttributes": [ {
                "attributeName": "ACCOUNT_NUMBER",
                "attributeValue": "1234AB"
            }, {
                "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.

 
 
 
 

• next
• previous |

© Copyright 2019, PB.