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 or PB Standard. The API uses the same request for both services. You can write one request and change the values as needed, depending on the service. For an example, see this FAQ.

Important

Before invoking this API, see the following considerations, found further down on this page:

• PB Expedited Considerations

• PB Standard Considerations

Request URLs

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

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: 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 might not apply to your operation.

Important

For the required fields and values, see the following considerations, found after the tables:

• 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. In a response, this array provides the URL or Base64 string for a document and in some cases can contain multiple objects. This field is required, except in the following cases: 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 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	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.
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. 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 Rate Expedited Returns, Create Expedited Returns, and Create Standard Returns. Note: You cannot rate Standard Returns.
references	Array[Object]	PB Standard, CBDS Only. Conditional. The merchant’s reference fields. Each object in the array includes a name-value pair that defines a reference field. This array applies only to the following two carriers: PB Standard: The array is optional. See PB Standard References. CBDS: The array is required for specific delivery solutions. See References Array in a CBDS Shipment. To pass references for carriers other than the above, see Reference Fields.
references.name	String	PB Standard, CBDS Only. The name of the reference field.
references.value	String	PB Standard, CBDS Only. The value for the reference field.
hazmatDetails	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.

Hazmat Details Object

This object is used only by PB Standard and provides details of a hazardous material or dangerous good. For a sample hazmatDetails object, see Hazardous Materials Shipment Sample Request.

Name	Data Type	Description
containerDetails	Array[Object]	Indicates one or more containers used to pack dangerous goods commodities.
containerDetails.commodityInfo	Array[Object]	Information about the material inside the containers.
containerDetails.commodityInfo.hazardClass	String	Class of the specified commodity. Valid values are: Explosives Gases FlammableCombustibleLiquids FlammableSolids OxidizingSubstancesOrganicPeroxides ToxicSubstancesAndInfectiousSubstances RadioactiveMaterial Corrosives LQDG ConsumerCommodities MiscellaneousHazardousMaterial
containerDetails.commodityInfo.quantity	Integer	The amount of the commodity.
containerDetails.commodityInfo.quantityUOM	String	The unit of measure.

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.

   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. Services: For the PB Expedited Delivery 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 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.

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

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

   For the available label options, 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.

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

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

12. 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 Merchant Accounts API.

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 that you cannot add First-Class Mail letters or flats to a SCAN form. Doing so will result in an error.

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

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

5. Services: For the PB Standard Delivery services and parcel types, see the tables on the Pitney Bowes reference page.

6. Label Settings: 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.

7. Required Fields: When issuing this API to create a PB Standard Delivery shipment, you must set the following:

   Field	Requirement
   fromAddress, toAddress	The following address fields are required: 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. Note that the deprecated value Newgistics also still works.
   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	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: You can optionally set the CLIENT_ID. If testing the Create Shipment API on Sandbox, set this to NGST. To print non-delivery instructions, include the NON_DELIVERY_OPTION shipment option. To print custom information or reference fields on the label, include the PRINT_CUSTOM_MESSAGE_2 shipment option. The ADD_TO_MANIFEST option is not necessary in the request. All PB Standard Delivery parcels are automatically eligible for close out, no matter how this option is set.

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

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

   • To include fields on the label, use the PRINT_CUSTOM_MESSAGE_2 shipment option.

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

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

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

13. All Parcels are Eligible for Close Out: When you create a PB Standard Delivery shipment, the shipment is automatically eligible for manifesting (close out). If you include the ADD_TO_MANIFEST option and set it to false, the API ignores the setting.

14. Close Out: To close out the day for PB Standard Delivery shipments, see Create a Pitney Bowes Manifest.

---

PB Standard Notifications

PB Standard can provide email and text notifications when a shipment is in transit or delivered. To configure a merchant account to receive notifications, contact your PB Standard implementation team or account manager. Once configured, a merchant can subscribe a shipment to notifications by adding the NOTIFICATIONS special service in the rates.specialServices array. The NOTIFICATIONS special service takes the following input parameters:

Parameter	Value
RECIPIENT_NOTIFICATION_TYPE	Required. The event for which to receive notifications. Set this to either of the following: ON_INTRANSIT ON_DELIVER
RECIPIENT_NOTIFICATION_EMAIL	Required. Enables email notification. Set this to the email address to receive notifications. You must use the same email address for all events. PB Standard accepts only one email address for all notifications.
RECIPIENT_NOTIFICATION_PHONE	Enables text notification. Enter the phone number as a string of continuous numbers, without spaces or punctuation. For example: 1234567890

For example:

"rates": [ {
  "specialServices": [ {
      "specialServiceId": "NOTIFICATIONS",
      "inputParameters": [ {
          "name": "RECIPIENT_NOTIFICATION_TYPE",
          "value": "ON_DELIVER"
      },{
          "name": "RECIPIENT_NOTIFICATION_EMAIL",
          "value": "widgets@example.com"
      },{
          "name": "RECIPIENT_NOTIFICATION_PHONE",
          "value": "8085551234"
      } ]
  }, ... ],
  ...
} ]

---

PB Standard References

In a PB Standard Delivery shipment, the references array allows merchants to include reference fields in the shipment data. The information entered will appear in manifest files and invoices.

The references array takes up to three objects, each of which maps to a specific field in the PB Standard data. The first object maps to the PB Standard “ReferenceNumber” field; the second to the “AddlRef1” field; and the third to the “AddlRef2” field. For each object you include, enter the name string as shown below. If you enter a different string, the system will change it. For each value field, enter a string of up to 50 characters. The following shows the reference field with the maximum three objects:

{
    "name": "ReferenceNumber",
    "value": "<shipper-generated value>"
},{
    "name": "AddlRef1",
    "value": "<shipper-generated value>"
},{
    "name": "AddlRef2",
    "value": "<shipper-generated value>"
}

The values entered in the references array will not appear on shipping labels. To print reference fields on shipping labels, set the PRINT_CUSTOM_MESSAGE_2 shipment option in the shipmentOptions array.

---

Sample Requests

Important

Before invoking this API, see the following considerations above on 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 2021, PB.