Create a Pitney Bowes Delivery Shipment

HTTP Request

POST /v1/shipments

Summary

This operation creates a Pitney Bowes Delivery label that uses either PB Expedited services or PB Standard services. PB Expedited provides domestic and international shipping through USPS®. PB Standard provides domestic postpaid shipping with USPS-compliant barcodes and requires shippers to containerize parcels. When invoking this API, follow the appropriate considerations on this page:

• PB Expedited Considerations
• PB Standard Considerations

For sample requests, see Sample Requests.

Request URIs

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

For requests that originate in the Asia-Pacific Region, Pitney Bowes provides the APAC Services URIs below. If you use APAC Services to create a shipment, you must also use APAC Services if you manifest or void the shipment.

APAC Sandbox: https://apac-sandbox.shippingapi.pitneybowes.com/shippingservices/v1/shipments?carrier=Newgistics
APAC Production: 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. Important: You must 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

The API call sends and receives a Shipment Object. The following table describes all possible fields in a Shipment Object, some of which might not apply to your operation. For the required fields and values for your operation, see one of the following after this table:

• PB Expedited Considerations
• PB Standard Considerations

Important

Some fields in the Shipment Object might not apply to your operation.

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. 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 soldToAddress object. If importer’s address is the same as the final recipient, the toAddress and soldToAddress must match.
altReturnAddress	Address Object	PB Expedited, CBDS Only. Applies as follows: PB Expedited: If you are sending an international shipment and if you have set the NON_DELIVERY_OPTION shipment option to redirect, then enter the address that a returned parcel should go to. CBDS: For a Create Shipment request, this is the address used to return a parcel from the CBDS Consolidation Center. If omitted, the fromAddress is used. The altReturnAddress is not returned in the response.
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]	Conditional. Defines the label, manifest, or other shipping document created by the API call. This field is required, except in the following cases: This field does not apply to Rate Parcel requests. This field does not apply to the Create CBDS Shipment request if the merchant prints the first-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 any additional requirements for a carrier or service, please see the Things to Consider section on the carrier’s Create Shipment page.
name	String	The name of the shipment option.
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: 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.
customsInfo	Customs Info Object	Customs clearance information used to fill out a commercial invoice.
customsItems	Array[Customs Items Object]	Information about each commodity in the shipment, used for customs clearance. The maximum number of objects in this array is 30.
domesticShipmentDetails	Domestic Shipment Details Object	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	Address Object	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 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. Set this to RETURN. Required for Expedited Returns and Standard Returns.
references	Array[Object]	Merchant-defined values. Applies to the following: PB Standard: Optional. See References Array in PB Standard. CBDS: Conditional. See References Array in a CBDS Request.
hazmatDetails	Hazmat Details Object	PB Standard Only. If shipping hazardous materials with PB Standard, use this 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.

---

PB Expedited Considerations

The following considerations apply to PB Expedited Delivery Shipments:

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

2. Address Fields: The fromAddress and toAddress objects require the following address fields:

   • addressLines
   • postalCode
   • countryCode

   The following additional field is required in the fromAddress object when shipping with Priority Mail Express (EM), also called Express Mail:

   • phone

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.

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. Services: For the available services and special services, see Services and Special Services.

6. Restrictions: To view restrictions on a service or special service, use the Carrier Rules API or see the USPS Domestic Mail Manual.

7. Tracking Requirement: The PB Shipping 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.

8. Labels: This operation 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.

   For the available label options, see Labels. Note that First-Class Mail (FCM) shipments that use the FLAT parcel type are supported only for 6X4 labels. First-Class Mail shipments that use the LETTER parcel type are supported only for 6X4 or 9X4 labels.

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

10. Customs: For 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 Form FAQs.

11. Shipper ID: You must specify a SHIPPER_ID in the shipmentOptions array and set its value to the merchant’s postalReportingNumber, which you can retrieve using the Get All Merchants API.

12. Reference IDs: 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.

13. 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: The following shipments cannot be added to a SCAN form:

    • First-Class Mail (FCM) flats (FLAT)
    • First-Class Mail (FCM) letters (LETTER)

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

