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 Applies to
Description

ADD_TO_MANIFEST

 USPS,
USPS PMOD (always true),
PB Presort,
PB Standard Delivery (always true)

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

CARRIER_FACILITY_ID

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

CLIENT_FACILITY_ID

 PB Standard Delivery,
PB Cross-Border		 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.

CLIENT_ID

 PB Standard Delivery,
PB Standard Returns,
PB Cross-Border

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:

CLIENT_SERVICE_FLAG

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

DISPOSITION_RULESET_ID

 PB Standard Returns 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.

FUTURE_SHIPMENT_DATE

 USPS,
PB Standard Delivery,
FedEx

  • 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.
HIDE_TOTAL_CARRIER_CHARGE USPS,
PB Presort

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.

IS_RECTANGULAR

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

MINIMAL_ADDRESS_VALIDATION

 USPS,
PB Presort,
PB Standard Delivery,
PB Cross-Border,
FedEx,
UPS

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.

NON_DELIVERY_OPTION

 USPS,
PB Presort,
PB Standard Delivery

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.

PERMIT_NUMBER

 PB Presort 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.
USPS,
PB Presort PKG,
PB Presort LGENV,
FedEx

Domestic Labels Only. Prints a merchant-defined message on the label. You can use this, for example, to print a merchant-defined 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.
  • FedEx: Merchants can enter up to 40 characters. The message prints under the address portion of the label. See this sample.
USPS,
PB Presort (PKG parcel type only),
PB Standard Delivery,
PB Cross-Border

Prints a merchant-defined message on the label. You can use this, for example, to print a merchant-defined 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.

  • CBDS: This option is RESPONSE ONLY. This option prints the end-to-end tracking number assigned by CBDS.
Presort 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.

PRINTER_MODEL

 USPS,
USPS PMOD,
PB Presort,
PB Standard Delivery,
PB Cross-Border

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"
}

RETURN_ID

 PB Standard Returns For a PB Standard Returns label, this is a unique merchant-generated identifier for the label. The format used for Return IDs is set up in advance with merchant’s Pitney Bowes implementation team.

SHIPPER_ID

 USPS,
PB Presort,
PB Standard Delivery,
PB Standard Returns,
PB Cross-Border,
FedEx,
UPS		 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.

SHIPPING_LABEL_RECEIPT

 USPS,
PB Standard Returns

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.

SHIPPING_LABEL_SENDER_SIGNATURE

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