Shared Resource Objects for Shipping

The following are objects that are commonly nested in API payloads in the Global Ecommerce Shipping APIs. For documentation of an API’s full payload, see the API call.

Object


Description

Address

An address associated with the shipment, such as the origin or destination.

Customs Info

Customs-clearance information.

Customs Items

Customs-clearance information about each commodity.

Dimension

Parcel dimensions.

Documents

The shipment documents, including the label.

Parcel

The physical characteristics of a parcel.

Rates

The shipment’s service, special services, parcel type, and dimensions. In a response, this object also includes the shipment’s charges.

Special Services

The special services applied to the shipment.

Address Object

Important

For required fields, see your API call.

Name

Data Type

Description

addressLines

Array[String]

Street address or P.O. Box. Include apartment number, if applicable. You can specify up to 3 address lines.

For USPS® domestic shipments: ensure that the street address is specified as the last of the 3 address lines. This way, the street address is printed right above the city, state, and postal code, per USPS label guidelines.

Max is 100.

cityTown

String

The city or town.

Max is 50.

stateProvince

String

The state or province. For a US or Canadian address, use the 2-letter state or province code. Example: When countryCode = CA, stateProvince length must = 2

postalCode

String

The postal code or ZIP code. For US addresses, use either the 5-digit or 9-digit ZIP code in one of the following formats:

  • 12345

  • 12345-6789

If you use a different format, such as 12345- or 123451234, you will receive an error.

countryCode

String

Two-character country code from the ISO country list.

company

String

The name of the company.

name

String

The first and last name.

phone

String

The phone number. Enter the digits with or without spaces or hyphens. When used for Pickups, the maximum is 10 digits.

email

String

The email address.

Max is 100.

residential

Boolean

Indicates whether this is a residential address. Pitney Bowes recommends including this parameter to improve address verification.

deliveryPoint

String

The 2-digit USPS domestic delivery point, when available.

carrierRoute

String

The last four characters of the USPS domestic carrier route code. The carrier route is the area served by a particular USPS mail carrier. The full carrier route code is a nine-character string comprising the five-digit postal code appended by these four characters.

taxId

String

Pickup Request Only. Tax identification number. This is optional for pickup requests.

status

String

RESPONSE ONLY. This field applies to the Validate Address and Suggest Addresses APIs. The field indicates whether the submitted address is valid and whether the API made changes to the address.

Possible values are:

  • VALIDATED_CHANGED: The address is valid, but the API made changes to improve the address. For example, if an address has a valid street number and street name (e.g. “100 Elm”) but is missing the street suffix (e.g. “St”), the API would add the suffix.

  • VALIDATED_AND_NOT_CHANGED: The address is valid. The API made no changes.

  • NOT_CHANGED: The address could not be validated. The API made no changes.

 

Customs Info Object

Important

The following is the generic Customs Info object, with abbreviated field descriptions. For the required fields for your API call and for detailed field descriptions, see your API call’s documentation page.

Name

Data Type


Description

certificateNumber

String

The certificate number associated with the commodity.

comments

String

Free-form comment entered by the shipper.

currencyCode

String

The currency used for monetary values, entered as three uppercase letters, per ISO 4217.

businessType

String

CBDS Quotes Only. See Request CBDS Quotes.

customsDeclaredValue

BigDecimal

The declared shipment value, entered in the currency specified in currencyCode. Do not use this field with PB Expedited.

EELPFC

String

A number provided by the Automated Export System.

firstMileInsuredAmount

BigDecimal

CBDS Quotes Only. See Request CBDS Quotes.

firstMileShippingAmount

BigDecimal

CBDS Quotes Only. See Request CBDS Quotes.

freightCharge

BigDecimal

FedEx Only. See Create FedEx Shipment.

fromCustomsReference

String

A reference provided by the shipper. This may or may not appear on the customs form, depending on the carrier.

handlingCosts

BigDecimal

FedEx Only. See Create FedEx Shipment.

importDate

String

CBDS Returns Only. See Create CBDS Return.

importerCustomsReference

String

A reference number used by the importer, such as a VAT number or PO number. Do not use this field for CBDS.

importerCustomsReferenceType

String

If importerCustomsReference contains a VAT or IOSS number, this specifies which. Either VAT_NUMBER or IOSS_NUMBER.

insuredAmount

BigDecimal

CBDS Quotes and FedEx Only. See either Request CBDS Quotes or Create FedEx Shipment.

