Note
The Fulfillment APIs are coming soon.
Find Orders¶
HTTP Requests¶
Return all Order Data¶
POST /v1/orders/search
Return a Subset of Order Data¶
POST /v1/orders/status/search
Summary¶
Use this operation to find orders based on your search criteria. The operation provides two HTTP requests. The Return all Order Data request returns all fields in the Orders object for each result. The Return a Subset of Order Data request returns a smaller payload focused on the current order status.
Request URLs¶
Return all Order Data¶
Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/fulfillment/v1/orders/search
Production: https://shipping-api.pitneybowes.com/shippingservices/fulfillment/v1/orders/search
Return a Subset of Order Data¶
Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/fulfillment/v1/orders/status/search
Production: https://shipping-api.pitneybowes.com/shippingservices/fulfillment/v1/orders/status/search
Query Parameters¶
Query parameters are optional.
Name |
Description |
---|---|
page |
The page number to return in the result set. Page numbering starts at Default value: |
size |
The number of orders to return per page. Default value: |
Request Headers¶
Name |
Description |
---|---|
Authorization |
Required. OAuth token generated using the Generate an OAuth Token API. |
X-PB-TransactionId |
Required. A unique identifier for the request, up to 25 characters. The following characters are allowed: letters, numbers, hyphens ( Important: Ensure this is a unique ID. |
Request Elements¶
The POST operation sends an object with the fields described here. Required fields are marked Required. Other fields are optional.
Name |
Data Type |
Description |
---|---|---|
clientId |
String |
Required. The client identifier assigned by Pitney Bowes. |
sort |
Array[String] |
The property upon which to sort and the sort order. Use the following syntax:
Where
And
For example: |
searchFields |
Array[Object] |
The search criteria. Each object in the array is a name-value pair with the following two elements:
You can search on the following Orders-object fields. For possible values, see the field’s definition here.
If no date filter is specified, the API returns orders created in the last six months. |
Response Elements¶
The response returns an object with the fields described here.
Name |
Data Type |
Description |
---|---|---|
totalPages |
Number |
The number of pages in the result set. |
totalElements |
Number |
The number of orders in the result set. |
first |
Boolean |
If true, this is the first page of the result set. |
last |
Boolean |
If true, this is the last page of the result set. |
size |
Number |
The number of orders per page in the result set. |
page |
Number |
The page number to return. Page numbering starts at 1. |
sort |
Array[String] |
The sort order. |
orders |
Array[Orders Object] |
The orders. Each object in the array is a separate order. |
Orders Object¶
The orders
array in the response contains the Orders object, described in the table below. (The table describes the Orders object for all operations that use it. Some fields in the table are labeled Required, meaning they are required in operations that send this object in the payload.)
Depending on which HTTP request you use, this operation returns all Orders data or a subset of the data, as shown in the Sample Request to Return a Subset of Order Data.
Name |
Data Type |
Description |
---|---|---|
clientId |
String |
Required. The client ID assigned by Pitney Bowes. |
orderId |
String |
RESPONSE ONLY. The order ID assigned by Pitney Bowes. |
clientOrderId |
String |
Required. The order ID assigned by the client. Maximum length: 50 characters |
customerOrderId |
String |
The customer-specific order number. Typically this is the order number from the website or ERP system. Maximum length: 50 characters |
brand |
String |
The manufacturer’s brand name for the item. Maximum length: 50 characters |
references |
Array[References Object] |
Additional reference information for the order. Each object in the array is a name-value pair that defines a reference field and value. |
salesChannel |
Object |
Reserved for future use. |
shippingDetails |
Required. The carrier details for the order. |
|
orderType |
String |
The type of order. Possible values:
|
createDate |
String |
Required. The date and time the order was created in the client system, specified in the ISO 8601 format: |
updateDate |
String |
The date and time the order was updated in the client system, specified in the ISO 8601 format: |
pbCreateDate |
String |
RESPONSE ONLY. The date and time the order was created in the Pitney Bowes system, returned in the ISO 8601 format: |
pbUpdateDate |
String |
RESPONSE ONLY. The date and time the order was updated in the Pitney Bowes system, returned in the ISO 8601 format: |
fromNode |
String |
The warehouse facility ID. |
shipOnDate |
String |
The date and time by which the order is promised to be shipped, specified in the ISO 8601 format: |
fulfillmentReleaseDate |
String |
The date and time the order is to be released for fulfillment, specified in the ISO 8601 format: |
promisedDeliveryDate |
String |
The date and time the order is promised to be delivered, specified in the ISO 8601 format: |
orderHandling |
String |
Possible value:
|
orderLines |
Array[Order Lines Object] |
Required. The items included in the order. |
orderCharges |
Cost details. |
|
toAddress |
Required. The order’s destination address. |
|
billingAddress |
The order’s billing address. |
|
isGift |
Boolean |
If |
giftMessageText |
String |
The gift message to be printed on the pack slip and included in the shipment. Maximum length: 1,024 characters |
valueAddedServices |
Array[Object] |
Reserved for future use. |
paymentDetails |
Array[Object] |
Reserved for future use. |
customsInfo |
Object |
Customs information for an international order. |
customsInfo.customsDeclaredValue |
Number |
The value that is declared in customs. |
customsInfo.importerCustomsReference |
String |
A reference number used by the importer, such as a VAT number, PO number, or insured number. Maximum length: 100 characters |
customsInfo.importerCustomsReferenceType |
String |
The type of reference number. Maximum length: 50 characters |
status |
String |
RESPONSE ONLY. Status of the order. Possible values are:
|
isOnHold |
Boolean |
RESPONSE ONLY. If |
holdReason |
Array[String] |
RESPONSE ONLY. Reason codes for the hold. |
internalNotes |
String |
Any notes associated with the order for internal reference. Maximum length: 255 characters |
Sample Requests¶
See the following examples:
Sample Request to Return all Order Data¶
The request returns the full Orders object.
curl -X POST ../v1/orders/search \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
"clientId": "NGST",
"sort": [
"createDate-asc"
],
"searchFields": [ {
"name": "status",
"values": [
"Received",
"CANCELED"
]
},{
"name": "ordertype",
"values": [
"eCom"
]
} ]
}'
{
"totalPages": 8,
"totalElements": 153,
"first": true,
"last": false,
"size": 20,
"page": 1,
"sort": [
"createDate-asc"
],
"orders": [ {
"clientId": "NGST",
"orderId": "ORA0000554970344591360US",
"clientOrderId": "NEW-ORD-0001",
"customerOrderId": "CUSTOM-ORD-1",
"references": [],
"shippingDetails": {
"carrier": "PITNEY BOWES",
"serviceId": "USPS",
"serviceName": "USPS",
"trackingNumber": "95605332216"
},
"orderType": "eCom",
"createDate": "<date>",
"updateDate": "<date>",
"pbCreateDate": "<date>",
"pbUpdateDate": "<date>",
"fromNode": "157",
"shipOnDate": "<date>",
"fulfillmentReleaseDate": "<date>",
"promisedDeliveryDate": "<date>",
"orderHandling": "E",
"orderLines": [ {
"lineId": 1,
"sku": "1642787722",
"originCountryCode": "US",
"originStateProvince": "CT",
"unitPrice": 10.0000,
"hSTariffCode": "HSCode",
"hSTariffCodeCountry": "IND",
"orderedQuantity": 1,
"lineTotal": 50.0000,
"inventoryType": "NEW"
} ],
"orderCharges": {
"orderCurrency": "USD",
"shippingAmount": 10.0000,
"totalItemAmount": 70.0000,
"dutyDetails": [ {
"name": "COUPON1",
"fee": 6.0000,
"currency": "USD",
"percentage": 1.0000
} ],
"totalTaxAmount": 1.0000,
"taxDetails": [ {
"name": "COUPON1",
"fee": 6.0000,
"currency": "USD",
"percentage": 1.0000
} ],
"totalDiscountAmount": 5.0000,
"discountDetails": [ {
"name": "COUPON1",
"fee": 6.0000,
"currency": "USD",
"percentage": 1.0000
} ],
"otherChargeDetails": [ {
"name": "COUPON1",
"fee": 6.0000,
"currency": "USD",
"percentage": 1.0000
} ],
"totalOrderAmount": 90.0000
},
"toAddress": {
"name": "John Smith",
"company": "ABC Co",
"phone": "111-111-1111",
"email": "john@example.com",
"addressLines": [
"Street NW10"
],
"cityTown": "Auburn",
"stateProvince": "AL",
"postalCode": "36830",
"countryCode": "US"
},
"billingAddress": {
"name": "John Smith",
"company": "ABC Co",
"phone": "111-111-1111",
"email": "john@example.com",
"addressLines": [
"Street NW10"
],
"cityTown": "Auburn",
"stateProvince": "AL",
"postalCode": "36830",
"countryCode": "US"
},
"isGift": false,
"status": "RECEIVED",
"isOnHold": false
}, ... ]
}
Sample Request to Return a Subset of Order Data¶
This operation returns a subset of fields in the Orders object.
curl -X POST .../v1/orders/status/search \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
"clientId": "NGST",
"sort": [
"pbCreateDate-desc"
],
"searchFields": [ {
"name": "status",
"values": [ "INPROGRESS" ]
} ]
}'
{
"totalPages": 2,
"totalElements": 38,
"first": true,
"last": false,
"size": 20,
"page": 1,
"sort": [
"pbCreateDate-desc"
],
"orders": [ {
"clientId": "NGST",
"orderId": "OR11A0000274346903867392US",
"customerOrderId": "111-212-1687792",
"clientOrderId": "0.415207155435539",
"brand": "Brand-A",
"status": "INPROGRESS",
"isOnHold": false,
"createDate": "<date>",
"updateDate": "<date>",
"pbCreateDate": "<date>",
"pbUpdateDate": "<date>"
}, ... ]
}
Error Codes¶
For lists of error codes returned by the Fulfillment APIs, please see 80-Prefix Error Codes (Fulfillment APIs).