Create a PB Expedited Delivery Label

HTTP Request

POST /v1/shipments

Summary

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

Note: To create a PB Standard Delivery label, click here.

PB Expedited Considerations

  1. PB Expedited uses USPS® as the carrier.

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

  3. For available services, parcel types, and labels sizes for PB Expedited, see the Pitney Bowes Carrier Reference page.

  4. Pitney Bowes requires that USPS parcels be trackable. If a parcel uses a service that is not trackable, such as Priority Mail (PM), you must add at least one trackable special service, such as Delivery Confirmation (DelCon). DelCon is no-charge service that triggers tracking but does not increase cost. Before adding a special service, check its compatibility.

  5. To send a letter or flat with an IMb (Intelligent Mail barcode), use the parameters listed in How do I print First-Class Mail letters and flats?

  6. If shipping a HAZMAT-flagged item, include one of the following special services in the rates.specialServices array. Do not include both. In the array, set specialServiceId to one of the following:

    • For most types of HAZMAT-flagged items, set specialServiceId to hazmat.

    • If you are shipping a used, damaged, or defective electronic device that contains or is packaged with a lithium battery, set specialServiceId to hazmat-electronics. Note that such an item can be shipped only through surface transportation. The hazmat-electronics special service prints the following text on the bottom of the label:

      RESTRICTED ELECTRONICS DEVICE
      SURFACE TRANSPORTATION ONLY

      As shown here:

      Sample Hazmat Electronics Label

  7. To make a shipment eligible for inclusion in a USPS SCAN form, set ADD_TO_MANIFEST to true in the shipmentOptions array. To include the shipment in a SCAN form, issue the Create Manifest request before 8 p.m. local time. For details on cutoff times, see this FAQ.

    IMPORTANT: If you set ADD_TO_MANIFEST to true but do not run Create Manifest before 8 p.m. local time, the shipment will not manifest until the next day or later, which will lead to a delay of up to a day before USPS starts sending tracking updates.

    Note: You cannot add First-Class Mail letters or flats to a SCAN form. Doing so will result in an error.

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

  9. You can write a single request to use for both PB Expedited and PB Standard labels and change the field values as needed. See Single Request for PB Expedited and PB Standard.

  10. For FAQS, see PB Expedited Delivery FAQs.

Request URLs

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

Query Parameter

Name

Description

includeDeliveryCommitment

If set to true, returns estimated transit time. Transit times is returned as number of days. Valid values:

  • true

  • false

See also:

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-Shipper-Rate-Plan

Shipper rate plan, if applicable. For more information, see this FAQ.

X-PB-Integrator-CarrierId

Negotiated services rate, if applicable.

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

  • phone: Required only for Priority Mail Express (EM)

To print a different address on the label from this one, see this FAQ.

toAddress

Address Object

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

  • addressLines

  • postalCode

  • countryCode

  • phone: Required only for Priority Mail Express (EM)

altReturnAddress

Address Object

If you are sending an international shipment, and if you have set the NON_DELIVERY_OPTION option to redirect, use this field to specify the address for a parcel return.

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. In the dimension object, enter values in inches and set unitOfMeasurement to IN.

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

Parcels using services other than Parcel Select cannot measure more than 108 inches in length and girth combined. Length is the parcel’s longest dimension. Girth is twice the sum of the height and width: girth = 2 * (height+width)

Parcels using Parcel Select can measure up to 130 inches in length and girth combined.

Additional limits might apply. See USPS rules at https://pe.usps.com/.

Soft Packs must measurements as described here.

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:

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:

shipmentOptions

Array[Object]

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

Set the following options:

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

  • ADD_TO_MANIFEST: Conditional. If the shipment is to be included in a USPS SCAN form, set this to true. To include the shipment in a SCAN form, either issue the manifest request or let Pitney Bowes auto-manifest the shipment. Note that if you set this to true but do not issue the manifest request before the cutoff time, there will be a delay of up to a day in receiving the first tracking events.

    Do not set ADD_TO_MANIFEST for First-Class Mail letters or flats. Doing so results in an error.

  • PRINT_CUSTOM_MESSAGE_1, PRINT_CUSTOM_MESSAGE_2: Optional. These print merchant-defined reference fields on the label.

