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

Default value: 1

size

The number of orders to return per page.

Default value: 20

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 (-), and underscores (_).

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:

<property>-<sort_direction>

Where <property> is one of the following:

createDate
updateDate
pbCreateDate
pbUpdateDate

And <sort_direction> is either of the following:

asc: ascending
desc: descending

For example: "createDate-asc"

searchFields

Array[Object]

The search criteria. Each object in the array is a name-value pair with the following two elements:

name: The field in the Orders object upon which to search, entered as a String.
values: The values to search for, entered as an array. The array takes the data type of the field being searched.

You can search on the following Orders-object fields. For possible values, see the field’s definition here.

brand
clientOrderId. To search this field, set “searchFields.name” to “orders”.
createDate
orderId. To search this field, set “searchFields.name” to “orders”.
orderType
pbCreateDate
pbUpdateDate
status
updateDate

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	Shipping Details Object	Required. The carrier details for the order.
orderType	String	The type of order. Possible values: `eCom` (default) `Retail`
createDate	String	Required. The date and time the order was created in the client system, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
updateDate	String	The date and time the order was updated in the client system, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
pbCreateDate	String	RESPONSE ONLY. The date and time the order was created in the Pitney Bowes system, returned in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
pbUpdateDate	String	RESPONSE ONLY. The date and time the order was updated in the Pitney Bowes system, returned in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
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: `YYYY-MM-DDThh:mm:ssZ`
fulfillmentReleaseDate	String	The date and time the order is to be released for fulfillment, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
promisedDeliveryDate	String	The date and time the order is promised to be delivered, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
orderHandling	String	Possible value: `X`: Normal (default) `R`: Rush order (Reserved for future use) `E`: Emergency order (Reserved for future use)
orderLines	Array[Order Lines Object]	Required. The items included in the order.
orderCharges	Order Charges Object	Cost details.
toAddress	Address Object	Required. The order’s destination address.
billingAddress	Address Object	The order’s billing address.
isGift	Boolean	If `true`, the order is a gift.
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: `BACKORDER` `CANCELED` `HOLD` `INPROGRESS` `ONHOLD` `RECEIVED` `RETURNED` `SHIPPED`
isOnHold	Boolean	RESPONSE ONLY. If `true`, the order is on hold.
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
Sample Request to Return a Subset of Order Data

Sample Request to Return all Order Data¶

The request returns the full Orders object.

Example Request¶

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"
        ]
    } ]
}'

Example Response¶

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

Example Request¶

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" ]
    } ]
}'

Example Response¶

{
    "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).