Note

The Fulfillment APIs are coming soon.

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

The POST operation sends an object with the fields described here. 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

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 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 (Fulfillment)]

The shipments. Each object in the array is a separate shipment.

Shipments Object (Fulfillment)

The shipments array in the response contains the Shipments object, described here:

Name

Data Type

Description

clientId

String

The client ID assigned by Pitney Bowes.

orderId

String

The order 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).

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[References Object]

Additional reference information for the shipment. Each object in the array is a name-value pair that defines a reference field and value.

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.

Shipment Cost Charges Object (Fulfillment)

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 (Fulfillment)

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": "NGST"
    "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": "NGST",
        "orderId": "O10000",
        "clientOrderId": "900000",
        "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).