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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3. Domestic Only: PB Standard Delivery labels are supported for domestic shipments only. You cannot print a PB Standard Delivery label for an international destination.

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

5. 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?

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

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

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

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

10. Containers: When shipping with PB Standard Delivery, shippers must containerize parcels. Shippers can print container labels through either the Container API or Merchant Portal.

11. 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 See also: Pitney Bowes Delivery Guarantee Do all USPS services return transit times?
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 carrier query parameter to Newgistics.

Request Headers

Name	Description
Authorization	Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type	Required. The media type of the request entity. Set this to application/json.
Accept-Language	Language and country code. Default: en-US
X-PB-TransactionId	Required. A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens (-), and underscores (_). Important: Ensure this is a unique ID.
X-PB-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
fromAddress	Address Object	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	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	PB Expedited and CBDS Only. Sets the address for parcel returns. Use this in the following situations: 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. CBDS: 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 enter the correct address will result in parcels being returned to the wrong address.
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 for the following carriers 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. 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	Domestic Shipment Details Object	CBDS Only. The tracking number and other information about the first-mile leg of the shipment. This does not apply if the Create Shipment API prints the first-mile label. Required if the merchant prints the first-mile label prior to invoking the Create Shipment API.
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.
shipmentType	String	Return Labels Only. For PB Expedited Return labels and PB Standard Return labels, set this to RETURN. Required for rating and creating Expedited Returns, and for creating Standard Returns. Note that you cannot rate Standard Returns.
references	Array[Object]	PB Standard and CBDS Only. The merchant’s 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 in a PB Standard Shipment References Array in a CBDS Shipment To pass references for carriers other than the above, see How do I Add Reference Fields for My Carrier?
hazmatDetails	Hazmat Details Object	PB Standard Only. If shipping hazardous materials with PB Standard, use this object.
carrierPayments	Array[Shipment: Carrier Payments Object]	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.

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

See also the Sample Doc Tab Request in the FAQs.

Priority Mail Shipment Sample Request

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

curl -X POST .../v1/shipments?includeDeliveryCommitment=true \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 76e4498e-85fe-43a1-b6d0" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "fromAddress": {
        "company": "Supplies",
        "name": "Kathryn Smith",
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830",
        "countryCode": "US"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Mary Jones",
        "addressLines": [
            "284 W Fulton St"
        ],
        "cityTown": "Garden City",
        "stateProvince": "KS",
        "postalCode": "67846",
        "countryCode": "US"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 8
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": 6,
            "width": 1,
            "height": 4
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "serviceId": "PM",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "Ins",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "50"
            } ]
        },{
            "specialServiceId": "DelCon",
            "inputParameters": [ ]
        } ]
    } ],
    "documents": [ {
        "size": "DOC_4X6",
        "fileFormat": "PNG",
        "contentType": "BASE64",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
      },{
        "name": "ADD_TO_MANIFEST",
        "value": "true"
      },{
        "name": "CLIENT_FACILITY_ID",
        "value": ""
      },{
        "name": "CARRIER_FACILITY_ID",
        "value": ""
      },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "Thank you for shopping with us!"
      }
    ],
    "references": [ {
        "name": "Order_Number",
        "value": "123876-54910"
    } ]
}'

Sample Response

