Create a Pitney Bowes Delivery Shipment¶
HTTP Request¶
POST /v1/shipments
Summary¶
This operation creates either a PB Expedited or PB Standard delivery label. The label created depends on the values sent in the request. The value of the carrier
field indicates whether the label is Expedited (USPS
) or Standard (PBCS
). The values of other fields also affect the label, as described on this page.
Before writing your API call, see the following considerations specific to each label type:
For the API description, see the sections on this page that begin here.
You can write one API call to use for both labels and change the field values as needed. For an example of one API call written for both labels, see Example Request Written for both Expedited and Standard.
PB Expedited Considerations¶
Important
For PB Expedited, set “carrier” to “USPS”.
The following considerations apply to PB Expedited Delivery Shipments:
Required Fields: When creating a PB Expedited Delivery shipment, set the following:
Field
Description
fromAddress
,
toAddress
The address objects require the following fields:
addressLines
postalCode
countryCode
phone
: Required infromAddress
if shipping with Express Mail / Priority Mail Express (EM
).
rates.carrier
Set this to
USPS
.rates.serviceId
See Services on the Pitney Bowes reference page.
To view restrictions on a service, use the Carrier Rules API or see the USPS Domestic Mail Manual.
rates.specialServices
See Special Services on the Pitney Bowes reference page.
To view restrictions on a special service, use the Carrier Rules API or see the USPS Domestic Mail Manual.
rates.parcelType
See Parcel Types on the Pitney Bowes reference page.
documents
See Labels on the Pitney Bowes reference page.
Note that First-Class Mail (FCM) shipments that use the FLAT parcel type are supported only for 6X4 labels. FCM shipments that use the LETTER parcel type are supported only for 6X4 or 9X4 labels.
shipmentOptions
You must include the SHIPPER_ID option and set its value to the merchant’s
postalReportingNumber
, which you can retrieve using the Get Merchant Accounts API.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.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 a comparison of complete and minimal address validation, see What is minimal address validation?
Dimensions: USPS encourages shippers to provide dimensions for all packages. Parcels cannot measure more than 108 inches in length and girth combined, with the exception of those using USPS Parcel Select. Length is the parcel’s longest dimension. Girth is twice the sum of the height and width:
girth = 2 * (height+width)
Parcels using the Parcel Select service can measure up to 130 inches in length and girth combined.
Additional limits might also apply to a parcel. Refer to the USPS rules at https://pe.usps.com/text/qsg300/Q201e.htm.
When setting dimensions in the dimension object, enter values in inches. Set the
unitOfMeasurement
field toIN
.Soft Packs: Soft Packs must meet the following requirements. The measurements must be taken prior to placing the item in the envelope:
The sum of the longest and next-longest dimensions must not exceed 36 inches.
The longest dimension must not exceed 18 inches.
The smallest dimension must not exceed 2 inches.
Tracking Requirement: The PB Ecommerce APIs require that all 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 a no-charge special service that triggers tracking but does not increase the cost of the shipment. Before adding a special service, check its compatibility with the service.HAZMAT: PB Expedited designates HAZMAT through the
rates.specialServices
array. If shipping a HAZMAT-flagged item with PB Expedited, include thehazmat
special service in the array.Labels: When you create a PB Expedited Delivery shipment, the API returns the USPS label as either a:
Base64 string that converts to a PNG.
Base64 string that converts to ZPL2.
URL that links to a PDF. Labels retrieved through URLs are available for 24 hours after label creation.
IMb: 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?
Customs: For PB Expedited Delivery shipments that use the
customs
object, you must set thedocuments.size
field to eitherDOC_4X6
orDOC_8X11
. The API will automatically provide the correct USPS customs form based on the information supplied in the request. The form is used as both the shipping label and the customs declaration. For more information, see the Customs Forms FAQs.SCAN Form: To make the shipment eligible for inclusion in a USPS SCAN form, set the ADD_TO_MANIFEST shipment option to
true
in theshipmentOptions
array. To include the shipment in a SCAN form, either issue the Create Manifest API or let Pitney Bowes auto-manifest the shipment at 6 a.m. UTC/GMT the day after the ship date.Note that you cannot add First-Class Mail letters or flats to a SCAN form. Doing so will result in an error.
Reference Fields on Labels: For PB Expedited Delivery shipments, you can print merchant-defined reference fields on shipping labels by setting the PRINT_CUSTOM_MESSAGE_1 and PRINT_CUSTOM_MESSAGE_2 options in the
shipmentOptions
array.Error Handling: If your request returns the HTTP 500 Internal Server Error, see Troubleshoot the 500 Internal Server Error.
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.
PB Standard Considerations¶
Important
For PB Standard, set “carrier” to “PBCS”.
The following considerations apply to PB Standard Delivery Shipments:
Onboarding with PB Standard: To print PB Standard Delivery labels, a merchant must 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 in the explanation of
shipmentOptions
further down in these considerations.Label Charge: A PB Standard 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.
Domestic Only: PB Standard Delivery labels are supported for domestic shipments only. You cannot print a PB Standard Delivery label for an international destination.
Required Fields: When creating a PB Standard Delivery shipment, set the following:
Field
Description
fromAddress
,
toAddress
The address objects require the following fields:
addressLines
postalCode
countryCode
name
For APAC Services, the
residential
field is also required.parcel.dimension
Set this to the correct dimensions. Dimensions are required for PB Standard Delivery shipments.
Important: Entering incorrect dimensions might result in an undeliverable package or an additional postage fee.
rates.carrier
Set this to
PBCS
to indicate the carrier is PB Standard.rates.serviceId
See Services on the Pitney Bowes reference page.
rates.specialServices
See Special Services on the Pitney Bowes reference page.
rates.parcelType
Set this to
PKG
.documents
PB Standard Delivery labels use 203 DPI by default. For label settings, see Labels on the Pitney Bowes reference page.
shipmentOptions
Required:
SHIPPER_ID: The merchant’s Shipper ID.
CLIENT_FACILITY_ID: The ID assigned to the merchant’s facility during onboarding with PB Standard. If testing the Create Shipment API on Sandbox, set this to
0093
.CARRIER_FACILITY_ID: The ID of the PB Standard facility assigned to the merchant during onboarding with PB Standard. If testing the Create Shipment API on Sandbox, set this to
1585
.
Conditional:
IS_RECTANGULAR: If you set an irregular parcel girth value in the
parcel.dimension
object, then this option is required and must be set tofalse
.
Note:
You can optionally set the CLIENT_ID. If testing the Create Shipment API on Sandbox, set this to
NGST
.To print non-delivery instructions, include the NON_DELIVERY_OPTION shipment option.
To print custom information or reference fields on the label, include the PRINT_CUSTOM_MESSAGE_2 shipment option.
The ADD_TO_MANIFEST option is not necessary in the request. All PB Standard Delivery parcels are automatically eligible for close out, no matter how this option is set.
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.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 a comparison of complete and minimal address validation, see What is minimal address validation?
Notifications: To subscribe the shipment to notifications, include the
NOTIFICATIONS
special service in the request. The merchant must be configured for PB Standard notifications. For more information, see PB Standard Notifications below.Reference Fields: To include merchant-defined reference fields in either the shipment data or on the label, do either or both of the following:
To include fields in the shipment data, use the
references
array, as described below in PB Standard References.To include fields on the label, use the PRINT_CUSTOM_MESSAGE_2 shipment option.
Custom Label Info: To print custom information on the label, whether a reference field or other information, use the PRINT_CUSTOM_MESSAGE_2 shipment option.
HAZMAT: PB Standard Delivery designates HAZMAT through the hazmatDetails object. For a sample request that uses the
hazmatDetails
object, see Hazardous Materials Shipment Sample Request.Containers: When shipping with PB Standard Delivery, shippers must containerize parcels. Shippers can print container labels through either the Container API or Merchant Portal.
Close Out: When you create a PB Standard Delivery shipment, the shipment is automatically eligible for manifesting (close out). The ADD_TO_MANIFEST option is always considered
true
, even if you set it tofalse
.To close out the day, see Create a Pitney Bowes Manifest.
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:
"rates": [ { "specialServices": [ { "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.
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 Parameters¶
Name |
Description |
---|---|
includeDeliveryCommitment |
PB Expedited Only. If set to
See also: |
carrier |
PB Standard 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 |
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 |
PB Expedited Only. Shipper rate plan, if applicable. For more information, see this FAQ. |
X-PB-Integrator-CarrierId |
PB Expedited Only. Negotiated services rate, if applicable. |
X-PB-UnifiedErrorStructure |
Recommended. Set this to |
Request / Response Elements¶
The API call sends and receives a Shipment Object. The following table describes all possible fields in a Shipment Object. Some might not apply to your operation. For the required fields and values for your operation, see the Expedited Considerations or Standard Considerations.
Important
Read the Expedited Considerations and Standard Considerations before invoking this API.
Important
Some fields in the Shipment Object might not apply to your operation.
Name |
Data Type |
Description |
---|---|---|
fromAddress |
Required. Origin address. If you want a different address to appear on the label from the one listed here, see How do I print a return address that is different from the origin address? |
|
toAddress |
Required. Destination address. FedEx, UPS: If you are shipping with FedEx or UPS to Puerto Rico or an international destination, and if the importer is different from the final recipient, this is the address of the importer. Enter the recipient’s address in the |
|
altReturnAddress |
PB Expedited, CBDS Only. Sets the address for parcel returns. Use this in the following situations:
|
|
parcel |
Required. Contains physical characteristics of the parcel. |
|
rates |
Array[Rates Object] |
Required. Specifies the carrier, service, parcel, and other information. In a response, this field also contains the service charges. Important: In a request, the |
documents |
Array[Documents Object] |
Conditional. Defines the label, manifest, or other shipping document created by the API call. In a response, this array provides the URL or Base64 string for a document and in some cases can contain multiple objects. This field is required, except in the following cases:
|
shipmentOptions |
Array[Object] |
Required. Each object in this array defines a shipment option. Specify each option as a name-value pair in the array. The |
shipmentOptions.name |
String |
The name of the shipment option. |
shipmentOptions.value |
String |
The value of the shipment option. |
customs |
Object |
Conditional. For shipments that use customs forms, this object contains the customs information. This field is required for the following carriers in the following situations:
|
customs.customsInfo |
Customs clearance information for the commercial invoice. When using the Customs Info Object, make sure to include the fields marked Required. |
|
customs.customsItems |
Array[Customs Items Object] |
Customs clearance information for each commodity. When using the Customs Items Object, make sure to include the fields marked Required. The maximum number of objects in this array is 30. |
domesticShipmentDetails |
CBDS Only. Required if the merchant prints the first-mile label prior to invoking the Create CBDS Shipment API. This object contains information about the first-mile leg of the shipment. |
|
soldToAddress |
FedEx, UPS Only. The final recipient of a the shipment. Required for a shipment from the U.S. to Puerto Rico or to an international destination. Otherwise optional. This address must match the If the final recipient’s address is the same as the importer’s address, the entries in the |
|
shipmentType |
String |
Return Labels Only. Set this to |
references |
Array[Object] |
PB Standard, CBDS Only. Conditional. The merchant’s reference fields. Each object in the array includes a name-value pair that defines a reference field. This array applies only to the following two carriers:
To pass references for carriers other than the above, see Reference Fields. |
references.name |
String |
PB Standard, CBDS Only. The name of the reference field. |
references.value |
String |
PB Standard, CBDS Only. The value for the reference field. |
hazmatDetails |
PB Standard Only. If shipping hazardous materials with PB Standard, use this object. |
|
carrierPayments |
FedEx, UPS Only. Indicates that one or more of the shipment costs should be charged to a third-party account. |
|
shipmentId |
String |
RESPONSE ONLY. Unique identifier for the shipment, generated by the system in response to shipment purchase. |
parcelTrackingNumber |
String |
RESPONSE ONLY. Tracking number assigned to the shipment by the system. |
Hazmat Details Object¶
This object is used by PB Standard. For an example, this sample request.
Name |
Data Type |
Description |
---|---|---|
containerDetails |
Array[Container Details Object] |
Indicates one or more containers used to pack dangerous goods commodities. |
Container Details Object¶
Name |
Data Type |
Description |
---|---|---|
commodityInfo |
Array[Object] |
Information about the material inside the containers. |
commodityInfo.hazardClass |
String |
Class of the specified commodity. Valid values are:
|
commodityInfo.quantity |
Integer |
The amount of the commodity. |
commodityInfo.quantityUOM |
String |
The unit of measure. |
Sample Requests¶
Important
Before invoking this API, see the following considerations at the top of this page:
For 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"
}
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"
} ]
}'
{
"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.
Note: PB Standard and PB Expedited differ in the fields they use to pass HAZMAT information. PB Standard uses the hazmatDetails object, as shown here, while PB Expedited uses the rates.specialServices 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": "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"
} ]
} ]
}
}'
{
"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.