Find an ASN¶

HTTP Requests¶

Return all ASN Data¶

POST /v1/receiving-asn/search

Return a Subset of ASN Data¶

POST /v1/receiving-asn/status/search

Summary¶

Use this operation to find ASNs (Advanced Shipment Notifications) based on your search criteria. The operation provides two HTTP requests. The Return all ASN Data request returns all the relevant fields in the ASN object for each result. The Return a Subset of ASN Data request returns a smaller payload focused on current status.

Request URLs¶

Return all ASN Data¶

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

Return a Subset of ASN Data¶

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/fulfillment/v1/receiving-asn/status/search
Production: https://shipping-api.pitneybowes.com/shippingservices/fulfillment/v1/receiving-asn/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 results 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]

Defines a property upon which to sort and defines the sort order. Use the following syntax:

<property>-<sort_direction>

Where <property> is one of the following:

createDate
updateDate
pbCreateDate
pbUpdateDate
pbDeliveredDate

And <sort_direction> is either of the following:

asc: ascending
desc: descending

For example: "pbCreateDate-asc"

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 value:
- createDate
- updateDate
- receivingAsnIds
- clientAsnIds
- status
- receivingNodes
- pbCreateDate
- pbUpdateDate
- pbDeliveredDate
- brands
- skus
- hasVariance - accept true or false
- purchaseOrderNumbers
values. Required when name is set to receivingAsnIds, clientAsnIds, status, or receivingNodes. This field takes a String array. Enter the values to search for as separate Strings in the array.
from. Applies when name is set to createDate, updateDate, pbCreateDate, pbUpdateDate, or pbDeliveredDate. Enter the beginning of the date range, as a String.
to. Applies when name is set to createDate, updateDate, pbCreateDate, pbUpdateDate, or pbDeliveredDate. 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 ASNs 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 ASNs per page in the result set.
page	Number	The page number to return. Page numbering starts at 1.
sort	Array[String]	The sort order.
asnList	Array[ASN Object]	The ASNs. Each object in the array is a separate ASN.
asnStatusList	Array[ASN Object]	The ASNs. Each object in the array is a separate ASN.

ASN Object¶

The asnStatusList array returns the ASN object. Depending on which HTTP request you use, the array returns all fields in the ASN object or a subset of those fields.

Name	Data Type	Description
clientId	String	The client ID assigned by Pitney Bowes.
brand	String	The manufacturer’s brand name for the item, up to 30 characters.
inboundType	String	The type of inbound shipment. Possible values: `PO`: Purchase Order `ASN`: Advanced Shipment Notification
clientASNId	String	A unique order ID assigned by the client, up to 35 characters.
purchaseOrderNumber	String	The purchase order number, up to 35 characters.
invoiceNumber	String	Reserved for future use.
receivingNode	String	The ID of the facility that will receive the incoming shipment.
vendorDetails	Object	The vendor.
vendorDetails.name	String	The name of the vendor, up to 50 characters.
vendorDetails.code	String	The unique code assigned to the vendor.
receivingASNId	String	The ASN ID assigned by Pitney Bowes.
status	String	The status of the ASN. Possible values: `CREATED` `INPROGRESS` `UPDATED` `ARRIVED` `COMPLETE` `CANCELED`
shippingDetails	Object	The carrier details for the shipment.
shippingDetails.carrier	String	The name of the carrier, up to 30 characters.
shippingDetails.serviceId	String	The ID of the carrier service, up to 30 characters.
shippingDetails.serviceName	String	Reserved for future use - The name of the carrier service, up to 30 characters.
shippingDetails.trackingNumber	String	Reserved for future use - The assigned tracking number, up to 40 characters.
createDate	String	The date and time the ASN was ordered, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
updateDate	String	The date and time the ASN was updated, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
estimatedDeliveryDate	String	The date and time the shipment is expected to be delivered to Pitney Bowes, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
receivedDate	String	The date and time the ASN was received, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
pbCreateDate	String	The date and time the ASN was created in the Pitney Bowes system, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
pbUpdateDate	String	The date and time the ASN was updated in the Pitney Bowes system, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
pbDeliveredDate	String	The date and time the ASN was delivered to Pitney Bowes, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
totalWeight	Object	The weight of the shipment.
totalWeight.weight	Number	The weight.
totalWeight.unitOfMeasurement	String	The weight’s unit of measurement. Possible value: `LB`: Pounds
totalVolume	Object	The volume of the shipment.
totalVolume.volume	String	The volume.
totalVolume.unitOfMeasurement	String	The volume’s unit of measurement. Possible values: `CubicInches` `CubicFeet` `CubicCentimeters` `CubicMeter`
fromAddress	Address Object	The address of the shipper.
toAddress	Address Object	The address of the facility where the shipment will be received.
billingAddress	Address Object	Reserved for future use.
additionalReferences	Array[Object]	Defines customer reference information for the ASN. Each object in the array is a name-value pair with the following fields: `name`: A String value that defines the reference the field, up to 50 characters. `value`: A String value that defines the reference value, up to 255 characters.
asnLines	Array[ASN Lines Object]	The line-level details of the ASN.
name	String	The name of the ASN, up to 100 characters.
pallets	Integer	The number of pallets.
cartons	Integer	The number of cartons.