The following considerations apply to PB Standard Delivery Shipments:

1. To print PB Standard Delivery labels, a merchant must onboard with PB Standard.

   You can test this API in the Sandbox environment before onboarding a merchant. Use the Sandbox IDs listed in the PB Standard IDs table.

2. 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. PB Standard Delivery labels are supported for domestic shipments only. You cannot print a PB Standard Delivery label for an international destination.

4. For the supported services, parcel types, and label sizes for PB Standard, see the tables on the Pitney Bowes reference page.

5. When issuing the API call, you must set the following:

   Field	Requirement
   fromAddress, toAddress	The following address fields are required: addressLines postalCode countryCode name
   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 NEWGISTICS, which indicates the carrier is PB Standard.
   rates.serviceId	See Services on the Pitney Bowes reference page.
   rates.specialServices	See Special Services on the PB Standard reference page.
   rates.parcelType	Set this to PKG.
   documents	See Labels on the PB Standard reference page.
   shipmentOptions	The following options are required in the shipmentOptions array: SHIPPER_ID: The merchant’s Shipper ID. CLIENT_FACILITY_ID: The Client Facility ID assigned to the merchant during onboarding with PB Standard. When testing this API in the Sandbox environment, set this to 0093. CARRIER_FACILITY_ID: The ID of the PB Standard Facility assigned to the merchant during onboarding with PB Standard. When testing this API in the Sandbox environment, set this to 1585. You can optionally set the CLIENT_ID. If you set an irregular parcel girth value in the parcel.dimension object, then you must include the IS_RECTANGULAR shipment option and set it to false.

6. 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. For a comparison of complete and minimal address validation, see What is minimal address validation?

   IMPORTANT: If you enable minimal address validation, the shipper takes 100% responsibility for any undelivered packages due to violation of carrier-addressing guidelines and is responsible for any surcharge or adjustment fee levied by the carrier for such a violation.

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

8. You can include merchant-defined reference fields in the shipment data and on the shipping label:

   • To include fields in the shipment data, use the references array, as described here
   • To include fields on the label, set the PRINT_CUSTOM_MESSAGE_2 shipment option in the shipmentOptions array.

9. To print customized information on the label, whether a reference field or other information, set the PRINT_CUSTOM_MESSAGE_2 shipment option in the shipmentOptions array.

10. PB Standard Delivery labels use 203 DPI by default. For label settings, see Labels. If you use APAC Services, see Label Settings for APAC Services.

11. The ADD_TO_MANIFEST shipment option is always considered true for PB Standard Delivery labels. If you set the option to false, the PB Shipping APIs ignore the setting and still consider the option to be true.

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

13. To close out the day, see Create a PB Standard Delivery Manifest (Closeout).

PB Standard Notifications

To configure PB Standard notifications, contact your PB Standard implementation team or account manager. Merchants who are configured for notifications can subscribe their shipments for notifications. To subscribe a shipment, include the NOTIFICATIONS special service in the rates.specialServices array. Configure the special service as follows:

• Set specialServiceId to NOTIFICATIONS

• Set the following parameters in the inputParameters array. All values are String values:

  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.

---

Sample Requests

See the following examples:

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

For a sample request for a Doc Tab label, see How do I print a Doc Tab label?

Priority Mail Shipment Sample Request

The following sample request prints a Priority Mail label. The request includes the includeDeliveryCommitment query parameter, which returns the estimated transit time in the response.

Sample Request for a Priority Mail Shipment

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": "John Smith",
        "phone": "303-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [ "4750 Walnut Street" ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Anna Martin",
        "phone": "620-555-0000",
        "email": "anna@example.com",
        "residential": false,
        "addressLines": [ "284 W Fulton" ],
        "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": [ { "name": "INPUT_VALUE", "value": "0"  } ]
        } ],
        "inductionPostalCode": "80302"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "contentType": "BASE64",
        "size": "DOC_4X6",
        "fileFormat": "PNG",
        "resolution": "DPI_203",
        "printDialogOption": "NO_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "ADD_TO_MANIFEST",
        "value": "true"
    },{
        "name": "PRINT_CUSTOM_MESSAGE_1",
        "value": "ORDER NUMBER: 12345-6789"
    },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "Thank you for shopping with us!"
    },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "true"
    } ]
}'

