Shipment Options

Overview

The following are the shipment options that can be set in the shipmentOptions array when creating and rating shipments.

Shipment Options

Name Description
Applies to these 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 PB Standard 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 Return
 USPS,
PB Standard (always true),
Presort,
PMOD (always true)

CARRIER_FACILITY_ID

 The ID of the Pitney Bowes facility that will receive the parcel. This is either a PB Standard facility or a CBDS Consolidation Center. PB Standard,
CBDS

CLIENT_FACILITY_ID

 An identifier for the merchant’s facility. Depending on the API call, this is either an ID that Pitney Bowes has assigned or an ID that the merchant has assigned. PB Standard,
CBDS

CLIENT_ID

The merchant’s ID for access to a specific service.

Note: The CLIENT_ID gives a merchant access to a specific service. This should not be confused with the PB SHIPPER_ID, which identifies the merchant’s Pitney Bowes account.

For test IDs for the Sandbox environment, see the following:

 PB Standard,
CBDS
DISPOSITION_RULESET_ID For a PB Standard Returns shipment, the ruleset to use if the consignee refuses the return. By default, the APIs use the PB Standard ruleset. If the merchant uses a different ruleset, specify the ruleset using this option. PB Standard

FUTURE_SHIPMENT_DATE

  • In a Request: Indicates the shipment label is to be tendered at a future date. Specify the date using the following format: YYYY-MM-DD. Do not specify a time, unless noted below.

    USPS Only: A USPS shipment created after 8 p.m. local time is automatically dated for the next day. If you print a USPS label after 8 p.m. and plan to induct it the next day, you do not need the FUTURE_SHIPMENT_DATE option.

    USPS Only: If you are shipping USPS Priority Mail Express (EM) and plan to miss the first induction deadline on the future day, include the time in the FUTURE_SHIPMENT_DATE value: YYYY-MM-DD HH:mm:ss. The time you enter will be used to determine a delivery estimation.

  • In a Response: This lists the shipment date and shipment time, in local time. This lists the date even if the date is the current day.

 USPS,
PB Standard,
FedEx
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,
Presort

IS_RECTANGULAR

 For a PB Standard shipment, indicates the parcel uses rectangular dimensions. This is true by default. If you set this to false, you must set a value for the irregularParcelGirth field in the Parcel Object. PB Standard
LABEL_ID RESPONSE ONLY. If a PB Standard Returns shipment creates a QR code, this is the alpha-numeric identifier for the QR code. The actual QR code is returned in the documents object. PB Standard

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,
PB Standard,
Presort,
CBDS,
FedEx,
UPS

NON_DELIVERY_OPTION

Provides instructions if a parcel cannot be delivered. Applies to the following labels:

  • 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.
  • PB Standard labels: Valid values are:
    • AddressServiceRequested
    • AddressServiceRequestedBPRS
    • ReturnServiceRequested
    • ReturnServiceRequestedBPRS
    • ChangeServiceRequested
    • ForwardingServiceRequested
    • ElectronicServiceRequested
  • PB Presort flats: Valid value is:
    • ElectronicServiceRequested. This prints the Electronic Service Requested endorsement on the PB Presort label.
 USPS,
PB Standard,
Presort

PERMIT_NUMBER

 The merchant’s permit number for flats for a PB Presort shipment. When shipping letters and flats through PB Presort, you must include the merchant’s permit number in the Create Shipment request. Presort

Domestic Labels Only. Prints a merchant-defined message on the label, such as a merchant reference field. The message position and font depend on the carrier:

  • USPS: Merchants can enter up to 50 characters. The message uses a 6-point font and prints down the right side of the address portion of the label. See this sample.

    Note: This shipment option is not available for USPS First-Class Mail letters or flats.

  • PB Presort: The position depends on the parcel type. For the PKG parcel type, merchants can enter up to 50 characters. The message uses a 6-point font and prints down the right side of the address portion of the label. See this sample.

    For the LGENV parcel type, merchants can enter up to 25 characters. The message prints above the address. See this sample.

 USPS,
Presort PKG,
Presort LGENV,
FedEx

For the carriers listed below, this prints a merchant-defined message on the label, such as a merchant reference field. The message position and font depend on the carrier:

  • USPS: Domestic Labels Only. Prints a message on the bottom of the label using an 8-point font. For most label sizes, merchants can enter up to 50 characters. For 4X6 labels, merchants can enter up to 102 characters, and the label prints up to three lines of 34 characters each. See this sample.

    Note: This shipment option is not available for USPS First-Class Mail letters or flats.

  • PB Presort, PKG parcel type only: Domestic Labels Only. Prints a message up to 50 characters on the bottom of the label. See this sample.

  • PB Standard: Prints a message up to 30 characters at the bottom right of the address section of the label. Do not exceed 30 characters as doing so might render the printed message unreadable.

For CBDS, this option is RESPONSE ONLY. This option prints the end-to-end tracking number assigned by CBDS.

 USPS,
PB Standard,
Presort (PKG parcel type only),
CBDS
If set to True, prints human-readable tracking information on a PB Presort label that uses STANDARD mail with LGENV. By default, this option is set to False. 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 UTF-8, 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,
PB Standard,
Presort,
CBDS,
PMOD

RETURN_ID

 A merchant-generated identifier for a PB Standard Returns label. PB Standard

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,
PB Standard,
Presort,
CBDS,
FedEx,
UPS

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

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
SMART_LABEL_BARCODE RESPONSE ONLY. The PB Standard SmartLabel® barcode number. This is different from the shipment tracking number returned in the parcelTrackingNumber field. PB Standard