Important

For Military and US Territory locations, both Pitney Bowes and the USPS require customs documentation. Starting on April 15th, 2024, the API will mandate the inclusion of customs information with each transaction. If a package is submitted for delivery to a military or US Territory location without the necessary customs information, an error will occur. The customs object and the new customs label will be accessible in the sandbox environment for your development and testing purposes starting from April 1st, 2024. This functionality will become available in production on April 15th, 2024. Details regarding the customs object and a sample transaction can be found in the document below.

Create a PB Delivery Label

HTTP Request

POST /v1/shipments

Summary

This operation creates a PB delivery label. The API returns the label as either a Base64 string that converts to a PNG or to ZPL2, or as a URL that links to a PDF. Labels retrieved through URLs are available for 24 hours after label creation.

Switch Between PB Delivery and Expedited

You can write one API call to use for both PB Delivery and PB Expedited labels and change the field values as needed. For an example of one API call written for both labels, see Write One Request for PB Expedited and PB Standard.

Address Validation

Pitney Bowes verifies addresses for accuracy against current USPS® data and makes corrections to delivery lines and last lines when possible. You can optionally limit the extent of corrections by enabling minimal address validation through the MINIMAL_ADDRESS_VALIDATION shipment option in the shipmentOptions array. For a comparison of complete and minimal address validation, see What is minimal address validation?

Important

If you enable minimal address validation, the shipper takes 100% responsibility for any undelivered packages due to violation of carrier-addressing guidelines and is responsible for any surcharge or adjustment fee levied by the carrier for such a violation.

Error Handling

If your request returns the HTTP 500 Internal Server Error, see these troubleshooting steps.

For other errors, do not resubmit the request without first checking whether the label was created. To check whether the label was created, issue the Retry Shipment API.

Considerations

  1. For an overview of PB Delivery services and operations, see the Pitney Bowes reference page.

  2. To print PB Delivery labels, a merchant must first onboard with PB Delivery. During onboarding, Pitney Bowes provides the merchant with a set of PB Delivery IDs.

    When testing in Sandbox, use the Sandbox values listed for shipmentOptions in the Request Elements table.

  3. A PB Delivery label is a domestic, post-paid label with a USPS-compliant barcode. The label incurs no charges at time of print. A sample label is shown below.

  4. PB Delivery labels are supported for domestic shipments only.

  5. To subscribe a PB Delivery shipment to notifications, include the NOTIFICATIONS special service in the request. The merchant must be configured for PB Delivery notifications. See PB Delivery Notifications below on this page.

  6. Containers Requirement: When shipping with PB Delivery, shippers must containerize parcels. Shippers can print container labels through either the Container API or Merchant Portal.

  7. Automatically Eligible for Close Out: When you create a PB Delivery shipment, the shipment is automatically eligible for manifesting (close out). To close out the day, see Create a PB Delivery Manifest (Closeout).

  8. Shipping to APO/FPO/DPO and US Territories: When creating a shipping label to military locations and certain domestic locations it is important to include customs information in the transaction. Hazardous Material cannot be shipped with PB Delivery to military locations and US Territories.

Important

As of March 31st, 2024; PB Deliveries that are bound for either Military APO/FPO/DPO addresses or US Territories require a printed customs label. To print this label it necessary to include customs information in the transacation. Detailed below is the customs object with required fields and a sample transaction to military location.

Request URLs

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

Request URLs for APAC Services

For PB Deliveries , Pitney Bowes provides APAC Services for requests that originate in the Asia-Pacific Region. APAC Services use the following Create Shipment URLs. If you use an APAC URL to create a shipment, you must also use an APAC URL if you manifest or void the shipment.

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

Query Parameter

Name

Description

carrier

APAC Services Only. If your PB Delivery request originates in the Asia-Pacific Region and if you use the APAC Services, 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.

Accept-Language

Language and country code. Default: en-US

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 Elements

Name

Data Type

Description

fromAddress

Address Object

Required. The origin address. The fromAddress object requires the following fields:

  • addressLines

  • postalCode

  • countryCode

  • name

  • residential: Required only for APAC Services

toAddress

Address Object

Required. The destination address. The toAddress object requires the following fields:

  • addressLines

  • postalCode

  • countryCode

  • name

  • residential: Required only for APAC Services

parcel

Parcel Object

