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 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 When creating a Newgistics shipment, set this to the Newgistics Facility ID provided by Newgistics. If testing in sandbox, set this to 1585. Newgistics
CLIENT_FACILITY_ID When creating a Newgistics shipment, set this to the Client Facility ID provided by Newgistics. If testing in sandbox, set this to 0093. Newgistics
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
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. When this is set to true, address validation will not make changes to the delivery line. Address validation will make corrections only to the city, state, and postal code.

Address validation, however, will still check 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 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
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 Complete 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_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
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