insuredNumber

String

invoiceNumber

String

The commercial invoice number assigned by the exporter.

licenseNumber

String

The export license number associated with the commodity.

otherCharge

BigDecimal

FedEx Only. See Create FedEx Shipment.

packingCosts

BigDecimal

FedEx Only. See Create FedEx Shipment.

portOfClearance

String

CBDS Returns & CBDS Quotes Only. See either Create CBDS Return or Request CBDS Quotes.

reasonForExport

String

The reason the commodity is being exported. Either GIFT, COMMERCIAL_SAMPLE, MERCHANDISE, DOCUMENTS, RETURNED_GOODS, or OTHER.

reasonForExportExplanation

String

Free-form information on the reason for export.

sdrValue

BigDecimal

When an international parcel is insured, the insured value must be expressed in Special Drawing Rights values. E.g. $100 USD = 66.87 SDR.

shippingAmount

BigDecimal

CBDS Quotes Only. See Request CBDS Quotes.

 

Customs Items Object

Important

The following is the generic Customs Items object, with abbreviated field descriptions. For the required fields for your API call and for detailed field descriptions, see your API call’s documentation page.

Name

Data Type


Description


brand

String

CBDS Only. The manufacturer’s brand name for the item.

categories

Array[Object]

HS Code API Only. See Retrieve HS Codes.

condition

String

CBDS Only. Condition of the commodity. Either new, used, refurbished, damaged, or unknown.

description

String

A detailed description of the commodity.

eccn

String

CBDS Only. The Export Control Classification Number (ECCN).

hazmat

Array[String]

CBDS Only. For a HAZMAT-flagged item, one or more of the HAZMAT classifications listed here.

hSTariffCode

String

The destination country’s tariff-classification number for the commodity.

hSTariffCodeCountry

String

CBDS Only. If the hSTariffCode field is used, this is the two-character ISO country code for the country supplying the HS code.

identifiers

Array[Object]

CBDS Only. Additional identifiers for the item. See your CBDS API call.

imageURL

Array[String]

CBDS Only. One or more URLs that link to an image of the commodity.

itemDimension

Dimension Object

CBDS Only. The dimensions for a single item.

itemId

String

CBDS Only. The merchant’s unique identifier for the commodity.

manufacturer

String

CBDS Only. The manufacturer of the item.

originCountryCode

String

The two-character ISO country code of the shipment’s origin country.

pricing

Object

CBDS Only. Pricing information for the commodity. See your CBDS API call.

quantity

Integer

The total number of items of this type of commodity.

quantityUOM

String

FedEx and UPS Only. See Create FedEx Shipment or Create UPS Shipment.

unitPrice

BigDecimal

The price of one item of this type of commodity.

unitWeight

Object

The weight and unit of measure of one item of the commodity.

unitWeight.weight

Number

The weight of the item.

unitWeight.unitOfMeasurement

String

The unit of measurement. For valid values, see your API call.

url

String

CBDS Only. The commodity’s URL on the merchant site.

 

Dimension Object

Name

Data Type

Description

length

BigDecimal

Required. The longest dimension.

Entering Dimensions: In the Dimension object, length is always the longest dimension. Height is the side that is perpendicular to the length and is measured in inches. Width is the remaining side that is also perpendicular to the length and is measured in inches. Girth is the distance around the thickest part of the remaining non-length sides and is measured in inches.For rectangular packages, girth is height multiplied by two plus width multiplied by two. For cylindrical packages, girth is the circumference of the cylinder. If you enter dimensions differently, the API will reassign them accordingly. For example, if you have a parcel that measures 6 x 4 x 1 inches, and if you assign 1 inch to the height:

"length": "6.0", "width": "4.0", "height": "1.0"

The API will reassign the values to assign 1 inch to the width:

"length": "6.0", "width": "1.0", "height": "4.0"

height

BigDecimal

Required. The second longest dimension. Height helps determine a parcel’s girth.

For the order of dimensions, see Entering Dimensions above.

width

BigDecimal

Required. The smallest dimension. Width helps determine a parcel’s girth.

Note: If you do not set width to the smallest dimension, the APIs will automatically reassign the dimension values to ensure width is set to the smallest dimension. See Entering Dimensions above.

unitOfMeasurement

String

Required. The unit of measure. Valid values:

  • IN: Inches (Required for PB Expedited)

  • CM: Centimeters

The following values are available only for CBDS international inbound delivery:

  • FT: Feet

  • YD: Yards

  • M: Meters

