Create a PB Delivery Manifest (Closeout)

HTTP Request

POST /v1/manifests

Summary

This operation closes out the day by electronically notifying Pitney Bowes how many PB Delivery 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 or print a container label. To print a container label, which is required by PB Delivery, see the Create Container Label API. Note that to print PB Delivery labels, the merchant must be onboarded with PB Delivery.

Considerations

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

  2. You can optionally close out only those parcels corresponding to specific facilities by including the CARRIER_FACILITY_ID_<#> parameter in the parameters array. Each instance of this parameter specifies the ID of a PB facility for which to close out all corresponding shipments. You can specify up to five facilities. Each facility requires a separate object in the parameters array. Replace <#> in the parameter name with an integer from 1 to 5. Start with CARRIER_FACILITY_ID_1 and increment by 1 up to CARRIER_FACILITY_ID_5. For example:

    "parameters": [ {
        "name": "CARRIER_FACILITY_ID_1",
        "value": "1585"
    },{
        "name": "CARRIER_FACILITY_ID_2",
        "value": "1234"
    },{
        "name": "CARRIER_FACILITY_ID_3",
        "value": "6789"
    }, ... ]
    

    Important: To close out shipments associated with more than 5 facilities, issue the API call again.

    If you use just one instance of this parameter, specify the parameter as CARRIER_FACILITY_ID_1.

    If this parameter is not specified, all shipments for all facilities are closed out.

    To test this parameter in the Sandbox environment, include just one instance of this parameter and set it to 1585.

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

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

  5. You cannot reprint or retry a PB Delivery manifest.

Request URLs

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

PB Delivery provides APAC Services for requests that originate in the Asia-Pacific Region. If you use APAC Services to create a PB Delivery 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 Delivery 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

Required fields are marked Required. All other fields are optional, except fields marked RESPONSE ONLY, which appear only in the response.

Name

Data Type

Description

carrier

String

Required. Set this to: PBCS

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.

parcelTrackingNumbers

Array[String]

Identifies shipments by their tracking numbers. Use the long version of the tracking number. List one or more tracking numbers, separated by commas. Enter each tracking number as a separate String.

parameters

Array[Object]

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

You must include the following parameters:

  • SHIPPER_ID: The merchant’s Pitney Bowes Shipper ID.

  • CLIENT_ID: The merchant’s unique PB Delivery client ID, which was assigned when the merchant onboarded with PB Delivery. If testing the Manifest API in Sandbox, set this to NGST.

You can optionally include the following:

  • CARRIER_FACILITY_ID_<#>, where <#> is an integer from 1 to 5. To use this parameter, see the explanation in the Considerations above.

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.

Sample Requests

See the following sample manifest requests:

PB Delivery 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 Delivery 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.