Required. The parcel’s weight and dimensions. Enter the correct dimensions to ensure on-time delivery.

Important: Incorrect dimensions might lead to an undeliverable parcel or an additional postage fee.

rates

Array[Rates Object]

Required. Specifies the carrier, service, and parcel type. The array takes one rates object. Set the following fields and values:

documents

Array[Documents Object]

Required. Defines the label. The array takes one documents object. Set the following:

  • type: Set to SHIPPING_LABEL.

  • size, fileFormat, and contentType: For valid combinations, see PB Delivery Labels.

customs

Object [Customs Object for PB Delivery]

Customs clearance information. This is required for shipments to APO/FPO/DPO locations and to US Territories.

shipmentOptions

Array[Object]

Required. Each object in this array defines a shipment option. Each object takes the following two fields, which take string values:

The following options are required or commonly used:

  • SHIPPER_ID: Required. Set this to the merchant’s Shipper ID.

  • CLIENT_FACILITY_ID: Required. The ID assigned to the merchant’s facility during onboarding with PB Delivery. If testing this API on Sandbox, set this to 0093.

  • CARRIER_FACILITY_ID: Required. The ID of the PB Delivery facility assigned to the merchant during onboarding with PB Delivery. If testing this API on Sandbox, set this to 1585.

  • IS_RECTANGULAR: Conditional. Required if you set an irregular parcel girth value in the parcel.dimension object. Set the option to false.

  • CLIENT_ID: Optional. The PB Delivery client ID assigned to the merchant during onboarding. If testing on Sandbox, set this to NGST. (Note: This is optional for PB Delivery but required for PB Returns.)

  • NON_DELIVERY_OPTION: Optional. Prints non-delivery instructions. For possible values, click here.

  • PRINT_CUSTOM_MESSAGE_2: Optional. Prints custom information on the label.

    Note

    ADD_TO_MANIFEST is not needed for PB Delivery and is ignored if included. All parcels are automatically eligible for close out, and this option is always considered true, even if set to false.

references

Array[Object]

Merchant-defined reference fields in the shipment data. Each object in the array includes a name-value pair that defines a reference field. See PB Delivery References.

Note

To include reference fields on the label, use the PRINT_CUSTOM_MESSAGE_2 shipment option.

hazmatDetails

HAZMAT Details Object

HAZMAT information for a shipment that includes hazardous materials.

Important

The hazmatDetails object were deprecated July 9, 2023, and replaced by the hazmat special service. See HAZMAT-Flagged Items for PB Delivery and PB Returns.

Customs Object for PB Delivery

Important

The customs object for PB Delivery will become available in Sandbox on April 1, 2024, and in Production, April 15, 2024.

Name

Data Type

Description

customs.info

Object

Customs clearance information for the commercial invoice. Required if you use the Customs Object.

customs.customsItems

Object

Customs clearance information for each commodity. If the shipment has multiple types of items, create separate customsItems objects for each type. The array takes a maximum of 30 objects. When more than 4 customs items are included multiple labels will be returned. Required if you use the customs object.

Customs Info Object for PB Delivery

Name

Data Type

Description

currencyCode

String

Required. The type of currency used for the monetary values in this API request. Use three uppercase letters, per ISO 4217. For example, use USD for US Dollars.

reasonForExport

String

Required. This field should set to MERCHANDISE for PB Delivery.

Customs Items Object for PB Delivery

If the shipment has multiple types of items, create separate customsItems objects for each. The array takes a maximum of 30 objects

Name

Data Type

Description

description

String

Required. A description of the commodity. The description will appear on the customs form. If the shipment has multiple types of items, create a separate customsItems object for each. Each description will appear on the form.

hSTariffCode

String

Required. The destination country’s tariff-classification number (HS code) for the commodity. Most countries use the six-digit Harmonized System (HS) as the basis for their tariff classifications and then add digits for more detail. The maximum length for an HS code is 14 characters. The HS code will appear on the customs form. If the shipment has multiple types of items, create a separate customsItems object for each.

Note

The hSTariffCode should contain a minimum of 6 numerical digits.

originCountryCode

String

Required. The two-character ISO country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values.

quantity

Integer

Required. Enter the total number of items of this type of commodity. The number of items cannot exceed 9999. USPS limits the number of items of one commodity to 9999.

unitPrice

BigDecimal

Required. The price of one item of this type of commodity.

unitWeight

Object