irregularParcelGirth

String

For a USPS irregular parcel, set this to the girth of the irregular parcel. Girth is twice the sum of the height and width:

girth = 2 * (height+width)

For a PB shipment, if you set an irregular parcel girth, then you must set the IS_RECTANGULAR shipment option to false in shipmentOptions.

 

Documents Object

Name

Data Type

Description

type

String

The type of document. Possible values:

  • SHIPPING_LABEL: Returns a shipping label.

  • QR_CODE: Returns a QR code that prints a PB Returns label. Available for PB Returns only.

  • MANIFEST: In the API response, this indicates that the returned document is an end-of-day manifest. This value applies only to the API response.

Required for CBDS shipments that print a label.

size

String

The recommended size of the label. The actual size of a label depends on the carrier. For valid values, see the carrier or API call.

Required if type is set to SHIPPING_LABEL.

contentType

String

Determines whether the API returns the document as a URL or a Base64-encoded string. The possible values are below. For the valid values for your operation, see your API call.

  • URL: The response returns a link to the label or manifest.

  • BASE64: Available for shipping labels only (both delivery and return labels). The response returns the shipping label as one or more Base64-encoded strings. If you use an APAC URL, the field instead returns raw ZPL, as described in Label Settings for APAC Services.

Required for:

  • PB Expedited

  • PB Delivery

  • PB Presort

  • CBDS Shipments that print a label

fileFormat

String

The file format for the document. The field can take the values below. Valid values depend on your API call. For valid values, see the API call.

  • PDF

  • PNG. Available for shipping labels only (both delivery and return labels).

  • ZPL2. Available for shipping labels only (both delivery and return labels). ZPL2 uses the Unicode character set. If you have an older printer that does not support Unicode, see this troubleshooting topic.

  • GIF. Available for PB Returns only. The documents.type field must be set to QR_CODE.

  • TIF. Available for PB Delivery only. For restrictions, see PB Delivery Labels.

  • BMP. Available for PB Delivery only. For restrictions, see PB Delivery Labels.

Required if the type field is set to SHIPPING_LABEL or QR_CODE.

resolution

String

PB Expedited, PB Delivery, & CBDS Only. The label’s dots per inch (DPI). This field is not required. Unless you need to change the resolution, it is recommended you leave out this field and use the default resolution.

This field does not apply to all shipments. It does not apply to PB Expedited 4X8 labels, PB Expedited COD labels, and PMOD labels. It might not apply to other shipments as well.

The field can take the values below, but valid values depend on the carrier and API call. For valid values, see the carrier or API call.

  • DPI_203

  • DPI_300

  • DPI_600 - Available for PB Delivery only. For restrictions, see PB Delivery Labels.

printDialogOption

String

If fileFormat is set to PDF, you can use this field to embed a script that renders an interactive Print dialog box when the merchant opens the shipping label. Valid values:

  • EMBED_PRINT_DIALOG: Embeds a script that renders a Print dialog box if fileFormat is set to PDF.

  • NO_PRINT_DIALOG: No print dialog box is rendered.

Required for:

  • PB Expedited Returns

  • PB Returns

  • CBDS Shipments that print a label

docTab

Array[Object]

4X8 Labels Only. In a Create Shipment request, this defines additional information to be printed on the 2-inch doc tab of a 4X8 label. See How do I print a doc tab?

contents

String

RESPONSE ONLY. When contentType is URL, this is the URL to access the label or manifest.

Note: The document is available for 24 hours after it is created.

pages

Array[Object]

RESPONSE ONLY. For a shipping label, if contentType is set to BASE64, this array contains the pages in the shipping label. The array contains multiple objects if the label has multiple pages.

pages.contents

String

Contains the Base64-encoded string for a page in the shipping label.

customerData

Object

PB Returns Only. This object is used to:

  • Print custom barcodes. See Custom Barcode Parameters.

  • Perform custom functions, such as printing merchant information on labels or applying merchant business rules. Merchants must set up custom functions in advance with their PB implementation teams.

customerData.labelDetails

Array[Object]

Parameters for custom barcodes or custom functions. Specify each parameter as an object with the following two fields, which take string values:

  • name: The parameter’s name.

  • value: The parameter’s value.

 

Parcel Object

Name

Data Type

Description

weight

Object

Required. The parcel’s weight and unit of measure.

weight.weight

BigDecimal

Required. The parcel’s weight.