Sample Response

{
    "fromAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "303-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [
            "4750 Walnut Street"
        ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301-2532",
        "countryCode": "US",
        "carrierRoute": "C036",
        "deliveryPoint": "99"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Anna Martin",
        "phone": "620-555-0000",
        "email": "anna@example.com",
        "residential": false,
        "addressLines": [
            "284 W Fulton"
        ],
        "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": "80302",
        "specialServices": [ {
            "fee": 0.0,
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "50"
            } ],
            "specialServiceId": "Ins"
        },{
            "fee": 0.0,
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "0"
            } ],
            "specialServiceId": "DelCon"
        } ],
        "dimensionalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": 0.0
        },
        "deliveryCommitment": {
            "additionalDetails": "By end of Day",
            "estimatedDeliveryDateTime": "2020-07-27",
            "guarantee": "NONE",
            "maxEstimatedNumberOfDays": "3",
            "minEstimatedNumberOfDays": "3"
        },
        "serviceId": "PM",
        "baseCharge": 5.81,
        "currencyCode": "USD",
        "destinationZone": "4",
        "totalCarrierCharge": 5.81
    } ],
    "documents": [ {
        "contentType": "BASE64",
        "fileFormat": "PNG",
        "pages": [ {
            "contents": "iVBRw0KGgoAAAANSUhEUgAABLAAAAcIAQAAAAAEKwXnAAAACXBIWXMAAC..."
        } ],
        "resolution": "DPI_203",
        "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": "2020-07-24 09:55:44.441"
    },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "true"
    },{
        "name": "SHIPPING_LABEL_RECEIPT",
        "value": "noOptions"
    },{
        "name": "PRINT_CUSTOM_MESSAGE_1",
        "value": "ORDER NUMBER: 12345-6789"
    },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "Thank you for shopping with us!"
    } ],
    "parcelTrackingNumber": "9405509898641491962768",
    "shipmentId": "USPS2200249704816432"
}

International Shipment Sample Request

The following sample request prints a label for an international shipment through PB Expedited:

Sample Request for an International Shipment

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": { ... },
    "toAddress": { ... },
    "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"
            } ]
        } ],
        "inductionPostalCode": "94105"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "CAD",
            "reasonForExport": "MERCHANDISE"
        },
        "customsItems": [ {
            "description": "Books",
            "hSTariffCode": "4901.99.0070",
            "originCountryCode": "US",
            "quantity": 3,
            "unitPrice": 32.00,
            "unitWeight": {
                "weight": 20.0,
                "unitOfMeasurement": "OZ"
            }
        } ]
    },
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "contentType": "URL",
        "size": "DOC_8X11",
        "fileFormat": "PDF",
        "printDialogOption": "EMBED_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "ADD_TO_MANIFEST",
        "value": "true"
    } ]
}'

Sample Response

{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 60.0
        },
        "dimension": {
            "length": 10.0,
            "width": 4.0,
            "height": 7.0,
            "unitOfMeasurement": "IN"
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "parcelType": "FRE",
        "inductionPostalCode": "94105",
        "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": 42.3,
        "currencyCode": "USD",
        "destinationZone": "1",
        "totalCarrierCharge": 42.3
    } ],
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../usps/872060188/outbound/label/facb9d96c1b74f4089ebd7d788c4eb4a.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": "2019-09-24 11:49:53.000"
    },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "false"
    },{
        "name": "SHIPPING_LABEL_RECEIPT",
        "value": "noOptions"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "CAD",
            "freightCharge": 0.0,
            "handlingCosts": 0.0,
            "otherCharge": 0.0,
            "packingCosts": 0.0,
            "reasonForExport": "MERCHANDISE"
        },
        "customsItems": [ {
            "description": "Books",
            "hSTariffCode": "4901.99.0070",
            "originCountryCode": "US",
            "quantity": 3,
            "unitPrice": 32.0,
            "unitWeight": {
                "unitOfMeasurement": "OZ",
                "weight": 20.0
            }
        } ]
    },
    "parcelTrackingNumber": "EP862168011US",
    "shipmentId": "USPS2200205085792904"
}