Required. The weight and unit of measure of one item of the commodity.

unitWeight.weight

Number

Required. The weight of the item. This field is required by the unitWeight object.

unitWeight.unitOfMeasurement

String

Required. The unit of measurement. This field is required by the unitWeight object. Set this to OZ.

PB Delivery Notifications

PB Delivery can provide email and text notifications when a shipment is in transit or delivered. To configure a merchant account to receive notifications, contact your PB Delivery implementation team or account manager. Once configured, a merchant can subscribe a shipment to notifications by adding the NOTIFICATIONS special service in the rates.specialServices array. The NOTIFICATIONS special service takes the following input parameters:

Parameter

Value

RECIPIENT_NOTIFICATION_TYPE

Required. The event for which to receive notifications. Set this to either of the following:

  • ON_INTRANSIT

  • ON_DELIVER

RECIPIENT_NOTIFICATION_EMAIL

Required. Enables email notification. Set this to the email address to receive notifications. You must use the same email address for all events. PB Delivery accepts only one email address for all notifications.

RECIPIENT_NOTIFICATION_PHONE

Enables text notification. Enter the phone number as a string of continuous numbers, without spaces or punctuation. For example: 1234567890

For example:

{
    "specialServiceId": "NOTIFICATIONS",
    "inputParameters": [ {
        "name": "RECIPIENT_NOTIFICATION_TYPE",
        "value": "ON_DELIVER"
    },{
        "name": "RECIPIENT_NOTIFICATION_EMAIL",
        "value": "widgets@example.com"
    },{
        "name": "RECIPIENT_NOTIFICATION_PHONE",
        "value": "8085551234"
    } ]
}

PB Delivery References

In a PB Delivery shipment, the references array allows merchants to include reference fields in the shipment data. The information entered will appear in manifest files and invoices.

The references array takes up to three objects, each of which maps to a specific field in the PB Delivery data. The first object maps to the PB Delivery “ReferenceNumber” field; the second to the “AddlRef1” field; and the third to the “AddlRef2” field. For each object you include, enter the name string as shown below. If you enter a different string, the system will change it. For each value field, enter a string of up to 50 characters. The following shows the reference field with the maximum three objects:

{
    "name": "ReferenceNumber",
    "value": "<shipper-generated value>"
},{
    "name": "AddlRef1",
    "value": "<shipper-generated value>"
},{
    "name": "AddlRef2",
    "value": "<shipper-generated value>"
}

The values entered in the references array will not appear on shipping labels. To print reference fields on shipping labels, set the PRINT_CUSTOM_MESSAGE_2 shipment option in the shipmentOptions array.

PB Delivery HAZMAT Details

Important

The hazmatDetails object was deprecated on July 9, 2023, and replaced by the hazmat special service. For details, see HAZMAT-Flagged Items for PB Delivery and PB Returns. You cannot use the hazmat or hazmat-electronics special services when shipping to or from Alaska, Hawaii, Puerto Rico, or APO/FPO/DPO destinations.

Response Elements

Name

Data Type

Description

fromAddress

Address Object

The origin address.

toAddress

Address Object

The destination address.

parcel

Parcel Object

The parcel’s weight and dimensions

rates

Array[Rates Object]

The carrier, service, parcel type, and service charges.

customs

Object[Customs Object for PB Delivery]

Customs clearance information.

documents

Array[Documents Object]

Returns the label as a URL or Base64 string.

shipmentOptions

Array[Object]

Each object in the array defines a shipment option.

references

Array[Object]

Each object in the array defines a reference field.

shipmentId

String

The unique identifier for the shipment generated by the system.

parcelTrackingNumber

String

The tracking number assigned to the shipment.

Sample Requests

See the following:

Parcel Select Shipment Sample Request

The following sample request prints a PB Delivery Parcel Select label. The request passes facility IDs through the shipmentOptions array and reference fields through the references array:

curl -X POST ".../v1/shipments" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 5a2d2cf4-f2c4-41ba-91e2" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "fromAddress": {
        "company": "Gallery",
        "name": "Dave Miller",
        "residential": false,
        "addressLines": [
            "12174 S Euclid St"
        ],
        "cityTown": "Garden Grove",
        "stateProvince": "CA",
        "postalCode": "92840",
        "countryCode": "US"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Jane Lee",
        "addressLines": [
            "400 S Santa Fe Ave"
        ],
        "cityTown": "Salina",
        "stateProvince": "KS",
        "postalCode": "67401",
        "countryCode": "US"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": "32"
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": "8",
            "width": "4",
            "height": "6"
        }
    },
    "rates": [ {
        "carrier": "PBCS",
        "serviceId": "PRCLSEL",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "DelCon",
            "inputParameters": [ ]
        } ]
    } ],
    "documents": [ {
        "size": "DOC_4X6",
        "fileFormat": "ZPL2",
        "contentType": "BASE64",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
      },{
        "name": "CLIENT_FACILITY_ID",
        "value": "0093"
      },{
        "name": "CARRIER_FACILITY_ID",
        "value": "1585"
      },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "Leave at door."
      }
    ],
    "references": [ {
        "name": "ReferenceNumber",
        "value": "45-67891"
      },{
        "name": "AddlRef1",
        "value": "d576-5432124CC78"
      },{
        "name": "AddlRef2",
        "value": "CC4321"
    } ]
}'
Sample Response
{
    "fromAddress": {
        "company": "Gallery",
        "name": "Dave Miller",
        "residential": false,
        "addressLines": [
            "12174 Euclid St"
        ],
        "cityTown": "Garden Grove",
        "stateProvince": "CA",
        "postalCode": "92840-3304",
        "countryCode": "US",
        "deliveryPoint": "74"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Jane Lee",
        "residential": false,
        "addressLines": [
            "400 S Santa Fe Ave"
        ],
        "cityTown": "Salina",
        "stateProvince": "KS",
        "postalCode": "67401-4144",
        "countryCode": "US",
        "deliveryPoint": "00"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 32.0
        },
        "dimension": {
            "length": 8.0,
            "width": 4.0,
            "height": 6.0,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": 0.0
        }
    },
    "rates": [ {
        "carrier": "PBCS",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "DelCon",
            "inputParameters": [ ]
        } ],
        "serviceId": "PRCLSEL"
    } ],
    "documents": [ {
        "contentType": "BASE64",
        "fileFormat": "ZPL2",
        "pages": [ {
            "contents": "XlhBXkxIMCwxNX5TRDIwXkxSTl5DSTI3Xk..."
        } ],
        "size": "DOC_4X6",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
      },{
        "name": "CLIENT_FACILITY_ID",
        "value": "0093"
      },{
        "name": "CARRIER_FACILITY_ID",
        "value": "1585"
      },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "Leave at door."
      }, {
         "name": "PARCEL_TRACKING_BARCODEVALUE",
         "value": "4206740192612901006014000001025096"
      },{
          "name": "PARCEL_TRACKING_ID",
          "value": "92612901006014000001025096"
      }
    ],
    "references": [ {
        "name": "ReferenceNumber",
        "value": "45-67891"
      },{
        "name": "AddlRef1",
        "value": "d576-5432124CC78"
      },{
        "name": "AddlRef2",
        "value": "CC4321"
    } ],
    "parcelTrackingNumber": "4206740192612901006014000001025096",
    "shipmentId": "NGST2200744454"
}

Parcel Select Shipment APO Sample Request