Sample Requests¶

See the following examples:

Sample Request to Return all ASN Data
Sample Request to Return a Subset of ASN Data

Sample Request to Return all ASN Data¶

This operation returns the full ASN object.

Sample Request¶

curl -X POST ".../v1/receiving-asn/search" \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "clientId": "1234",
    "sort": [
        "pbCreateDate-asc"
    ],
    "searchFields": [ {
        "name": "status",
        "values": [
            "UPDATED"
        ]
    },
    ...
    ]
}'

Sample Response¶

{
    "totalPages": 1,
    "totalElements": 2,
    "first": true,
    "last": true,
    "size": 2,
    "page": 1,
    "sort": [
        "pbCreateDate-desc"
    ],
    "asnList": [ {
        "clientId": "1234",
        "inboundType": "ASN",
        "clientASNId": "ORASN123-2112-11232",
        "purchaseOrderNumber": "Not Applicable",
        "receivingASNId": "ASN156A0029204893659052712,",
        "status": "CANCELLED",
        "receivingNode": "160",
        "vendorDetails": {
            "name": "Vendor ABC",
            "code": "VENDOR-121"
        },
        "shippingDetails": {
            "carrier": "UPS",
            "serviceId": "UPSG"
        },
        "createDate": "2022-04-06T20:01:39Z",
        "updateDate": null,
        "estimatedDeliveryDate": "2022-04-23T00:00:00Z",
        "pbCreateDate": "2022-04-07T14:09:21Z",
        "pbUpdateDate": null,
        "pbDeliveredDate": null,
        "toAddress": {
            "name": "Pitney Bowes Facility",
            "email": "pb@example.com",
            "addressLines": [
                "1200 WORLDWIDE BLVD"
            ],
            "cityTown": "Hebron",
            "stateProvince": "KY",
            "postalCode": "41048",
            "countryCode": "US"
        },
        "notes": "Note 1",
        "additionalReferences": [ {
            "name": "REFERENCE-1",
            "value": "Ref1"
        } ],
        "asnLines": [ {
            "lineId": 100,
            "purchaseOrderNumberLineId": 100,
            "PBlineId": 1,
            "sku": "PRODUCT-SKU-001",
            "inventoryType": "NEW",
            "originCountryCode": "US",
            "expectedQuantity": 100,
            "unitOfMeasurement": "EACH",
            "estimatedDeliveryDate": "2022-04-06T20:01:39Z",
            "costDetails": {
                "retailPrice": 15,
                "wholeSalePrice": 10,
                "unitCost": 15,
                "currency": "USD"
            }
        },
        ...
        ]
    },
    ...
    ],
    "name": "<manifest-name>",
    "carton": 2,
    "pallets": 3
}

Sample Request to Return a Subset of ASN Data¶

This operation returns a subset of fields in the ASN object.

Example Request¶

curl -X POST ".../v1/receiving-asn/status/search" \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "clientId": "1234",
    "sort": [
      "pbCreateDate-desc"
    ],
    "searchFields": [ {
        "name": "receiving-asn",
        "values": [
            "ASN156A0029204893659052712",
            "ASN156A0029204893659061212"
        ],
        "to": "2022-02-06T20:01:39",
        "from": "2022-03-06T20:01:39"
    } ]
}'

Example Response¶

{
    "totalPages": 1,
    "totalElements": 2,
    "first": true,
    "last": true,
    "size": 2,
    "page": 1,
    "sort": [
      "pbCreateDate-desc"
    ],
    "asnStatusList": [ {
        "clientId": "1234",
        "inboundType": "ASN",
        "clientASNId": "ORASN123-2112-11232",
        "purchaseOrderNumber": "Not Applicable",
        "receivingASNId": "ASN156A0029204893659052712,",
        "status": "CANCELLED",
        "receivingNode": "FACILITY-1",
        "vendorDetails": {
            "name": "Vendor ABC",
            "code": "VENDOR-121"
        },
        "createDate": "2022-02-06T20:01:39Z",
        "updateDate": null,
        "estimatedDeliveryDate": "2022-02-11T00:00:00Z",
        "pbCreateDate": "2022-02-07T14:09:21Z",
        "pbUpdateDate": null,
        "pbDeliveredDate": null
    },
    ...
    ]
}

Error Codes¶

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