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

ADD_TO_MANIFEST

Applies to: Expedited, Presort, PB Delivery, PMOD

To make a PB Expedited or PB Presort shipment eligible for inclusion in the end-of-day manifest, set this to true. For PB Delivery and PMOD, the system always sets this option to true, no matter how the option is set in the API call.

For PB Expedited, note the following:

  • SCAN form: To include the shipment on the same day’s SCAN form, manifest the shipment before 8 p.m. local time.

  • Tracking: If you manifest the shipment after the cutoff time or let the shipment auto-manifest, there will be a delay of up to one day before USPS sends the first tracking data. Until then, USPS will not recognize the shipment as trackable.

  • Do no use this option for FCM flats and letters. It does not apply. Using it results in an error.

AUTHORITY_TO_LEAVE

Applies to: PB Delivery

CARRIER: LEAVE IF NO RESPONSE message is printed on the label and instructs carriers to leave the parcel if no one is available to accept the parcel. A parcel may be left in an unprotected location such as a stairway or uncovered porch.

Important

This service does not work with APAC servers.

A carrier release endorsement may only be used on:

  • Uninsured parcels

  • Parcels that do not require a signature

CARRIER_FACILITY_ID

Applies to: PB Delivery, CBDS Outbound, CBDS Inbound

The ID of the Pitney Bowes facility that will receive the parcel. This is either a PB facility or a CBDS Hub.

CLIENT_FACILITY_ID

Applies to: PB Delivery, CBDS Outbound

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

Applies to: PB Delivery, PB Returns, CBDS Outbound, CBDS Returns

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

Applies to: PB Returns

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

CONTENT_VERIFICATION

Applies to: CBDS Returns

Indicates whether the contents of the parcel should be verified. Valid values:

  • true

  • false

Defaults to false if the option is not provided.

DELIVERY_SOLUTION

Applies to: CBDS

Selects the delivery solution for a CBDS shipment. See Select the Delivery Solution when Creating a Shipment.

DISPOSITION_RULESET_ID

Applies to: PB Returns

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

FUTURE_SHIPMENT_DATE

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

    • You can extend the shipment date up to 7 days.

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

    • If you are shipping with USPS Priority Mail Express (EM) and plan to miss the first induction deadline on the future day, specify both the date and time. Use the following format: YYYY-MM-DD HH:mm:ss

  • 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

Applies to: Expedited

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

Applies to: PB Delivery, PB Returns

For a PB 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

Applies to: PB Returns

RESPONSE ONLY. If a PB 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

Applies to: Expedited, PB Delivery, PB Returns, Presort, FedEx, UPS, CBDS

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.

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

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

For CBDS, this option appears only in the response. You cannot send it in the request.

NON_DELIVERY_OPTION

Applies to: Expedited, PB Delivery, Presort

Prints instructions on the label or form on what to do 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 Delivery: For the default, see this FAQ. 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.

PARCEL_TRACKING_BARCODEVALUE

Applies to: PB Delivery, PB Returns,Expedited, UPS, and FedEx

Contains the full value of the parcel barcode including any portions that might not be displayed in the human readable text.

PARCEL_TRACKING_ID

Applies to: PB Delivery, PB Returns, Expedited, UPS, and FedEx

Contains the tracking number ID value and matches the human readable portion under the barcode.

PERMIT_NUMBER

Applies to: 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.

PERMIT_CITY

Applies to: PB Presort

The city from which the merchant’s permit was issued. When shipping letters and flats through PB Presort, you must include the merchant’s permit number, city, and state in the Create Shipment request.

PERMIT_STATE

Applies to: PB Presort

The state from which the merchant’s permit was issued. When shipping letters and flats through PB Presort, you must include the merchant’s permit number, city, and state in the Create Shipment request.

Applies to: Expedited, Presort PKG, 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: 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, 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, enter up to 25 characters. The message prints above the address. See this sample.

  • FedEx: Enter up to 40 characters. The message prints under the address portion of the label. See this sample.

Applies to: Expedited, PB Delivery, Presort PKG, CBDS

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 a 6-point font and up to 4 lines of 25 characters each. Enter up to 100 characters. See this sample. Note: This shipment option is not available for USPS First-Class Mail letters or flats.

  • PB Presort, domestic labels only: For the PKG parcel type, prints a message up to 50 characters on the bottom of the label. See this sample.

  • PB 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, RESPONSE ONLY: In a response, this option prints the end-to-end tracking number.

Applies to: 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.

Applies to: CBDS Returns

Indicates whether the packing slip should be printed. Valid values:

  • true

  • false

Defaults to false if the option is not provided.

PRINTER_MODEL

Applies to: Expedited, PB Delivery, Presort, CBDS, 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 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_DISPOSITION

Applies to: CBDS Returns

The disposition for the parcel. Valid value: RETURN_TO_SELLER or DESTROY.

Defaults to RETURN_TO_SELLER if the option is not provided.

RETURN_ID

Applies to: PB Returns

For a PB Returns label, this is a unique merchant-generated identifier for the label. The Order ID is frequently used as this value. The identifier is included as part of the Pitney Bowes barcode. This value can be alpha-numeric, up to 20 characters in length.

RETURN_REASON

Applies to: CBDS Returns

The reason for the return. Enter up to 100 characters. If you send more than 100 characters, the API truncates the string to 100 characters.

SELLER_ID

Applies to: CBDS Outbound, CBDS Returns

A seller ID that a marketplace shipper has shared with Pitney Bowes in advance. A marketplace shipper is a shipper who uses the same SHIPPER_ID for all sellers and who gives each seller a unique seller ID. In shipment and rate requests, pass the seller ID here in the SELLER_ID shipment option.

SHIPPER_ID

Applies to: All carriers

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 retrieved through the Get Merchants API.

SHIPPING_LABEL_RECEIPT

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

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

Applies to: PB Returns

RESPONSE ONLY. The PB Returns barcode number. This is different from the shipment tracking number returned in the parcelTrackingNumber field.