Create a Pitney Bowes Manifest

HTTP Request

POST /v1/manifests

Summary

This operation manifests trackable shipments for either PB Expedited or PB Standard.

For PB Expedited, this operation creates a USPS^® SCAN form (Shipment Confirmation Acceptance Notice) that combines all trackable shipments into a single form with a single bar code. When the carrier scans the barcode, all shipments for that barcode receive an Acceptance event from USPS. If the SCAN form includes shipments from multiple different induction postal codes, this operation generates a multi-page form with one bar code per page.

For PB Standard, this operation closes out the day by electronically notifying Pitney Bowes how many parcels await. By default, this operation closes out all parcels generated since the previous closeout. You can optionally specify which parcels to close out using their tracking numbers. This operation does not generate a pickup slip nor print a container label. To print a container label, which is required by PB Standard Delivery, see the Create Container Label API. Note that to print PB Standard Delivery labels, the merchant must be onboarded with PB Standard.

Before writing your API call, see the PB Expedited Considerations and PB Standard Considerations.

Considerations for a PB Expedited SCAN Form

The following considerations apply to PB Expedited SCAN forms:

1. PB Expedited (USPS) Delivery shipments with the ADD_TO_MANIFEST shipment option set to true are eligible for inclusion in a SCAN form.

2. To create a SCAN form for the current day, you must issue the Create Manifest request before 8 p.m. local time. If you issue the Create Manifest request after 8 p.m., you must assign the next day’s date in the submissionDate field. For more information, see What are the cutoff times for USPS shipments and manifests?

3. If an eligible shipment is not included in a SCAN form by 6 a.m. UTC/GMT the next calendar day, it is instead auto-manifested. Shipments, once manifested, cannot be re-manifested.

   Note: To prevent a shipment from being auto-manifested, set the shipment’s FUTURE_SHIPMENT_DATE option when creating the shipment. For details, see Can I choose to manifest a shipment at a later date?

4. Up to 7000 shipments can be included in a single Create Manifest request.

5. You can add shipments to the SCAN form by specifying Shipper ID, tracking numbers, or both:

   • If you specify Shipper ID, the form will include all eligible shipments created with that Shipper ID. To specify Shipper ID, add the SHIPPER_ID parameter to the parameters array.

   • If you specify tracking numbers, the form will include all eligible shipments with those tracking numbers. To specify tracking numbers, use the parcelTrackingNumbers array.

   Note: If you specify both Shipper ID and tracking numbers, ensure the tracking numbers belong to the Shipper ID or the API will return an error.

6. You can filter further by specifying an inductionPostalCode. When specified, the inductionPostalCode value in the manifest request must match the rates.inductionPostalCode value of the shipment. If a shipment has no rates.inductionPostalCode, the value in the manifest request must match the shipment’s fromAddress.postalCode.

   If you specify an inductionPostalCode in the manifest request, only shipments that meet the above criteria are included in the manifest.

7. If a manifest request contains shipments with different inductionPostalCode values, then a multi-page manifest is created, with one inductionPostalCode value per page. The pages are accessed via a single PDF.

8. The following PB Expedited shipments cannot be added to the SCAN form:

   • First-Class Mail Flats (Service ID: FCM, Parcel Type: FLAT)

   • First-Class Mail Letters (Service ID: FCM, Parcel Type: LETTER)

   • PB Expedited Returns

9. The following address fields are required in the fromAddress object:

   • addressLines

   • postalCode

   • countryCode

10. The MANIFEST_TYPE parameter is not required. It can be either left out or set to NORMAL.

11. USPS SCAN forms retrieved through URLs are available for 24 hours after creation.

Considerations for a PB Standard Manifest (Closeout)

The following considerations apply to PB Standard manifests (closeouts):

1. When issuing the API call, you must set the following:

   Field	Value
   carrier	PBCS (PB Standard)
   submissionDate	The date the shipments are to be tendered to the carrier.
   parameters	You must include the following Manifest Parameters: SHIPPER_ID: The merchant’s Pitney Bowes Shipper ID. CLIENT_ID: The merchant’s unique PB Standard client ID, which was assigned when the merchant onboarded with PB Standard. If testing the Manifest API in Sandbox, set this to NGST.

2. You can optionally close out specific parcels by specifying the parcel tracking numbers in the parcelTrackingNumbers array.

3. You can optionally close out only those parcels corresponding to specific facilities by including the CARRIER_FACILITY_ID_<#> parameter in the parameters array. You can specify up to five facilities. Each requires a separate object in the parameters array.

   If testing the Manifest API in Sandbox, set this to 1585.

4. Manifest requests for PB Standard Delivery do not support filtering by induction postal code.

5. The manifest response does not contain a pickup slip.

6. You cannot reprint or retry a PB Standard Delivery manifest.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/manifests
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/manifests

For PB Standard, Pitney Bowes provides APAC Services for requests that originate in the Asia-Pacific Region. If you use APAC Services to create a PB Standard shipment, then you must use APAC Services to manifest the shipment. Use one of the following URLs. You can use these URLs only if you used APAC Services to create the shipment:

Sandbox URL APAC: https://apac-sandbox.shippingapi.pitneybowes.com/shippingservices/v1/manifests?carrier=Newgistics
Production URL APAC: https://apac.shippingapi.pitneybowes.com/shippingservices/v1/manifests?carrier=Newgistics

Query Parameter

Name	Description
carrier	APAC Services Only. If your PB Standard manifest request originates in the Asia-Pacific Region and if you use the APAC Services URL, you must set the carrier query parameter to Newgistics.

Request Headers

