Shipment Options

Overview

The following are the shipment options that can be set in the shipmentOptions array in the Create Shipment API.

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 Newgistics and USPS PMOD labels, the system always sets this to true, no matter how the option is set in the API call.

The following USPS shipments cannot be added to a SCAN form:

  • FCM flats
  • FCM letters
  • Scan-Based Returns
 USPS,
Newgistics (always true),
PB Presort,
PB Cross-Border,
PMOD (always true)
CARRIER_FACILITY_ID
  • If creating a Newgistics shipment, set this to the Newgistics Facility ID provided by Newgistics. If testing in sandbox, set this to 1585.
  • If creating a PB Cross-Border shipment, use this field if the shipper does not use a first-mile integrated solution. Set this to the Consolidation Center ID listed in the Consolidation Centers table.
 Newgistics,
PB Cross-Border
CLIENT_FACILITY_ID
  • If creating a Newgistics shipment, set this to the Client Facility ID provided by Newgistics. If testing in sandbox, set this to 0093.
  • If creating a PB Cross-Border shipment, set this to the distribution center ID of the shipper.
 Newgistics,
PB Cross-Border
CLIENT_ID Cross-Border Quotes Only. If the merchant uses Newgistics, set this to the Newgistics Merchant ID. See Newgistics IDs. PB Cross-Border
FUTURE_SHIPMENT_DATE
  • In a request: Use this field 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/GMT using one of the following formats:
    • YYYY-MM-DD
    • YYYY-MM-DD HH:MM:SS
  • In response: This lists the shipment date in UTC/GMT. This lists the shipment date even if the date is not a future date but is the current day.
 USPS,
PB Cross-Border
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,
PB Cross-Border
IS_RECTANGULAR

This is true by default.

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

 Newgistics
MINIMAL_ADDRESS_VALIDATION

Domestic Addresses Only. When this is set to true, address validation will not make changes to the delivery line (street address). Address validation will make corrections only to the city, state, and postal code. The APIs will still, however, evaluate the entire address against current USPS address data to ensure the address is not marked as undeliverable.

For details, see What is minimal address validation?

By default, this option is false.

 USPS,
Newgistics,
PB Presort,
PB Cross-Border
NON_DELIVERY_OPTION

This field applies to USPS international labels and to Newgistics labels, which are domestic labels. This field provides instructions if a parcel cannot be delivered.

For USPS 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,
PB Cross-Border
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.

Note: This option is not supported for 6X4 labels with IMb barcodes.

 USPS,
PB Presort (PKG parcel type only)
PRINT_CUSTOM_MESSAGE_2

Use of this field depends on the carrier:

  • USPS, Newgistics, PB Presort: Domestic Labels Only. Prints a user-defined 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).

    For USPS and PB Presort, the custom message appears on the bottom of the label. For Newgistics, the message is printed at the bottom right of the address section of the label.

Note: This option is not supported for 6X4 labels with IMb barcodes.

  • PB Cross-Border: Prints the end-to-end tracking number assigned by PB Cross-Border.
 USPS,
Newgistics,
PB Presort (PKG parcel type only),
PB Cross-Border
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,
PB Cross-Border,
PMOD
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,
PB Cross-Border
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