Create a PB Standard Delivery Label

HTTP Request

POST /v1/shipments

Summary

This operation creates a PB Standard 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 Standard and Expedited

You can write one API call to use for both PB Standard and PB Expedited labels and change the field values as needed. For an example of one API call written for both labels, see Single 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 PB Standard, reference information, see the Pitney Bowes page.

2. To print PB Standard labels, a merchant must first onboard with PB Standard. During onboarding, Pitney Bowes provides the merchant with a set of PB Standard IDs. When testing in Sandbox, use the Sandbox values listed for shipmentOptions in the Request / Response Elements table.

3. A PB Standard 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 Standard labels are supported for domestic shipments only. You cannot print a PB Standard Delivery label for an international destination.

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

6. Containers Requirement: When shipping with PB Standard 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 Standard Delivery shipment, the shipment is automatically eligible for manifesting (close out). To close out the day, see Create a PB Standard Delivery Manifest (Closeout).

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 Standard, 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 Standard 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 / 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
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. USPS encourages shippers to always provide dimensions. 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 response specifies the service charges. The array takes one rates object. Set the following fields and values: carrier: Set to PBCS. serviceId: See Delivery Services. For restrictions, use Carrier Rules. specialServices: See PB Standard Special Services. For restrictions, use Carrier Rules. parcelType: Set to PKG.
documents	Array[Documents Object]	Required. Defines the label. The response returns the label as a URL or Base64 string. The array takes one documents object. Set the following: type: Set to SHIPPING_LABEL. size, fileFormat, and contentType: For valid combinations, see Standard Delivery Labels. Note that PB Standard labels use 203 DPI by default.
shipmentOptions	Array[Object]	Required. Each object in this array defines a shipment option. Each object takes the following two fields, which take string values: name: The shipment option. value: The option’s value. 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 Standard. If testing this API on Sandbox, set this to 0093. CARRIER_FACILITY_ID: Required. The ID of the PB Standard facility assigned to the merchant during onboarding with PB Standard. 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 merchant’s ID for access to Standard Delivery. If testing on Sandbox, set this to NGST. Note that while CLIENT_ID is optional for Standard Delivery, it is required for Standard 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 Standard 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 Standard References. Note To include reference fields on the label, use the PRINT_CUSTOM_MESSAGE_2 shipment option.
hazmatDetails	Hazmat Details Object	For a shipment that includes hazardous materials, enter HAZMAT information here, as shown in this sample request.
shipmentId	String	RESPONSE ONLY. The unique identifier for the shipment generated by the system.
parcelTrackingNumber	String	RESPONSE ONLY. The tracking number assigned to the shipment.

PB Standard Notifications

PB Standard 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 Standard 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 Standard 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 Standard References

In a PB Standard 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 Standard data. The first object maps to the PB Standard “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.

Hazmat Details Object

The hazmatDetails object, used only by PB Standard, takes the containerDetails array, which provides information on the hazardous materials inside containers. The objects in the containerDetails array take the fields described below. For an example, see this sample request.

commodityInfo	Array[Object]	Information about the material inside the containers.
commodityInfo.hazardClass	String	Class of the specified commodity. Valid values are: Explosives Gases FlammableCombustibleLiquids FlammableSolids OxidizingSubstancesOrganicPeroxides ToxicSubstancesAndInfectiousSubstances RadioactiveMaterial Corrosives LQDG ConsumerCommodities MiscellaneousHazardousMaterial
commodityInfo.quantity	Integer	The amount of the commodity.
commodityInfo.quantityUOM	String	The unit of measure.

Sample Requests

See the following:

• Parcel Select Shipment Sample Request

• Hazardous Materials Shipment Sample Request

Parcel Select Shipment Sample Request

The following sample request prints a PB Standard 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."
      }
    ],
    "references": [ {
        "name": "ReferenceNumber",
        "value": "45-67891"
      },{
        "name": "AddlRef1",
        "value": "d576-5432124CC78"
      },{
        "name": "AddlRef2",
        "value": "CC4321"
    } ],
    "parcelTrackingNumber": "4206740192612901006014000001025096",
    "shipmentId": "NGST2200744454"
}