{
    "fromAddress": {
        "company": "Supplies",
        "name": "Kathryn Smith",
        "residential": false,
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830-6433",
        "countryCode": "US",
        "carrierRoute": "C010",
        "deliveryPoint": "52"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Mary Jones",
        "residential": false,
        "addressLines": [
            "284 W Fulton St"
        ],
        "cityTown": "Garden City",
        "stateProvince": "KS",
        "postalCode": "67846-5352",
        "countryCode": "US",
        "carrierRoute": "C007",
        "deliveryPoint": "84"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 8.0
        },
        "dimension": {
            "length": 6.0,
            "width": 1.0,
            "height": 4.0,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": 0.0
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "parcelType": "PKG",
        "inductionPostalCode": "29601",
        "specialServices": [ {
            "fee": 0.0,
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "50"
            } ],
            "specialServiceId": "Ins"
        },{
            "fee": 0.0,
            "specialServiceId": "DelCon"
        } ],
        "dimensionalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": 0.0
        },
        "deliveryCommitment": {
            "additionalDetails": "By end of Day",
            "estimatedDeliveryDateTime": "2021-06-25",
            "guarantee": "NONE",
            "maxEstimatedNumberOfDays": "3",
            "minEstimatedNumberOfDays": "3"
        },
        "serviceId": "PM",
        "baseCharge": 7.88,
        "currencyCode": "USD",
        "destinationZone": "5",
        "totalCarrierCharge": 7.88
    } ],
    "documents": [ {
        "contentType": "BASE64",
        "fileFormat": "PNG",
        "pages": [ {
            "contents": "iVBORw0KGgoAAAANSUhEUgAABLAAAAcIAQAAAAAEKwXnAAAACXB..."
        } ],
        "size": "DOC_4X6",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "HIDE_TOTAL_CARRIER_CHARGE",
        "value": "false"
      },{
        "name": "SHIPPER_ID",
        "value": "9024324564"
      },{
        "name": "ADD_TO_MANIFEST",
        "value": "true"
      },{
        "name": "FUTURE_SHIPMENT_DATE",
        "value": "2021-06-22 09:17:32.360"
      },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "false"
      },{
        "name": "SHIPPING_LABEL_RECEIPT",
        "value": "noOptions"
      },{
        "name": "CLIENT_FACILITY_ID",
        "value": ""
      },{
        "name": "CARRIER_FACILITY_ID",
        "value": ""
      },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "Thank you for shopping with us!"
      }
    ],
    "references": [ {
        "name": "Order_Number",
        "value": "123876-54910"
    } ],
    "parcelTrackingNumber": "9405509898641492016876",
    "shipmentId": "USPS2200334203501014"
}

International Shipment Sample Request

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

curl -X POST .../v1/shipments?includeDeliveryCommitment=true \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 93e30b6f-b6cc-4528-bef0" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "fromAddress": {
        "company": "Emporium",
        "name": "Anna Martin",
        "addressLines": [
            "625 S Main St"
        ],
        "cityTown": "Greenville",
        "stateProvince": "SC",
        "postalCode": "29601",
        "countryCode": "US"
    },
    "toAddress": {
        "company": "Museo",
        "name": "Director",
        "addressLines": [
            "Av. Juárez 8, Colonia Centro, Centro, 06010 "
        ],
        "cityTown": "Mexico City",
        "postalCode": "CDMX",
        "countryCode": "MX"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 60
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": 10.0,
            "width": 4.0,
            "height": 7.0
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "serviceId": "EMI",
        "parcelType": "FRE",
        "specialServices": [ {
            "specialServiceId": "Ins",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "100"
            } ]
        } ]
    } ],
    "documents": [ {
        "size": "DOC_8X11",
        "fileFormat": "PDF",
        "contentType": "URL",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
      },{
        "name": "ADD_TO_MANIFEST",
        "value": "true"
      },{
        "name": "CLIENT_FACILITY_ID",
        "value": ""
      },{
        "name": "CARRIER_FACILITY_ID",
        "value": ""
      },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "Thank you!"
      }
    ],
    "references": [ {
        "name": "Order_Number",
        "value": "1f514-7908"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD",
            "reasonForExport": "MERCHANDISE"
        },
        "customsItems": [ {
            "description": "Books",
            "quantity": 3,
            "unitPrice": 32.00,
            "unitWeight": {
                "weight": 20.0,
                "unitOfMeasurement": "OZ"
            }
        } ]
    }
}'

Sample Response

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

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.

 
 
 
 

• next
• previous |

© Copyright 2022, PB.