For all available options, see Shipment Options.

customs

Object

Customs clearance information.

Required for shipments to international destinations. Conditional for shipments to APO/FPO/DPO, U.S. Territories, and FAS, as explained in this FAQ.

customs.customsInfo

Customs Info Object

Customs clearance information for the commercial invoice. This is required if you use the customs object.

customs.customsItems

Array[Customs Items Object]

Customs clearance information for each commodity. This is required if you use the customs object. The array takes a maximum of 30 objects.

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.

Customs Info Object for PB Expedited

Name

Data Type

Description

certificateNumber

String

The certificate number associated with the commodity.

comments

String

Free form comments regarding the exported shipment entered by the shipper.

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, CAD for Canadian Dollars, and EUR for Euros. The full list of currency codes can be downloaded in XLS or XML from https://www.iso.org/iso-4217-currency-codes.html.

EELPFC

String

A number provided by the Automated Export System (AES).

Required if the item is valued at more than $2,500 USD per Schedule B export codes.

fromCustomsReference

String

Free form reference information provided by the requestor of the shipment. Depending on the carrier this information may or may not be rendered on the customs documents.

importerCustomsReference

String

A reference number used by the importer, such as a VAT number, PO number, or insured number. Pitney Bowes does not print the number on the customs form.

Required for shipments to the EU from outside the EU. Enter a VAT or IOSS number. Specify which type of number in the importerCustomsReferenceType field.

Required for shipments to Brazil. Enter the Importer’s Tax Identification Number. Brazil requires the Tax ID for all imports. Items missing the Tax ID are subject to return. If using the First-Class Package International Service (FCPIS), set the label size to DOC_8X11. See also: Where is the Importer’s Tax ID displayed?

importerCustomsReferenceType

String

Required if you enter a VAT or IOSS number in the importerCustomsReference field. Specify which type of number you entered:

  • VAT_NUMBER

  • IOSS_NUMBER

insuredNumber

String

If the sender wishes to insure the contents, they complete an insurance receipt and affix the insured numbered label to the package. The insured number label is what this field represents.

invoiceNumber

String

The commercial invoice number assigned by the exporter.

licenseNumber

String

The export license number associated with the commodity.

reasonForExport

String

Required. The reason the commodity is being exported. Valid values are:

  • GIFT

  • COMMERCIAL_SAMPLE

  • MERCHANDISE

  • DOCUMENTS (If using this value, see also this related FAQ)

  • RETURNED_GOODS

  • OTHER

Note: For USPS First-Class Mail International (FCMI), you must set this field to DOCUMENTS. FCMI cannot ship goods. To ship goods through USPS, you can use First-Class Package International Service (FCPIS) or other services.

reasonForExportExplanation

String

The reason the commodity is being exported.

Required if the reasonForExport field is set to OTHER.

sdrValue

BigDecimal

When an international parcel is insured, the insured value must be expressed in Special Drawing Rights values. E.g. $100 USD = 66.87 SDR.

 

Customs Items Object for PB Expedited

Name

Data Type

Description

description

String

Required. A detailed description of the commodity, up to 255 characters.

hSTariffCode

String

The destination country’s tariff-classification number for the commodity, up to 14 characters. Most countries use the six-digit Harmonized System (HS) as the basis for their tariff classifications and add additional digits for more detail.

originCountryCode

String

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

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

unitWeight.unitOfMeasurement

String

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

Sample Requests

See the following:

See also the Sample Doc Tab Request in the FAQs.

Priority Mail Shipment Sample Request

The following sample request prints a PB Expedited Priority Mail label. The request uses the includeDeliveryCommitment query parameter to return estimated transit time.

