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 carrier field determines whether the label is Expedited (USPS) or Standard (PBCS). Before writing your API call, see the PB Expedited Considerations and PB Standard Considerations.

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

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 in `fromAddress` 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 to IN.
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 the hazmat 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 the documents.size field to either DOC_4X6 or DOC_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 the shipmentOptions 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 a Create Shipment Request.

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

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 to `false`. Note the Following Options: CLIENT_ID: Optional. The merchant’s ID for access to Standard Delivery. If testing on Sandbox, you can 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 or reference fields on the label. ADD_TO_MANIFEST: This 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 References Array in a PB Standard Shipment.
- 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 to false.

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:
{
    "specialServiceId": "NOTIFICATIONS",
    "inputParameters": [ {
        "name": "RECIPIENT_NOTIFICATION_TYPE",
        "value": "ON_DELIVER"
    },{
        "name": "RECIPIENT_NOTIFICATION_EMAIL",
        "value": "widgets@example.com"
    },{
        "name": "RECIPIENT_NOTIFICATION_PHONE",
        "value": "8085551234"
    } ]
}

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 true, returns estimated transit time. Transit times is returned as number of days. Valid values:

true
false

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	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 `true` to use the standard error object if an error occurs.

Request / Response Elements¶

Important

Please see the Expedited Considerations and Standard Considerations on this page before creating a shipment.

This POST operation sends and receives the Shipment object, described here. Required fields are marked Required. All other fields are optional, with two exceptions: 1. Fields that are marked RESPONSE ONLY appear only in the response. 2. Fields that are marked as applying only to other label types apply only to those types.

Name	Data Type	Description
shipmentType	String	Return Labels Only. For return labels, set this to `RETURN`. Required: Expedited Returns, Standard Returns Recommended: CBDS Returns
fromAddress	Address Object	Required. Origin address. If you want a different address to appear on the label from the one listed here, see this FAQ. The FAQ does not apply to PB Standard.
toAddress	Address Object	Required. Destination address. If you are shipping to Puerto Rico or an international destination with FedEx or UPS, and if the importer is different from the final recipient, enter the address of the importer here in the `toAddress` object. For the address of the recipient, use the `soldToAddress` object. If the importer is the same as the final recipient, the `toAddress` and `soldToAddress` must match.
altReturnAddress	Address Object	For these carriers, sets an address for parcel returns: PB Expedited: 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. PB Presort PMOD CBDS Outbound & CBDS Domestic: By default, parcel returns are sent to a shipment’s `fromAddress`. (Parcel returns are sent from the CBDS Hub.) If the `fromAddress` is the wrong address for your returns, then you must use the `altReturnAddress` to enter the correct address for returns. Failure to do so will result returns to the wrong address. FedEx UPS
additionalAddresses	Array[Additional Addresses Object]	CBDS Returns Only. If the seller’s address is different from the `toAddress`, enter the seller’s address here. Required if the `toAddress` and seller address are different.
parcel	Parcel Object	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 `rates` array can contain only one rates object.
documents	Array[Documents Object]	Required, except as noted below. 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 does not apply to: - Rate Parcel API. - Create CBDS Shipment API if the merchant prints the first-mile label prior to invoking the API.
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 `SHIPPER_ID` option is required. For additional requirements for a carrier, see the Considerations section on the carrier’s Create Shipment page.
shipmentOptions.name	String	The name of the shipment option.
shipmentOptions.value	String	The value of the shipment option.
customs	Object	For shipments that use customs forms, this object contains the customs information. Required in the following situations: PB Expedited: Required for shipments to international destinations. Conditional for shipments to APO/FPO/DPO, U.S. Territories, and FAS, as explained in this FAQ. CBDS: Required for all shipments. FedEx: Required for shipments to international destinations and Puerto Rico. UPS: Required for shipments to international destinations and Puerto Rico.
customs.customsInfo	Customs Info Object	Customs clearance information for the commercial invoice. Required in the `customs` object.
customs.customsItems	Array[Customs Items Object]	Customs clearance information for each commodity. Required in the `customs` object. Maximum number of objects in the array: 30
domesticShipmentDetails	Domestic Shipment Details Object	CBDS Only. The first-mile label’s tracking number and other information about the first-mile leg. Required if the merchant prints the first-mile label prior to invoking the API. Send the first-mile label’s tracking number and details. RESPONSE ONLY for all other CBDS shipment requests.
references	Array[Object]	PB Standard & CBDS Only. Optional reference fields. Each object in the array includes a name-value pair that defines a reference field. See the following, depending on your carrier: References Array for PB Standard References Array for CBDS References Array for CBDS Returns For carriers other than the above, see this FAQ.
hazmatDetails	Hazmat Details Object	PB Standard Only. If shipping hazardous materials with PB Standard, use this object.
carrierPayments	Array[Carrier Payments Object]	FedEx & UPS Only. If one or more of the shipment costs should be charged to a third-party account, enter the information in this array.
soldToAddress	Address Object	FedEx & UPS Only. The final recipient of a the shipment. Required for shipments from the U.S. to Puerto Rico or international destinations. Otherwise optional. This address must match the `toAddress.countryCode`, with the exception of shipments to Canada and to U.S. satellite countries. If the final recipient’s address is the same as the importer’s address, the entries in the `soldToAddress` object must match the entries in the `toAddress` object.
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.

References Array in a PB Standard Shipment¶

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 field, used only by PB Standard, contains the hazmat details object. For an example, see 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¶

The hazmatDetails.containerDetails array takes the 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: `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¶

Important

Before invoking this API, see the following considerations at the top of this page:

PB Expedited Considerations
PB Standard Considerations

For sample requests, see the following:

Priority Mail Shipment Sample Request
International Shipment Sample Request
Parcel Select Shipment Sample Request
Hazardous Materials Shipment Sample Request

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"
}

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.

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"
            } ]
        } ]
    }
}'

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.

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`