Get Merchant Accounts¶

HTTP Request¶

GET /v1/developers/{developerId}/merchants

Summary¶

This operation retrieves the merchants who enrolled for a Pitney Bowes merchant account through your developer ID. For more information on merchant enrollment, see Manage Merchant Accounts.

Request URLs¶

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/developers/{developerId}/merchants
Production: https://shipping-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.

Default Value: 20
Maximum Value: 2000

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.
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.

Merchant Object¶

The Merchant API’s content array returns the Merchant Object:

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[Merchant Carrier Accounts 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.
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 website that converts milliseconds since the Epoch, such as https://currentmillis.com.
subscriptionAccount	String	Any subscription account that the merchant might have.

Merchant Carrier Accounts Object¶

The merchantCarrierAccounts array returns the following object.

Name	Data Type	Description
accountNumber	String	The merchant’s account number with the carrier.
carrierName	String	The carrier. Possible values: `FEDEX` `UPS`
deactivationDate	Number	If the carrier account has been removed, this field is set to the date of removal. If the carrier account is still active, this field is set to `0`.
isActive	Boolean	If `true`, the carrier account is active. If `false`, the merchant has removed the carrier account.
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.
merchantCarrierAccountAttributes	Array[Object]	The objects in this array display settings that correspond to settings in the merchant’s carrier account. Each object in the array is a name-value pair and contains the following fields: attributeName: The carrier account attribute. This field takes a String. attributeValue: The value of the carrier account attribute. This field takes a String.
registrationDate	Number	The date the merchant’s carrier account was registered with Pitney Bowes, shown as milliseconds since the Unix Epoch.
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": [ {
        "company": "Store Inc",
        "deactivatedDate": null,
        "developerId": "12345678",
        "email": "avery@example.com",
        "enterpriseAccount": "4567890",
        "fullName": "Avery Jones",
        "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"
        },
        ...
        ],
        "merchantStatus": "ACTIVE",
        "merchantStatusReason": null,
        "merchantType": "DEFAULT",
        "paymentAccountNumber": "3456789",
        "paymentServicesAccountId": "12345678-abdc-1234-abcd-efg123456789",
        "paymentServicesAccountIdActive": true,
        "postalReportingNumber": "902455555",
        "registeredDate": 1557792000000,
        "subscriptionAccount": "6789012"
    },
    ...
    ],
    "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 error codes returned by the Ecommerce APIs, please see Error Codes.