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

PB Expedited,
PB Standard Delivery,
PB Presort,
PMOD

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

Do not include this option for the following types of PB Expedited (USPS) shipments. Doing so will result in an error:

  • 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.

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

PB Expedited,
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.

    PB Expedited 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.

    PB Expedited Only: If you are shipping with 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

PB Expedited,
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 dimension 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

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

Domestic addresses include the 50 states, District of Columbia, U.S. territories, and APO/FPO/DPO.

For PB Standard Returns labels, this option applies only to the fromAddress, which is address of the buyer who is returning the parcel.

By default, this option is false.

NON_DELIVERY_OPTION

PB Expedited,
PB Standard Delivery,
PB Presort

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

  • PB Expedited 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

    See also What is the default non-delivery option?

  • 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.

PB Expedited,
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:

  • PB Expedited: 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.

PB Expedited,
PB Standard Delivery,
PB Presort (PKG parcel type only),
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:

  • PB Expedited, 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.

PB 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

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

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

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

PB Expedited,
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 PB Expedited, the value returned in the response will be noOptions.

SHIPPING_LABEL_SENDER_SIGNATURE

PB Expedited

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.