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.
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, enter length as the longest dimension, height as next longest, and width as shortest. 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 Standard 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 Standard Returns label. Available for PB Standard 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 Standard 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 Standard Returns only. The documents.type field must be set to QR_CODE. TIF. Available for PB Standard Delivery only. For restrictions, see Standard Delivery Labels. BMP. Available for PB Standard Delivery only. For restrictions, see Standard Delivery Labels. Required if the type field is set to SHIPPING_LABEL or QR_CODE.
resolution	String	PB Expedited, PB Standard, & 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 Standard Delivery only. For restrictions, see Standard 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 Standard 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 Standard 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 Standard 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 Standard 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 Standard: 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 Standard: 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 Standard: Note that for PB Standard, 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 Standard.
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 Standard (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: PB Expedited: Issue the Carrier Rules API; locate the combination of service and parcel type; locate the special service; and then locate the inputParameterRules array. For details on how the array maps to this field, see this FAQ. PB Standard: See PB Standard Special Services. PB Presort: See PB Presort Special Services. PMOD: If specialServiceId is set to PMOD_OPTIONS, the inputParameters array must contain each option listed in PMOD Options. FedEx: See FedEx Special Services. UPS: See UPS Special Services. 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.

 
 
 
 

• next
• previous |

© Copyright 2023 Pitney Bowes Inc. All rights reserved.