The following sample requests a PB Delivery Parcel Select label to a military location. The request includes the customs object with the minimum fields required to print the customs document:

  curl --location '.../v1/shipments' \
  --header 'X-PB-TransactionID: sndfdr165698'
  --header 'Authorization: Bearer <oauth_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "fromAddress": {
          "company": "",
          "name": "XOXO SHIPPING INC.",
          "phone": "2035145555",
          "email": "",
          "addressLines": [
              "1000 VIA FORTUNA"
          ],
          "cityTown": "AUSTIN",
          "stateProvince": "TX",
          "postalCode": "78746",
          "countryCode": "US"
      },
      "toAddress": {
          "company": "Test Consumer",
          "name": "Attn. Line",
          "phone": "785-000-0000",
          "email": "test.address@pb.com",
          "residential": true,
          "addressLines": [
              "480 CMR box 1231"
          ],
          "cityTown": "APO",
          "stateProvince": "AE",
          "postalCode": "09128",
          "countryCode": "US"
      },
      "parcel": {
          "weight": {
              "unitOfMeasurement": "OZ",
              "weight": "125.0"
          },
          "dimension": {
              "unitOfMeasurement": "IN",
              "length": "30",
              "width": "25",
              "height": "25"
          }
      },
      "rates": [ {
          "carrier": "PBCS",
          "serviceId": "PRCLSEL",
          "parcelType": "PKG"
         }
      ],
      "documents": [
       {
          "type": "SHIPPING_LABEL",
          "contentType": "BASE64",
          "size": "DOC_4X6",
          "fileFormat": "PNG",
          "printDialogOption": "NO_PRINT_DIALOG"
      }
       ],
       "shipmentOptions": [
       {
          "name": "SHIPPER_ID",
          "value": "<<Shipper ID>>"
       },
       {
          "name": "MINIMAL_ADDRESS_VALIDATION",
          "value": "true"
       },
       {
          "name": "HIDE_TOTAL_CARRIER_CHARGE",
          "value": "true"
       },
       {
          "name": "CLIENT_ID",
          "value": "NGST"
       },
       {
          "name": "PRINT_CUSTOM_MESSAGE_2",
          "value": "PRINT CUSTOM MESSAGE"
       },
       {
          "name": "CLIENT_FACILITY_ID",
          "value": "0093"
       },
       {
          "name": "CARRIER_FACILITY_ID",
          "value": "0921"
       },
       {
          "name": "NON_DELIVERY_OPTION",
          "value": "ChangeServiceRequested"
       },
       {
          "name": "ADD_TO_MANIFEST",
          "value": "true"
       },
       {
          "name": "AUTHORITY_TO_LEAVE",
          "value": "false"
       }
   ],
     "customs": {
          "customsInfo": {
             "currencyCode": "USD",
             "reasonForExport": "MERCHANDISE"
       },
          "customsItems": [
           {
               "description": "Books Plumbing",
               "hSTariffCode": "4901.99.0070",
               "originCountryCode": "US",
               "quantity": 1,
               "unitPrice": 32,
               "unitWeight": {
                   "unitOfMeasurement": "OZ",
                   "weight": 15
               }
           },
           {
               "description": "Books Construction",
               "hSTariffCode": "4901.99.0070",
               "originCountryCode": "US",
               "quantity": 1,
               "unitPrice": 32,
               "unitWeight": {
                   "unitOfMeasurement": "OZ",
                   "weight": 15
               }
           },
           {
               "description": "Books Electronics",
               "hSTariffCode": "4901.99.0070",
               "originCountryCode": "US",
               "quantity": 1,
               "unitPrice": 32,
               "unitWeight": {
                   "unitOfMeasurement": "OZ",
                   "weight": 15
               }
           },
       {
              "description": "Books Bicycles",
              "hSTariffCode": "4901.99.0070",
              "originCountryCode": "US",
              "quantity": 1,
              "unitPrice": 32,
              "unitWeight": {
              "unitOfMeasurement": "OZ",
              "weight": 15
     }
    }
  ]
 }
}'
Sample Response
{
    "fromAddress": {
        "company": "",
        "name": "XOXO SHIPPING INC.",
        "phone": "2035145555",
        "email": "",
        “addressLines”: [
            “1000 VIA FORTUNA”
        ],
        "cityTown": "AUSTIN",
        "stateProvince": "TX",
        "postalCode": "78746",
        "countryCode": "US",
        "deliveryPoint": "99"
    },
    "toAddress": {
        "company": "Test Consumer",
        "name": "Attn. Line",
        "phone": "785-000-0000",
        "email": "test.address@pb.com",
        "residential": true,
        "addressLines": [
            "480 CMR box 1231"
        ],
        "cityTown": "APO",
        "stateProvince": "AE",
        "postalCode": "09128-1013",
        "countryCode": "US",
        "deliveryPoint": "31"
        },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 125.0
        },
        "dimension": {
            "length": 30.0,
            "width": 25.0,
            "height": 25.0,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": 0.0
        }
    },
    "rates": [
     {
        "carrier": "pbcs",
        "parcelType": "PKG",
        "specialServices": [],
            "specialServiceId": "PRCLSEL",
            "serviceId": "PRCLSEL"
    }
    ],
    "documents": [ {
        "contentType": "BASE64",
        "fileFormat": "ZPL2",
        "pages": [ {
            "contents": ""<<BASE64 ZPL2 Response>>"
        }
        ],
        "size": "DOC_4X6",
        "type": "SHIPPING_LABEL"
    }
    ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "3001829203"
      },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "true"
      },{
        "name": "HIDE_TOTAL_CARRIER_CHARGE",
        "value": "true"
      },{
        "name": "CLIENT_ID",
        "value": "NGST."
      }, {
         "name": "PRINT_CUSTOM_MESSAGE_2",
         "value": "PRINT CUSTOM MESSAGE"
         },
     {
         "name": "CLIENT_FACILITY_ID",
         "value": "0093"
     },
     {
         "name": "CARRIER_FACILITY_ID",
         "value": "0921"
     },
     {
         "name": "NON_DELIVERY_OPTION",
         "value": "ChangeServiceRequested"
     },
     {
         "name": "ADD_TO_MANIFEST",
         "value": "true"
     },
     {
         "name": "AUTHORITY_TO_LEAVE",
         "value": "false"
     },
     {
         "name": "PARCEL_TRACKING_BARCODEVALUE",
         "value": "4200912892612901006014000013743278"
     },
     {
         "name": "PARCEL_TRACKING_ID",
         "value": "92612901006014000013743278"
     }
 ],
    "customs": {
      "customsInfo": {
         "currencyCode": "USD",
         "freightCharge": 0.0,
         "handlingCosts": 0.0,
         "otherCharge": 0.0,
         "packingCosts": 0.0,
         "reasonForExport": "MERCHANDISE"
     },
    "customsItems": [
         {
             "description": "Books Plumbing",
             "hSTariffCode": "4901.99.0070",
             "originCountryCode": "US",
             "quantity": 1,
             "unitPrice": 32.0,
             "unitWeight": {
                 "unitOfMeasurement": "OZ",
                 "weight": 15.0
             }
         },
         {
             "description": "Books Construction",
             "hSTariffCode": "4901.99.0070",
             "originCountryCode": "US",
             "quantity": 1,
             "unitPrice": 32.0,
             "unitWeight": {
                 "unitOfMeasurement": "OZ",
                 "weight": 15.0
             }
         },
         {
             "description": "Books Electronics",
             "hSTariffCode": "4901.99.0070",
             "originCountryCode": "US",
             "quantity": 1,
             "unitPrice": 32.0,
             "unitWeight": {
                 "unitOfMeasurement": "OZ",
                 "weight": 15.0
             }
         }
         {
           "description": "Books Bicycles",
             "hSTariffCode": "4901.99.0070",
             "originCountryCode": "US",
             "quantity": 1,
             "unitPrice": 32.0,
             "unitWeight": {
                 "unitOfMeasurement": "OZ",
                 "weight": 15.0
              }
          }
       ]
 },
    "parcelTrackingNumber": "4202014792612901006014000001105019",
    "shipmentId": "NGST2215759034775757"
}