Name	Description
Authorization	Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type	Required. The media type of the request entity. Set this to application/json.
X-PB-TransactionId	Required. A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens (-), and underscores (_). Important: Ensure this is a unique ID.
X-PB-UnifiedErrorStructure	Recommended. Set this to true to use the standard error object if an error occurs.

Request / Response Elements

This POST operation sends and receives the Manifest object, described in the table below. The table describes the Manifest object for all operations that use it. If a field is not used in this POST operation, it is marked as such. Fields required in the request are marked Required. All other fields are optional, except fields marked RESPONSE ONLY, which appear only in the response.

See the PB Expedited Considerations and PB Standard Considerations before invoking this API.

Name	Data Type	Description
carrier	String	Required. The carrier to which the manifest applies. For some operations, this field is not present in the response. Valid values: USPS: PB Expedited or PMOD PBCS: PB Standard PBPresort: PB Presort
submissionDate	String	Required. The date the shipments are to be tendered to the carrier, entered as YYYY-MM-DD.
fromAddress	Address Object	The shipment origin address. Required for: Pitney Bowes Manifest (Expedited Only) PMOD Manifest
inductionPostalCode	String	Postal code where the shipments are tendered to the carrier. Do not use for PB Standard manifests. The field does not apply.
parcelTrackingNumbers	Array[String]	Identifies shipments by their tracking numbers. List one or more tracking numbers, separated by commas. Enter each tracking number as a separate String. If the carrier field is set to PBCS, use the long version of the tracking number.
parameters	Array[Object]	Each object in the array defines a different manifest parameter. This field is used only in the request and is not returned in the response. Required for PB Standard Manifests (Closeouts).
parameters.name	String	The name of the manifest parameter.
parameters.value	String	The value of the manifest parameter.
manifestId	String	RESPONSE ONLY. The unique manifest ID. This field is not returned for APAC Services. This field is not returned for APAC Services.
manifestTrackingNumber	String	RESPONSE ONLY. The manifest tracking number. This is returned only if carrier has a value of USPS.
documents	Array[Documents Object]	RESPONSE ONLY. The manifest. This field is not returned for a PB Standard manifest.

Sample Requests

See the following sample manifest requests:

• PB Expedited SCAN Form by Shipper ID

• PB Expedited SCAN Form by Tracking Numbers

• PB Standard Closeout by Shipper ID

• PB Standard Closeout by Tracking Numbers

PB Expedited SCAN Form by Shipper ID

curl -X POST .../v1/manifests \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "carrier": "USPS",
    "submissionDate": "2021-07-23",
    "fromAddress": {
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "postalCode": "36830-6433",
        "countryCode": "US"
    },
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}'

Sample Response

{
    "carrier": "USPS",
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../scanform/b2f4a1ad0e7046669540562f73da79e8.pdf",
        "type": "MANIFEST"
    } ],
    "fromAddress": {
        "company": "",
        "name": "",
        "residential": false,
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830",
        "countryCode": "US"
    },
    "manifestId": "9475709899581000182251",
    "manifestTrackingNumber": "9475709899581000182251",
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "submissionDate": "2021-07-23"
}

PB Expedited SCAN Form by Tracking Numbers

curl -X POST .../v1/manifests \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "carrier": "USPS",
    "submissionDate": "2021-07-23",
    "fromAddress": {
        "addressLines": [
            "545 Market St"
        ],
        "postalCode": "94105",
        "countryCode": "US"
    },
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "parcelTrackingNumbers": [
        "9405509898641492021204",
        "9405509898641492021150",
        "9405509898641492021211"
    ]
}'

Sample Response

{
    "carrier": "USPS",
    "documents": [ {
        "contentType": "URL",
        "contents": "https://..../scanform/b3368cba764a46f9b368aa0bc9483105.pdf",
        "type": "MANIFEST"
    } ],
    "fromAddress": {
        "company": "",
        "name": "",
        "residential": false,
        "addressLines": [
            "545 Market St"
        ],
        "cityTown": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105",
        "countryCode": "US"
    },
    "manifestId": "9475709899581009777182",
    "manifestTrackingNumber": "9475709899581009777182",
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "parcelTrackingNumbers": [
        "9405509898641492021204",
        "9405509898641492021150",
        "9405509898641492021211"
    ],
    "submissionDate": "2021-07-23"
}

PB Standard Closeout by Shipper ID

Request

curl -X POST .../v1/manifests \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <transaction-id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "carrier": "PBCS",
    "submissionDate": "2021-07-23",
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "NGST"
    } ]
}'

Sample Response

{
    "carrier": "pbcs",
    "manifestId": "NEWGISTICS07231627070957381",
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "NGST"
    } ],
    "submissionDate": "2021-07-23"
}

PB Standard Closeout by Tracking Numbers

Request to Close Out by Tracking Number

curl -X POST .../v1/manifests \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <transaction-id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "carrier": "PBCS",
    "submissionDate": "2021-07-23",
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "NGST"
    } ],
    "parcelTrackingNumbers": [
        "4206740192612123456789000008534003",
        "4206740192612123456789000008524226",
        "4206740192612123456789000008526541"
    ]
}'

Sample Response

{
    "carrier": "pbcs",
    "manifestId": "NEWGISTICS07231627071131109",
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "NGST"
    } ],
    "parcelTrackingNumbers": [
        "4206740192612123456789000008534003",
        "4206740192612123456789000008524226",
        "4206740192612123456789000008526541"
    ],
    "submissionDate": "2021-07-23"
}

Error Codes

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.

 
 
 
 

• next
• previous |

© Copyright 2022, PB.