Find Shipment Details for Fulfilled Orders

HTTP Request

POST /v1/shipments/search

Summary

This operation provides information for fulfilled orders.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/fulfillment/v1/shipments/search
Production: https://shipping-api.pitneybowes.com/shippingservices/fulfillment/v1/shipments/search

Query Parameters

Query parameters are optional.

Name	Description
page	The number of the page to return from the result set. Page numbering starts at 1. Default value: 1
size	The number of fulfilled 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

Required fields are marked Required. All other fields are optional.

Name	Data Type	Description
clientId	String	Required. The client identifier assigned by Pitney Bowes.
sort	Array[String]	Determines the sort order for the ship date. By default, the API returns the earliest ship date first. You can choose to return the most recent shipment first. Possible values: shipppedDate-asc: Returns earliest ship date first. This is the default. shipppedDate-desc: Returns most recent ship date first.
searchFields	Array[Object]	Defines search criteria. Each object in the array defines a search field and search values. The object takes the following elements: name: Required. The name of the search field, entered as a String. Possible values: orderIds shipmentIds shippedDate brands values: Required when name is set to orderIds or shipmentIds. This field takes a String array. Enter the values to search for as separate Strings in the array. To search for orders that have no order ID (i.e., that predate the REST APIs), enter the legacy API’s shipment ID as the value for orderIds. from: Applies only when name is set to shippedDate. Enter the start of the date range, as a String. to: Applies only when name is set to shippedDate. Enter the end of the date range, as a String. If no date filter is specified, the API returns orders created in the last six months.

Response Elements

Name	Data Type	Description
totalPages	Number	The number of pages in the result set.
totalElements	Number	The number of shipments 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 shipments per page in the result set.
page	Number	The page number to return. Page numbering starts at 1.
sort	Array[String]	The sort order.
shipments	Array[Shipments Object]	The shipments. Each object in the array is a separate shipment.

Shipments Object (Fulfilled Orders)

The shipments array returns the Shipments Object:

Name	Data Type	Description
clientId	String	The client ID assigned by Pitney Bowes.
clientOrderId	String	The order ID assigned by the client. This has a 1:1 relationship with the Pitney Bowes order ID (orderId).
orderId	String	The order ID assigned by Pitney Bowes.
customerOrderId	String	The customer order ID assigned by the client. This ID can be assigned to multiple different shipments (i.e., multiple different Pitney Bowes order IDs).
brand	String	The manufacturer’s brand name for the item.
references	Array[Object]	Additional reference information for the shipment. Each object in the array is a name-value pair that defines a reference field and value.
references.name	String	The name of the reference field, up to 50 characters.
references.values	String	The value, up to 255 characters
shipmentId	String	An identifier for the shipment.
additionalId	String	An identifier for the container.
shippingDetails	Shipping Details Object	The carrier details for the shipment.
shippedDate	String	The date the shipment was shipped.
estimatedDeliveryDate	String	The date the shipment is expected to be delivered.
toAddress	Address Object	The shipment’s destination address.
fromNode	String	The warehouse facility ID.
parcel	Object	The parcel’s weight and dimensions.
parcel.Weight	Weight Object	The parcel’s weight.
parcel.dimensions	Dimensions Object	The parcel’s dimensions.
billableWeight	Object	The billed weight for the shipment.
billableWeight.Weight	Weight Object	The billed weight.
billableWeight.dimensions	Dimensions Object	The billed dimensions.
shipmentCostCharges	Shipment Cost Charges Object	The carrier and service. (In the future, this object will also return shipment charges.)
shipmentLines	Array[Shipment Lines Object]	The content of the shipment.

Shipping Details Object (Fulfilled Orders)

Name	Data Type	Description
carrier	String	Required. The name of the carrier. Maximum length: 30 characters
serviceId	String	Required. The ID of the carrier service. Maximum length: 30 characters
serviceName	String	Reserved for future use - The name of the carrier service. Maximum length: 30 characters
trackingNumber	String	Reserved for future use - The assigned tracking number. Maximum length: 40 characters

Address Object (Fulfilled Orders)

Name	Data Type	Description
addressLines	Array[String]	Street address or P.O. Box. Include apartment number if applicable. You can specify up to 3 address lines. Maximum: 100 characters
cityTown	String	The city or town. Maximum: 50 characters
stateProvince	String	The state or province. Maximum: 50 characters
postalCode	String	The postal code or ZIP code. Maximum: 20 characters
countryCode	String	The ISO-2 country code. Maximum: 2 characters
company	String	The name of the company. Maximum: 50 characters
name	String	The first and last name. Maximum: 100 characters
phone	String	The phone number. Enter the digits with or without spaces or hyphens. Maximum: 25 characters
email	String	The email address. Maximum: 70 characters

Weight Object (Fulfilled Orders)

Name	Data Type	Description
weight	Number	The weight.
unitOfMeasurement	String	The unit of measurement for the specified weight. Possible value: LB: Pounds

Dimensions Object (Fulfilled Orders)