Hazardous Materials Shipment Sample Request

The following sample request prints a PB Delivery label for a HAZMAT-flagged shipment.

Important

The hazmatDetails object were deprecated July 9, 2023, and replaced by the hazmat special service. See HAZMAT-Flagged Items for PB Delivery and PB Returns.

curl -X POST ".../v1/shipments" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 5a2d2cf4-f2c4-41ba-91e2" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
 {
    "fromAddress": {
        "company": "Supplies",
        "name": "Kathryn Smith",
        "phone": "334-000-0000",
        "email": "kathryn@example.com",
        "residential": "false",
        "addressLines": [
            "2501 West Rosecrans Ave",
            "Address Line2"
        ],
        "cityTown": "Los Angeles",
        "stateProvince": "CA",
        "postalCode": "90220",
        "countryCode": "US"
 },
   "toAddress": {
       "company": "test",
       "name": "Jane",
       "phone": "785-000-0000",
       "email": "books@example.com",
       "residential": "false",
       "addressLines": [
           "4215 mt highway 35"
        ],
        "postalCode": "59901",
        "cityTown": "kalispell",
        "stateProvince": "montana",
        "countryCode": "US"
 },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": "22"
     },
         "dimension": {
             "unitOfMeasurement": "IN",
             "length": "10",
             "width": "4",
             "height": "6"
     }
     },
     "rates": [
         {
             "carrier": "PBCS",
             "serviceId": "PRCLSEL",
             "parcelType": "PKG",
             "specialServices": [
                 {
                     "specialServiceId": "hazmat",
                     "inputParameters": [
                          {
                             "name": "HAZMAT_TYPE",
                             "value": "Class 7 Radioactive Materials"
                           }
                       ]
                   }
               ]
           }
       ],
       "documents": [
           {
               "type": "SHIPPING_LABEL",
               "contentType": "URL",
               "size": "DOC_4X6",
               "fileFormat": "PDF",
               "resolution": "DPI_300"
           }
         ],
         "shipmentOptions": [
             {
                 "name": "SHIPPER_ID",
                 "value": "9024324564"
             },
             {
                 "name": "IS_RECTANGULAR",
                  "value": "true"
              },
             {
                 "name": "CLIENT_FACILITY_ID",
                 "value": "0093"
              },
             {
                 "name": "CARRIER_FACILITY_ID",
                 "value": "1585"
              },
             {
                  "name": "NON_DELIVERY_OPTION",
                  "value": "ChangeServiceRequested"
              },
             {
                  "name": "PRINT_CUSTOM_MESSAGE_2",
                  "value": "PRINTCUSTOMMESSAGE"
            }
        ]
     }'