Parcel Select Shipment Sample Request

The following sample request prints a Parcel Select label:

Sample Request for a Parcel Select Shipment

curl -X POST .../v1/shipments \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 5a2d2cf4-f2c4-41ba-91e2" \
-d '
{
    "fromAddress": {
        "company": "Supplies",
        "name": "Kathryn Smith",
        "phone": "334-000-0000",
        "email": "kathryn@example.com",
        "residential": false,
        "addressLines": [ "2352 Bent Creek Rd" ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830",
        "countryCode": "US"
    },
    "toAddress": {
        "company": "Books",
        "name": "Jane",
        "phone": "785-000-0000",
        "email": "books@example.com",
        "residential": false,
        "addressLines": [ "400 S Santa Fe Ave" ],
        "cityTown": "Salina",
        "stateProvince": "KS",
        "postalCode": "67401",
        "countryCode": "US"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": "32"
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": "10",
            "width": "4",
            "height": "6",
            "irregularParcelGirth": "20"
        }
    },
    "rates": [ {
        "carrier": "NEWGISTICS",
        "serviceId": "PRCLSEL",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "DelCon"
        },{
            "specialServiceId":"NOTIFICATIONS",
            "inputParameters": [ {
                "name":"RECIPIENT_NOTIFICATION_TYPE",
                "value":"ON_DELIVER"
            },{
                "name":"RECIPIENT_NOTIFICATION_EMAIL",
                "value":"kathryn@example.com"
            } ]
        } ]
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "contentType": "BASE64",
        "size": "DOC_4X6",
        "fileFormat": "ZPL2"
    } ],
    "references": [ {
        "name": "ReferenceNumber",
        "value": "OR1234"
    },{
        "name": "AddlRef1",
        "value": "CC123456"
    },{
        "name": "AddlRef2",
        "value": "CC4321"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "IS_RECTANGULAR",
        "value": "false"
    },{
        "name": "CLIENT_FACILITY_ID",
        "value": "0093"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "1585"
    },{
        "name": "NON_DELIVERY_OPTION",
        "value": "ChangeServiceRequested"
    } ]
}'

Sample Response

{
    "fromAddress": {
        "company": "Supplies",
        "name": "Kathryn Smith",
        "phone": "334-000-0000",
        "email": "kathryn@example.com",
        "residential": false,
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830-6433",
        "countryCode": "US",
        "deliveryPoint": "52"
    },
    "toAddress": {
        "company": "Books",
        "name": "Jane",
        "phone": "785-000-0000",
        "email": "books@example.com",
        "residential": false,
        "addressLines": [
            "400 S Santa Fe Ave"
        ],
        "cityTown": "Salina",
        "stateProvince": "KS",
        "postalCode": "67401-4144",
        "countryCode": "US",
        "deliveryPoint": "21"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 32.0
        },
        "dimension": {
            "length": 10.0,
            "width": 4.0,
            "height": 6.0,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": 20.0
        }
    },
    "rates": [ {
        "carrier": "NEWGISTICS",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "DelCon",
            "inputParameters": []
        },{
            "specialServiceId":"NOTIFICATIONS",
            "inputParameters": [ {
                "name":"RECIPIENT_NOTIFICATION_TYPE",
                "value":"ON_DELIVER"
            },{
                "name":"RECIPIENT_NOTIFICATION_EMAIL",
                "value":"kathryn@example.com"
            } ]
        } ],
        "serviceId": "PRCLSEL"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "contentType": "BASE64",
        "fileFormat": "ZPL2",
        "pages": [ {
            "contents": "XlhBXkxIMCwxNX5TRDIwXkxSTl5DSTI3Xk..."
        } ]
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "IS_RECTANGULAR",
        "value": "false"
    },{
        "name": "CLIENT_FACILITY_ID",
        "value": "0093"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "1585"
    },{
        "name": "NON_DELIVERY_OPTION",
        "value": "ChangeServiceRequested"
    } ],
    "references": [ {
        "name": "ReferenceNumber",
        "value": "OR1234"
    },{
        "name": "AddlRef1",
        "value": "CC123456"
    },{
        "name": "AddlRef2",
        "value": "CC4321"
    } ],
    "shipmentId": "NGST2200744454",
    "parcelTrackingNumber": "420900469261212345678900000130487"
}

