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:

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 Delivery 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
 USPS,
PB Standard Delivery (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 Delivery,
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 Delivery,
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 Delivery,
PB Standard Returns,
CBDS

CLIENT_SERVICE_FLAG

 For a PB Standard Returns label, set this to Standard. PB Standard Returns

DISPOSITION_RULESET_ID

 For a PB Standard Returns label, the ruleset assigned to the merchant during onboarding for PB Standard Returns. The ruleset determines the routing and the disposition of the returned parcel. PB Standard Returns

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, do not set FUTURE_SHIPMENT_DATE.

    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 Delivery,
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 Delivery
PB Standard Returns
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 Returns

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

NON_DELIVERY_OPTION

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

  • USPS international shipments: 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 Delivery: 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 Delivery,
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 Delivery: 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 Delivery,
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 Delivery,
Presort,
CBDS,
PMOD

RETURN_ID

 For a PB Standard Returns label, this is a merchant-generated identifier for the label. PB Standard Returns

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

SHIPPING_LABEL_RECEIPT

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

  • RECEIPT_ONLY: The returned PDF contains the label and a receipt with the return label’s tracking number.

  • INSTRUCTIONS_ONLY: The returned PDF contains the label and instructions for the return.

    Note: For PB Standard Returns, you can set up customized instructions by contacting your Pitney Bowes implementation team.

  • RECEIPT_WITH_INSTRUCTIONS: The returned PDF contains the label, the instructions for the return, and a receipt with the return label’s tracking number.

  • NO_OPTIONS (default): The returned PDF contains only the label with no instructions or receipt. Note that for USPS, the value returned in the response will be noOptions.

 USPS,
PB Standard Returns

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 Returns