curl -X POST ".../v1/shipments?includeDeliveryCommitment=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 76e4498e-85fe-43a1-b6d0" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "fromAddress": {
        "company": "Supplies",
        "name": "Kathryn Smith",
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830",
        "countryCode": "US"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Mary Jones",
        "addressLines": [
            "284 W Fulton St"
        ],
        "cityTown": "Garden City",
        "stateProvince": "KS",
        "postalCode": "67846",
        "countryCode": "US"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 8
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": 6,
            "width": 1,
            "height": 4
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "serviceId": "PM",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "Ins",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "50"
            } ]
        },{
            "specialServiceId": "DelCon",
            "inputParameters": [ ]
        } ]
    } ],
    "documents": [ {
        "size": "DOC_4X6",
        "fileFormat": "PNG",
        "contentType": "BASE64",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
      },{
        "name": "ADD_TO_MANIFEST",
        "value": "true"
      },{
        "name": "CLIENT_FACILITY_ID",
        "value": ""
      },{
        "name": "CARRIER_FACILITY_ID",
        "value": ""
      },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "Thank you for shopping with us!"
      }
    ],
    "references": [ {
        "name": "Order_Number",
        "value": "123876-54910"
    } ]
}'
Sample Response
{
    "fromAddress": {
        "company": "Supplies",
        "name": "Kathryn Smith",
        "residential": false,
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830-6433",
        "countryCode": "US",
        "carrierRoute": "C010",
        "deliveryPoint": "52"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Mary Jones",
        "residential": false,
        "addressLines": [
            "284 W Fulton St"
        ],
        "cityTown": "Garden City",
        "stateProvince": "KS",
        "postalCode": "67846-5352",
        "countryCode": "US",
        "carrierRoute": "C007",
        "deliveryPoint": "84"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 8.0
        },
        "dimension": {
            "length": 6.0,
            "width": 1.0,
            "height": 4.0,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": 0.0
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "parcelType": "PKG",
        "inductionPostalCode": "29601",
        "specialServices": [ {
            "fee": 0.0,
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "50"
            } ],
            "specialServiceId": "Ins"
        },{
            "fee": 0.0,
            "specialServiceId": "DelCon"
        } ],
        "dimensionalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": 0.0
        },
        "deliveryCommitment": {
            "additionalDetails": "By end of Day",
            "estimatedDeliveryDateTime": "2021-06-25",
            "guarantee": "NONE",
            "maxEstimatedNumberOfDays": "3",
            "minEstimatedNumberOfDays": "3"
        },
        "serviceId": "PM",
        "baseCharge": 7.88,
        "currencyCode": "USD",
        "destinationZone": "5",
        "totalCarrierCharge": 7.88
    } ],
    "documents": [ {
        "contentType": "BASE64",
        "fileFormat": "PNG",
        "pages": [ {
            "contents": "iVBORw0KGgoAAAANSUhEUgAABLAAAAcIAQAAAAAEKwXnAAAACXB..."
        } ],
        "size": "DOC_4X6",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "HIDE_TOTAL_CARRIER_CHARGE",
        "value": "false"
      },{
        "name": "SHIPPER_ID",
        "value": "9024324564"
      },{
        "name": "ADD_TO_MANIFEST",
        "value": "true"
      },{
        "name": "FUTURE_SHIPMENT_DATE",
        "value": "2021-06-22 09:17:32.360"
      },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "false"
      },{
        "name": "SHIPPING_LABEL_RECEIPT",
        "value": "noOptions"
      },{
        "name": "CLIENT_FACILITY_ID",
        "value": ""
      },{
        "name": "CARRIER_FACILITY_ID",
        "value": ""
      },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "Thank you for shopping with us!"
      }
    ],
    "references": [ {
        "name": "Order_Number",
        "value": "123876-54910"
    } ],
    "parcelTrackingNumber": "9405509898641492016876",
    "shipmentId": "USPS2200334203501014"
}

International Shipment Sample Request

The following sample request prints a PB Expedited international shipment label. The request uses the customs object to provide customs information:

curl -X POST ".../v1/shipments?includeDeliveryCommitment=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 93e30b6f-b6cc-4528-bef0" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "fromAddress": {
        "company": "Emporium",
        "name": "Anna Martin",
        "addressLines": [
            "625 S Main St"
        ],
        "cityTown": "Greenville",
        "stateProvince": "SC",
        "postalCode": "29601",
        "countryCode": "US"
    },
    "toAddress": {
        "company": "Museo",
        "name": "Director",
        "addressLines": [
            "Av. Juárez 8, Colonia Centro, Centro, 06010 "
        ],
        "cityTown": "Mexico City",
        "postalCode": "CDMX",
        "countryCode": "MX"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 60
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": 10.0,
            "width": 4.0,
            "height": 7.0
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "serviceId": "EMI",
        "parcelType": "FRE",
        "specialServices": [ {
            "specialServiceId": "Ins",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "100"
            } ]
        } ]
    } ],
    "documents": [ {
        "size": "DOC_8X11",
        "fileFormat": "PDF",
        "contentType": "URL",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
      },{
        "name": "ADD_TO_MANIFEST",
        "value": "true"
      },{
        "name": "CLIENT_FACILITY_ID",
        "value": ""
      },{
        "name": "CARRIER_FACILITY_ID",
        "value": ""
      },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "Thank you!"
      }
    ],
    "references": [ {
        "name": "Order_Number",
        "value": "1f514-7908"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD",
            "reasonForExport": "MERCHANDISE"
        },
        "customsItems": [ {
            "description": "Books",
            "quantity": 3,
            "unitPrice": 32.00,
            "unitWeight": {
                "weight": 20.0,
                "unitOfMeasurement": "OZ"
            }
        } ]
    }
}'
Sample Response
{
    "fromAddress": {
        "company": "Emporium",
        "name": "Anna Martin",
        "residential": false,
        "addressLines": [
            "625 S Main St"
        ],
        "cityTown": "Greenville",
        "stateProvince": "SC",
        "postalCode": "29601-2504",
        "countryCode": "US",
        "carrierRoute": "C009",
        "deliveryPoint": "25"
    },
    "toAddress": {
        "company": "Museo",
        "name": "Director",
        "addressLines": [
            "Av. Juárez 8, Colonia Centro, Centro, 06010 "
        ],
        "cityTown": "Mexico City",
        "postalCode": "CDMX",
        "countryCode": "MX"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 60.0
        },
        "dimension": {
            "length": 10.0,
            "width": 4.0,
            "height": 7.0,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": 0.0
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "parcelType": "FRE",
        "inductionPostalCode": "29601",
        "specialServices": [ {
            "fee": 0.0,
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "100"
            } ],
            "specialServiceId": "Ins"
        } ],
        "dimensionalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": 0.0
        },
        "deliveryCommitment": {
            "additionalDetails": "3 - 5 business days to many major markets",
            "estimatedDeliveryDateTime": "",
            "guarantee": "NONE",
            "maxEstimatedNumberOfDays": "5",
            "minEstimatedNumberOfDays": "3"
        },
        "serviceId": "EMI",
        "baseCharge": 57.95,
        "currencyCode": "USD",
        "destinationZone": "2",
        "totalCarrierCharge": 57.95
    } ],
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../usps/872060188/outbound/label/facb9d96c1b74f40ebd7d788c4eb4a.pdf",
        "fileFormat": "PDF",
        "size": "DOC_8X11",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "HIDE_TOTAL_CARRIER_CHARGE",
        "value": "false"
      },{
        "name": "SHIPPER_ID",
        "value": "9024324564"
      },{
        "name": "ADD_TO_MANIFEST",
        "value": "true"
      },{
        "name": "FUTURE_SHIPMENT_DATE",
        "value": "2021-06-22 10:01:54.173"
      },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "false"
      },{
        "name": "SHIPPING_LABEL_RECEIPT",
        "value": "noOptions"
      },{
        "name": "CLIENT_FACILITY_ID",
        "value": ""
      },{
        "name": "CARRIER_FACILITY_ID",
        "value": ""
      },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "Thank you!"
      }
    ],
    "references": [ {
        "name": "Order_Number",
        "value": "1f514-7908"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD",
            "freightCharge": 0.0,
            "handlingCosts": 0.0,
            "otherCharge": 0.0,
            "packingCosts": 0.0,
            "reasonForExport": "MERCHANDISE"
        },
        "customsItems": [ {
            "description": "Books",
            "quantity": 3,
            "unitPrice": 32.0,
            "unitWeight": {
                "unitOfMeasurement": "OZ",
                "weight": 20.0
            }
        } ]
    },
    "parcelTrackingNumber": "EP864140815US",
    "shipmentId": "USPS2200205085792904"
}

Error Codes

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