Sample Response
 {
      "fromAddress": {
          "company": "Supplies",
          "name": "Kathryn Smith",
          "phone": "334-000-0000",
          "email": "kathryn@example.com",
          "residential": false,
          "addressLines": [
              "2501 W Rosecrans Ave",
              "Address LINE2"
          ],
          "cityTown": "Los Angeles",
          "stateProvince": "CA",
          "postalCode": "90059-3566",
          "countryCode": "US",
          "deliveryPoint": "01"
       },
       "toAddress": {
           "company": "test",
           "name": "Jane",
           "phone": "785-000-0000",
           "email": "books@example.com",
           "residential": true,
           "addressLines": [
           "4215 Mt Highway 35"
           ],
            "cityTown": "Kalispell",
            "stateProvince": "MT",
            "postalCode": "59901-8202",
            "countryCode": "US",
           "deliveryPoint": "15"
       },
       "parcel": {
           "weight": {
              "unitOfMeasurement": "OZ",
              "weight": 22.0
           },
           "dimension": {
               "length": 10.0,
               "width": 4.0,
               "height": 6.0,
               "unitOfMeasurement": "IN",
               "irregularParcelGirth": 0.0
           }
       },
       "rates": [
           {
               "carrier": "pbcs",
               "parcelType": "PKG",
               "specialServices": [
                   {
                       "inputParameters": [
                           {
                               "name": "HAZMAT_TYPE",
                               "value": "Class 7 Radioactive Materials"
                            }
                        ],
                        "specialServiceId": "hazmat"
               }
                ],
                "serviceId": "PRCLSEL"
            }
         ],
         "documents": [
             {
                 "contentType": "URL",
                 "contents": "https://.../8a4968574a48DA2ac66d9d9af311387e.pdf",
                 "fileFormat": "PDF",
                 "resolution": "DPI_300",
                 "size": "DOC_4X6",
                 "type": "SHIPPING_LABEL"
              }
          ],
          "shipmentOptions": [
              {
                  "name": "SHIPPER_ID",
                  "value": "3800037825"
               },
              {
                  "name": "IS_RECTANGULAR",
                  "value": "true"
                },
              {
                  "name": "CLIENT_FACILITY_ID",
                  "value": "0093"
                },
               {
                  "name": "CARRIER_FACILITY_ID",
                  "value": "1585"
                },
               {
                  "name": "NON_DELIVERY_OPTION",
                  "value": "ChangeServiceRequested"
               },
              {
                  "name": "PRINT_CUSTOM_MESSAGE_2",
                  "value": "PRINTCUSTOMMESSAGE"
               },
               {
                   "name": "PARCEL_TRACKING_BARCODEVALUE",
                   "value": "4206740192612901006014000001025096"
               },
               {
                    "name": "PARCEL_TRACKING_ID",
                    "value": "92612901006014000001025096"
         }
     ],
     "parcelTrackingNumber": "4205990192395901006014000000005138",
     "shipmentId": "NGST2200470612152691"
   }

Sample PB Delivery Label

  • The top of label displays the Return Address, the Endorsement (for example: “Return Service Requested”), Ship To Address and the Service Name.

  • The middle of label displays the USPS Tracking Barcode.

  • The bottom of label displays the 2D barcodes, the sort information used internally by PB Delivery, and the Delivery Post Office.

Sample PB Delivery Label

Error Codes

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