Hazardous Materials Shipment Sample Request

The following request includes the hazmatDetails object:

Sample Request for a Shipment with Hazardous Materials

curl -X POST .../v1/shipments \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 5a2d2cf4-f2c4-41ba-91e2" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": "50"
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": "6",
            "width": "3",
            "height": "8",
            "irregularParcelGirth": "30"
        }
    },
    "rates": [ {
        "carrier": "NEWGISTICS",
        "serviceId": "PBD3D",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId":"NOTIFICATIONS",
            "inputParameters": [ {
                "name":"RECIPIENT_NOTIFICATION_TYPE",
                "value":"ON_DELIVER"
            },{
                "name":"RECIPIENT_NOTIFICATION_EMAIL",
                "value":"abc@example.com"
            } ]
        } ]
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "contentType": "URL",
        "size": "DOC_4X5",
        "fileFormat": "PDF"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "IS_RECTANGULAR",
        "value": "false"
    },{
        "name": "CLIENT_FACILITY_ID",
        "value": "0093"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "1585"
    },{
        "name": "NON_DELIVERY_OPTION",
        "value": "ChangeServiceRequested"
    } ],
    "references": [ {
        "name": "ReferenceNumber",
        "value": "OR5678"
    }, {
        "name": "AddlRef1",
        "value": "AA345678"
    }, {
        "name": "AddlRef2",
        "value": "AA8765"
    } ],
    "hazmatDetails": {
        "containerDetails": [ {
            "commodityInfo": [ {
                "hazardClass": "Gases"
            } ]
        } ]
    }
}'

Sample Response

{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 50.0
        },
        "dimension": {
            "length": 6.0,
            "width": 3.0,
            "height": 8.0,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": 30.0
        }
    },
    "rates": [ {
        "carrier": "NEWGISTICS",
        "parcelType": "PKG",
        "specialServices": [ {
            "inputParameters": [ {
                "name": "RECIPIENT_NOTIFICATION_TYPE",
                "value": "ON_DELIVER"
            },{
                "name": "RECIPIENT_NOTIFICATION_EMAIL",
                "value": "abc@example.com"
            } ],
            "specialServiceId": "NOTIFICATIONS"
        } ],
        "serviceId": "PBD3D"
    } ],
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../8a4968574a48DA2ac66d9d9af311387e.pdf",
        "fileFormat": "PDF",
        "size": "DOC_4X5",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "IS_RECTANGULAR",
        "value": "false"
    },{
        "name": "CLIENT_FACILITY_ID",
        "value": "0093"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "1585"
    },{
        "name": "NON_DELIVERY_OPTION",
        "value": "ChangeServiceRequested"
    } ],
    "references": [ {
        "name": "ReferenceNumber",
        "value": "OR5678"
    },{
        "name": "AddlRef1",
        "value": "AA345678"
    },{
        "name": "AddlRef2",
        "value": "AA8765"
    } ],
    "hazmatDetails": {
        "containerDetails": [ {
            "commodityInfo": [ {
                "hazardClass": "Gases"
            } ]
        } ]
    },
    "parcelTrackingNumber": "42000907926129010060140000293915",
    "shipmentId": "NGST202983128906"
}

---

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 API error codes, please see Error Codes.

 

 

 

 

 

 

 
 
 
 

• next
• previous |

© Copyright 2021, PB.