Hazardous Materials Shipment Sample Request

The following sample request prints a PB Standard label for a HAZMAT-flagged shipment. The HAZMAT information is passed through the hazmatDetails object.

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": "John Smith",
        "residential": true,
        "addressLines": [
            "1545 W Railroad Dr"
        ],
        "cityTown": "Glenns Ferry",
        "stateProvince": "ID",
        "postalCode": "83623",
        "countryCode": "US"
    },
    "toAddress": {
        "company": "Equipment",
        "name": "Bill Wilson",
        "addressLines": [
            "643 Greenway Rd"
        ],
        "cityTown": "Boone",
        "stateProvince": "NC",
        "postalCode": "28607",
        "countryCode": "US"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": "50"
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": "6",
            "width": "3",
            "height": "8"
        }
    },
    "rates": [ {
        "carrier": "PBCS",
        "serviceId": "PRCLSEL",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "NOTIFICATIONS",
            "inputParameters": [ {
                "name": "RECIPIENT_NOTIFICATION_TYPE",
                "value": "ON_DELIVER"
            },{
                "name": "RECIPIENT_NOTIFICATION_EMAIL",
                "value": "john@example.com"
            } ]
        } ]
    } ],
    "documents": [ {
        "size": "DOC_4X5",
        "fileFormat": "PDF",
        "contentType": "URL",
        "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": "Shipping Ref#: 5678"
      }
    ],
    "references": [ {
        "name": "ReferenceNumber",
        "value": "5678"
      }, {
        "name": "AddlRef1",
        "value": "345ef678"
    } ],
    "hazmatDetails": {
        "containerDetails": [ {
            "commodityInfo": [ {
                "hazardClass": "Gases"
            } ]
        } ]
    }
}'

Sample Response

{
    "fromAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "residential": true,
        "addressLines": [
            "1545 W Railroad Dr"
        ],
        "cityTown": "Glenns Ferry",
        "stateProvince": "ID",
        "postalCode": "83623-5015",
        "countryCode": "US",
        "deliveryPoint": "45"
    },
    "toAddress": {
        "company": "Equipment",
        "name": "Bill Wilson",
        "residential": false,
        "addressLines": [
            "643 Greenway Rd"
        ],
        "cityTown": "Boone",
        "stateProvince": "NC",
        "postalCode": "28607-4819",
        "countryCode": "US",
        "deliveryPoint": "99"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 50.0
        },
        "dimension": {
            "length": 6.0,
            "width": 3.0,
            "height": 8.0,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": 0.0
        }
    },
    "rates": [ {
        "carrier": "PBCS",
        "parcelType": "PKG",
        "specialServices": [ {
            "inputParameters": [ {
                "name": "RECIPIENT_NOTIFICATION_TYPE",
                "value": "ON_DELIVER"
            },{
                "name": "RECIPIENT_NOTIFICATION_EMAIL",
                "value": "john@example.com"
            } ],
            "specialServiceId": "NOTIFICATIONS"
        } ],
        "serviceId": "PRCLSEL"
    } ],
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../8a4968574a48DA2ac66d9d9af311387e.pdf",
        "fileFormat": "PDF",
        "size": "DOC_4X5",
        "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": "Shipping Ref#: 5678"
      }
    ],
    "references": [ {
        "name": "ReferenceNumber",
        "value": "5678"
      },{
        "name": "AddlRef1",
        "value": "345ef678"
    } ],
    "hazmatDetails": {
        "containerDetails": [ {
            "commodityInfo": [ {
                "hazardClass": "Gases"
            } ]
        } ]
    },
    "parcelTrackingNumber": "4202860792612901006014000001032896",
    "shipmentId": "NGST2029831289065841"
}

---

Sample PB Standard Delivery Label

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

• The middle of label displays the Mail Class (for example: Parcel Select) and displays information used internally by PB Standard.

• The bottom of label displays the USPS Tracking Barcode and the Delivery Post Office.

---

Error Codes

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

 
 
 
 

• next
• previous |

© Copyright 2023, PB.