weight.unitOfMeasurement

String

Required. The unit of measure. For USPS shipments, set this to OZ.

Valid values, depending on the carrier:

  • OZ: Ounces

  • GM: Grams

  • G: Grams (CBDS only)

  • LB: Pounds (CBDS only)

  • KG: Kilograms (CBDS only)

dimension

Dimension Object

Defines the parcel’s dimensions. For the order of dimensions, see the Dimension Object.

Required for the following shipments:

  • PB Expedited using the Parcel Select service or using a Soft Pack Envelope

  • PB Delivery

  • PB Presort

  • CBDS International Outbound from Canada

  • CBDS Domestic

  • CBDS Returns

Recommended for all shipments. Entering accurate dimensions helps avoid additional fees or parcels being undelivered.

currencyCode

String

ISO Currency Code. Use three uppercase letters, per ISO 4217. For example, for US Dollars use USD, for Canadian Dollars use CAD, and for Euros use EUR. For all currency codes, see https://www.iso.org/iso-4217-currency-codes.html.

valueOfGoods

BigDecimal

RESPONSE ONLY. For a CBDS shipment, the total value for the items in the shipment based on information sent in customs.customsItems.

Note

Do not send this field in a request. It will be ignored. The correct value will be sent in the response, based on the information you sent in customs.customsItems array.

 

Rates Object

Name

Data Type

Description

carrier

String

Required. Carrier name. Valid values are:

  • USPS: PB Expedited or PMOD

  • PBCS: PB Delivery

  • PBPRESORT: PB Presort

  • PBI: CBDS

  • HUB: CBDS Final-Mile Label

  • FEDEX: FedEx

  • UPS: United Parcel Service

serviceId

String

The carrier-specific service. Required if creating a shipment. Optional if rating a parcel. For valid values, see the carrier or API call.

If you use PB Expedited as the carrier:

  • Use the Carrier Rules API to determine any additional restrictions. See also the USPS Domestic Mail Manual.

  • The APIs require all USPS parcels be trackable. If the parcel uses a service that is not trackable, such as Priority Mail, add a trackable special service, such as Delivery Confirmation (DelCon). DelCon is a no-charge special service that triggers tracking but does not increase cost. Before adding a special service, check its compatibility with the service.

Required if creating a shipment.

parcelType

String

The parcel type. For supported parcel types, see the carrier or API call.

Required if:

  • Creating a shipment

  • Rating a FedEx or UPS parcel

Do not use this field with the CBDS Quotes API. It does not apply.

specialServices

Array[Special Services Object]

The special services to be applied. For valid values, see the carrier or API call.

Important

Including a special service in a Create Shipment request applies the special service.

Do not pass this array with CBDS shipments or CBDS Quotes.

inductionPostalCode

String

PB Expedited, PB Presort, PMOD, FedEx, & UPS Only. The postal code where the shipment is tendered to the carrier. If this field is present, the postal code specified here is used instead of the postal code in the fromAddress when calculating rates and when determining if a shipment can be added to a manifest. If this field is absent, the postal code listed in the fromAddress is used instead.

currencyCode

String

PB Expedited, CBDS, PMOD, FedEx, & UPS Only. Type of currency referenced in the piece price. For example: USD, CAD, EUR

dimensionalWeight

Object

RESPONSE ONLY. PB Expedited Only. If dimensional (DIM) weight pricing applies, this object lists the DIM weight. If DIM weight does not apply, this object lists 0.0 as the weight. DIM weight applies to large light packages, as explained in this FAQ.

This field applies only to PB Expedited and applies only when using the Create Shipment API. This field does not apply to the Rate Shipment API.

dimensionalWeight.
weight

Double

The calculated DIM weight. To calculate DIM weight, see this FAQ.

dimensionalWeight.
unitOfMeasurement

String

The unit of measure for the calculated DIM weight. Possible values:

  • GM: Grams

  • OZ: Ounces

baseCharge

Double

RESPONSE ONLY. The cost payable to the carrier to move the shipment, without any included fees, surcharges, discounts, special services, taxes, or duties, except as noted here:

  • PB Expedited: If your request includes a shipper rate plan, see this FAQ.

  • PB Delivery: The baseCharge equals the discounted transportation cost plus any of the following if applicable: Peak Parcel Adjustment fee, NMO charge, Oversize charge, Non-Continental Shipment fee.

totalCarrierCharge

Double

