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¶
PB Expedited uses USPS® as the carrier.
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.
For available services, parcel types, and labels sizes for PB Expedited, see the Pitney Bowes Carrier Reference page.
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.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?
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, setspecialServiceId
to one of the following:For most types of HAZMAT-flagged items, set
specialServiceId
tohazmat
.If you are shipping a used, damaged, or defective electronic device that contains or is packaged with a lithium battery, set
specialServiceId
tohazmat-electronics
. Note that such an item can be shipped only through surface transportation. Thehazmat-electronics
special service prints the following text on the bottom of the label:RESTRICTED ELECTRONICS DEVICE
SURFACE TRANSPORTATION ONLYAs shown here:
To make a shipment eligible for inclusion in a USPS SCAN form, set
ADD_TO_MANIFEST
totrue
in theshipmentOptions
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
totrue
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.
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.
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.
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
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 |
Accept-Language |
Language and country code. Default: |
X-PB-TransactionId |
Required. A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens ( 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 |
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 |
Required. The origin address. The
To print a different address on the label from this one, see this FAQ. |
|
toAddress |
Required. The destination address. The
|
|
altReturnAddress |
If you are sending an international shipment, and if you have set the NON_DELIVERY_OPTION option to |
|
parcel |
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 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: 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
|
documents |
Array[Documents Object] |
Required. Defines the label. The response returns the label as a URL or Base64 string. The array takes one
|
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:
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 clearance information for the commercial invoice. This is required if you use the |
|
customs.customsItems |
Array[Customs Items Object] |
Customs clearance information for each commodity. This is required if you use the |
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 |
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 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 ( |
importerCustomsReferenceType |
String |
Required if you enter a VAT or IOSS number in the
|
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:
Note: For USPS First-Class Mail International ( |
reasonForExportExplanation |
String |
The reason the commodity is being exported. Required if the |
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.unitOfMeasurement |
String |
The unit of measurement. This field is required by the |
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"
} ]
}'
{
"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"
}
} ]
}
}'
{
"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.