Name	Data Type	Description
length	Number, up to 4 decimal places	The parcel’s longest dimension.
height	Number, up to 4 decimal places	The parcel’s second longest dimension.
width	Number, up to 4 decimal places	The parcel’s shortest dimension.
dimensionUOM	String	The unit of measurement. Valid value: IN This field is not used if the unitOfMeasurement field is used.
unitOfMeasurement	String	The unit of measurement. Valid value: IN This field is not used if the dimensionUOM field is used.

Shipment Cost Charges Object (Fulfilled Orders)

The shipments.shipmentCostCharges object in the response comprises the following fields:

Name	Data Type	Description
carrier	String	The name of the carrier.
serviceId	String	The ID of the carrier service.

Note The following fields are reserved for future use:

specialServices	Array[String]	The special services applied to the shipment.
dimensionalWeight	Weight Object	The parcel’s weight.
deliveryCommitment	Object	The estimated date and time of delivery.
estimatedDeliveryDate	String	The estimated date and time of delivery.
baseCharge	Number	The base charge.
currencyCode	String	The ISO currency code. For example: USD, CAD, EUR
totalCarrierCharge	Number	The total carrier charge.
surcharges	Array[Object]	Additional fees or surcharges for the shipment.
name	String	The type of surcharge.
fee	Number	The amount of the surcharge.
totalTaxAmount	Number	The total tax amount.
totalDutyAmount	Number	The total duty amount.

Shipment Lines Object (Fulfilled Orders)

The shipments.shipmentLines array contains the Shipment Lines object, described here:

Name	Data Type	Description
orderLineId	Number	The line ID assigned by Pitney Bowes.
lineId	Number	The line ID assigned by the client.
sku	String	The SKU used to track the item in the warehouse.
alternateSku	String	An alternate SKU, if applicable.
inventoryType	Sting	The type of item inventory. Possible values: NEW REFURBISHED (Reserved for future use)
shippedQuantity	Number	The quantity of items shipped.
lotDetails	Array[Object]	The lot number and quantity, if applicable.
lotDetails.lotNumber	String	The item lot number.
lotDetails.quantity	Number	The quantity used from the lot.
serialNumbers	Array[String]	The serial numbers of the items shipped.

Sample Request

curl -X POST ".../v1/shipments/search" \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "clientId": "1234",
    "sort": [
        "shippedDate-asc"
    ],
    "searchFields": [ {
        "name": "brands",
        "values": [
            "Acme"
        ]
    },{
        "name": "shippedDate",
        "from": "2022-01-10T00:00:00Z",
        "to":  "2022-03-04T00:00:00Z"
    } ]
}'

Sample Response

{
    "totalPages": 1,
    "totalElements": 8,
    "first": true,
    "last": true,
    "size": 20,
    "page": 1,
    "sort": [
        "shippedDate-asc"
    ],
    "shipments": [ {
        "clientId": "1234",
        "clientOrderId": "900000",
        "orderId": "O10000",
        "customerOrderId": "PO88888",
        "references": [ {
            "name": "ref",
            "value": "123876-54910"
        } ],
        "shipmentId": "S100000",
        "additionalId": "C90001",
        "shippingDetails": {
            "carrier": "USPS",
            "serviceId": "PME",
            "serviceName": "Priority Mail Express",
            "trackingNumber": "T1234567890"
        },
        "shippedDate": "2022-01-09T20:40:12-07:00",
        "estimatedDeliveryDate": "2022-01-11T18:00:00-07:00",
        "toAddress": {
            "name": "Anna Martin",
            "company": "Emporium",
            "phone": "+1 555 111 1111",
            "email": "anna@example.com",
            "addressLines": [
                "625 S Main St"
            ],
            "cityTown": "Greenville",
            "stateProvince": "SC",
            "postalCode": "29601",
            "countryCode": "US"
        },
        "fromNode": "160",
        "parcel": {
            "Weight": {
                "Weight": 2.0000,
                "unitOfMeasurement": "Lb"
            },
            "dimensions": {
                "length": 10.0000,
                "height": 5.0000,
                "width": 3.0000,
                "unitOfMeasurement": "In"
            }
        },
        "billableWeight": {
            "Weight": {
                "Weight": 1.5000,
                "unitOfMeasurement": "Lb"
            },
            "dimensions": {
                "length": 25.0000,
                "height": 25.0000,
                "width": 10.0000,
                "unitOfMeasurement": "In"
            }
        },
        "shipmentCostCharges": {
            "carrier": "USPS1",
            "serviceId": "PME1"
        },
        "shipmentLines": [ {
            "orderLineId": 1,
            "lineId": 1,
            "sku": "SKU100200",
            "alternateSku": "UPC99",
            "inventoryType": "New",
            "shippedQuantity": 2,
            "lotDetails": [ {
                "lotNumber": "L100",
                "quantity": 1
            },{
                "lotNumber": "L110",
                "quantity": 1
            } ],
            "serialNumbers": [
                "SN90000",
                "SN90001"
            ]
        },
        ...
        ]
    },
    ...
    ]
}

Error Codes

For lists of error codes returned by the Fulfillment APIs, please see 80-Prefix Error Codes (Fulfillment APIs).

 
 
 
 

• next
• previous |

© Copyright 2024 Pitney Bowes Inc. All rights reserved.