RESPONSE ONLY. The total amount payable to the carrier, including all fees, surcharges, discounts, special services, taxes, and duties, except as noted here:

  • CBDS: In certain cases, the totalCarrierCharge might not reflect additional surcharges.

  • UPS: In the Sandbox environment, the data UPS supplies for totalCarrierCharge might be incorrect. Specifically it might be 1% too low or exclude special service fees, or both. In Production, UPS provides the correct data.

  • PB Delivery: The totalCarrierCharge is the sum of baseCharge and surcharges.

If your request includes a shipper rate plan, see this FAQ on how the shipper rate affects this field.

surcharges

Array[Object]

RESPONSE ONLY. Additional fees or surcharges for the shipment. Each object in the array defines a surcharge and fee, except in the following instance:

PB Delivery: Note that for PB Delivery, the surcharges array shows only the fuel surcharge and does not show any other applicable surcharges.

surcharges.name

String

The type of surcharge. For possible surcharges, see the carrier’s reference page.

surcharges.fee

Double

The amount of the surcharge.

alternateBaseCharge

Double

RESPONSE ONLY. If your request includes a shipper rate plan and if the shipper does not have an NSA, this is the base service charge payable by the shipper, excluding special service charges. The rate is based on the plan specified in the X-PB-Shipper-Rate-Plan parameter. This field can be returned only if carrier has a value of USPS.

If the shipper has an NSA, do not use this field. Use the response’s baseCharge field instead. For more information, see this FAQ.

alternateTotalCharge

Double

RESPONSE ONLY. If your request includes a shipper rate plan and if the shipper does not have an NSA, this is the total charge payable by the shipper, including special service charges. The rate is based on the plan specified in the X-PB-Shipper-Rate-Plan parameter. This field can be returned only if carrier has a value of USPS.

If the shipper has an NSA, do not use this field. Use the response’s totalCarrierCharge field instead. For more information, see this FAQ.

deliveryCommitment

Object

RESPONSE ONLY. Time in transit for the shipment.

Note: For PB Expedited shipment, see also Pitney Bowes Delivery Guarantee.

Note: This field does not apply to PB Delivery.

deliveryCommitment.
minEstimatedNumberOfDays

String

The minimum number of delivery days.

deliveryCommitment.
maxEstimatedNumberOfDays

String

The maximum number of delivery days.

deliveryCommitment.
estimatedDeliveryDateTime

String

The estimated delivery date and time in the local time of the destination.

deliveryCommitment.
guarantee

String

States whether carrier delivery is guaranteed. Possible values:

  • FULL

  • NONE

deliveryCommitment.
additionalDetails

String

These are carrier specific details that may be provided.

destinationZone

Depends on carrier

RESPONSE ONLY. Applies only to the carriers listed below. The destination zone used to determine the rate. The zone is based on the origin address and destination address. The origin address can be a hub address.

The data type for this field depends on the carrier. The data type is:

  • String for PB Expedited, PB Delivery (Rates API only), PB Presort, and PMOD

  • Number for CBDS

rateTypeId

String

RESPONSE ONLY. The type of rate, such as COMMERCIAL_BASE (USPS) or COMMERCIAL (FedEx, UPS).

linePrice

BigDecimal

RESPONSE ONLY. CBDS Only. The unit price multiplied by quantity.

totalTaxAmount

BigDecimal

RESPONSE ONLY. CBDS, FedEx, & UPS Only. The total tax amount payable to the carrier.

totalDutyAmount

BigDecimal

RESPONSE ONLY. CBDS Only. The total duty amount payable to the carrier.

 

Special Services Object

Name

Data Type

Description

specialServiceId

String

Required. The special service to be applied. For valid values, see the carrier’s reference page.

Important

Do not include a special service unless you intend to apply it.

inputParameters

Array[Object]

The parameters for the special service, such as an insurance value or a receipt-number format. To determine parameters for a special service, use the instructions listed for your carrier:

Required if the special service requires input parameters. If a special service does not require input parameters, you can either leave out the array or pass an empty array.

inputParameters.name

String

The name of the input parameter. This field is required in the inputParameters array.

For PB Expedited, this maps to the inputParameterRules.name field in the Carrier Rules API.

inputParameters.value

String

The value of the parameter. This field is required in the inputParameters array.

For PB Expedited, the possible values are listed in the inputParameterRules array in the Carrier Rules API.

fee

Double

RESPONSE ONLY. The amount of fee expressed in the currency of the origin country.