Shipment Options

Overview

Set shipment options in the shipmentOptions array when creating a shipment. The SHIPPER_ID is always required.

Shipment Options

Name Description Applies to the following carriers
ADD_TO_MANIFEST

Set this value to true in order to make this shipment eligible to be included in the end-of-day manifest.

For PMOD and Newgistics labels, the system always sets this to true, no matter how the option is set in the API call.

USPS,
Newgistics (always true),
PB Presort,
PMOD (always true)
CARRIER_FACILITY_ID Enter the Newgistics Facility ID in this field. If testing in sandbox, set this to 1585. Newgistics
CLIENT_FACILITY_ID Enter the Client Facility ID in this field. If testing in sandbox, set this to 0093. Newgistics
FUTURE_SHIPMENT_DATE

This field can be used if the shipment label is to be tendered at a future date. USPS allows you to extend the shipment date up to 7 days. Specify this value in UTC (Coordinated Universal Time) using one of the following formats:

  • YYYY-MM-DD
  • YYYY-MM-DD HH:MM:SS
USPS
HIDE_TOTAL_CARRIER_CHARGE

Set the value to true in order to hide the carrier shipping charge on the label. Please note, the carrier shipping charge will still appear on the receipt. This field applies to both domestic and international shipments.

Note: When shipping to Brazil, set this option to false. Per Conditions for Brazil in the International Mail Manual, shipments to Brazil that do not indicate the applicable postage and fees on PS Form 2976-A can hinder the customs clearance process and cause delays in clearing the items.

USPS, PB Presort
IS_RECTANGULAR

This is true by default.

For a Newgistics shipment, if IS_RECTANGULAR is false, then you must set a value for irregularParcelGirth in the parcel object.

Newgistics
MINIMAL_ADDRESS_VALIDATION

Domestic Addresses Only. If this is set to true, and if address validation cannot confirm the delivery line, Pitney Bowes allows address validation to confirm only the city, state, and postal code.

Address validation still checks for completeness and will still return an error if the address is marked “Undeliverable” by USPS.

USPS, Newgistics, PB Presort
NON_DELIVERY_OPTION

This field applies to international labels and to Newgistics labels. This field provides instructions if a parcel cannot be delivered.

For international labels, valid values are:

  • return: Return the parcel to the shipment’s fromAddress.
  • redirect: Return the parcel to the shipment’s altReturnAddress.
  • abandon: Don’t return the parcel.

For Newgistics labels, valid values are:

  • AddressServiceRequested
  • AddressServiceRequestedBPRS
  • ReturnServiceRequested
  • ReturnServiceRequestedBPRS
  • ChangeServiceRequested
  • ForwardingServiceRequested
  • ElectronicServiceRequested
USPS, Newgistics
PERMIT_NUMBER The merchant’s permit number for flats. You must include the merchant’s permit number in the request when shipping letters and flats through PB Presort. PB Presort
PRINT_CUSTOM_MESSAGE_1 Domestic Labels Only. Prints a custom message along the side of the address portion of the label. You can enter up to 50 characters. USPS, PB Presort
PRINT_CUSTOM_MESSAGE_2

Domestic Labels Only. Prints a custom message on the label of up to 50 characters. On a 4X6 USPS domestic label, this prints a custom message of up to 102 characters (three lines of 34 characters each).

The location of the message depends on the carrier:

  • USPS and PB Presort: The message is printed on the bottom of the label.
  • Newgistics: The message is printed at the bottom right of the address section of the label.
USPS, Newgistics, PB Presort
PRINTER_MODEL

Uses ASCII instead of Unicode to generate labels. This option is intended for older ZPL printers that do not support Unicode. By default, the PB Shipping APIs generate labels using the Unicode character set, which supports international characters.

Important: If you request ASCII, international characters might not print properly. Consider contacting your Zebra printer provider to update your printer’s firmware to a version that supports Unicode.

To request ASCII, set this option to ZP500 (which simply means generate with ASCII and does not mean your printer must be a ZP500):

{
    "name" : "PRINTER_MODEL",
    "value" : "ZP500"
}
USPS, Newgistics, PB Presort, PMOD
SHIPPER_BASE_CHARGE (Deprecated) Deprecated. For returned charges, please see Rates Object.  
SHIPPER_ID The Shipper ID of the merchant on whose behalf the label is being printed. The merchant’s Shipper ID is found in the postalReportingNumber field in the merchant object. USPS, Newgistics, PB Presort
SHIPPER_TOTAL_CHARGE (Deprecated) Deprecated. For returned charges, please see Rates Object.  
SHIPPING_LABEL_RECEIPT

DOC_8X11 Labels Only. Prints a receipt for the shipping label. Valid values are:

  • NO_OPTIONS (default)
  • RECEIPT_ONLY
  • RECEIPT_WITH_INSTRUCTIONS
  • INSTRUCTIONS_ONLY
USPS, PB Presort
SHIPPING_LABEL_SENDER_SIGNATURE

Adds the sender’s signature and the date on CN 22 and CP 72 shipping labels.

Enter the signature as a String. The sender’s signature date is automatically populated.


USPS, PB Presort